From 503193b5ef46e78c024031b09f5bc92f44a31930 Mon Sep 17 00:00:00 2001
From: David Mytton <david@arcjet.com>
Date: Fri, 6 Dec 2024 15:07:27 +0000
Subject: [PATCH] chore: Distinguish features by plan (#313)

---
 src/content/docs/blueprints/cookie-banner.mdx |  16 +-
 .../docs/blueprints/ip-geolocation.mdx        |  21 ++-
 .../docs/blueprints/vpn-proxy-detection.mdx   |  12 +-
 src/content/docs/reference/bun.mdx            | 108 +----------
 src/content/docs/reference/nestjs.mdx         | 108 +----------
 src/content/docs/reference/nextjs.mdx         | 168 ++++--------------
 src/content/docs/reference/nodejs.mdx         | 108 +----------
 src/content/docs/reference/remix.mdx          | 108 +----------
 src/content/docs/reference/sveltekit.mdx      | 108 +----------
 src/snippets/reference/shared/IPAnalysis.mdx  | 121 +++++++++++++
 10 files changed, 195 insertions(+), 683 deletions(-)
 create mode 100644 src/snippets/reference/shared/IPAnalysis.mdx

diff --git a/src/content/docs/blueprints/cookie-banner.mdx b/src/content/docs/blueprints/cookie-banner.mdx
index f0b0bb1b..50186aed 100644
--- a/src/content/docs/blueprints/cookie-banner.mdx
+++ b/src/content/docs/blueprints/cookie-banner.mdx
@@ -3,11 +3,21 @@ title: "Cookie Banner with Arcjet"
 description: "Use Arcjet's IP analysis to show a cookie banner in some jurisdictions."
 ---
 
-import { Aside } from "@astrojs/starlight/components";
+import { Aside, Badge } from "@astrojs/starlight/components";
 
-Cookie banners serve as digital consent notices, informing visitors about data tracking practices. While not universally mandated, they are required in specific jurisdictions, notably the EU under GDPR. Prudent websites implement these notifications selectively, ensuring compliance where necessary while preserving a streamlined user experience in regions without such requirements.
+Cookie banners serve as digital consent notices, informing visitors about data
+tracking practices. While not universally mandated, they are required in
+specific jurisdictions, notably the EU under GDPR. Prudent websites implement
+these notifications selectively, ensuring compliance where necessary while
+preserving a streamlined user experience in regions without such requirements.
 
-Using Arcjet's IP Geolocation feature it is possible to selectively show the banner's to users resident in jurisdictions that require them, without interfering with the experience of everyone else.
+Using Arcjet's IP Geolocation feature it is possible to selectively show the
+banner's to users resident in jurisdictions that require them, without
+interfering with the experience of everyone else.
+
+Country data is available on the <Badge text="Free" variant="caution" /> plan,
+but the region data is only available on the <Badge text="Pro" variant="note" />
+and above.
 
 <Aside type="caution">
   IP geolocation can be notoriously inaccurate, especially for mobile devices,
diff --git a/src/content/docs/blueprints/ip-geolocation.mdx b/src/content/docs/blueprints/ip-geolocation.mdx
index b28ee47a..80022a75 100644
--- a/src/content/docs/blueprints/ip-geolocation.mdx
+++ b/src/content/docs/blueprints/ip-geolocation.mdx
@@ -3,21 +3,24 @@ title: "Arcjet IP geolocation"
 description: "Use Arcjet's IP analysis to customize the response based on the IP location."
 ---
 
-import { Aside } from "@astrojs/starlight/components";
+import { Aside, Badge } from "@astrojs/starlight/components";
 
 Every decision provided by Arcjet includes IP address analysis. You can use this
 to customize your response based on the IP location.
 
 ## Available fields
 
-- Latitude and longitude.
-- Postal code e.g. `94104`.
-- City e.g. `San Francisco`.
-- Region e.g. `California`.
-- Country e.g. `US`.
-- Country name e.g. `United States`.
-- Continent e.g. `NA`.
-- Continent name e.g. `North America`.
+- Latitude and longitude. <Badge text="Pro" variant="note" />
+- Postal code e.g. `94104`. <Badge text="Pro" variant="note" />
+- City e.g. `San Francisco`. <Badge text="Pro" variant="note" />
+- Region e.g. `California`. <Badge text="Pro" variant="note" />
+- Country e.g. `US`. <Badge text="Free" variant="caution" /> <Badge text="Pro" variant="note" />
+- Country name e.g. `United States`. <Badge text="Free" variant="caution" /> <Badge text="Pro" variant="note" />
+- Continent e.g. `NA`. <Badge text="Pro" variant="note" />
+- Continent name e.g. `North America`. <Badge text="Pro" variant="note" />
+
+Note that the availability of these fields depends on your pricing plan,
+indicated by the badge next to each field.
 
 <Aside type="caution">
   IP geolocation can be notoriously inaccurate, especially for mobile devices,
diff --git a/src/content/docs/blueprints/vpn-proxy-detection.mdx b/src/content/docs/blueprints/vpn-proxy-detection.mdx
index 6a5a8b73..65e8de30 100644
--- a/src/content/docs/blueprints/vpn-proxy-detection.mdx
+++ b/src/content/docs/blueprints/vpn-proxy-detection.mdx
@@ -3,7 +3,7 @@ title: "VPN & proxy detection"
 description: "Use Arcjet's IP analysis to detect VPNs and proxies."
 ---
 
-import { Aside } from "@astrojs/starlight/components";
+import { Aside, Badge } from "@astrojs/starlight/components";
 
 Every decision provided by Arcjet includes IP address analysis. You can use this
 to detect VPNs and proxies.
@@ -11,12 +11,14 @@ to detect VPNs and proxies.
 ## Available fields
 
 - **IP AS type.** This is the [Autonomous
-  System](<https://en.wikipedia.org/wiki/Autonomous_system_(Internet)>) associated
-  with the IP, which can be used to identify VPNs and proxies. This can be one
-  of `isp`, `hosting`, `business` or `education`.
+  System](<https://en.wikipedia.org/wiki/Autonomous_system_(Internet)>)
+  associated with the IP, which can be used to identify VPNs and proxies. This
+  can be one of `isp`, `hosting`, `business` or `education`. This field is only
+  available on <Badge text="Pro" variant="note" /> plans and above.
 - **IP type.** Arcjet adds one or more categories to the IP address to help you
   identify VPNs and proxies. The categories are `vpn`, `proxy`, `tor`,
-  `hosting`, `relay`.
+  `hosting`, `relay`. This field is available on the <Badge text="Free"
+  variant="caution" /> plan and above.
 
 ## Checking for data
 
diff --git a/src/content/docs/reference/bun.mdx b/src/content/docs/reference/bun.mdx
index bab214d0..492274dc 100644
--- a/src/content/docs/reference/bun.mdx
+++ b/src/content/docs/reference/bun.mdx
@@ -31,6 +31,7 @@ import WithRuleTS from "/src/snippets/reference/bun/WithRule.ts?raw";
 import WithRuleJS from "/src/snippets/reference/bun/WithRule.js?raw";
 import Comments from "/src/components/Comments.astro";
 import Requirements from "@/snippets/get-started/bun/Requirements.mdx";
+import IPAnalysis from "@/snippets/reference/shared/IPAnalysis.mdx";
 
 [<SDKVersionBun/>](https://www.npmjs.com/package/@arcjet/bun)
 
@@ -434,112 +435,7 @@ more information about these properties.
 
 ### IP analysis
 
-As of SDK version `1.0.0-alpha.11`, the `ArcjetDecision` object contains an `ip`
-property. This includes additional data about the client IP address:
-
-#### IP location
-
-The IP location fields may be `undefined`, but you can use various methods to
-check their availability. Using the methods will also refine the type to remove
-the need for null or undefined checks.
-
-- `hasLatitude()` (`bool`): returns whether the `latitude` and `accuracyRadius`
-  fields are available.
-- `hasLongitude()` (`bool`): returns whether the `longitude` and
-  `accuracyRadius` fields are available.
-- `hasAccuracyRadius()` (`bool`): returns whether the `longitude`, `latitude`,
-  and `accuracyRadius` fields are available.
-- `hasTimezone()` (`bool`): returns whether the `timezone` field is available.
-- `hasPostalCode()` (`bool`): returns whether the `postalCode` field is
-  available.
-- `hasCity()` (`bool`): returns whether the `city` field is available.
-- `hasRegion()` (`bool`): returns whether the `region` field is available.
-- `hasCountry()` (`bool`): returns whether the `country` and `countryName`
-  fields are available.
-- `hasContinent()` (`bool`): returns whether the `continent` and `continentName`
-  fields are available.
-- `latitude` (`number | undefined`): the latitude of the client IP address.
-- `longitude` (`number | undefined`): the longitude of the client IP address.
-- `accuracyRadius` (`number | undefined`): how accurate the location is in
-  kilometers.
-- `timezone` (`string | undefined`): the timezone of the client IP address.
-- `postalCode` (`string | undefined`): the postal or zip code of the client IP
-  address.
-- `city` (`string | undefined`): the city of the client IP address.
-- `region` (`string | undefined`): the region of the client IP address.
-- `country` (`string | undefined`): the country code the client IP address.
-- `countryName` (`string | undefined`): the country name of the client IP
-  address.
-- `continent` (`string | undefined`): the continent code of the client IP
-  address.
-- `continentName` (`string | undefined`): the continent name of the client IP
-  address.
-
-##### Location accuracy
-
-IP geolocation can be notoriously inaccurate, especially for mobile devices,
-satellite internet providers, and even just normal users. Likewise with the
-specific fields like `city` and `region`, which can be very inaccurate. Country
-is usually accurate, but there are often cases where IP addresses are
-mis-located. These fields are provided for convenience e.g. suggesting a user
-location, but should not be relied upon by themselves.
-
-#### IP AS
-
-This is useful for identifying the network operator of the client IP address.
-This is useful for understanding whether the client is likely to be automated or
-not, or being stricter with requests from certain networks.
-
-The IP AS fields may be `undefined`, but you can use the `hasASN()` method to
-check their availability. Using this method will also refine the type to remove
-the need for null-ish checks.
-
-- `hasASN()` (`bool`): returns whether all of the ASN fields are available.
-- `asn` (`string | undefined`): the autonomous system (AS) number of the client
-  IP address.
-- `asnName` (`string | undefined`): the name of the AS of the client IP address.
-- `asnDomain` (`string | undefined`): the domain of the AS of the client IP
-  address.
-- `asnType` (`'isp' | 'hosting' | 'business' | 'education'`): the type of the AS
-  of the client IP address. Real users are more likely to be on an ISP or
-  business network rather than a hosting provider. Education networks often have
-  a single or small number of IP addresses even though there are many users. A
-  common mistake is to block a single IP because of too many requests when it is
-  a university or company network using
-  [NAT](https://en.wikipedia.org/wiki/Carrier-grade_NAT) (Network Address
-  Translation) to give many users the same IP.
-- `asnCountry` (`string | undefined`): the country code of the AS of the client
-  IP address. This is the administrative country of the AS, not necessarily the
-  country of the client IP address.
-
-#### IP type
-
-The `service` field may be `undefined`, but you can use the `hasService()`
-method to check the availability. Using this method will also refine the type to
-remove the need for null-ish checks.
-
-- `hasService()` (`bool`): whether the `service` field is available.
-- `service` (`string | undefined`): the name of the service associated with the
-  IP address—e.g. `Apple Private Relay`.
-- `isHosting()` (`bool`): returns whether the IP address of the client is owned
-  by a hosting provider. Requests originating from a hosting provider IP
-  significantly increase the likelihood that this is an automated client.
-- `isVpn()` (`bool`): returns whether the IP address of the client is owned by a
-  VPN provider. Many people use VPNs for privacy or work purposes, so by itself
-  this is not an indicator of the client being automated. However, it does
-  increase the risk score of the client and depending on your use case it may be
-  a characteristic you wish to restrict.
-- `isProxy()` (`bool`): returns whether the IP address of the client is owned by
-  a proxy provider. Similar to `isVpn()`, but proxies are more likely to involve
-  automated traffic.
-- `isTor()` (`bool`): returns whether the IP address of the client is known to
-  be part of the Tor network. As with `isVpn()`, there are legitimate uses for
-  hiding your identity through Tor, however it is also often a way to hide the
-  origin of malicious traffic.
-- `isRelay()` (`bool`): returns whether the IP address of the client is owned by
-  a relay service. The most common example is Apple iCloud Relay, which
-  indicates the client is less likely to be automated because Apple requires a
-  paid subscription linked to an Apple account in good standing.
+<IPAnalysis />
 
 ## Error handling
 
diff --git a/src/content/docs/reference/nestjs.mdx b/src/content/docs/reference/nestjs.mdx
index 3b4899e4..73696d55 100644
--- a/src/content/docs/reference/nestjs.mdx
+++ b/src/content/docs/reference/nestjs.mdx
@@ -14,6 +14,7 @@ import ProxiesTS from "/src/snippets/reference/nestjs/Proxies.ts?raw";
 import ConfigurationTS from "/src/snippets/reference/nestjs/Configuration.ts?raw";
 import IPLocationTS from "/src/snippets/reference/nestjs/IPLocation.ts?raw";
 import NodeVersions from "/src/snippets/reference/node-versions.mdx";
+import IPAnalysis from "/src/snippets/reference/shared/IPAnalysis.mdx";
 
 [<SDKVersionNestjs />](https://www.npmjs.com/package/@arcjet/nest)
 
@@ -337,112 +338,7 @@ information about these properties.
 
 ### IP analysis
 
-As of SDK version `1.0.0-alpha.11`, the `ArcjetDecision` object contains an `ip`
-property. This includes additional data about the client IP address:
-
-#### IP location
-
-The IP location fields may be `undefined`, but you can use various methods to
-check their availability. Using the methods will also refine the type to remove
-the need for null or undefined checks.
-
-- `hasLatitude()` (`bool`): returns whether the `latitude` and `accuracyRadius`
-  fields are available.
-- `hasLongitude()` (`bool`): returns whether the `longitude` and
-  `accuracyRadius` fields are available.
-- `hasAccuracyRadius()` (`bool`): returns whether the `longitude`, `latitude`,
-  and `accuracyRadius` fields are available.
-- `hasTimezone()` (`bool`): returns whether the `timezone` field is available.
-- `hasPostalCode()` (`bool`): returns whether the `postalCode` field is
-  available.
-- `hasCity()` (`bool`): returns whether the `city` field is available.
-- `hasRegion()` (`bool`): returns whether the `region` field is available.
-- `hasCountry()` (`bool`): returns whether the `country` and `countryName`
-  fields are available.
-- `hasContinent()` (`bool`): returns whether the `continent` and `continentName`
-  fields are available.
-- `latitude` (`number | undefined`): the latitude of the client IP address.
-- `longitude` (`number | undefined`): the longitude of the client IP address.
-- `accuracyRadius` (`number | undefined`): how accurate the location is in
-  kilometers.
-- `timezone` (`string | undefined`): the timezone of the client IP address.
-- `postalCode` (`string | undefined`): the postal or zip code of the client IP
-  address.
-- `city` (`string | undefined`): the city of the client IP address.
-- `region` (`string | undefined`): the region of the client IP address.
-- `country` (`string | undefined`): the country code the client IP address.
-- `countryName` (`string | undefined`): the country name of the client IP
-  address.
-- `continent` (`string | undefined`): the continent code of the client IP
-  address.
-- `continentName` (`string | undefined`): the continent name of the client IP
-  address.
-
-##### Location accuracy
-
-IP geolocation can be notoriously inaccurate, especially for mobile devices,
-satellite internet providers, and even just normal users. Likewise with the
-specific fields like `city` and `region`, which can be very inaccurate. Country
-is usually accurate, but there are often cases where IP addresses are
-mis-located. These fields are provided for convenience e.g. suggesting a user
-location, but should not be relied upon by themselves.
-
-#### IP AS
-
-This is useful for identifying the network operator of the client IP address.
-This is useful for understanding whether the client is likely to be automated or
-not, or being stricter with requests from certain networks.
-
-The IP AS fields may be `undefined`, but you can use the `hasASN()` method to
-check their availability. Using this method will also refine the type to remove
-the need for null-ish checks.
-
-- `hasASN()` (`bool`): returns whether all of the ASN fields are available.
-- `asn` (`string | undefined`): the autonomous system (AS) number of the client
-  IP address.
-- `asnName` (`string | undefined`): the name of the AS of the client IP address.
-- `asnDomain` (`string | undefined`): the domain of the AS of the client IP
-  address.
-- `asnType` (`'isp' | 'hosting' | 'business' | 'education'`): the type of the AS
-  of the client IP address. Real users are more likely to be on an ISP or
-  business network rather than a hosting provider. Education networks often have
-  a single or small number of IP addresses even though there are many users. A
-  common mistake is to block a single IP because of too many requests when it is
-  a university or company network using
-  [NAT](https://en.wikipedia.org/wiki/Carrier-grade_NAT) (Network Address
-  Translation) to give many users the same IP.
-- `asnCountry` (`string | undefined`): the country code of the AS of the client
-  IP address. This is the administrative country of the AS, not necessarily the
-  country of the client IP address.
-
-#### IP type
-
-The `service` field may be `undefined`, but you can use the `hasService()`
-method to check the availability. Using this method will also refine the type to
-remove the need for null-ish checks.
-
-- `hasService()` (`bool`): whether the `service` field is available.
-- `service` (`string | undefined`): the name of the service associated with the
-  IP address—e.g. `Apple Private Relay`.
-- `isHosting()` (`bool`): returns whether the IP address of the client is owned
-  by a hosting provider. Requests originating from a hosting provider IP
-  significantly increase the likelihood that this is an automated client.
-- `isVpn()` (`bool`): returns whether the IP address of the client is owned by a
-  VPN provider. Many people use VPNs for privacy or work purposes, so by itself
-  this is not an indicator of the client being automated. However, it does
-  increase the risk score of the client and depending on your use case it may be
-  a characteristic you wish to restrict.
-- `isProxy()` (`bool`): returns whether the IP address of the client is owned by
-  a proxy provider. Similar to `isVpn()`, but proxies are more likely to involve
-  automated traffic.
-- `isTor()` (`bool`): returns whether the IP address of the client is known to
-  be part of the Tor network. As with `isVpn()`, there are legitimate uses for
-  hiding your identity through Tor, however it is also often a way to hide the
-  origin of malicious traffic.
-- `isRelay()` (`bool`): returns whether the IP address of the client is owned by
-  a relay service. The most common example is Apple iCloud Relay, which
-  indicates the client is less likely to be automated because Apple requires a
-  paid subscription linked to an Apple account in good standing.
+<IPAnalysis />
 
 #### Example
 
diff --git a/src/content/docs/reference/nextjs.mdx b/src/content/docs/reference/nextjs.mdx
index e36eed30..b804a34c 100644
--- a/src/content/docs/reference/nextjs.mdx
+++ b/src/content/docs/reference/nextjs.mdx
@@ -3,50 +3,51 @@ title: "Arcjet Next.js SDK reference"
 prev: false
 ---
 
+import Requirements from "@/snippets/get-started/next-js/Requirements.mdx";
 import {
-  Tabs,
-  TabItem,
-  LinkCard,
   CardGrid,
   Code,
+  LinkCard,
+  TabItem,
+  Tabs,
 } from "@astrojs/starlight/components";
+import Comments from "/src/components/Comments.astro";
 import SDKVersionNextjs from "/src/components/SDKVersionNextjs.astro";
 import WhatIsArcjet from "/src/components/WhatIsArcjet.astro";
-import ConfigurationTS from "/src/snippets/reference/nextjs/Configuration.ts?raw";
+import ClientOverrideJS from "/src/snippets/reference/nextjs/ClientOverride.js?raw";
+import ClientOverrideTS from "/src/snippets/reference/nextjs/ClientOverride.ts?raw";
 import ConfigurationJS from "/src/snippets/reference/nextjs/Configuration.js?raw";
-import MultipleRulesTS from "/src/snippets/reference/nextjs/MultipleRules.ts?raw";
-import MultipleRulesJS from "/src/snippets/reference/nextjs/MultipleRules.js?raw";
-import LoggerTS from "/src/snippets/reference/nextjs/Logger.ts?raw";
+import ConfigurationTS from "/src/snippets/reference/nextjs/Configuration.ts?raw";
+import DecisionLogAppJS from "/src/snippets/reference/nextjs/DecisionLogApp.js?raw";
+import DecisionLogAppTS from "/src/snippets/reference/nextjs/DecisionLogApp.ts?raw";
+import DecisionLogPagesJS from "/src/snippets/reference/nextjs/DecisionLogPages.js?raw";
+import DecisionLogPagesTS from "/src/snippets/reference/nextjs/DecisionLogPages.ts?raw";
+import ErrorHandlingAppJS from "/src/snippets/reference/nextjs/ErrorHandlingApp.js?raw";
+import ErrorHandlingAppTS from "/src/snippets/reference/nextjs/ErrorHandlingApp.ts?raw";
+import ErrorHandlingPagesJS from "/src/snippets/reference/nextjs/ErrorHandlingPages.js?raw";
+import ErrorHandlingPagesTS from "/src/snippets/reference/nextjs/ErrorHandlingPages.ts?raw";
+import IPLocationAppJS from "/src/snippets/reference/nextjs/IPLocationApp.js?raw";
+import IPLocationAppTS from "/src/snippets/reference/nextjs/IPLocationApp.ts?raw";
+import IPLocationPagesJS from "/src/snippets/reference/nextjs/IPLocationPages.js?raw";
+import IPLocationPagesTS from "/src/snippets/reference/nextjs/IPLocationPages.ts?raw";
 import LoggerJS from "/src/snippets/reference/nextjs/Logger.js?raw";
-import ProxiesTS from "/src/snippets/reference/nextjs/Proxies.ts?raw";
-import ClientOverrideTS from "/src/snippets/reference/nextjs/ClientOverride.ts?raw";
-import ClientOverrideJS from "/src/snippets/reference/nextjs/ClientOverride.js?raw";
-import ProtectAppTS from "/src/snippets/reference/nextjs/ProtectApp.ts?raw";
-import ProtectPagesTS from "/src/snippets/reference/nextjs/ProtectPages.ts?raw";
+import LoggerTS from "/src/snippets/reference/nextjs/Logger.ts?raw";
+import MultipleRulesJS from "/src/snippets/reference/nextjs/MultipleRules.js?raw";
+import MultipleRulesTS from "/src/snippets/reference/nextjs/MultipleRules.ts?raw";
+import PageComponent from "/src/snippets/reference/nextjs/PageComponent.tsx?raw";
 import ProtectAppJS from "/src/snippets/reference/nextjs/ProtectApp.js?raw";
+import ProtectAppTS from "/src/snippets/reference/nextjs/ProtectApp.ts?raw";
 import ProtectPagesJS from "/src/snippets/reference/nextjs/ProtectPages.js?raw";
+import ProtectPagesTS from "/src/snippets/reference/nextjs/ProtectPages.ts?raw";
+import ProxiesTS from "/src/snippets/reference/nextjs/Proxies.ts?raw";
 import ServerAction from "/src/snippets/reference/nextjs/ServerAction.tsx?raw";
 import ServerActionProp from "/src/snippets/reference/nextjs/ServerActionProp.tsx?raw";
-import WithRuleAppTS from "/src/snippets/reference/nextjs/WithRuleApp.ts?raw";
-import WithRulePagesTS from "/src/snippets/reference/nextjs/WithRulePages.ts?raw";
 import WithRuleAppJS from "/src/snippets/reference/nextjs/WithRuleApp.js?raw";
+import WithRuleAppTS from "/src/snippets/reference/nextjs/WithRuleApp.ts?raw";
 import WithRulePagesJS from "/src/snippets/reference/nextjs/WithRulePages.js?raw";
-import DecisionLogAppTS from "/src/snippets/reference/nextjs/DecisionLogApp.ts?raw";
-import DecisionLogPagesTS from "/src/snippets/reference/nextjs/DecisionLogPages.ts?raw";
-import DecisionLogAppJS from "/src/snippets/reference/nextjs/DecisionLogApp.js?raw";
-import DecisionLogPagesJS from "/src/snippets/reference/nextjs/DecisionLogPages.js?raw";
-import IPLocationAppTS from "/src/snippets/reference/nextjs/IPLocationApp.ts?raw";
-import IPLocationPagesTS from "/src/snippets/reference/nextjs/IPLocationPages.ts?raw";
-import IPLocationAppJS from "/src/snippets/reference/nextjs/IPLocationApp.js?raw";
-import IPLocationPagesJS from "/src/snippets/reference/nextjs/IPLocationPages.js?raw";
-import ErrorHandlingAppTS from "/src/snippets/reference/nextjs/ErrorHandlingApp.ts?raw";
-import ErrorHandlingPagesTS from "/src/snippets/reference/nextjs/ErrorHandlingPages.ts?raw";
-import ErrorHandlingAppJS from "/src/snippets/reference/nextjs/ErrorHandlingApp.js?raw";
-import ErrorHandlingPagesJS from "/src/snippets/reference/nextjs/ErrorHandlingPages.js?raw";
+import WithRulePagesTS from "/src/snippets/reference/nextjs/WithRulePages.ts?raw";
 import NodeVersions from "/src/snippets/reference/node-versions.mdx";
-import PageComponent from "/src/snippets/reference/nextjs/PageComponent.tsx?raw";
-import Comments from "/src/components/Comments.astro";
-import Requirements from "@/snippets/get-started/next-js/Requirements.mdx";
+import IPAnalysis from "/src/snippets/reference/shared/IPAnalysis.mdx";
 
 [<SDKVersionNextjs/>](https://www.npmjs.com/package/@arcjet/next)
 
@@ -393,7 +394,7 @@ The `protect` function function returns a `Promise` that resolves to an
   re-evaluated. The SDK automatically caches `DENY` decisions for the length of
   the TTL.
 - `ip` (`ArcjetIpDetails`) - An object containing Arcjet's analysis of the
-  client IP address. See [IP analysis](#ip-analysis) below for more information.
+  client IP address. See IP analysis below for more information.
 
 ### Conclusion
 
@@ -546,112 +547,7 @@ more information about these properties.
 
 ### IP analysis
 
-As of SDK version `1.0.0-alpha.11`, the `ArcjetDecision` object contains an `ip`
-property. This includes additional data about the client IP address:
-
-#### IP location
-
-The IP location fields may be `undefined`, but you can use various methods to
-check their availability. Using the methods will also refine the type to remove
-the need for null or undefined checks.
-
-- `hasLatitude()` (`bool`): returns whether the `latitude` and `accuracyRadius`
-  fields are available.
-- `hasLongitude()` (`bool`): returns whether the `longitude` and
-  `accuracyRadius` fields are available.
-- `hasAccuracyRadius()` (`bool`): returns whether the `longitude`, `latitude`,
-  and `accuracyRadius` fields are available.
-- `hasTimezone()` (`bool`): returns whether the `timezone` field is available.
-- `hasPostalCode()` (`bool`): returns whether the `postalCode` field is
-  available.
-- `hasCity()` (`bool`): returns whether the `city` field is available.
-- `hasRegion()` (`bool`): returns whether the `region` field is available.
-- `hasCountry()` (`bool`): returns whether the `country` and `countryName`
-  fields are available.
-- `hasContinent()` (`bool`): returns whether the `continent` and `continentName`
-  fields are available.
-- `latitude` (`number | undefined`): the latitude of the client IP address.
-- `longitude` (`number | undefined`): the longitude of the client IP address.
-- `accuracyRadius` (`number | undefined`): how accurate the location is in
-  kilometers.
-- `timezone` (`string | undefined`): the timezone of the client IP address.
-- `postalCode` (`string | undefined`): the postal or zip code of the client IP
-  address.
-- `city` (`string | undefined`): the city of the client IP address.
-- `region` (`string | undefined`): the region of the client IP address.
-- `country` (`string | undefined`): the country code the client IP address.
-- `countryName` (`string | undefined`): the country name of the client IP
-  address.
-- `continent` (`string | undefined`): the continent code of the client IP
-  address.
-- `continentName` (`string | undefined`): the continent name of the client IP
-  address.
-
-##### Location accuracy
-
-IP geolocation can be notoriously inaccurate, especially for mobile devices,
-satellite internet providers, and even just normal users. Likewise with the
-specific fields like `city` and `region`, which can be very inaccurate. Country
-is usually accurate, but there are often cases where IP addresses are
-mis-located. These fields are provided for convenience e.g. suggesting a user
-location, but should not be relied upon by themselves.
-
-#### IP AS
-
-This is useful for identifying the network operator of the client IP address.
-This is useful for understanding whether the client is likely to be automated or
-not, or being stricter with requests from certain networks.
-
-The IP AS fields may be `undefined`, but you can use the `hasASN()` method to
-check their availability. Using this method will also refine the type to remove
-the need for null-ish checks.
-
-- `hasASN()` (`bool`): returns whether all of the ASN fields are available.
-- `asn` (`string | undefined`): the autonomous system (AS) number of the client
-  IP address.
-- `asnName` (`string | undefined`): the name of the AS of the client IP address.
-- `asnDomain` (`string | undefined`): the domain of the AS of the client IP
-  address.
-- `asnType` (`'isp' | 'hosting' | 'business' | 'education'`): the type of the AS
-  of the client IP address. Real users are more likely to be on an ISP or
-  business network rather than a hosting provider. Education networks often have
-  a single or small number of IP addresses even though there are many users. A
-  common mistake is to block a single IP because of too many requests when it is
-  a university or company network using
-  [NAT](https://en.wikipedia.org/wiki/Carrier-grade_NAT) (Network Address
-  Translation) to give many users the same IP.
-- `asnCountry` (`string | undefined`): the country code of the AS of the client
-  IP address. This is the administrative country of the AS, not necessarily the
-  country of the client IP address.
-
-#### IP type
-
-The `service` field may be `undefined`, but you can use the `hasService()`
-method to check the availability. Using this method will also refine the type to
-remove the need for null-ish checks.
-
-- `hasService()` (`bool`): whether the `service` field is available.
-- `service` (`string | undefined`): the name of the service associated with the
-  IP address—e.g. `Apple Private Relay`.
-- `isHosting()` (`bool`): returns whether the IP address of the client is owned
-  by a hosting provider. Requests originating from a hosting provider IP
-  significantly increase the likelihood that this is an automated client.
-- `isVpn()` (`bool`): returns whether the IP address of the client is owned by a
-  VPN provider. Many people use VPNs for privacy or work purposes, so by itself
-  this is not an indicator of the client being automated. However, it does
-  increase the risk score of the client and depending on your use case it may be
-  a characteristic you wish to restrict.
-- `isProxy()` (`bool`): returns whether the IP address of the client is owned by
-  a proxy provider. Similar to `isVpn()`, but proxies are more likely to involve
-  automated traffic.
-- `isTor()` (`bool`): returns whether the IP address of the client is known to
-  be part of the Tor network. As with `isVpn()`, there are legitimate uses for
-  hiding your identity through Tor, however it is also often a way to hide the
-  origin of malicious traffic.
-- `isRelay()` (`bool`): returns whether the IP address of the client is owned by
-  a relay service. The most common example is Apple iCloud Relay, which
-  indicates the client is less likely to be automated because Apple requires a
-  paid subscription linked to an Apple account in good standing.
+<IPAnalysis />
 
 #### Example
 
diff --git a/src/content/docs/reference/nodejs.mdx b/src/content/docs/reference/nodejs.mdx
index b1b6be56..992e2aef 100644
--- a/src/content/docs/reference/nodejs.mdx
+++ b/src/content/docs/reference/nodejs.mdx
@@ -24,6 +24,7 @@ import ClientOverrideJS from "/src/snippets/reference/nodejs/ClientOverride.js?r
 import NodeVersions from "/src/snippets/reference/node-versions.mdx";
 import Comments from "/src/components/Comments.astro";
 import Requirements from "@/snippets/get-started/node-js/Requirements.mdx";
+import IPAnalysis from "@/snippets/reference/shared/IPAnalysis.mdx";
 
 [<SDKVersionNodejs />](https://www.npmjs.com/package/@arcjet/node)
 
@@ -393,112 +394,7 @@ information about these properties.
 
 ### IP analysis
 
-As of SDK version `1.0.0-alpha.11`, the `ArcjetDecision` object contains an `ip`
-property. This includes additional data about the client IP address:
-
-#### IP location
-
-The IP location fields may be `undefined`, but you can use various methods to
-check their availability. Using the methods will also refine the type to remove
-the need for null or undefined checks.
-
-- `hasLatitude()` (`bool`): returns whether the `latitude` and `accuracyRadius`
-  fields are available.
-- `hasLongitude()` (`bool`): returns whether the `longitude` and
-  `accuracyRadius` fields are available.
-- `hasAccuracyRadius()` (`bool`): returns whether the `longitude`, `latitude`,
-  and `accuracyRadius` fields are available.
-- `hasTimezone()` (`bool`): returns whether the `timezone` field is available.
-- `hasPostalCode()` (`bool`): returns whether the `postalCode` field is
-  available.
-- `hasCity()` (`bool`): returns whether the `city` field is available.
-- `hasRegion()` (`bool`): returns whether the `region` field is available.
-- `hasCountry()` (`bool`): returns whether the `country` and `countryName`
-  fields are available.
-- `hasContinent()` (`bool`): returns whether the `continent` and `continentName`
-  fields are available.
-- `latitude` (`number | undefined`): the latitude of the client IP address.
-- `longitude` (`number | undefined`): the longitude of the client IP address.
-- `accuracyRadius` (`number | undefined`): how accurate the location is in
-  kilometers.
-- `timezone` (`string | undefined`): the timezone of the client IP address.
-- `postalCode` (`string | undefined`): the postal or zip code of the client IP
-  address.
-- `city` (`string | undefined`): the city of the client IP address.
-- `region` (`string | undefined`): the region of the client IP address.
-- `country` (`string | undefined`): the country code the client IP address.
-- `countryName` (`string | undefined`): the country name of the client IP
-  address.
-- `continent` (`string | undefined`): the continent code of the client IP
-  address.
-- `continentName` (`string | undefined`): the continent name of the client IP
-  address.
-
-##### Location accuracy
-
-IP geolocation can be notoriously inaccurate, especially for mobile devices,
-satellite internet providers, and even just normal users. Likewise with the
-specific fields like `city` and `region`, which can be very inaccurate. Country
-is usually accurate, but there are often cases where IP addresses are
-mis-located. These fields are provided for convenience e.g. suggesting a user
-location, but should not be relied upon by themselves.
-
-#### IP AS
-
-This is useful for identifying the network operator of the client IP address.
-This is useful for understanding whether the client is likely to be automated or
-not, or being stricter with requests from certain networks.
-
-The IP AS fields may be `undefined`, but you can use the `hasASN()` method to
-check their availability. Using this method will also refine the type to remove
-the need for null-ish checks.
-
-- `hasASN()` (`bool`): returns whether all of the ASN fields are available.
-- `asn` (`string | undefined`): the autonomous system (AS) number of the client
-  IP address.
-- `asnName` (`string | undefined`): the name of the AS of the client IP address.
-- `asnDomain` (`string | undefined`): the domain of the AS of the client IP
-  address.
-- `asnType` (`'isp' | 'hosting' | 'business' | 'education'`): the type of the AS
-  of the client IP address. Real users are more likely to be on an ISP or
-  business network rather than a hosting provider. Education networks often have
-  a single or small number of IP addresses even though there are many users. A
-  common mistake is to block a single IP because of too many requests when it is
-  a university or company network using
-  [NAT](https://en.wikipedia.org/wiki/Carrier-grade_NAT) (Network Address
-  Translation) to give many users the same IP.
-- `asnCountry` (`string | undefined`): the country code of the AS of the client
-  IP address. This is the administrative country of the AS, not necessarily the
-  country of the client IP address.
-
-#### IP type
-
-The `service` field may be `undefined`, but you can use the `hasService()`
-method to check the availability. Using this method will also refine the type to
-remove the need for null-ish checks.
-
-- `hasService()` (`bool`): whether the `service` field is available.
-- `service` (`string | undefined`): the name of the service associated with the
-  IP address—e.g. `Apple Private Relay`.
-- `isHosting()` (`bool`): returns whether the IP address of the client is owned
-  by a hosting provider. Requests originating from a hosting provider IP
-  significantly increase the likelihood that this is an automated client.
-- `isVpn()` (`bool`): returns whether the IP address of the client is owned by a
-  VPN provider. Many people use VPNs for privacy or work purposes, so by itself
-  this is not an indicator of the client being automated. However, it does
-  increase the risk score of the client and depending on your use case it may be
-  a characteristic you wish to restrict.
-- `isProxy()` (`bool`): returns whether the IP address of the client is owned by
-  a proxy provider. Similar to `isVpn()`, but proxies are more likely to involve
-  automated traffic.
-- `isTor()` (`bool`): returns whether the IP address of the client is known to
-  be part of the Tor network. As with `isVpn()`, there are legitimate uses for
-  hiding your identity through Tor, however it is also often a way to hide the
-  origin of malicious traffic.
-- `isRelay()` (`bool`): returns whether the IP address of the client is owned by
-  a relay service. The most common example is Apple iCloud Relay, which
-  indicates the client is less likely to be automated because Apple requires a
-  paid subscription linked to an Apple account in good standing.
+<IPAnalysis />
 
 #### Example
 
diff --git a/src/content/docs/reference/remix.mdx b/src/content/docs/reference/remix.mdx
index 05ec3df8..bf0b4a6f 100644
--- a/src/content/docs/reference/remix.mdx
+++ b/src/content/docs/reference/remix.mdx
@@ -24,6 +24,7 @@ import ClientOverrideJS from "/src/snippets/reference/remix/ClientOverride.js?ra
 import NodeVersions from "/src/snippets/reference/node-versions.mdx";
 import Comments from "/src/components/Comments.astro";
 import Requirements from "@/snippets/get-started/remix/Requirements.mdx";
+import IPAnalysis from "@/snippets/reference/shared/IPAnalysis.mdx";
 
 [<SDKVersionRemix />](https://www.npmjs.com/package/@arcjet/remix)
 
@@ -393,112 +394,7 @@ information about these properties.
 
 ### IP analysis
 
-As of SDK version `1.0.0-alpha.11`, the `ArcjetDecision` object contains an `ip`
-property. This includes additional data about the client IP address:
-
-#### IP location
-
-The IP location fields may be `undefined`, but you can use various methods to
-check their availability. Using the methods will also refine the type to remove
-the need for null or undefined checks.
-
-- `hasLatitude()` (`bool`): returns whether the `latitude` and `accuracyRadius`
-  fields are available.
-- `hasLongitude()` (`bool`): returns whether the `longitude` and
-  `accuracyRadius` fields are available.
-- `hasAccuracyRadius()` (`bool`): returns whether the `longitude`, `latitude`,
-  and `accuracyRadius` fields are available.
-- `hasTimezone()` (`bool`): returns whether the `timezone` field is available.
-- `hasPostalCode()` (`bool`): returns whether the `postalCode` field is
-  available.
-- `hasCity()` (`bool`): returns whether the `city` field is available.
-- `hasRegion()` (`bool`): returns whether the `region` field is available.
-- `hasCountry()` (`bool`): returns whether the `country` and `countryName`
-  fields are available.
-- `hasContinent()` (`bool`): returns whether the `continent` and `continentName`
-  fields are available.
-- `latitude` (`number | undefined`): the latitude of the client IP address.
-- `longitude` (`number | undefined`): the longitude of the client IP address.
-- `accuracyRadius` (`number | undefined`): how accurate the location is in
-  kilometers.
-- `timezone` (`string | undefined`): the timezone of the client IP address.
-- `postalCode` (`string | undefined`): the postal or zip code of the client IP
-  address.
-- `city` (`string | undefined`): the city of the client IP address.
-- `region` (`string | undefined`): the region of the client IP address.
-- `country` (`string | undefined`): the country code the client IP address.
-- `countryName` (`string | undefined`): the country name of the client IP
-  address.
-- `continent` (`string | undefined`): the continent code of the client IP
-  address.
-- `continentName` (`string | undefined`): the continent name of the client IP
-  address.
-
-##### Location accuracy
-
-IP geolocation can be notoriously inaccurate, especially for mobile devices,
-satellite internet providers, and even just normal users. Likewise with the
-specific fields like `city` and `region`, which can be very inaccurate. Country
-is usually accurate, but there are often cases where IP addresses are
-mis-located. These fields are provided for convenience e.g. suggesting a user
-location, but should not be relied upon by themselves.
-
-#### IP AS
-
-This is useful for identifying the network operator of the client IP address.
-This is useful for understanding whether the client is likely to be automated or
-not, or being stricter with requests from certain networks.
-
-The IP AS fields may be `undefined`, but you can use the `hasASN()` method to
-check their availability. Using this method will also refine the type to remove
-the need for null-ish checks.
-
-- `hasASN()` (`bool`): returns whether all of the ASN fields are available.
-- `asn` (`string | undefined`): the autonomous system (AS) number of the client
-  IP address.
-- `asnName` (`string | undefined`): the name of the AS of the client IP address.
-- `asnDomain` (`string | undefined`): the domain of the AS of the client IP
-  address.
-- `asnType` (`'isp' | 'hosting' | 'business' | 'education'`): the type of the AS
-  of the client IP address. Real users are more likely to be on an ISP or
-  business network rather than a hosting provider. Education networks often have
-  a single or small number of IP addresses even though there are many users. A
-  common mistake is to block a single IP because of too many requests when it is
-  a university or company network using
-  [NAT](https://en.wikipedia.org/wiki/Carrier-grade_NAT) (Network Address
-  Translation) to give many users the same IP.
-- `asnCountry` (`string | undefined`): the country code of the AS of the client
-  IP address. This is the administrative country of the AS, not necessarily the
-  country of the client IP address.
-
-#### IP type
-
-The `service` field may be `undefined`, but you can use the `hasService()`
-method to check the availability. Using this method will also refine the type to
-remove the need for null-ish checks.
-
-- `hasService()` (`bool`): whether the `service` field is available.
-- `service` (`string | undefined`): the name of the service associated with the
-  IP address—e.g. `Apple Private Relay`.
-- `isHosting()` (`bool`): returns whether the IP address of the client is owned
-  by a hosting provider. Requests originating from a hosting provider IP
-  significantly increase the likelihood that this is an automated client.
-- `isVpn()` (`bool`): returns whether the IP address of the client is owned by a
-  VPN provider. Many people use VPNs for privacy or work purposes, so by itself
-  this is not an indicator of the client being automated. However, it does
-  increase the risk score of the client and depending on your use case it may be
-  a characteristic you wish to restrict.
-- `isProxy()` (`bool`): returns whether the IP address of the client is owned by
-  a proxy provider. Similar to `isVpn()`, but proxies are more likely to involve
-  automated traffic.
-- `isTor()` (`bool`): returns whether the IP address of the client is known to
-  be part of the Tor network. As with `isVpn()`, there are legitimate uses for
-  hiding your identity through Tor, however it is also often a way to hide the
-  origin of malicious traffic.
-- `isRelay()` (`bool`): returns whether the IP address of the client is owned by
-  a relay service. The most common example is Apple iCloud Relay, which
-  indicates the client is less likely to be automated because Apple requires a
-  paid subscription linked to an Apple account in good standing.
+<IPAnalysis />
 
 #### Example
 
diff --git a/src/content/docs/reference/sveltekit.mdx b/src/content/docs/reference/sveltekit.mdx
index 735d74bf..8b618e0e 100644
--- a/src/content/docs/reference/sveltekit.mdx
+++ b/src/content/docs/reference/sveltekit.mdx
@@ -32,6 +32,7 @@ import ClientOverrideJS from "/src/snippets/reference/sveltekit/ClientOverride.j
 import NodeVersions from "/src/snippets/reference/node-versions.mdx";
 import Comments from "/src/components/Comments.astro";
 import Requirements from "@/snippets/get-started/sveltekit/Requirements.mdx";
+import IPAnalysis from "@/snippets/reference/shared/IPAnalysis.mdx";
 
 [<SDKVersionSvelteKit/>](https://www.npmjs.com/package/@arcjet/sveltekit)
 
@@ -454,112 +455,7 @@ more information about these properties.
 
 ### IP analysis
 
-As of SDK version `1.0.0-alpha.11`, the `ArcjetDecision` object contains an `ip`
-property. This includes additional data about the client IP address:
-
-#### IP location
-
-The IP location fields may be `undefined`, but you can use various methods to
-check their availability. Using the methods will also refine the type to remove
-the need for null or undefined checks.
-
-- `hasLatitude()` (`bool`): returns whether the `latitude` and `accuracyRadius`
-  fields are available.
-- `hasLongitude()` (`bool`): returns whether the `longitude` and
-  `accuracyRadius` fields are available.
-- `hasAccuracyRadius()` (`bool`): returns whether the `longitude`, `latitude`,
-  and `accuracyRadius` fields are available.
-- `hasTimezone()` (`bool`): returns whether the `timezone` field is available.
-- `hasPostalCode()` (`bool`): returns whether the `postalCode` field is
-  available.
-- `hasCity()` (`bool`): returns whether the `city` field is available.
-- `hasRegion()` (`bool`): returns whether the `region` field is available.
-- `hasCountry()` (`bool`): returns whether the `country` and `countryName`
-  fields are available.
-- `hasContinent()` (`bool`): returns whether the `continent` and `continentName`
-  fields are available.
-- `latitude` (`number | undefined`): the latitude of the client IP address.
-- `longitude` (`number | undefined`): the longitude of the client IP address.
-- `accuracyRadius` (`number | undefined`): how accurate the location is in
-  kilometers.
-- `timezone` (`string | undefined`): the timezone of the client IP address.
-- `postalCode` (`string | undefined`): the postal or zip code of the client IP
-  address.
-- `city` (`string | undefined`): the city of the client IP address.
-- `region` (`string | undefined`): the region of the client IP address.
-- `country` (`string | undefined`): the country code the client IP address.
-- `countryName` (`string | undefined`): the country name of the client IP
-  address.
-- `continent` (`string | undefined`): the continent code of the client IP
-  address.
-- `continentName` (`string | undefined`): the continent name of the client IP
-  address.
-
-##### Location accuracy
-
-IP geolocation can be notoriously inaccurate, especially for mobile devices,
-satellite internet providers, and even just normal users. Likewise with the
-specific fields like `city` and `region`, which can be very inaccurate. Country
-is usually accurate, but there are often cases where IP addresses are
-mis-located. These fields are provided for convenience e.g. suggesting a user
-location, but should not be relied upon by themselves.
-
-#### IP AS
-
-This is useful for identifying the network operator of the client IP address.
-This is useful for understanding whether the client is likely to be automated or
-not, or being stricter with requests from certain networks.
-
-The IP AS fields may be `undefined`, but you can use the `hasASN()` method to
-check their availability. Using this method will also refine the type to remove
-the need for null-ish checks.
-
-- `hasASN()` (`bool`): returns whether all of the ASN fields are available.
-- `asn` (`string | undefined`): the autonomous system (AS) number of the client
-  IP address.
-- `asnName` (`string | undefined`): the name of the AS of the client IP address.
-- `asnDomain` (`string | undefined`): the domain of the AS of the client IP
-  address.
-- `asnType` (`'isp' | 'hosting' | 'business' | 'education'`): the type of the AS
-  of the client IP address. Real users are more likely to be on an ISP or
-  business network rather than a hosting provider. Education networks often have
-  a single or small number of IP addresses even though there are many users. A
-  common mistake is to block a single IP because of too many requests when it is
-  a university or company network using
-  [NAT](https://en.wikipedia.org/wiki/Carrier-grade_NAT) (Network Address
-  Translation) to give many users the same IP.
-- `asnCountry` (`string | undefined`): the country code of the AS of the client
-  IP address. This is the administrative country of the AS, not necessarily the
-  country of the client IP address.
-
-#### IP type
-
-The `service` field may be `undefined`, but you can use the `hasService()`
-method to check the availability. Using this method will also refine the type to
-remove the need for null-ish checks.
-
-- `hasService()` (`bool`): whether the `service` field is available.
-- `service` (`string | undefined`): the name of the service associated with the
-  IP address—e.g. `Apple Private Relay`.
-- `isHosting()` (`bool`): returns whether the IP address of the client is owned
-  by a hosting provider. Requests originating from a hosting provider IP
-  significantly increase the likelihood that this is an automated client.
-- `isVpn()` (`bool`): returns whether the IP address of the client is owned by a
-  VPN provider. Many people use VPNs for privacy or work purposes, so by itself
-  this is not an indicator of the client being automated. However, it does
-  increase the risk score of the client and depending on your use case it may be
-  a characteristic you wish to restrict.
-- `isProxy()` (`bool`): returns whether the IP address of the client is owned by
-  a proxy provider. Similar to `isVpn()`, but proxies are more likely to involve
-  automated traffic.
-- `isTor()` (`bool`): returns whether the IP address of the client is known to
-  be part of the Tor network. As with `isVpn()`, there are legitimate uses for
-  hiding your identity through Tor, however it is also often a way to hide the
-  origin of malicious traffic.
-- `isRelay()` (`bool`): returns whether the IP address of the client is owned by
-  a relay service. The most common example is Apple iCloud Relay, which
-  indicates the client is less likely to be automated because Apple requires a
-  paid subscription linked to an Apple account in good standing.
+<IPAnalysis />
 
 ## Error handling
 
diff --git a/src/snippets/reference/shared/IPAnalysis.mdx b/src/snippets/reference/shared/IPAnalysis.mdx
new file mode 100644
index 00000000..6d5e7267
--- /dev/null
+++ b/src/snippets/reference/shared/IPAnalysis.mdx
@@ -0,0 +1,121 @@
+import { Badge } from "@astrojs/starlight/components";
+
+As of SDK version `1.0.0-alpha.11`, the `ArcjetDecision` object contains an `ip`
+property. This includes additional data about the client IP address:
+
+#### IP location
+
+The following are available on the <Badge text="Free" variant="caution" /> plan:
+
+- `country` (`string | undefined`): the country code the client IP address.
+- `countryName` (`string | undefined`): the country name of the client IP
+  address.
+
+The following are available on the <Badge text="Pro" variant="note" /> plan and
+above:
+
+- `latitude` (`number | undefined`): the latitude of the client IP address.
+- `longitude` (`number | undefined`): the longitude of the client IP address.
+- `accuracyRadius` (`number | undefined`): how accurate the location is in
+  kilometers.
+- `timezone` (`string | undefined`): the timezone of the client IP address.
+- `postalCode` (`string | undefined`): the postal or zip code of the client IP
+  address.
+- `city` (`string | undefined`): the city of the client IP address.
+- `region` (`string | undefined`): the region of the client IP address.
+- `continent` (`string | undefined`): the continent code of the client IP
+  address.
+- `continentName` (`string | undefined`): the continent name of the client IP
+  address.
+
+The IP location fields may be `undefined`, but you can use various methods to
+check their availability. Using the methods will also refine the type to remove
+the need for null or undefined checks.
+
+- `hasLatitude()` (`bool`): returns whether the `latitude` and `accuracyRadius`
+  fields are available.
+- `hasLongitude()` (`bool`): returns whether the `longitude` and
+  `accuracyRadius` fields are available.
+- `hasAccuracyRadius()` (`bool`): returns whether the `longitude`, `latitude`,
+  and `accuracyRadius` fields are available.
+- `hasTimezone()` (`bool`): returns whether the `timezone` field is available.
+- `hasPostalCode()` (`bool`): returns whether the `postalCode` field is
+  available.
+- `hasCity()` (`bool`): returns whether the `city` field is available.
+- `hasRegion()` (`bool`): returns whether the `region` field is available.
+- `hasCountry()` (`bool`): returns whether the `country` and `countryName`
+  fields are available.
+- `hasContinent()` (`bool`): returns whether the `continent` and `continentName`
+  fields are available.
+
+##### Location accuracy
+
+IP geolocation can be notoriously inaccurate, especially for mobile devices,
+satellite internet providers, and even just normal users. Likewise with the
+specific fields like `city` and `region`, which can be very inaccurate. Country
+is usually accurate, but there are often cases where IP addresses are
+mis-located. These fields are provided for convenience e.g. suggesting a user
+location, but should not be relied upon by themselves.
+
+#### IP AS
+
+This is useful for identifying the network operator of the client IP address.
+This is useful for understanding whether the client is likely to be automated or
+not, or being stricter with requests from certain networks.
+
+The IP AS fields may be `undefined`, but you can use the `hasASN()` method to
+check their availability. Using this method will also refine the type to remove
+the need for null-ish checks.
+
+The following are available on the <Badge text="Pro" variant="note" /> plan and
+above:
+
+- `hasASN()` (`bool`): returns whether all of the ASN fields are available.
+- `asn` (`string | undefined`): the autonomous system (AS) number of the client
+  IP address.
+- `asnName` (`string | undefined`): the name of the AS of the client IP address.
+- `asnDomain` (`string | undefined`): the domain of the AS of the client IP
+  address.
+- `asnType` (`'isp' | 'hosting' | 'business' | 'education'`): the type of the AS
+  of the client IP address. Real users are more likely to be on an ISP or
+  business network rather than a hosting provider. Education networks often have
+  a single or small number of IP addresses even though there are many users. A
+  common mistake is to block a single IP because of too many requests when it is
+  a university or company network using
+  [NAT](https://en.wikipedia.org/wiki/Carrier-grade_NAT) (Network Address
+  Translation) to give many users the same IP.
+- `asnCountry` (`string | undefined`): the country code of the AS of the client
+  IP address. This is the administrative country of the AS, not necessarily the
+  country of the client IP address.
+
+#### IP type
+
+The `service` field may be `undefined`, but you can use the `hasService()`
+method to check the availability. Using this method will also refine the type to
+remove the need for null-ish checks.
+
+The following are available on the <Badge text="Free" variant="caution" />
+and <Badge text="Pro" variant="note" /> plans, and above:
+
+- `hasService()` (`bool`): whether the `service` field is available.
+- `service` (`string | undefined`): the name of the service associated with the
+  IP address—e.g. `Apple Private Relay`.
+- `isHosting()` (`bool`): returns whether the IP address of the client is owned
+  by a hosting provider. Requests originating from a hosting provider IP
+  significantly increase the likelihood that this is an automated client.
+- `isVpn()` (`bool`): returns whether the IP address of the client is owned by a
+  VPN provider. Many people use VPNs for privacy or work purposes, so by itself
+  this is not an indicator of the client being automated. However, it does
+  increase the risk score of the client and depending on your use case it may be
+  a characteristic you wish to restrict.
+- `isProxy()` (`bool`): returns whether the IP address of the client is owned by
+  a proxy provider. Similar to `isVpn()`, but proxies are more likely to involve
+  automated traffic.
+- `isTor()` (`bool`): returns whether the IP address of the client is known to
+  be part of the Tor network. As with `isVpn()`, there are legitimate uses for
+  hiding your identity through Tor, however it is also often a way to hide the
+  origin of malicious traffic.
+- `isRelay()` (`bool`): returns whether the IP address of the client is owned by
+  a relay service. The most common example is Apple iCloud Relay, which
+  indicates the client is less likely to be automated because Apple requires a
+  paid subscription linked to an Apple account in good standing.