@c15t/backend 2.0.0-rc.0 → 2.0.0-rc.10

package/dist-types/utils/background.d.ts

@@ -0,0 +1,6 @@
+import type { C15TContext } from '../types';
+/**
+ * Executes non-critical work via configured background runner when available.
+ * Falls back to fire-and-forget local execution.
+ */
+export declare function runInBackground(ctx: C15TContext, task: () => Promise<void>): void;

package/{dist → dist-types}/utils/create-telemetry-options.d.ts

@@ -1,6 +1,6 @@
 import { type Meter, type Span } from '@opentelemetry/api';
 import type { C15TOptions } from '../types';
-type TelemetryConfig = NonNullable<C15TOptions['advanced']>['telemetry'];
+type TelemetryConfig = C15TOptions['telemetry'];
 /**
  * Creates telemetry configuration from provided options
  *
@@ -68,4 +68,3 @@ export declare function getTraceContext(): {
  */
 export declare const withSpanContext: <T>(span: Span, operation: () => Promise<T>) => Promise<T>;
 export {};
-//# sourceMappingURL=create-telemetry-options.d.ts.map

package/{dist → dist-types}/utils/env.d.ts

@@ -57,4 +57,3 @@ export declare const nodeENV: string;
  * ```
  */
 export declare const isTest: boolean;
-//# sourceMappingURL=env.d.ts.map

package/{dist → dist-types}/utils/extract-error-message.d.ts

@@ -6,4 +6,3 @@
  * real messages.
  */
 export declare function extractErrorMessage(error: unknown): string;
-//# sourceMappingURL=extract-error-message.d.ts.map

package/{dist → dist-types}/utils/instrumentation.d.ts

@@ -3,8 +3,8 @@ import type { C15TOptions } from '../types';
  * Span attributes for database operations
  */
 export interface DatabaseSpanAttributes {
-    /** The database operation type (find, create, update, delete) */
-    operation: 'find' | 'create' | 'update' | 'delete' | 'findOrCreate';
+    /** The database operation type */
+    operation: 'find' | 'create' | 'update' | 'delete' | 'findOrCreate' | 'findLatest' | 'findByHash' | 'syncCurrent' | 'findOrCreateLegalDocument';
     /** The entity type being operated on */
     entity: string;
     /** Optional additional attributes */
@@ -67,4 +67,3 @@ export declare function withExternalSpan<T>(attributes: ExternalSpanAttributes,
  * @returns The result of the operation
  */
 export declare function withCacheSpan<T>(operation: 'get' | 'set' | 'delete', layer: 'bundled' | 'memory' | 'external', fn: () => Promise<T>, options?: C15TOptions): Promise<T>;
-//# sourceMappingURL=instrumentation.d.ts.map

package/{dist → dist-types}/utils/logger.d.ts

@@ -13,4 +13,3 @@ export declare function getLogger(options?: LoggerOptions): ReturnType<typeof cr
  * @returns The initialized global logger instance
  */
 export declare function initLogger(options: LoggerOptions): ReturnType<typeof createLogger>;
-//# sourceMappingURL=logger.d.ts.map

package/{dist → dist-types}/utils/metrics.d.ts

@@ -130,4 +130,3 @@ export declare function getMetrics(options?: C15TOptions): C15TMetrics | null;
  * Reset the metrics instance (useful for testing)
  */
 export declare function resetMetrics(): void;
-//# sourceMappingURL=metrics.d.ts.map

package/dist-types/version.d.ts

@@ -0,0 +1 @@
+export declare const version = "2.0.0-rc.10";

package/docs/README.md

@@ -0,0 +1,49 @@
+# c15t Backend Docs
+
+Self-hosted c15t backend docs for configuration, policy packs, APIs, and operational behavior.
+
+If you are changing consent flows, consent UI, script loading, server-side setup, or backend configuration in an app that uses this package, start here before editing code.
+
+## Start Here
+
+- [Quickstart](./quickstart.md)
+- [Database Setup](./guides/database-setup.md)
+- [Policy Packs](./guides/policy-packs.md)
+- [Configuration](./api/configuration.md)
+
+## Workflow Rules
+
+### Database & Initial Setup
+
+Use this when:
+- configuring a self-hosted backend
+- choosing adapters or initial backend wiring
+
+Prefer:
+- Start with the documented database setup guide.
+- Prefer the documented adapter and setup path before custom backend wiring.
+
+If that is not enough:
+- Use the API reference when you need exact option-level behavior.
+
+Read next:
+- [Quickstart](./quickstart.md)
+- [Database Setup](./guides/database-setup.md)
+- [Configuration](./api/configuration.md)
+
+### Policy Packs & Regional Behavior
+
+Use this when:
+- configuring region-aware consent behavior
+- deciding whether logic belongs in backend policy config or frontend code
+
+Prefer:
+- Prefer policy-pack and documented backend configuration over frontend-only regional logic.
+- Keep consent behavior centralized in backend policy configuration where possible.
+
+Avoid:
+- Do not scatter policy decisions across client code when the backend can own them.
+
+Read next:
+- [Policy Packs](./guides/policy-packs.md)
+- [Configuration](./api/configuration.md)

package/docs/api/configuration.md

@@ -0,0 +1,208 @@
+---
+title: Configuration Reference
+description: Complete reference for all c15t backend configuration options.
+---
+All options are passed to `c15tInstance()`. Only `adapter` and `trustedOrigins` are required.
+
+## Options
+
+### C15TOptions
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|adapter|[FumaDBAdapter](https://v2.c15t.com/docs/self-host/guides/database-setup)|The database adapter to use.|-|✅ Required|
+|tenantId|string \|undefined|Tenant ID for multi-tenant deployments. When set, all database queries are automatically scoped to this tenant.|-|Optional|
+|tablePrefix|[string \|undefined](https://v2.c15t.com/docs/self-host/guides/database-setup)|Optional prefix for all database table names. Useful when sharing a database with other applications to avoid naming conflicts.|-|Optional|
+|appName|[string \|undefined](https://v2.c15t.com/docs/self-host/api/configuration)|Application name used as backend metadata and identity. Returned by \`/init\` (\`appName\`), used in logs, telemetry defaults (\`service.name\`), and cache key prefixing.|"c15t"|Optional|
+|basePath|[string \|undefined](https://v2.c15t.com/docs/self-host/api/endpoints)|Base path prefix for all API routes (e.g. \`/api/self-host\`).|-|Optional|
+|trustedOrigins|[string\[\]](https://v2.c15t.com/docs/self-host/api/configuration)|Allowed origins for CORS. Required for browser-based consent collection. Protocol is optional; matching is protocol-agnostic and normalized.|-|✅ Required|
+|logger|LoggerOptions \|undefined|Logger configuration.|-|Optional|
+|disableGeoLocation|boolean \|undefined|Disables the use of Geo Location to determine the jurisdiction. When enabled, the jurisdiction will be set to "GDPR" to show the strictest version of the banner as we don't know the jurisdiction in this case.|false|Optional|
+|customTranslations|Record\<string, Partial\<Translations>> \|undefined|Override base translations.|-|Optional|
+|i18n|I18nOptions \|undefined|Internationalization message profiles used by runtime policies.|-|Optional|
+|policyPacks|[PolicyConfig \|undefined](https://v2.c15t.com/docs/self-host/guides/policy-packs)|Runtime regional policy pack resolved per request.|-|Optional|
+|branding|"c15t" \|"consent" \|"none" \|"inth" \|undefined|Select which branding to show in the consent banner. Use "inth" for the INTH brand. "consent" is a deprecated alias for "inth". Use "none" to hide branding.|"c15t"|Optional|
+|openapi|[OpenAPIOptions \|undefined](https://v2.c15t.com/docs/self-host/api/endpoints)|OpenAPI spec generation and documentation UI options.|-|Optional|
+|telemetry|[TelemetryOptions \|undefined](https://v2.c15t.com/docs/self-host/guides/observability)|OpenTelemetry configuration for tracing and metrics. Telemetry is opt-in and disabled by default. Users must provide their own SDK setup (Node, Bun, edge, etc.).|-|Optional|
+|ipAddress|[IPAddressOptions \|undefined](https://v2.c15t.com/docs/self-host/api/configuration)|IP address tracking and masking options.|-|Optional|
+|cache|[CacheOptions \|undefined](https://v2.c15t.com/docs/self-host/guides/caching)|Cache configuration for external persistent storage. Used for caching GVL and other data.|-|Optional|
+|apiKeys|string\[] \|undefined|API keys for authenticated endpoints. Used for server-side endpoints like GET /subjects.|-|Optional|
+|iab|[IABOptions \|undefined](https://v2.c15t.com/docs/self-host/guides/iab-tcf)|IAB TCF configuration including GVL, CMP registration, and custom vendors. Disabled by default - most users don't need IAB TCF. Set enabled: true to activate IAB support.|-|Optional|
+|policySnapshot|PolicySnapshotOptions \|undefined|Optional signed policy snapshots used to keep /init and /subjects consistent.|-|Optional|
+|legalDocumentSnapshot|LegalDocumentSnapshotOptions \|undefined|Optional signed legal-document snapshots issued by external document renderers.|-|Optional|
+|background|BackgroundOptions \|undefined|Optional background task runner for non-critical side effects.|-|Optional|
+
+#### `adapter` FumaDBAdapter
+
+The database adapter to use.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|name|string|Name of the adapter|-|✅ Required|
+|generateSchema|Object \|undefined|Generate ORM schema based on FumaDB Schema|-|Optional|
+|createMigrationEngine|((this: FumaDBAdapterContext) => Migrator) \|undefined|-|-|Optional|
+
+#### `logger` LoggerOptions
+
+Logger configuration.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|disabled|boolean \|undefined|Whether logging is disabled.|-|Optional|
+|level|"info" \|"warn" \|"error" \|"debug" \|undefined|The minimum log level to publish.|-|Optional|
+|log|((level: LogLevel, message: string, ...args: unknown\[]) => void) \|undefined|Custom log handler function.|-|Optional|
+|appName|string \|undefined|Custom application name to display in log messages.|-|Optional|
+|getTraceContext|(() => TraceContext \|null) \|undefined|Optional callback to get trace context for log correlation.|-|Optional|
+
+#### `i18n` I18nOptions
+
+Internationalization message profiles used by runtime policies.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|messages|I18nMessageProfiles \|undefined|Named translation catalogs grouped by profile.|-|Optional|
+|defaultProfile|string \|undefined|Fallback profile used when a policy does not provide \`messageProfile\`.|-|Optional|
+
+#### `policyPacks` PolicyConfig
+
+Runtime regional policy pack resolved per request.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|id|string|-|-|✅ Required|
+|match|Object \|undefined|-|-|✅ Required|
+|i18n|Object \|undefined|-|-|Optional|
+|consent|Object \|undefined|-|-|Optional|
+|ui|Object \|undefined|-|-|Optional|
+|proof|Object \|undefined|-|-|Optional|
+
+#### `policySnapshot` PolicySnapshotOptions
+
+Optional signed policy snapshots used to keep /init and /subjects consistent.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|signingKey|string|Secret used for signing and verifying policy snapshot tokens.|-|✅ Required|
+|onValidationFailure|"reject" \|"resolve\_current" \|undefined|How writes should behave when snapshot validation fails.|-|Optional|
+|issuer|string \|undefined|JWT issuer claim for snapshot tokens.|-|Optional|
+|audience|string \|undefined|JWT audience claim for snapshot tokens. When omitted, c15t derives a default snapshot audience and scopes it per tenant.|-|Optional|
+|ttlSeconds|number \|undefined|Snapshot token lifetime in seconds.|-|Optional|
+
+#### `legalDocumentSnapshot` LegalDocumentSnapshotOptions
+
+Optional signed legal-document snapshots issued by external document renderers.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|signingKey|string|Secret used for signing and verifying legal-document snapshot tokens.|-|✅ Required|
+|issuer|string \|undefined|JWT issuer claim for legal-document snapshot tokens.|-|Optional|
+|audience|string \|undefined|JWT audience claim for legal-document snapshot tokens. When omitted, c15t derives a default audience and scopes it per tenant.|-|Optional|
+
+#### `background` BackgroundOptions
+
+Optional background task runner for non-critical side effects.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|run|(task: () => Promise\<void>) => void|Executes non-critical tasks after the response path has completed.|-|✅ Required|
+
+### OpenAPIOptions
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|enabled|boolean \|undefined|Enable/disable OpenAPI spec generation|true|Optional|
+|specPath|string \|undefined|Path to serve the OpenAPI JSON spec|"/spec.json"|Optional|
+|docsPath|string \|undefined|Path to serve the API documentation UI|"/docs"|Optional|
+|options|Object \|undefined|OpenAPI specification options|-|Optional|
+|customUiTemplate|string \|undefined|Custom template for rendering the API documentation UI If provided, this will be used instead of the default Scalar UI|-|Optional|
+
+#### `options`
+
+OpenAPI specification options
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|info|Object \|undefined|-|-|Optional|
+|servers|Array\<Object> \|undefined|-|-|Optional|
+|security|Record\<string, string\[]>\[] \|undefined|-|-|Optional|
+
+### TelemetryOptions
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|enabled|boolean \|undefined|Enable telemetry (tracing and metrics). Must be explicitly set to true to activate.|false|Optional|
+|tracer|Tracer \|undefined|User-provided tracer instance. Users should set up their own OpenTelemetry SDK and pass the tracer here.|-|Optional|
+|meter|Meter \|undefined|User-provided meter instance for metrics. Users should set up their own OpenTelemetry SDK and pass the meter here.|-|Optional|
+|defaultAttributes|Record\<string, string \|number \|boolean> \|undefined|Default attributes to include on all spans and metrics.|-|Optional|
+
+### IPAddressOptions
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|tracking|boolean \|undefined|Enable/disable IP address tracking. When disabled, all IP addresses will be stored as null.|true|Optional|
+|masking|boolean \|undefined|Enable/disable IP address masking to reduce PII collection.|true|Optional|
+|ipAddressHeaders|string\[] \|undefined|Override the default IP address headers used to extract client IP. Headers are checked in order, first match wins.|-|Optional|
+
+### CacheOptions
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|adapter|CacheAdapter \|undefined|External cache adapter (Redis, KV, etc.). If not provided, only in-memory cache is used.|-|Optional|
+
+### IABOptions
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|enabled|true|Enable IAB TCF support. When false or not provided, /init does not include IAB payload fields. When true, /init includes IAB payload only when IAB is active for the resolved request policy (or when no policies are configured).|-|✅ Required|
+|cmpId|number \|undefined|CMP ID registered with IAB Europe. This is returned to clients via the /init endpoint so they can use the correct CMP identity in TC Strings. See List of registered CMPs: https\://iabeurope.eu/cmp-list/|-|Optional|
+|bundled|Object \|undefined \|null|Bundled GVL translations by language code. These are checked first before any cache or fetch.|-|Optional|
+|vendorIds|number\[] \|undefined|Vendor IDs to filter when fetching non-bundled languages. Reduces payload size.|-|Optional|
+|endpoint|string \|undefined|Override the default GVL endpoint.|'https\://gvl.consent.io'|Optional|
+|customVendors|Array\<Object> \|undefined|Custom vendors not registered with IAB. These are synced to the frontend via the /init endpoint.|-|Optional|
+
+## Return Value
+
+`c15tInstance()` returns:
+
+```ts
+interface C15TInstance {
+  /** Standard Fetch API handler */
+  handler: (request: Request) => Promise<Response>;
+
+  /** Resolved configuration */
+  options: C15TOptions;
+
+  /** Internal context (database, registry, logger) */
+  $context: C15TContext;
+
+  /** OpenAPI spec as JSON */
+  getOpenAPISpec: () => Promise<Record<string, unknown>>;
+
+  /** OpenAPI docs UI as HTML string */
+  getDocsUI: () => string;
+}
+```
+
+## Edge Init Options
+
+`unstable_c15tEdgeInit()` from `@c15t/backend/edge` accepts a subset of `C15TOptions` — only the fields needed for consent policy resolution without a database. This edge runtime API is unstable in `2.0`. See the [Edge Deployment guide](/docs/self-host/guides/edge-deployment) for usage.
+
+### C15TEdgeOptions
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|C15TEdgeOptions|C15TEdgeOptions|Type alias for C15TEdgeOptions|-|✅ Required|
+
+## defineConfig Helper
+
+For type-safe configuration in a separate file:
+
+```ts title="c15t.config.ts"
+import { defineConfig } from '@c15t/backend';
+
+export default defineConfig({
+  adapter: kyselyAdapter(db),
+  trustedOrigins: ['https://example.com'],
+  // full autocomplete on all options here
+});
+```

package/docs/api/endpoints.md

@@ -0,0 +1,211 @@
+---
+title: API Endpoints
+description: Full reference for every c15t consent backend endpoint.
+---
+All endpoints are relative to your configured `basePath` (e.g. `/api/c15t`).
+
+> ℹ️ **Info:**
+> The backend auto-generates interactive API docs at \{basePath}/docs using your OpenAPI spec. Visit this URL in a browser to explore endpoints with a visual UI.
+
+## GET /init
+
+Returns the initial consent state for a client. This is the first call made by the frontend SDKs.
+
+**Response:**
+
+```json
+{
+  "jurisdiction": "GDPR",
+  "location": {
+    "countryCode": "DE",
+    "regionCode": "BY"
+  },
+  "translations": {
+    "language": "de",
+    "translations": { "...": "..." }
+  },
+  "branding": "c15t",
+  "gvl": null
+}
+```
+
+|Field|Description|
+|--|--|
+|`jurisdiction`|Detected regulation (`GDPR`, `UK_GDPR`, `CCPA`, etc.)|
+|`location`|Geo-location from IP address|
+|`translations`|Server-side translations based on `Accept-Language`|
+|`branding`|Branding configuration|
+|`gvl`|Global Vendor List (if IAB TCF is enabled)|
+
+## GET /status
+
+Health check endpoint. Returns server version and client info.
+
+**Response:**
+
+```json
+{
+  "version": "1.8.0",
+  "timestamp": "2026-02-11T12:00:00.000Z",
+  "client": {
+    "ip": "192.168.1.0",
+    "acceptLanguage": "en-US",
+    "userAgent": "Mozilla/5.0 ...",
+    "region": { "countryCode": "US", "regionCode": "CA" }
+  }
+}
+```
+
+## POST /subjects
+
+Records a consent event. This is an append-only operation — every call creates a new consent record.
+
+**Request:**
+
+```json
+{
+  "type": "cookie_banner",
+  "subjectId": "sub_abc123",
+  "domain": "example.com",
+  "preferences": {
+    "necessary": true,
+    "measurement": true,
+    "marketing": false
+  },
+  "givenAt": 1707648000000,
+  "metadata": {}
+}
+```
+
+|Field|Type|Required|Description|
+|--|--|--|--|
+|`type`|string|Yes|`cookie_banner`, `privacy_policy`, `dpa`, `terms_and_conditions`, `marketing_communications`, `age_verification`, `other`|
+|`subjectId`|string|Yes|Client-generated subject identifier|
+|`domain`|string|Yes|Domain where consent was given|
+|`preferences`|object|No|Consent category preferences (for `cookie_banner` type)|
+|`givenAt`|number|Yes|Epoch timestamp|
+|`policyId`|string|No|Associated policy ID|
+|`metadata`|object|No|Arbitrary metadata|
+|`externalSubjectId`|string|No|External user ID for cross-device linking|
+|`identityProvider`|string|No|Identity provider name|
+
+**Response:**
+
+```json
+{
+  "subject": { "id": "sub_abc123", "...": "..." },
+  "consent": { "id": "con_xyz789", "type": "cookie_banner", "...": "..." }
+}
+```
+
+## GET /subjects/:id
+
+Retrieves consent status for a subject.
+
+**Query Parameters:**
+
+|Parameter|Description|
+|--|--|
+|`type`|Comma-separated consent types to filter (e.g. `cookie_banner,privacy_policy`)|
+
+**Response:**
+
+```json
+{
+  "subject": { "id": "sub_abc123" },
+  "consents": [
+    {
+      "id": "con_xyz789",
+      "type": "cookie_banner",
+      "givenAt": "2026-02-11T12:00:00.000Z",
+      "jurisdiction": "GDPR",
+      "preferences": { "necessary": true, "measurement": true }
+    }
+  ],
+  "isValid": true
+}
+```
+
+## PATCH /subjects/:id
+
+Links a subject to an external user ID for cross-device consent resolution.
+
+**Request:**
+
+```json
+{
+  "externalId": "user_12345",
+  "identityProvider": "auth0"
+}
+```
+
+**Response:**
+
+```json
+{
+  "subject": {
+    "id": "sub_abc123",
+    "externalId": "user_12345",
+    "identityProvider": "auth0"
+  }
+}
+```
+
+## GET /consents/check
+
+Check consent status by external ID — useful for cross-device consent resolution.
+
+**Query Parameters:**
+
+|Parameter|Description|
+|--|--|
+|`externalId`|The external user ID to look up|
+|`type`|Comma-separated consent types|
+
+**Response:**
+
+```json
+{
+  "found": true,
+  "consents": [
+    { "id": "con_xyz789", "type": "cookie_banner", "...": "..." }
+  ]
+}
+```
+
+## GET /subjects (Authenticated)
+
+List subjects by external ID. Requires an API key.
+
+**Headers:**
+
+```
+Authorization: Bearer sk_live_abc123
+```
+
+**Query Parameters:**
+
+|Parameter|Description|
+|--|--|
+|`externalId`|The external user ID to search|
+
+**Response:**
+
+```json
+{
+  "subjects": [
+    { "id": "sub_abc123", "externalId": "user_12345" }
+  ]
+}
+```
+
+> ℹ️ **Info:**
+> This endpoint requires API key authentication. Configure API keys in the apiKeys option. The key is passed via the Authorization: Bearer header using timing-safe comparison.
+
+## GET /spec.json
+
+Returns the OpenAPI 3.1 specification for the consent API.
+
+## GET /docs
+
+Serves the interactive API documentation UI (Scalar).

package/docs/guides/caching.md

@@ -0,0 +1,85 @@
+---
+title: Caching
+description: Add a caching layer to your self-hosted c15t backend for production performance.
+---
+The backend includes a caching layer for frequently accessed data like GVL (Global Vendor List) lookups and custom server-side translations. By default, an in-memory cache is used — suitable for single-instance deployments. For production with multiple instances, plug in Redis or Cloudflare KV so all instances share the same cache.
+
+## In-Memory (Default)
+
+No configuration needed. The default memory cache has a 5-minute TTL and is suitable for development and single-instance deployments.
+
+## Upstash Redis
+
+```ts title="c15t.ts"
+import { c15tInstance } from '@c15t/backend';
+import { createUpstashRedisAdapter } from '@c15t/backend/cache';
+
+export const c15t = c15tInstance({
+  // ...
+  cache: {
+    adapter: createUpstashRedisAdapter({
+      url: process.env.UPSTASH_REDIS_REST_URL,
+      token: process.env.UPSTASH_REDIS_REST_TOKEN,
+    }),
+  },
+});
+```
+
+If you already have an Upstash Redis client, pass it directly:
+
+```ts
+import { createUpstashRedisAdapterFromClient } from '@c15t/backend/cache';
+import { Redis } from '@upstash/redis';
+
+const redis = new Redis({
+  url: process.env.UPSTASH_REDIS_REST_URL,
+  token: process.env.UPSTASH_REDIS_REST_TOKEN,
+});
+
+const adapter = createUpstashRedisAdapterFromClient(redis);
+```
+
+## Cloudflare KV
+
+For Cloudflare Workers deployments:
+
+```ts title="worker.ts"
+import { c15tInstance } from '@c15t/backend';
+import { createCloudflareKVAdapter } from '@c15t/backend/cache';
+
+export default {
+  async fetch(request: Request, env: Env) {
+    const c15t = c15tInstance({
+      // ...
+      cache: {
+        adapter: createCloudflareKVAdapter(env.GVL_CACHE),
+      },
+    });
+
+    return c15t.handler(request);
+  },
+};
+```
+
+## Custom Cache Adapter
+
+Implement the `CacheAdapter` interface to use any cache backend:
+
+```ts
+import type { CacheAdapter } from '@c15t/backend/cache';
+
+const customCache: CacheAdapter = {
+  async get<T>(key: string): Promise<T | null> {
+    // retrieve from your cache
+  },
+  async set<T>(key: string, value: T, ttlMs?: number): Promise<void> {
+    // store in your cache
+  },
+  async delete(key: string): Promise<void> {
+    // remove from cache
+  },
+  async has(key: string): Promise<boolean> {
+    // check existence
+  },
+};
+```