@rayselfs/cf-rule-engine 1.9.0 → 1.9.1

package/dist/adapters/viewer-request-async.d.cts

@@ -1,5 +1,28 @@
 import { Rule } from '../core/types.cjs';
 
+/**
+ * Creates a CloudFront Function viewer-request handler where rules are resolved
+ * asynchronously before each request — for example, loading redirect maps or
+ * CIDR lists from CloudFront KeyValueStore at startup.
+ *
+ * The `setup` function receives the raw CF event and returns a `Rule[]`. It is
+ * called once per invocation, so any async initialization (e.g. KVS reads)
+ * should be cached outside the handler when possible.
+ *
+ * @param setup - Async factory that receives the CF event and returns the ordered rule list.
+ * @returns An async CloudFront Function handler `async (event) => request | response`.
+ *
+ * @example
+ * ```ts
+ * import { rule } from '@rayselfs/cf-rule-engine'
+ * import { kvsRedirect } from '@rayselfs/cf-rule-engine/behaviors/kvs'
+ * import { defineViewerRequestAsync } from '@rayselfs/cf-rule-engine/adapters/viewer-request'
+ *
+ * export default defineViewerRequestAsync(async () => [
+ *   await kvsRedirect(handle, 'redirects'),
+ * ])
+ * ```
+ */
 declare function defineViewerRequestAsync(setup: (event: unknown) => Promise<Rule[]>): (event: unknown) => Promise<unknown>;
 
 export { defineViewerRequestAsync };

package/dist/adapters/viewer-request-async.d.ts

@@ -1,5 +1,28 @@
 import { Rule } from '../core/types.js';
 
+/**
+ * Creates a CloudFront Function viewer-request handler where rules are resolved
+ * asynchronously before each request — for example, loading redirect maps or
+ * CIDR lists from CloudFront KeyValueStore at startup.
+ *
+ * The `setup` function receives the raw CF event and returns a `Rule[]`. It is
+ * called once per invocation, so any async initialization (e.g. KVS reads)
+ * should be cached outside the handler when possible.
+ *
+ * @param setup - Async factory that receives the CF event and returns the ordered rule list.
+ * @returns An async CloudFront Function handler `async (event) => request | response`.
+ *
+ * @example
+ * ```ts
+ * import { rule } from '@rayselfs/cf-rule-engine'
+ * import { kvsRedirect } from '@rayselfs/cf-rule-engine/behaviors/kvs'
+ * import { defineViewerRequestAsync } from '@rayselfs/cf-rule-engine/adapters/viewer-request'
+ *
+ * export default defineViewerRequestAsync(async () => [
+ *   await kvsRedirect(handle, 'redirects'),
+ * ])
+ * ```
+ */
 declare function defineViewerRequestAsync(setup: (event: unknown) => Promise<Rule[]>): (event: unknown) => Promise<unknown>;
 
 export { defineViewerRequestAsync };

package/dist/behaviors/construct-response.d.cts

@@ -3,7 +3,7 @@ import { BehaviorFn } from '../core/types.cjs';
 /**
  * Options for constructing a synthetic HTTP response at the edge.
  */
-interface ConstructResponseOptions {
+type ConstructResponseOptions = {
     /**
      * The HTTP status code for the response (e.g. `200`, `403`, `404`).
      */
@@ -24,7 +24,7 @@ interface ConstructResponseOptions {
      * @example `{ 'x-request-id': '123', 'retry-after': '60' }`
      */
     headers?: Record<string, string>;
-}
+};
 /**
  * Constructs and returns a synthetic HTTP response directly from the edge,
  * without forwarding the request to the origin.

package/dist/behaviors/construct-response.d.ts

@@ -3,7 +3,7 @@ import { BehaviorFn } from '../core/types.js';
 /**
  * Options for constructing a synthetic HTTP response at the edge.
  */
-interface ConstructResponseOptions {
+type ConstructResponseOptions = {
     /**
      * The HTTP status code for the response (e.g. `200`, `403`, `404`).
      */
@@ -24,7 +24,7 @@ interface ConstructResponseOptions {
      * @example `{ 'x-request-id': '123', 'retry-after': '60' }`
      */
     headers?: Record<string, string>;
-}
+};
 /**
  * Constructs and returns a synthetic HTTP response directly from the edge,
  * without forwarding the request to the origin.

package/dist/behaviors/image-optimize.d.cts

@@ -5,8 +5,13 @@ import { HttpRequest, BehaviorFn } from '../core/types.cjs';
  *
  * Determines which request headers are injected so the proxy knows where to
  * fetch the source image:
- *   - gateway: injects X-Img-Source-Type=gateway and X-Img-Upstream-Gateway
- *   - s3:      injects X-Img-Source-Type=s3 and X-Img-Source-Bucket
+ *   - `s3`: injects `X-Img-Source-Type: s3` and `X-Img-Source-Bucket`
+ *   - `gateway`: injects `X-Img-Source-Type: gateway` and `X-Img-Upstream-Gateway`
+ *     (proxy treats any non-`s3` value as a gateway fallback)
+ *
+ * **Required for all requests** — the proxy always resolves the upstream source,
+ * even when no optimization params are present (pass-through mode). If origin
+ * headers are missing, the proxy returns an error.
  */
 type ImageOriginConfig = {
     type: 'gateway';
@@ -32,7 +37,7 @@ type ImageOriginResolver = ImageOriginConfig | ((request: HttpRequest) => ImageO
  * the normalized `imwidth`, `f`, and `q` params to drive imgproxy transformation
  * and S3 caching.
  */
-interface ImageOptimizeOptions {
+type ImageOptimizeOptions = {
     /** Ordered list of breakpoint widths (px). Request widths snap to the nearest ceiling breakpoint. */
     breakpoints: number[];
     /** Preferred format priority. Defaults to ['avif', 'webp', 'jpeg']. */
@@ -45,13 +50,13 @@ interface ImageOptimizeOptions {
     imformatParam?: string;
     /**
      * Origin configuration for image-optimize-proxy.
-      * When provided, injects the corresponding X-Img-* request headers so the
-      * proxy knows how to resolve the source image. This removes the need to
-      * configure CloudFront origin custom headers separately in Terraform.
-      *
-      * Accepts either a static config object or a resolver function that receives
-      * the request and returns the appropriate origin (or undefined to skip).
-      */
+     * When provided, injects the corresponding X-Img-* request headers so the
+     * proxy knows how to resolve the source image. This removes the need to
+     * configure CloudFront origin custom headers separately in Terraform.
+     *
+     * Accepts either a static config object or a resolver function that receives
+     * the request and returns the appropriate origin (or undefined to skip).
+     */
     origin?: ImageOriginResolver;
     /**
      * CloudFront origin verification secret.
@@ -59,16 +64,16 @@ interface ImageOptimizeOptions {
      * The proxy validates this header to ensure requests originate from CloudFront.
      */
     originSecret?: string;
-}
+};
 /** Resolved normalized image parameters. */
-interface ResolvedImageParams {
+type ResolvedImageParams = {
     /** Width snapped to nearest ceiling breakpoint. */
     breakpoint: number;
     /** Resolved output format. */
     format: 'avif' | 'webp' | 'jpeg';
     /** Quality value (1-100). */
     quality: number;
-}
+};
 /**
  * Resolves normalized image parameters (breakpoint, format, quality) from a request.
  *
@@ -101,6 +106,12 @@ declare function resolveImageParams(request: Pick<HttpRequest, 'querystring' | '
  *     or X-Img-Source-Bucket headers (eliminates need for Terraform origin custom headers)
  *   - When `originSecret` is set, injects X-Origin-Verify header
  *
+ * ⚠️  **Origin headers are required even for pass-through requests.** The proxy
+ * always resolves the upstream source regardless of whether optimization params
+ * are present. If `origin` is not configured here, set `X-Img-Upstream-Gateway`
+ * or `X-Img-Source-Type` / `X-Img-Source-Bucket` as CloudFront origin custom
+ * headers in Terraform — otherwise the proxy returns an error for every request.
+ *
  * Architecture:
  *   CF Function (viewer-request): imageOptimize — normalize querystring + inject origin headers
  *   image-optimize-proxy (origin): reads imwidth/f/q + X-Img-* headers, calls imgproxy sidecar, caches to S3

package/dist/behaviors/image-optimize.d.ts

@@ -5,8 +5,13 @@ import { HttpRequest, BehaviorFn } from '../core/types.js';
  *
  * Determines which request headers are injected so the proxy knows where to
  * fetch the source image:
- *   - gateway: injects X-Img-Source-Type=gateway and X-Img-Upstream-Gateway
- *   - s3:      injects X-Img-Source-Type=s3 and X-Img-Source-Bucket
+ *   - `s3`: injects `X-Img-Source-Type: s3` and `X-Img-Source-Bucket`
+ *   - `gateway`: injects `X-Img-Source-Type: gateway` and `X-Img-Upstream-Gateway`
+ *     (proxy treats any non-`s3` value as a gateway fallback)
+ *
+ * **Required for all requests** — the proxy always resolves the upstream source,
+ * even when no optimization params are present (pass-through mode). If origin
+ * headers are missing, the proxy returns an error.
  */
 type ImageOriginConfig = {
     type: 'gateway';
@@ -32,7 +37,7 @@ type ImageOriginResolver = ImageOriginConfig | ((request: HttpRequest) => ImageO
  * the normalized `imwidth`, `f`, and `q` params to drive imgproxy transformation
  * and S3 caching.
  */
-interface ImageOptimizeOptions {
+type ImageOptimizeOptions = {
     /** Ordered list of breakpoint widths (px). Request widths snap to the nearest ceiling breakpoint. */
     breakpoints: number[];
     /** Preferred format priority. Defaults to ['avif', 'webp', 'jpeg']. */
@@ -45,13 +50,13 @@ interface ImageOptimizeOptions {
     imformatParam?: string;
     /**
      * Origin configuration for image-optimize-proxy.
-      * When provided, injects the corresponding X-Img-* request headers so the
-      * proxy knows how to resolve the source image. This removes the need to
-      * configure CloudFront origin custom headers separately in Terraform.
-      *
-      * Accepts either a static config object or a resolver function that receives
-      * the request and returns the appropriate origin (or undefined to skip).
-      */
+     * When provided, injects the corresponding X-Img-* request headers so the
+     * proxy knows how to resolve the source image. This removes the need to
+     * configure CloudFront origin custom headers separately in Terraform.
+     *
+     * Accepts either a static config object or a resolver function that receives
+     * the request and returns the appropriate origin (or undefined to skip).
+     */
     origin?: ImageOriginResolver;
     /**
      * CloudFront origin verification secret.
@@ -59,16 +64,16 @@ interface ImageOptimizeOptions {
      * The proxy validates this header to ensure requests originate from CloudFront.
      */
     originSecret?: string;
-}
+};
 /** Resolved normalized image parameters. */
-interface ResolvedImageParams {
+type ResolvedImageParams = {
     /** Width snapped to nearest ceiling breakpoint. */
     breakpoint: number;
     /** Resolved output format. */
     format: 'avif' | 'webp' | 'jpeg';
     /** Quality value (1-100). */
     quality: number;
-}
+};
 /**
  * Resolves normalized image parameters (breakpoint, format, quality) from a request.
  *
@@ -101,6 +106,12 @@ declare function resolveImageParams(request: Pick<HttpRequest, 'querystring' | '
  *     or X-Img-Source-Bucket headers (eliminates need for Terraform origin custom headers)
  *   - When `originSecret` is set, injects X-Origin-Verify header
  *
+ * ⚠️  **Origin headers are required even for pass-through requests.** The proxy
+ * always resolves the upstream source regardless of whether optimization params
+ * are present. If `origin` is not configured here, set `X-Img-Upstream-Gateway`
+ * or `X-Img-Source-Type` / `X-Img-Source-Bucket` as CloudFront origin custom
+ * headers in Terraform — otherwise the proxy returns an error for every request.
+ *
  * Architecture:
  *   CF Function (viewer-request): imageOptimize — normalize querystring + inject origin headers
  *   image-optimize-proxy (origin): reads imwidth/f/q + X-Img-* headers, calls imgproxy sidecar, caches to S3

package/dist/behaviors/index.d.cts

@@ -21,11 +21,11 @@ export { ResponseBehaviorFn, ResponseRule } from '../core/types.cjs';
  * Token format: `exp=<unix>~acl=<path>~hmac=<hex>`
  * The `key` is the hex-encoded HMAC-SHA256 secret (Akamai `verifyTokenAuthorization.key`).
  */
-interface VerifyTokenOptions {
+type VerifyTokenOptions = {
     key: string;
     param?: string;
     failureStatus?: 401 | 403;
-}
+};
 /**
  * Validates an Akamai Edge Auth Token 2.0 (HMAC-SHA256) from the request querystring.
  * Returns 403 on missing / expired / invalid token; continues on success.

package/dist/behaviors/index.d.ts

@@ -21,11 +21,11 @@ export { ResponseBehaviorFn, ResponseRule } from '../core/types.js';
  * Token format: `exp=<unix>~acl=<path>~hmac=<hex>`
  * The `key` is the hex-encoded HMAC-SHA256 secret (Akamai `verifyTokenAuthorization.key`).
  */
-interface VerifyTokenOptions {
+type VerifyTokenOptions = {
     key: string;
     param?: string;
     failureStatus?: 401 | 403;
-}
+};
 /**
  * Validates an Akamai Edge Auth Token 2.0 (HMAC-SHA256) from the request querystring.
  * Returns 403 on missing / expired / invalid token; continues on success.

package/dist/behaviors/kvs.d.cts

@@ -1,6 +1,34 @@
 import { BehaviorFn } from '../core/types.cjs';
 import { KvsHandle } from '../shared/kvs.cjs';
 
+/**
+ * Loads a redirect map from CloudFront KeyValueStore and returns a `BehaviorFn`
+ * that performs 301/302 redirects based on exact URI matches.
+ *
+ * The KVS value at `key` must be a JSON-encoded `Record<string, string>` mapping
+ * source URIs to destination URLs (e.g. `{ "/old": "https://example.com/new" }`).
+ * Requests whose URI does not appear in the map are passed through unchanged.
+ *
+ * Intended for use with `defineViewerRequestAsync` — the KVS read happens once
+ * at setup time and the resulting map is captured in the returned closure.
+ *
+ * @param handle - KVS handle (from `@aws-sdk/cloudfront-keyvaluestore` or equivalent).
+ * @param key - The KVS key whose value is a JSON redirect map.
+ * @param statusCode - HTTP redirect status code. Defaults to `301`.
+ * @returns A `BehaviorFn` to pass to `rule()`.
+ *
+ * @example
+ * ```ts
+ * import { defineViewerRequestAsync } from '@rayselfs/cf-rule-engine/adapters/viewer-request'
+ * import { rule } from '@rayselfs/cf-rule-engine'
+ * import { kvsRedirect } from '@rayselfs/cf-rule-engine/behaviors/kvs'
+ *
+ * export default defineViewerRequestAsync(async (event) => {
+ *   const handle = CloudFront.createKeyValueStore(event)
+ *   return [rule(await kvsRedirect(handle, 'redirects'))]
+ * })
+ * ```
+ */
 declare function kvsRedirect(handle: KvsHandle, key: string, statusCode?: number): Promise<BehaviorFn>;
 
 export { kvsRedirect };

package/dist/behaviors/kvs.d.ts

@@ -1,6 +1,34 @@
 import { BehaviorFn } from '../core/types.js';
 import { KvsHandle } from '../shared/kvs.js';
 
+/**
+ * Loads a redirect map from CloudFront KeyValueStore and returns a `BehaviorFn`
+ * that performs 301/302 redirects based on exact URI matches.
+ *
+ * The KVS value at `key` must be a JSON-encoded `Record<string, string>` mapping
+ * source URIs to destination URLs (e.g. `{ "/old": "https://example.com/new" }`).
+ * Requests whose URI does not appear in the map are passed through unchanged.
+ *
+ * Intended for use with `defineViewerRequestAsync` — the KVS read happens once
+ * at setup time and the resulting map is captured in the returned closure.
+ *
+ * @param handle - KVS handle (from `@aws-sdk/cloudfront-keyvaluestore` or equivalent).
+ * @param key - The KVS key whose value is a JSON redirect map.
+ * @param statusCode - HTTP redirect status code. Defaults to `301`.
+ * @returns A `BehaviorFn` to pass to `rule()`.
+ *
+ * @example
+ * ```ts
+ * import { defineViewerRequestAsync } from '@rayselfs/cf-rule-engine/adapters/viewer-request'
+ * import { rule } from '@rayselfs/cf-rule-engine'
+ * import { kvsRedirect } from '@rayselfs/cf-rule-engine/behaviors/kvs'
+ *
+ * export default defineViewerRequestAsync(async (event) => {
+ *   const handle = CloudFront.createKeyValueStore(event)
+ *   return [rule(await kvsRedirect(handle, 'redirects'))]
+ * })
+ * ```
+ */
 declare function kvsRedirect(handle: KvsHandle, key: string, statusCode?: number): Promise<BehaviorFn>;
 
 export { kvsRedirect };

package/dist/behaviors/redirect.d.cts

@@ -3,14 +3,14 @@ import { BehaviorFn } from '../core/types.cjs';
 /**
  * Options for configuring redirect behavior.
  */
-interface RedirectOptions {
+type RedirectOptions = {
     /**
      * When `true`, the original request's query string is appended to the redirect
      * `location` URL. Useful for preserving search params during path migrations.
      * Default: `false`.
      */
     preserveQuerystring?: boolean;
-}
+};
 /**
  * Redirects the request to the specified URL with the given HTTP status code.
  *

package/dist/behaviors/redirect.d.ts

@@ -3,14 +3,14 @@ import { BehaviorFn } from '../core/types.js';
 /**
  * Options for configuring redirect behavior.
  */
-interface RedirectOptions {
+type RedirectOptions = {
     /**
      * When `true`, the original request's query string is appended to the redirect
      * `location` URL. Useful for preserving search params during path migrations.
      * Default: `false`.
      */
     preserveQuerystring?: boolean;
-}
+};
 /**
  * Redirects the request to the specified URL with the given HTTP status code.
  *

package/dist/behaviors/set-cors-headers.d.cts

@@ -16,14 +16,11 @@ type Origin = `https://${string}` | `http://${string}`;
  * - `ORIGIN_ECHO` (`'echo'`) — echo any request `Origin` if present, skip if none
  */
 type OriginPolicy = OriginWildcard | Origin[] | OriginEcho;
-/**
- * Standard HTTP methods allowed in `Access-Control-Allow-Methods`.
- */
 type Methods = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS' | 'TRACE' | 'CONNECT';
 /**
  * CORS configuration options for `setCorsHeaders` and `preflightRequest`.
  */
-interface CorsOptions {
+type CorsOptions = {
     /**
      * Origin policy. See `OriginPolicy` for details.
      */
@@ -54,7 +51,20 @@ interface CorsOptions {
      * Omit to exclude the header.
      */
     maxAge?: number;
-}
+};
+/**
+ * Sets CORS response headers with configurable origin policy.
+ *
+ * @param options - CORS configuration. `allowedOrigins` is required.
+ * @returns A `ResponseBehaviorFn` to use directly in `defineViewerResponse` or wrapped in a `ResponseRule`.
+ *
+ * @example
+ * ```ts
+ * setCorsHeaders({ allowedOrigins: ORIGIN_WILDCARD })
+ * setCorsHeaders({ allowedOrigins: ['https://*.viverse.com'] })
+ * setCorsHeaders({ allowedOrigins: ORIGIN_ECHO, allowCredentials: true })
+ * ```
+ */
 declare function setCorsHeaders(options: CorsOptions): ResponseBehaviorFn;
 
 export { type CorsOptions, type Methods, ORIGIN_ECHO, ORIGIN_WILDCARD, type Origin, type OriginEcho, type OriginPolicy, type OriginWildcard, setCorsHeaders };

package/dist/behaviors/set-cors-headers.d.ts

@@ -16,14 +16,11 @@ type Origin = `https://${string}` | `http://${string}`;
  * - `ORIGIN_ECHO` (`'echo'`) — echo any request `Origin` if present, skip if none
  */
 type OriginPolicy = OriginWildcard | Origin[] | OriginEcho;
-/**
- * Standard HTTP methods allowed in `Access-Control-Allow-Methods`.
- */
 type Methods = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS' | 'TRACE' | 'CONNECT';
 /**
  * CORS configuration options for `setCorsHeaders` and `preflightRequest`.
  */
-interface CorsOptions {
+type CorsOptions = {
     /**
      * Origin policy. See `OriginPolicy` for details.
      */
@@ -54,7 +51,20 @@ interface CorsOptions {
      * Omit to exclude the header.
      */
     maxAge?: number;
-}
+};
+/**
+ * Sets CORS response headers with configurable origin policy.
+ *
+ * @param options - CORS configuration. `allowedOrigins` is required.
+ * @returns A `ResponseBehaviorFn` to use directly in `defineViewerResponse` or wrapped in a `ResponseRule`.
+ *
+ * @example
+ * ```ts
+ * setCorsHeaders({ allowedOrigins: ORIGIN_WILDCARD })
+ * setCorsHeaders({ allowedOrigins: ['https://*.viverse.com'] })
+ * setCorsHeaders({ allowedOrigins: ORIGIN_ECHO, allowCredentials: true })
+ * ```
+ */
 declare function setCorsHeaders(options: CorsOptions): ResponseBehaviorFn;
 
 export { type CorsOptions, type Methods, ORIGIN_ECHO, ORIGIN_WILDCARD, type Origin, type OriginEcho, type OriginPolicy, type OriginWildcard, setCorsHeaders };

package/dist/behaviors/set-csp.d.cts

@@ -3,7 +3,7 @@ import { ResponseBehaviorFn } from '../core/types.cjs';
 /**
  * Configuration for the `Content-Security-Policy` header.
  */
-interface CspOptions {
+type CspOptions = {
     /**
      * Map of CSP directive names to their values.
      * Each entry becomes one `<directive> <value>` segment in the header,
@@ -16,7 +16,7 @@ interface CspOptions {
      * ```
      */
     directives: Record<string, string>;
-}
+};
 /**
  * Sets the `Content-Security-Policy` response header from a directives map.
  *

package/dist/behaviors/set-csp.d.ts

@@ -3,7 +3,7 @@ import { ResponseBehaviorFn } from '../core/types.js';
 /**
  * Configuration for the `Content-Security-Policy` header.
  */
-interface CspOptions {
+type CspOptions = {
     /**
      * Map of CSP directive names to their values.
      * Each entry becomes one `<directive> <value>` segment in the header,
@@ -16,7 +16,7 @@ interface CspOptions {
      * ```
      */
     directives: Record<string, string>;
-}
+};
 /**
  * Sets the `Content-Security-Policy` response header from a directives map.
  *

package/dist/behaviors/set-security-headers.d.cts

@@ -8,7 +8,7 @@ import { ResponseBehaviorFn } from '../core/types.cjs';
  *
  * Pass at least one field.
  */
-interface SecurityHeadersOptions {
+type SecurityHeadersOptions = {
     /**
      * Value for the `Strict-Transport-Security` header.
      * Example: `'max-age=31536000; includeSubDomains'`
@@ -31,7 +31,7 @@ interface SecurityHeadersOptions {
      * Note: deprecated in modern browsers but still used for legacy compatibility.
      */
     xXssProtection?: string;
-}
+};
 /**
  * Sets security headers on the outgoing response.
  *

package/dist/behaviors/set-security-headers.d.ts

@@ -8,7 +8,7 @@ import { ResponseBehaviorFn } from '../core/types.js';
  *
  * Pass at least one field.
  */
-interface SecurityHeadersOptions {
+type SecurityHeadersOptions = {
     /**
      * Value for the `Strict-Transport-Security` header.
      * Example: `'max-age=31536000; includeSubDomains'`
@@ -31,7 +31,7 @@ interface SecurityHeadersOptions {
      * Note: deprecated in modern browsers but still used for legacy compatibility.
      */
     xXssProtection?: string;
-}
+};
 /**
  * Sets security headers on the outgoing response.
  *

package/dist/core/types.d.cts

@@ -1,5 +1,5 @@
 /** Represents an HTTP request with URI, method, headers, and querystring. */
-interface HttpRequest {
+type HttpRequest = {
     uri: string;
     method: string;
     protocol: string;
@@ -11,16 +11,16 @@ interface HttpRequest {
     }>;
     clientIp: string;
     country?: string;
-}
+};
 /** Represents an HTTP response with status code and headers. */
-interface HttpResponse {
+type HttpResponse = {
     statusCode: number;
     statusDescription?: string;
     headers: Record<string, {
         value: string;
     }>;
     body?: string;
-}
+};
 /** A function that evaluates criteria against a request and returns a boolean. */
 type CriteriaFn = (request: HttpRequest) => boolean;
 /** Result of a behavior function: either continue processing or respond. */
@@ -36,15 +36,15 @@ type BehaviorFn = (request: HttpRequest) => BehaviorResult;
 /** A function that modifies an HTTP response. */
 type ResponseBehaviorFn = (request: HttpRequest, response: HttpResponse) => HttpResponse;
 /** A response rule: an optional criteria guard plus a ResponseBehaviorFn. */
-interface ResponseRule {
+type ResponseRule = {
     criteria?: CriteriaFn;
     behavior: ResponseBehaviorFn;
-}
+};
 /** A rule combining optional criteria and a behavior function. */
-interface Rule {
+type Rule = {
     criteria?: CriteriaFn;
     behavior: BehaviorFn;
-}
+};
 /** Handler for CloudFront viewer request events. */
 type ViewerRequestHandler = (event: unknown) => unknown;
 /** Handler for CloudFront viewer response events. */

package/dist/core/types.d.ts

@@ -1,5 +1,5 @@
 /** Represents an HTTP request with URI, method, headers, and querystring. */
-interface HttpRequest {
+type HttpRequest = {
     uri: string;
     method: string;
     protocol: string;
@@ -11,16 +11,16 @@ interface HttpRequest {
     }>;
     clientIp: string;
     country?: string;
-}
+};
 /** Represents an HTTP response with status code and headers. */
-interface HttpResponse {
+type HttpResponse = {
     statusCode: number;
     statusDescription?: string;
     headers: Record<string, {
         value: string;
     }>;
     body?: string;
-}
+};
 /** A function that evaluates criteria against a request and returns a boolean. */
 type CriteriaFn = (request: HttpRequest) => boolean;
 /** Result of a behavior function: either continue processing or respond. */
@@ -36,15 +36,15 @@ type BehaviorFn = (request: HttpRequest) => BehaviorResult;
 /** A function that modifies an HTTP response. */
 type ResponseBehaviorFn = (request: HttpRequest, response: HttpResponse) => HttpResponse;
 /** A response rule: an optional criteria guard plus a ResponseBehaviorFn. */
-interface ResponseRule {
+type ResponseRule = {
     criteria?: CriteriaFn;
     behavior: ResponseBehaviorFn;
-}
+};
 /** A rule combining optional criteria and a behavior function. */
-interface Rule {
+type Rule = {
     criteria?: CriteriaFn;
     behavior: BehaviorFn;
-}
+};
 /** Handler for CloudFront viewer request events. */
 type ViewerRequestHandler = (event: unknown) => unknown;
 /** Handler for CloudFront viewer response events. */

package/dist/criteria/file-extension.d.cts

@@ -20,11 +20,11 @@ import { CriteriaFn } from '../core/types.cjs';
  *
  * // Apply long-lived cache to static assets
  * rule(fileExtension(['js', 'css', 'woff2', 'woff']),
- *   setCacheControl({ maxAge: 31536000 }))
+ *   setCacheControl('public, max-age=31536000, immutable'))
  *
  * // Apply image optimization for image requests
- * rule(fileExtension(['jpg', 'jpeg', 'png', 'gif', 'webp']),
- *   imageOptimize())
+ * rule(fileExtension(['jpg', 'jpeg', 'png', 'gif']),
+ *   imageOptimize({ breakpoints: [320, 640, 960, 1280, 1920] }))
  * ```
  */
 declare function fileExtension(extensions: string[]): CriteriaFn;

package/dist/criteria/file-extension.d.ts

@@ -20,11 +20,11 @@ import { CriteriaFn } from '../core/types.js';
  *
  * // Apply long-lived cache to static assets
  * rule(fileExtension(['js', 'css', 'woff2', 'woff']),
- *   setCacheControl({ maxAge: 31536000 }))
+ *   setCacheControl('public, max-age=31536000, immutable'))
  *
  * // Apply image optimization for image requests
- * rule(fileExtension(['jpg', 'jpeg', 'png', 'gif', 'webp']),
- *   imageOptimize())
+ * rule(fileExtension(['jpg', 'jpeg', 'png', 'gif']),
+ *   imageOptimize({ breakpoints: [320, 640, 960, 1280, 1920] }))
  * ```
  */
 declare function fileExtension(extensions: string[]): CriteriaFn;

package/dist/criteria/index.cjs

@@ -1,8 +1,5 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
-var _chunkVEEOQ7TScjs = require('../chunk-VEEOQ7TS.cjs');
-
-
 var _chunkG7JGTBTTcjs = require('../chunk-G7JGTBTT.cjs');
 
 
@@ -12,26 +9,29 @@ var _chunkZEFLAOTLcjs = require('../chunk-ZEFLAOTL.cjs');
 var _chunkLVOM5GJ6cjs = require('../chunk-LVOM5GJ6.cjs');
 
 
-var _chunkOTFDML3Kcjs = require('../chunk-OTFDML3K.cjs');
+var _chunk32SMWYAFcjs = require('../chunk-32SMWYAF.cjs');
 
 
-var _chunkOSZWDCTScjs = require('../chunk-OSZWDCTS.cjs');
+var _chunkL7NBJ4JAcjs = require('../chunk-L7NBJ4JA.cjs');
 
 
-var _chunkU54FZCOHcjs = require('../chunk-U54FZCOH.cjs');
+var _chunkJGJW7D2Ncjs = require('../chunk-JGJW7D2N.cjs');
 
 
-var _chunk32SMWYAFcjs = require('../chunk-32SMWYAF.cjs');
+var _chunkMK4QBCD5cjs = require('../chunk-MK4QBCD5.cjs');
+require('../chunk-WZKRNMF2.cjs');
 
 
-var _chunkL7NBJ4JAcjs = require('../chunk-L7NBJ4JA.cjs');
+var _chunkOTFDML3Kcjs = require('../chunk-OTFDML3K.cjs');
 
 
-var _chunkJGJW7D2Ncjs = require('../chunk-JGJW7D2N.cjs');
+var _chunkVEEOQ7TScjs = require('../chunk-VEEOQ7TS.cjs');
 
 
-var _chunkMK4QBCD5cjs = require('../chunk-MK4QBCD5.cjs');
-require('../chunk-WZKRNMF2.cjs');
+var _chunkOSZWDCTScjs = require('../chunk-OSZWDCTS.cjs');
+
+
+var _chunkU54FZCOHcjs = require('../chunk-U54FZCOH.cjs');
 require('../chunk-ULICUDDH.cjs');
 require('../chunk-75ZPJI57.cjs');
 

package/dist/criteria/index.js

@@ -1,6 +1,3 @@
-import {
-  pathEquals
-} from "../chunk-UD456E4I.js";
 import {
   pathPrefix
 } from "../chunk-XLSZ5RB7.js";
@@ -10,15 +7,6 @@ import {
 import {
   userAgentMatches
 } from "../chunk-VQGBRWJK.js";
-import {
-  methodIs
-} from "../chunk-PY3JMRDG.js";
-import {
-  countryIs
-} from "../chunk-5CPBXZ4X.js";
-import {
-  fileExtension
-} from "../chunk-LBJUCJF2.js";
 import {
   headerContains
 } from "../chunk-SRQF5UEJ.js";
@@ -32,6 +20,18 @@ import {
   ipCidr
 } from "../chunk-YHTUV2SA.js";
 import "../chunk-NWRGD3AH.js";
+import {
+  methodIs
+} from "../chunk-PY3JMRDG.js";
+import {
+  pathEquals
+} from "../chunk-UD456E4I.js";
+import {
+  countryIs
+} from "../chunk-5CPBXZ4X.js";
+import {
+  fileExtension
+} from "../chunk-LBJUCJF2.js";
 import "../chunk-EEZ7NUJG.js";
 import "../chunk-MLKGABMK.js";
 export {

package/dist/criteria/kvs.d.cts

@@ -1,6 +1,34 @@
 import { CriteriaFn } from '../core/types.cjs';
 import { KvsHandle } from '../shared/kvs.cjs';
 
+/**
+ * Loads a CIDR allowlist from CloudFront KeyValueStore and returns a `CriteriaFn`
+ * that matches client IPs against the loaded ranges.
+ *
+ * The KVS value at `key` must be a JSON-encoded `string[]` of CIDR ranges
+ * (e.g. `["10.0.0.0/8", "203.0.113.0/24"]`). If the key is absent or the value
+ * is empty, no IPs will match.
+ *
+ * Intended for use with `defineViewerRequestAsync` — the KVS read happens once
+ * at setup time.
+ *
+ * @param handle - KVS handle.
+ * @param key - The KVS key whose value is a JSON CIDR array.
+ * @returns A `CriteriaFn` to pass to `rule()`.
+ *
+ * @example
+ * ```ts
+ * import { defineViewerRequestAsync } from '@rayselfs/cf-rule-engine/adapters/viewer-request'
+ * import { rule, not } from '@rayselfs/cf-rule-engine'
+ * import { kvsIpCidr } from '@rayselfs/cf-rule-engine/criteria/kvs'
+ * import { redirect } from '@rayselfs/cf-rule-engine/behaviors'
+ *
+ * export default defineViewerRequestAsync(async (event) => {
+ *   const handle = CloudFront.createKeyValueStore(event)
+ *   return [rule(not(await kvsIpCidr(handle, 'allowed-cidrs')), redirect(302, 'https://www.example.com'))]
+ * })
+ * ```
+ */
 declare function kvsIpCidr(handle: KvsHandle, key: string): Promise<CriteriaFn>;
 
 export { kvsIpCidr };

package/dist/criteria/kvs.d.ts

@@ -1,6 +1,34 @@
 import { CriteriaFn } from '../core/types.js';
 import { KvsHandle } from '../shared/kvs.js';
 
+/**
+ * Loads a CIDR allowlist from CloudFront KeyValueStore and returns a `CriteriaFn`
+ * that matches client IPs against the loaded ranges.
+ *
+ * The KVS value at `key` must be a JSON-encoded `string[]` of CIDR ranges
+ * (e.g. `["10.0.0.0/8", "203.0.113.0/24"]`). If the key is absent or the value
+ * is empty, no IPs will match.
+ *
+ * Intended for use with `defineViewerRequestAsync` — the KVS read happens once
+ * at setup time.
+ *
+ * @param handle - KVS handle.
+ * @param key - The KVS key whose value is a JSON CIDR array.
+ * @returns A `CriteriaFn` to pass to `rule()`.
+ *
+ * @example
+ * ```ts
+ * import { defineViewerRequestAsync } from '@rayselfs/cf-rule-engine/adapters/viewer-request'
+ * import { rule, not } from '@rayselfs/cf-rule-engine'
+ * import { kvsIpCidr } from '@rayselfs/cf-rule-engine/criteria/kvs'
+ * import { redirect } from '@rayselfs/cf-rule-engine/behaviors'
+ *
+ * export default defineViewerRequestAsync(async (event) => {
+ *   const handle = CloudFront.createKeyValueStore(event)
+ *   return [rule(not(await kvsIpCidr(handle, 'allowed-cidrs')), redirect(302, 'https://www.example.com'))]
+ * })
+ * ```
+ */
 declare function kvsIpCidr(handle: KvsHandle, key: string): Promise<CriteriaFn>;
 
 export { kvsIpCidr };

package/dist/helpers/index.cjs

@@ -9,12 +9,12 @@ var _chunkEMDI676Gcjs = require('../chunk-EMDI676G.cjs');
 var _chunkLSCC62CZcjs = require('../chunk-LSCC62CZ.cjs');
 require('../chunk-ZEFLAOTL.cjs');
 require('../chunk-LVOM5GJ6.cjs');
-require('../chunk-OTFDML3K.cjs');
 
 
 var _chunkL7NBJ4JAcjs = require('../chunk-L7NBJ4JA.cjs');
 require('../chunk-MK4QBCD5.cjs');
 require('../chunk-WZKRNMF2.cjs');
+require('../chunk-OTFDML3K.cjs');
 require('../chunk-IHVOAORH.cjs');
 require('../chunk-ULICUDDH.cjs');
 

package/dist/helpers/index.js

@@ -9,12 +9,12 @@ import {
 } from "../chunk-C32DL3EP.js";
 import "../chunk-Y7TIDVVC.js";
 import "../chunk-VQGBRWJK.js";
-import "../chunk-PY3JMRDG.js";
 import {
   headerEquals
 } from "../chunk-BZQJYOU2.js";
 import "../chunk-YHTUV2SA.js";
 import "../chunk-NWRGD3AH.js";
+import "../chunk-PY3JMRDG.js";
 import "../chunk-H3RK4USR.js";
 import "../chunk-EEZ7NUJG.js";
 import {

package/dist/helpers/whitelist.d.cts

@@ -3,7 +3,7 @@ import { Rule } from '../core/types.cjs';
 /**
  * Configuration options for the IP/User-Agent access whitelist.
  */
-interface WhitelistOptions {
+type WhitelistOptions = {
     /**
      * CIDR ranges to allow (e.g. office IPs, VPN, stage VPCs).
      * At least one of `cidrs` or `userAgents` must be non-empty, otherwise
@@ -32,7 +32,7 @@ interface WhitelistOptions {
      * @example `['/api/health', '/public/*']`
      */
     bypassPaths?: string[];
-}
+};
 /**
  * Creates a `Rule` that restricts access by IP CIDR range and/or User-Agent
  * pattern. Any request that does not match an allowed CIDR or User-Agent

package/dist/helpers/whitelist.d.ts

@@ -3,7 +3,7 @@ import { Rule } from '../core/types.js';
 /**
  * Configuration options for the IP/User-Agent access whitelist.
  */
-interface WhitelistOptions {
+type WhitelistOptions = {
     /**
      * CIDR ranges to allow (e.g. office IPs, VPN, stage VPCs).
      * At least one of `cidrs` or `userAgents` must be non-empty, otherwise
@@ -32,7 +32,7 @@ interface WhitelistOptions {
      * @example `['/api/health', '/public/*']`
      */
     bypassPaths?: string[];
-}
+};
 /**
  * Creates a `Rule` that restricts access by IP CIDR range and/or User-Agent
  * pattern. Any request that does not match an allowed CIDR or User-Agent

package/dist/shared/kvs.d.cts

@@ -1,5 +1,10 @@
-interface KvsHandle {
+/**
+ * Minimal interface for a CloudFront KeyValueStore handle.
+ * Compatible with the handle returned by `CloudFront.createKeyValueStore(event)`
+ * in the CF Function runtime.
+ */
+type KvsHandle = {
     get(key: string): Promise<string | undefined>;
-}
+};
 
 export type { KvsHandle };

package/dist/shared/kvs.d.ts

@@ -1,5 +1,10 @@
-interface KvsHandle {
+/**
+ * Minimal interface for a CloudFront KeyValueStore handle.
+ * Compatible with the handle returned by `CloudFront.createKeyValueStore(event)`
+ * in the CF Function runtime.
+ */
+type KvsHandle = {
     get(key: string): Promise<string | undefined>;
-}
+};
 
 export type { KvsHandle };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rayselfs/cf-rule-engine",
-  "version": "1.9.0",
+  "version": "1.9.1",
   "description": "Composable, tree-shakeable CloudFront Function rules",
   "license": "MIT",
   "sideEffects": false,