@arcjet/astro 1.0.0-beta.10 → 1.0.0-beta.12

package/index.d.ts

@@ -1,75 +1,330 @@
-import type { BotOptions, EmailOptions, FixedWindowRateLimitOptions, ProtectSignupOptions, SensitiveInfoOptions, ShieldOptions, SlidingWindowRateLimitOptions, TokenBucketRateLimitOptions } from "arcjet";
+import type { BotOptions, EmailOptions, FilterOptions, FixedWindowRateLimitOptions, ProtectSignupOptions, SensitiveInfoOptions, ShieldOptions, SlidingWindowRateLimitOptions, TokenBucketRateLimitOptions } from "arcjet";
 import type { AstroIntegration } from "astro";
 type IntegrationRule<Characteristics extends readonly string[]> = {
     type: "shield";
-    options?: ShieldOptions;
+    options: ShieldOptions;
 } | {
     type: "bot";
-    options?: BotOptions;
+    options: BotOptions;
 } | {
     type: "email";
-    options?: EmailOptions;
+    options: EmailOptions;
+} | {
+    type: "filter";
+    options: FilterOptions;
 } | {
     type: "sensitiveInfo";
-    options?: SensitiveInfoOptions<never>;
+    options: SensitiveInfoOptions<never>;
 } | {
     type: "fixedWindow";
-    options?: FixedWindowRateLimitOptions<Characteristics>;
+    options: FixedWindowRateLimitOptions<Characteristics>;
 } | {
     type: "slidingWindow";
-    options?: SlidingWindowRateLimitOptions<Characteristics>;
+    options: SlidingWindowRateLimitOptions<Characteristics>;
 } | {
     type: "tokenBucket";
-    options?: TokenBucketRateLimitOptions<Characteristics>;
+    options: TokenBucketRateLimitOptions<Characteristics>;
 } | {
     type: "protectSignup";
-    options?: ProtectSignupOptions<Characteristics>;
+    options: ProtectSignupOptions<Characteristics>;
 };
+/**
+ * Configuration for the Astro integration of Arcjet.
+ *
+ * @template Characteristics
+ *   Characteristics to track a user by.
+ */
 type ArcjetIntegrationOptions<Characteristics extends readonly string[]> = {
+    /**
+     * Integration rules to apply when protecting a request (required).
+     *
+     * These rules are *different* from those exposed from `arcjet` core.
+     * You have to import them from this integration (`@arcjet/astro`) instead.
+     */
     rules: IntegrationRule<Characteristics>[];
+    /**
+     * Characteristics to track a user by (default: `["src.ip"]`).
+     *
+     * Can also be passed to rules.
+     */
     characteristics?: Characteristics;
+    /**
+     * Configuration for the default client (optional).
+     */
     client?: RemoteClientOptions;
+    /**
+     * IP addresses and CIDR ranges of trusted load balancers and proxies
+     * (optional, example: `["100.100.100.100", "100.100.100.0/24"]`).
+     */
     proxies?: string[];
 };
-export declare function shield(options?: ShieldOptions): {
+/**
+ * Arcjet Shield WAF rule.
+ *
+ * Applying this rule protects your application against common attacks,
+ * including the OWASP Top 10.
+ *
+ * The Arcjet Shield WAF analyzes every request to your application to detect
+ * suspicious activity.
+ * Once a certain suspicion threshold is reached,
+ * subsequent requests from that client are blocked for a period of time.
+ *
+ * @param options
+ *   Configuration for the Shield rule.
+ * @returns
+ *   Astro integration Shield rule to provide to the SDK in the `rules` field.
+ */
+export declare function shield(options: ShieldOptions): {
     readonly type: "shield";
-    readonly options: ShieldOptions | undefined;
+    readonly options: ShieldOptions;
 };
-export declare function detectBot(options?: BotOptions): {
+/**
+ * Arcjet bot detection rule.
+ *
+ * Applying this rule allows you to manage traffic by automated clients and
+ * bots.
+ *
+ * Bots can be good (such as search engine crawlers or monitoring agents) or bad
+ * (such as scrapers or automated scripts).
+ * Arcjet allows you to configure which bots you want to allow or deny by
+ * specific bot names such as curl, as well as by category such as search
+ * engine bots.
+ *
+ * Bots are detected based on various signals such as the user agent, IP
+ * address, DNS records, and more.
+ *
+ * @param options
+ *   Configuration for the bot rule (required).
+ * @returns
+ *   Astro integration Bot rule to provide to the SDK in the `rules` field.
+ */
+export declare function detectBot(options: BotOptions): {
     readonly type: "bot";
-    readonly options: BotOptions | undefined;
+    readonly options: BotOptions;
 };
-export declare function validateEmail(options?: EmailOptions): {
+/**
+ * Arcjet email validation rule.
+ *
+ * Applying this rule allows you to validate and verify an email address.
+ *
+ * The first step of the analysis is to validate the email address syntax.
+ * This runs locally within the SDK and validates the email address is in the
+ * correct format.
+ * If the email syntax is valid, the SDK will pass the email address to the
+ * Arcjet cloud API to verify the email address.
+ * This performs several checks, depending on the rule configuration.
+ *
+ * @param options
+ *   Configuration for the email validation rule (required).
+ * @returns
+ *   Astro integration Email rule to provide to the SDK in the `rules` field.
+ */
+export declare function validateEmail(options: EmailOptions): {
     readonly type: "email";
-    readonly options: EmailOptions | undefined;
+    readonly options: EmailOptions;
+};
+/**
+ * Arcjet filter rule.
+ *
+ * Applying this rule lets you block requests using Wireshark-like display
+ * filter expressions over HTTP headers, IP addresses, and other request
+ * fields.
+ * You can quickly enforce rules like allow/deny by country, network, or
+ * `user-agent` pattern.
+ *
+ * See the [reference guide](https://docs.arcjet.com/filters/reference) for
+ * more info on the expression language fields, functions, and values.
+ *
+ * @param options
+ *   Configuration (required).
+ * @returns
+ *   Astro integration Filter rule to provide to the SDK in the `rules` field.
+ *
+ * @example
+ *   In this example, the expression matches non-VPN GET requests from the US.
+ *   Requests matching the expression are allowed, all others are denied.
+ *
+ *   ```ts
+ *   filter({
+ *     allow: [
+ *       'http.request.method eq "GET" and ip.src.country eq "US" and not ip.src.vpn',
+ *     ],
+ *     mode: "LIVE",
+ *   })
+ *   ```
+ *
+ * @link https://docs.arcjet.com/filters/reference
+ */
+export declare function filter(options: FilterOptions): {
+    readonly type: "filter";
+    readonly options: FilterOptions;
 };
-export declare function sensitiveInfo(options?: SensitiveInfoOptions<never>): {
+/**
+ * Arcjet sensitive information detection rule.
+ *
+ * Applying this rule protects against clients sending you sensitive information
+ * such as personally identifiable information (PII) that you do not wish to
+ * handle.
+ * The rule runs entirely locally so no data ever leaves your environment.
+ *
+ * This rule includes built-in detections for email addresses, credit/debit card
+ * numbers, IP addresses, and phone numbers.
+ * You can also provide a custom detection function to identify additional
+ * sensitive information.
+ *
+ * @param options
+ *   Configuration for the sensitive information detection rule (required).
+ * @returns
+ *   Astro integration Sensitive information rule to provide to the SDK in the `rules` field.
+ */
+export declare function sensitiveInfo(options: SensitiveInfoOptions<never>): {
     readonly type: "sensitiveInfo";
-    readonly options: SensitiveInfoOptions<never> | undefined;
+    readonly options: SensitiveInfoOptions<never>;
 };
-export declare function fixedWindow<Characteristics extends readonly string[]>(options?: FixedWindowRateLimitOptions<Characteristics>): {
+/**
+ * Arcjet fixed window rate limiting rule.
+ *
+ * Applying this rule sets a fixed window rate limit which tracks the number of
+ * requests made by a client over a fixed time window.
+ *
+ * This is the simplest algorithm.
+ * It tracks the number of requests made by a client over a fixed time window
+ * such as 60 seconds.
+ * If the client exceeds the limit, they are blocked until the window expires.
+ *
+ * This algorithm is useful when you want to apply a simple fixed limit in a
+ * fixed time window.
+ * For example, a simple limit on the total number of requests a client can make.
+ * However, it can be susceptible to the stampede problem where a client makes
+ * a burst of requests at the start of a window and then is blocked for the rest
+ * of the window.
+ * The sliding window algorithm can be used to avoid this.
+ *
+ * @template Characteristics
+ *   Characteristics to track a user by.
+ * @param options
+ *   Configuration for the fixed window rate limiting rule (required).
+ * @returns
+ *   Astro integration Fixed window rule to provide to the SDK in the `rules` field.
+ */
+export declare function fixedWindow<Characteristics extends readonly string[]>(options: FixedWindowRateLimitOptions<Characteristics>): {
     readonly type: "fixedWindow";
-    readonly options: FixedWindowRateLimitOptions<Characteristics> | undefined;
+    readonly options: FixedWindowRateLimitOptions<Characteristics>;
 };
-export declare function slidingWindow<Characteristics extends readonly string[]>(options?: SlidingWindowRateLimitOptions<Characteristics>): {
+/**
+ * Arcjet sliding window rate limiting rule.
+ *
+ * Applying this rule sets a sliding window rate limit which tracks the number
+ * of requests made by a client over a sliding window so that the window moves
+ * with time.
+ *
+ * This algorithm is useful to avoid the stampede problem of the fixed window.
+ * It provides smoother rate limiting over time and can prevent a client from
+ * making a burst of requests at the start of a window and then being blocked
+ * for the rest of the window.
+ *
+ * @template Characteristics
+ *   Characteristics to track a user by.
+ * @param options
+ *   Configuration for the sliding window rate limiting rule (required).
+ * @returns
+ *   Astro integration Sliding window rule to provide to the SDK in the `rules` field.
+ */
+export declare function slidingWindow<Characteristics extends readonly string[]>(options: SlidingWindowRateLimitOptions<Characteristics>): {
     readonly type: "slidingWindow";
-    readonly options: SlidingWindowRateLimitOptions<Characteristics> | undefined;
+    readonly options: SlidingWindowRateLimitOptions<Characteristics>;
 };
-export declare function tokenBucket<Characteristics extends readonly string[]>(options?: TokenBucketRateLimitOptions<Characteristics>): {
+/**
+ * Arcjet token bucket rate limiting rule.
+ *
+ * Applying this rule sets a token bucket rate limit.
+ *
+ * This algorithm is based on a bucket filled with a specific number of tokens.
+ * Each request withdraws some amount of tokens from the bucket and the bucket
+ * is refilled at a fixed rate.
+ * Once the bucket is empty, the client is blocked until the bucket refills.
+ *
+ * This algorithm is useful when you want to allow clients to make a burst of
+ * requests and then still be able to make requests at a slower rate.
+ *
+ * @template Characteristics
+ *   Characteristics to track a user by.
+ * @param options
+ *   Configuration for the token bucket rate limiting rule (required).
+ * @returns
+ *   Astro integration Token bucket rule to provide to the SDK in the `rules` field.
+ */
+export declare function tokenBucket<Characteristics extends readonly string[]>(options: TokenBucketRateLimitOptions<Characteristics>): {
     readonly type: "tokenBucket";
-    readonly options: TokenBucketRateLimitOptions<Characteristics> | undefined;
+    readonly options: TokenBucketRateLimitOptions<Characteristics>;
 };
-export declare function protectSignup<Characteristics extends readonly string[]>(options?: ProtectSignupOptions<Characteristics>): {
+/**
+ * Arcjet signup form protection rule.
+ *
+ * Applying this rule combines rate limiting, bot protection, and email
+ * validation to protect your signup forms from abuse.
+ * Using this rule will configure the following:
+ *
+ * - Rate limiting - signup forms are a common target for bots. Arcjet’s rate
+ *   limiting helps to prevent bots and other automated or malicious clients
+ *   from submitting your signup form too many times in a short period of time.
+ * - Bot protection - signup forms are usually exclusively used by humans, which
+ *   means that any automated submissions to the form are likely to be
+ *   fraudulent.
+ * - Email validation - email addresses should be validated to ensure the signup
+ *   is coming from a legitimate user with a real email address that can
+ *   actually receive messages.
+ *
+ * @template Characteristics
+ *   Characteristics to track a user by.
+ * @param options
+ *   Configuration for the signup form protection rule.
+ * @returns
+ *   Astro integration Signup form protection rule to provide to the SDK in the `rules` field.
+ */
+export declare function protectSignup<Characteristics extends readonly string[]>(options: ProtectSignupOptions<Characteristics>): {
     readonly type: "protectSignup";
-    readonly options: ProtectSignupOptions<Characteristics> | undefined;
+    readonly options: ProtectSignupOptions<Characteristics>;
 };
+/**
+ * Configuration for {@linkcode createRemoteClient}.
+ */
 export type RemoteClientOptions = {
-    baseUrl?: string;
-    timeout?: number;
+    /**
+     * Base URI for HTTP requests to Decide API (optional).
+     *
+     * Defaults to the environment variable `ARCJET_BASE_URL` (if that value
+     * is known and allowed) and the standard production API otherwise.
+     */
+    baseUrl?: string | undefined;
+    /**
+     * Timeout in milliseconds for the Decide API (optional).
+     *
+     * Defaults to `500` in production and `1000` in development.
+     */
+    timeout?: number | undefined;
 };
-export declare function createRemoteClient({ baseUrl, timeout }: RemoteClientOptions): {
+/**
+ * Create a remote client.
+ *
+ * @param options
+ *   Configuration (optional).
+ * @returns
+ *   Client.
+ */
+export declare function createRemoteClient(options?: RemoteClientOptions | undefined): {
     readonly baseUrl: string | undefined;
     readonly timeout: number | undefined;
 };
-export default function arcjet<Characteristics extends readonly string[]>({ rules, characteristics, client, proxies, }?: ArcjetIntegrationOptions<Characteristics>): AstroIntegration;
+/**
+ * Create a new Astro integration of Arcjet.
+ *
+ * @template Characteristics
+ *   Characteristics to track a user by.
+ * @param options
+ *   Configuration.
+ * @returns
+ *   Astro integration of Arcjet.
+ */
+export default function arcjet<Characteristics extends readonly string[]>(options?: ArcjetIntegrationOptions<Characteristics>): AstroIntegration;
 export {};

package/index.js

@@ -7,107 +7,112 @@ const validateProxies = z.array(z.string());
 const validateCharacteristics = z.array(z.string());
 const validateClientOptions = z
     .object({
-    baseUrl: z.string(),
-    timeout: z.number(),
+    baseUrl: z.string().optional(),
+    timeout: z.number().optional(),
 })
     .strict()
     .optional();
+// TODO: once `arcjet` core has `exactOptionalProperties` we can use
+// `satisfies z.ZodType<ShieldOptions>` and such here.
 const validateShieldOptions = z
     .object({
-    mode: validateMode,
+    mode: validateMode.optional(),
 })
-    .strict()
-    .optional();
-const validateBotOptions = z
-    .union([
+    .strict();
+const validateBotOptions = z.union([
     z
         .object({
-        mode: validateMode,
+        mode: validateMode.optional(),
         allow: z.array(z.string()),
     })
         .strict(),
     z
         .object({
-        mode: validateMode,
+        mode: validateMode.optional(),
         deny: z.array(z.string()),
     })
         .strict(),
-])
-    .optional();
-const validateEmailOptions = z
-    .union([
+]);
+const validateEmailOptions = z.union([
     z
         .object({
-        mode: validateMode,
+        mode: validateMode.optional(),
         allow: z.array(z.string()),
-        requireTopLevelDomain: z.boolean(),
-        allowDomainLiteral: z.boolean(),
+        requireTopLevelDomain: z.boolean().optional(),
+        allowDomainLiteral: z.boolean().optional(),
     })
         .strict(),
     z
         .object({
-        mode: validateMode,
+        mode: validateMode.optional(),
         deny: z.array(z.string()),
-        requireTopLevelDomain: z.boolean(),
-        allowDomainLiteral: z.boolean(),
+        requireTopLevelDomain: z.boolean().optional(),
+        allowDomainLiteral: z.boolean().optional(),
     })
         .strict(),
-])
-    .optional();
-const validateSensitiveInfoOptions = z
-    .union([
+]);
+const validateFilterOptions = z.union([
     z
         .object({
-        mode: validateMode,
+        mode: validateMode.optional(),
         allow: z.array(z.string()),
-        contextWindowSize: z.number(),
     })
         .strict(),
     z
         .object({
-        mode: validateMode,
+        mode: validateMode.optional(),
         deny: z.array(z.string()),
-        contextWindowSize: z.number(),
     })
         .strict(),
-])
-    .optional();
+]);
+const validateSensitiveInfoOptions = z.union([
+    z
+        .object({
+        mode: validateMode.optional(),
+        allow: z.array(z.string()),
+        contextWindowSize: z.number().optional(),
+    })
+        .strict(),
+    z
+        .object({
+        mode: validateMode.optional(),
+        deny: z.array(z.string()),
+        contextWindowSize: z.number().optional(),
+    })
+        .strict(),
+]);
 const validateFixedWindowOptions = z
     .object({
-    mode: validateMode,
-    characteristics: validateCharacteristics,
+    mode: validateMode.optional(),
+    characteristics: validateCharacteristics.optional(),
     window: z.union([z.string(), z.number()]),
     max: z.number(),
 })
-    .strict()
-    .optional();
+    .strict();
 const validateSlidingWindowOptions = z
     .object({
-    mode: validateMode,
-    characteristics: validateCharacteristics,
+    mode: validateMode.optional(),
+    characteristics: validateCharacteristics.optional(),
     interval: z.union([z.string(), z.number()]),
     max: z.number(),
 })
-    .strict()
-    .optional();
+    .strict();
 const validateTokenBucketOptions = z
     .object({
-    mode: validateMode,
-    characteristics: validateCharacteristics,
+    mode: validateMode.optional(),
+    characteristics: validateCharacteristics.optional(),
     refillRate: z.number(),
     interval: z.union([z.string(), z.number()]),
     capacity: z.number(),
 })
-    .strict()
-    .optional();
+    .strict();
 const validateProtectSignupOptions = z
     .object({
     rateLimit: validateSlidingWindowOptions,
     bots: validateBotOptions,
     email: validateEmailOptions,
 })
-    .strict()
-    .optional();
+    .strict();
 function validateAndSerialize(schema, value) {
     const v = schema.parse(value);
     return v ? JSON.stringify(v) : "";
@@ -135,6 +140,13 @@ function integrationRuleToClientRule(rule) {
                 code: `validateEmail(${serializedOpts})`,
             };
         }
+        case "filter": {
+            const serializedOpts = validateAndSerialize(validateFilterOptions, rule.options);
+            return {
+                importName: `filter`,
+                code: `filter(${serializedOpts})`,
+            };
+        }
         case "sensitiveInfo": {
             const serializedOpts = validateAndSerialize(validateSensitiveInfoOptions, rule.options);
             return {
@@ -176,34 +188,270 @@ function integrationRuleToClientRule(rule) {
     }
 }
 // Mirror the rule functions in the SDK but produce serializable rules
+// Note: please keep JSDocs in sync with `arcjet` core.
+/**
+ * Arcjet Shield WAF rule.
+ *
+ * Applying this rule protects your application against common attacks,
+ * including the OWASP Top 10.
+ *
+ * The Arcjet Shield WAF analyzes every request to your application to detect
+ * suspicious activity.
+ * Once a certain suspicion threshold is reached,
+ * subsequent requests from that client are blocked for a period of time.
+ *
+ * @param options
+ *   Configuration for the Shield rule.
+ * @returns
+ *   Astro integration Shield rule to provide to the SDK in the `rules` field.
+ */
 function shield(options) {
     return { type: "shield", options };
 }
+// Note: please keep JSDocs in sync with `arcjet` core.
+/**
+ * Arcjet bot detection rule.
+ *
+ * Applying this rule allows you to manage traffic by automated clients and
+ * bots.
+ *
+ * Bots can be good (such as search engine crawlers or monitoring agents) or bad
+ * (such as scrapers or automated scripts).
+ * Arcjet allows you to configure which bots you want to allow or deny by
+ * specific bot names such as curl, as well as by category such as search
+ * engine bots.
+ *
+ * Bots are detected based on various signals such as the user agent, IP
+ * address, DNS records, and more.
+ *
+ * @param options
+ *   Configuration for the bot rule (required).
+ * @returns
+ *   Astro integration Bot rule to provide to the SDK in the `rules` field.
+ */
 function detectBot(options) {
     return { type: "bot", options };
 }
+// Note: please keep JSDocs in sync with `arcjet` core.
+/**
+ * Arcjet email validation rule.
+ *
+ * Applying this rule allows you to validate and verify an email address.
+ *
+ * The first step of the analysis is to validate the email address syntax.
+ * This runs locally within the SDK and validates the email address is in the
+ * correct format.
+ * If the email syntax is valid, the SDK will pass the email address to the
+ * Arcjet cloud API to verify the email address.
+ * This performs several checks, depending on the rule configuration.
+ *
+ * @param options
+ *   Configuration for the email validation rule (required).
+ * @returns
+ *   Astro integration Email rule to provide to the SDK in the `rules` field.
+ */
 function validateEmail(options) {
     return { type: "email", options };
 }
+// Note: please keep JSDocs in sync with `arcjet` core.
+/**
+ * Arcjet filter rule.
+ *
+ * Applying this rule lets you block requests using Wireshark-like display
+ * filter expressions over HTTP headers, IP addresses, and other request
+ * fields.
+ * You can quickly enforce rules like allow/deny by country, network, or
+ * `user-agent` pattern.
+ *
+ * See the [reference guide](https://docs.arcjet.com/filters/reference) for
+ * more info on the expression language fields, functions, and values.
+ *
+ * @param options
+ *   Configuration (required).
+ * @returns
+ *   Astro integration Filter rule to provide to the SDK in the `rules` field.
+ *
+ * @example
+ *   In this example, the expression matches non-VPN GET requests from the US.
+ *   Requests matching the expression are allowed, all others are denied.
+ *
+ *   ```ts
+ *   filter({
+ *     allow: [
+ *       'http.request.method eq "GET" and ip.src.country eq "US" and not ip.src.vpn',
+ *     ],
+ *     mode: "LIVE",
+ *   })
+ *   ```
+ *
+ * @link https://docs.arcjet.com/filters/reference
+ */
+function filter(options) {
+    return { type: "filter", options };
+}
+// Note: please keep JSDocs in sync with `arcjet` core.
+/**
+ * Arcjet sensitive information detection rule.
+ *
+ * Applying this rule protects against clients sending you sensitive information
+ * such as personally identifiable information (PII) that you do not wish to
+ * handle.
+ * The rule runs entirely locally so no data ever leaves your environment.
+ *
+ * This rule includes built-in detections for email addresses, credit/debit card
+ * numbers, IP addresses, and phone numbers.
+ * You can also provide a custom detection function to identify additional
+ * sensitive information.
+ *
+ * @param options
+ *   Configuration for the sensitive information detection rule (required).
+ * @returns
+ *   Astro integration Sensitive information rule to provide to the SDK in the `rules` field.
+ */
 function sensitiveInfo(options) {
     return { type: "sensitiveInfo", options };
 }
+// Note: please keep JSDocs in sync with `arcjet` core.
+/**
+ * Arcjet fixed window rate limiting rule.
+ *
+ * Applying this rule sets a fixed window rate limit which tracks the number of
+ * requests made by a client over a fixed time window.
+ *
+ * This is the simplest algorithm.
+ * It tracks the number of requests made by a client over a fixed time window
+ * such as 60 seconds.
+ * If the client exceeds the limit, they are blocked until the window expires.
+ *
+ * This algorithm is useful when you want to apply a simple fixed limit in a
+ * fixed time window.
+ * For example, a simple limit on the total number of requests a client can make.
+ * However, it can be susceptible to the stampede problem where a client makes
+ * a burst of requests at the start of a window and then is blocked for the rest
+ * of the window.
+ * The sliding window algorithm can be used to avoid this.
+ *
+ * @template Characteristics
+ *   Characteristics to track a user by.
+ * @param options
+ *   Configuration for the fixed window rate limiting rule (required).
+ * @returns
+ *   Astro integration Fixed window rule to provide to the SDK in the `rules` field.
+ */
 function fixedWindow(options) {
-    return { type: "fixedWindow", options };
+    return {
+        type: "fixedWindow",
+        options,
+    };
 }
+// Note: please keep JSDocs in sync with `arcjet` core.
+/**
+ * Arcjet sliding window rate limiting rule.
+ *
+ * Applying this rule sets a sliding window rate limit which tracks the number
+ * of requests made by a client over a sliding window so that the window moves
+ * with time.
+ *
+ * This algorithm is useful to avoid the stampede problem of the fixed window.
+ * It provides smoother rate limiting over time and can prevent a client from
+ * making a burst of requests at the start of a window and then being blocked
+ * for the rest of the window.
+ *
+ * @template Characteristics
+ *   Characteristics to track a user by.
+ * @param options
+ *   Configuration for the sliding window rate limiting rule (required).
+ * @returns
+ *   Astro integration Sliding window rule to provide to the SDK in the `rules` field.
+ */
 function slidingWindow(options) {
-    return { type: "slidingWindow", options };
+    return {
+        type: "slidingWindow",
+        options,
+    };
 }
+// Note: please keep JSDocs in sync with `arcjet` core.
+/**
+ * Arcjet token bucket rate limiting rule.
+ *
+ * Applying this rule sets a token bucket rate limit.
+ *
+ * This algorithm is based on a bucket filled with a specific number of tokens.
+ * Each request withdraws some amount of tokens from the bucket and the bucket
+ * is refilled at a fixed rate.
+ * Once the bucket is empty, the client is blocked until the bucket refills.
+ *
+ * This algorithm is useful when you want to allow clients to make a burst of
+ * requests and then still be able to make requests at a slower rate.
+ *
+ * @template Characteristics
+ *   Characteristics to track a user by.
+ * @param options
+ *   Configuration for the token bucket rate limiting rule (required).
+ * @returns
+ *   Astro integration Token bucket rule to provide to the SDK in the `rules` field.
+ */
 function tokenBucket(options) {
-    return { type: "tokenBucket", options };
+    return {
+        type: "tokenBucket",
+        options,
+    };
 }
+// Note: please keep JSDocs in sync with `arcjet` core.
+/**
+ * Arcjet signup form protection rule.
+ *
+ * Applying this rule combines rate limiting, bot protection, and email
+ * validation to protect your signup forms from abuse.
+ * Using this rule will configure the following:
+ *
+ * - Rate limiting - signup forms are a common target for bots. Arcjet’s rate
+ *   limiting helps to prevent bots and other automated or malicious clients
+ *   from submitting your signup form too many times in a short period of time.
+ * - Bot protection - signup forms are usually exclusively used by humans, which
+ *   means that any automated submissions to the form are likely to be
+ *   fraudulent.
+ * - Email validation - email addresses should be validated to ensure the signup
+ *   is coming from a legitimate user with a real email address that can
+ *   actually receive messages.
+ *
+ * @template Characteristics
+ *   Characteristics to track a user by.
+ * @param options
+ *   Configuration for the signup form protection rule.
+ * @returns
+ *   Astro integration Signup form protection rule to provide to the SDK in the `rules` field.
+ */
 function protectSignup(options) {
-    return { type: "protectSignup", options };
+    return {
+        type: "protectSignup",
+        options,
+    };
 }
-function createRemoteClient({ baseUrl, timeout }) {
-    return { baseUrl, timeout };
+/**
+ * Create a remote client.
+ *
+ * @param options
+ *   Configuration (optional).
+ * @returns
+ *   Client.
+ */
+function createRemoteClient(options) {
+    const settings = options ?? {};
+    return { baseUrl: settings.baseUrl, timeout: settings.timeout };
 }
-function arcjet({ rules, characteristics, client, proxies, } = { rules: [] }) {
+/**
+ * Create a new Astro integration of Arcjet.
+ *
+ * @template Characteristics
+ *   Characteristics to track a user by.
+ * @param options
+ *   Configuration.
+ * @returns
+ *   Astro integration of Arcjet.
+ */
+function arcjet(options = { rules: [] }) {
+    const { rules, characteristics, client, proxies } = options;
     const arcjetImports = new Set();
     const arcjetRules = [];
     for (const rule of rules) {
@@ -331,6 +579,21 @@ function arcjet({ rules, characteristics, client, proxies, } = { rules: [] }) {
               ${Array.from(arcjetImports).join(",\n")}
             } from "arcjet"
 
+            /**
+             * Instance of the Astro integration of Arcjet.
+             *
+             * Primarily has a \`protect()\` method to make a decision about how a request
+             * should be handled.
+             *
+             * > 👉 **Note**: this is generated by \`@arcjet/astro\` based on how you configure
+             * > Arcjet in your \`astro.config.mjs\` file.
+             * > In that configuration file, you can pass the (serializable) options that apply
+             * > to all requests.
+             * > You can call \`aj.withRule\` *on* this default client to extend its behavior.
+             *
+             * @template Props
+             *   Configuration.
+             */
             const client = createArcjetClient({
               rules: [
                 ${arcjetRules.join(",\n")}
@@ -348,4 +611,4 @@ function arcjet({ rules, characteristics, client, proxies, } = { rules: [] }) {
     };
 }
 
-export { createRemoteClient, arcjet as default, detectBot, fixedWindow, protectSignup, sensitiveInfo, shield, slidingWindow, tokenBucket, validateEmail };
+export { createRemoteClient, arcjet as default, detectBot, filter, fixedWindow, protectSignup, sensitiveInfo, shield, slidingWindow, tokenBucket, validateEmail };

package/internal.d.ts

@@ -10,51 +10,99 @@ type WithoutCustomProps = {
 type PlainObject = {
     [key: string]: unknown;
 };
+/**
+ * Configuration for {@linkcode createRemoteClient}.
+ */
 export type RemoteClientOptions = {
+    /**
+     * Base URI for HTTP requests to Decide API (optional).
+     *
+     * Defaults to the environment variable `ARCJET_BASE_URL` (if that value
+     * is known and allowed) and the standard production API otherwise.
+     */
     baseUrl?: string;
+    /**
+     * Timeout in milliseconds for the Decide API (optional).
+     *
+     * Defaults to `500` in production and `1000` in development.
+     */
     timeout?: number;
 };
+/**
+ * Create a remote client.
+ *
+ * @param options
+ *   Configuration (optional).
+ * @returns
+ *   Client.
+ */
 export declare function createRemoteClient(options?: RemoteClientOptions): import("@arcjet/protocol/client.js").Client;
 /**
- * The options used to configure an {@link ArcjetAstro} client.
+ * Configuration for the Astro integration of Arcjet.
+ *
+ * @template Rules
+ *   List of rules.
+ * @template Characteristics
+ *   Characteristics to track a user by.
  */
 export type ArcjetOptions<Rules extends [...Array<Primitive | Product>], Characteristics extends readonly string[]> = Simplify<CoreOptions<Rules, Characteristics> & {
     /**
-     * One or more IP Address of trusted proxies in front of the application.
-     * These addresses will be excluded when Arcjet detects a public IP address.
+     * IP addresses and CIDR ranges of trusted load balancers and proxies
+     * (optional, example: `["100.100.100.100", "100.100.100.0/24"]`).
      */
     proxies?: Array<string>;
 }>;
 /**
- * The ArcjetAstro client provides a public `protect()` method to
- * make a decision about how an Astro request should be handled.
+ * Instance of the Astro integration of Arcjet.
+ *
+ * Primarily has a `protect()` method to make a decision about how a request
+ * should be handled.
+ *
+ * @template Props
+ *   Configuration.
  */
 export interface ArcjetAstro<Props extends PlainObject> {
     /**
-     * Runs a request through the configured protections. The request is
-     * analyzed and then a decision made on whether to allow, deny, or challenge
-     * the request.
+     * Make a decision about how to handle a request.
      *
-     * @param request - A `Request` provided to the fetch handler.
-     * @param props - Additonal properties required for running rules against a request.
-     * @returns An {@link ArcjetDecision} indicating Arcjet's decision about the request.
+     * This will analyze the request locally where possible and otherwise call
+     * the Arcjet decision API.
+     *
+     * @param ctx
+     *   Additional context for this function call.
+     * @param request
+     *   Details about the {@linkcode ArcjetRequest} that Arcjet needs to make a
+     *   decision.
+     * @returns
+     *   Promise that resolves to an {@linkcode ArcjetDecision} indicating
+     *   Arcjet’s decision about the request.
      */
     protect(request: Request, ...props: Props extends WithoutCustomProps ? [] : [Props]): Promise<ArcjetDecision>;
     /**
-     * Augments the client with another rule. Useful for varying rules based on
-     * criteria in your handler—e.g. different rate limit for logged in users.
+     * Augment the client with another rule.
+     *
+     * Useful for varying rules based on criteria in your handler such as
+     * different rate limit for logged in users.
      *
-     * @param rule The rule to add to this execution.
-     * @returns An augmented {@link ArcjetAstro} client.
+     * @template Rule
+     *   Type of rule.
+     * @param rule
+     *   Rule to add to Arcjet.
+     * @returns
+     *   Arcjet instance augmented with the given rule.
      */
     withRule<Rule extends Primitive | Product>(rule: Rule): ArcjetAstro<Simplify<Props & ExtraProps<Rule>>>;
 }
 /**
- * Create a new {@link ArcjetAstro} client. Always build your initial client
- * outside of a request handler so it persists across requests. If you need to
- * augment a client inside a handler, call the `withRule()` function on the base
- * client.
+ * Create a new Astro integration of Arcjet.
  *
- * @param options - Arcjet configuration options to apply to all requests.
+ * @template Rules
+ *   List of rules.
+ * @template Characteristics
+ *   Characteristics to track a user by.
+ * @param options
+ *   Configuration.
+ * @returns
+ *   Astro integration of Arcjet.
  */
 export declare function createArcjetClient<const Rules extends (Primitive | Product)[], const Characteristics extends readonly string[]>(options: ArcjetOptions<Rules, Characteristics>): ArcjetAstro<Simplify<ExtraProps<Rules> & CharacteristicProps<Characteristics>>>;

package/internal.js

@@ -1,7 +1,7 @@
 import core__default from 'arcjet';
 export * from 'arcjet';
-import findIP, { parseProxy } from '@arcjet/ip';
-import ArcjetHeaders from '@arcjet/headers';
+import findIp, { parseProxy } from '@arcjet/ip';
+import { ArcjetHeaders } from '@arcjet/headers';
 import { baseUrl, isDevelopment, logLevel, platform } from '@arcjet/env';
 import { Logger } from '@arcjet/logger';
 import { createClient } from '@arcjet/protocol/client.js';
@@ -36,17 +36,21 @@ function errorMessage(err) {
     }
     return "Unknown problem";
 }
+/**
+ * Create a remote client.
+ *
+ * @param options
+ *   Configuration (optional).
+ * @returns
+ *   Client.
+ */
 function createRemoteClient(options) {
-    // The base URL for the Arcjet API. Will default to the standard production
-    // API unless environment variable `ARCJET_BASE_URL` is set.
     const url = options?.baseUrl ?? baseUrl(env);
-    // The timeout for the Arcjet API in milliseconds. This is set to a low value
-    // in production so calls fail open.
     const timeout = options?.timeout ?? (isDevelopment(env) ? 1000 : 500);
     // Transport is the HTTP client that the client uses to make requests.
     const transport = createTransport(url);
     const sdkStack = "ASTRO";
-    const sdkVersion = "1.0.0-beta.10";
+    const sdkVersion = "1.0.0-beta.12";
     return createClient({
         transport,
         baseUrl: url,
@@ -56,12 +60,16 @@ function createRemoteClient(options) {
     });
 }
 /**
- * Create a new {@link ArcjetAstro} client. Always build your initial client
- * outside of a request handler so it persists across requests. If you need to
- * augment a client inside a handler, call the `withRule()` function on the base
- * client.
+ * Create a new Astro integration of Arcjet.
  *
- * @param options - Arcjet configuration options to apply to all requests.
+ * @template Rules
+ *   List of rules.
+ * @template Characteristics
+ *   Characteristics to track a user by.
+ * @param options
+ *   Configuration.
+ * @returns
+ *   Astro integration of Arcjet.
  */
 function createArcjetClient(options) {
     const client = options.client ?? createRemoteClient();
@@ -85,7 +93,7 @@ function createArcjetClient(options) {
         // We construct an ArcjetHeaders to normalize over Headers
         const headers = new ArcjetHeaders(request.headers);
         const url = new URL(request.url);
-        let ip = findIP({
+        let ip = findIp({
             ip: clientAddress,
             headers,
         }, { platform: platform(env), proxies });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcjet/astro",
-  "version": "1.0.0-beta.10",
+  "version": "1.0.0-beta.12",
   "description": "Arcjet helps developers protect their Astro sites in just a few lines of code. Bot detection. Rate limiting. Email validation. Attack protection. Data redaction. A developer-first approach to security.",
   "keywords": [
     "analyze",
@@ -47,27 +47,28 @@
     "build": "rollup --config rollup.config.js",
     "lint": "eslint .",
     "prepublishOnly": "npm run build",
-    "test": "npm run build && npm run lint"
+    "test-api": "node --test",
+    "test-coverage": "node --experimental-test-coverage --test",
+    "test": "npm run build && npm run lint && npm run test-coverage"
   },
   "dependencies": {
-    "@arcjet/env": "1.0.0-beta.10",
-    "@arcjet/headers": "1.0.0-beta.10",
-    "@arcjet/ip": "1.0.0-beta.10",
-    "@arcjet/logger": "1.0.0-beta.10",
-    "@arcjet/protocol": "1.0.0-beta.10",
-    "@arcjet/transport": "1.0.0-beta.10",
-    "arcjet": "1.0.0-beta.10"
+    "@arcjet/env": "1.0.0-beta.12",
+    "@arcjet/headers": "1.0.0-beta.12",
+    "@arcjet/ip": "1.0.0-beta.12",
+    "@arcjet/logger": "1.0.0-beta.12",
+    "@arcjet/protocol": "1.0.0-beta.12",
+    "@arcjet/transport": "1.0.0-beta.12",
+    "arcjet": "1.0.0-beta.12"
   },
   "peerDependencies": {
     "astro": "^5.9.3"
   },
   "devDependencies": {
-    "@arcjet/eslint-config": "1.0.0-beta.10",
-    "@arcjet/rollup-config": "1.0.0-beta.10",
-    "@arcjet/tsconfig": "1.0.0-beta.10",
-    "@rollup/wasm-node": "4.46.2",
-    "astro": "5.12.8",
-    "eslint": "9.32.0",
+    "@arcjet/eslint-config": "1.0.0-beta.12",
+    "@arcjet/rollup-config": "1.0.0-beta.12",
+    "@rollup/wasm-node": "4.50.0",
+    "astro": "5.13.5",
+    "eslint": "9.34.0",
     "typescript": "5.9.2"
   },
   "publishConfig": {