@c15t/backend 2.0.0-rc.4 → 2.0.0-rc.6

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
+  },
+};
+```

package/docs/guides/database-setup.md

@@ -0,0 +1,128 @@
+---
+title: Database Setup
+description: Configure a database adapter for your self-hosted c15t backend.
+---
+The c15t backend requires a database to store consent records, subjects, audit logs, and policies. Five adapters are supported — choose the one that matches your existing stack.
+
+## Adapters
+
+### Kysely
+
+```ts title="c15t.ts"
+import { c15tInstance } from '@c15t/backend';
+import { kyselyAdapter } from '@c15t/backend/db/adapters/kysely';
+import { Kysely, PostgresDialect } from 'kysely';
+import { Pool } from 'pg';
+
+const db = new Kysely({
+  dialect: new PostgresDialect({
+    pool: new Pool({ connectionString: process.env.DATABASE_URL }),
+  }),
+});
+
+export const c15t = c15tInstance({
+  adapter: kyselyAdapter(db),
+  trustedOrigins: ['https://example.com'],
+});
+```
+
+### Drizzle
+
+```ts title="c15t.ts"
+import { c15tInstance } from '@c15t/backend';
+import { drizzleAdapter } from '@c15t/backend/db/adapters/drizzle';
+import { drizzle } from 'drizzle-orm/node-postgres';
+
+const db = drizzle(process.env.DATABASE_URL);
+
+export const c15t = c15tInstance({
+  adapter: drizzleAdapter(db),
+  trustedOrigins: ['https://example.com'],
+});
+```
+
+### Prisma
+
+```ts title="c15t.ts"
+import { c15tInstance } from '@c15t/backend';
+import { prismaAdapter } from '@c15t/backend/db/adapters/prisma';
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+
+export const c15t = c15tInstance({
+  adapter: prismaAdapter(prisma),
+  trustedOrigins: ['https://example.com'],
+});
+```
+
+### TypeORM
+
+```ts title="c15t.ts"
+import { c15tInstance } from '@c15t/backend';
+import { typeormAdapter } from '@c15t/backend/db/adapters/typeorm';
+import { DataSource } from 'typeorm';
+
+const dataSource = new DataSource({
+  type: 'postgres',
+  url: process.env.DATABASE_URL,
+});
+
+export const c15t = c15tInstance({
+  adapter: typeormAdapter(dataSource),
+  trustedOrigins: ['https://example.com'],
+});
+```
+
+### MongoDB
+
+```ts title="c15t.ts"
+import { c15tInstance } from '@c15t/backend';
+import { mongoAdapter } from '@c15t/backend/db/adapters/mongo';
+import { MongoClient } from 'mongodb';
+
+const client = new MongoClient(process.env.MONGODB_URI);
+
+export const c15t = c15tInstance({
+  adapter: mongoAdapter(client),
+  trustedOrigins: ['https://example.com'],
+});
+```
+
+## Migrations
+
+To create & update the database you can use the migrator which is included in the CLI:
+
+|Package manager|Command|
+|:--|:--|
+|npm|`npx @c15t/cli@rc`|
+|pnpm|`pnpm dlx @c15t/cli@rc`|
+|yarn|`yarn dlx @c15t/cli@rc`|
+|bun|`bunx @c15t/cli@rc`|
+
+## Table Prefix
+
+If you share a database with other applications, use `tablePrefix` to namespace the c15t tables:
+
+```ts
+c15tInstance({
+  adapter: kyselyAdapter(db),
+  tablePrefix: 'c15t_',
+  trustedOrigins: ['https://example.com'],
+});
+```
+
+This prefixes all table names (e.g. `c15t_subject`, `c15t_consent`, `c15t_audit_log`).
+
+## Schema Overview
+
+The backend creates and manages these tables:
+
+|Table|Purpose|
+|--|--|
+|`subject`|Consent subjects (users/devices). Tracks identification status and external IDs.|
+|`consent`|Append-only consent records. Stores preferences, jurisdiction, IP, and timestamps.|
+|`domain`|Domain/website configuration for multi-domain setups.|
+|`consent_policy`|Versioned consent policies.|
+|`consent_purpose`|Maps consent purposes to categories.|
+|`audit_log`|Immutable log of all consent-related actions.|

package/docs/guides/edge-deployment.md

@@ -0,0 +1,248 @@
+---
+title: Edge Deployment
+description: Run consent policy resolution at the edge for faster initial banner loads.
+---
+The `/init` endpoint determines consent policy from geo headers, resolves translations, and optionally fetches the GVL. None of this requires a database. The `@c15t/backend/edge` export lets you run this logic in edge runtimes (Vercel Middleware, Cloudflare Workers, Deno Deploy) so the consent banner resolves from the nearest PoP instead of round-tripping to your origin.
+
+```
+Standard:  Browser → Origin (single region)  → c15tInstance(/init) → Response
+Edge:      Browser → Edge   (nearest PoP)    → c15tEdgeInit        → Response
+```
+
+## When to use this
+
+* Your origin server is in a single region and users are globally distributed
+* You want the consent banner to appear as fast as possible (edge latency is typically 10-50ms vs 100-300ms to origin)
+* You already use edge middleware for other purposes (auth, redirects, A/B testing)
+
+You do **not** need this if:
+
+* Your origin is already multi-region or on a platform like Cloudflare Workers
+* Consent banner latency is not a concern for your use case
+
+## Setup
+
+### 1. Extract shared config
+
+Keep your policy configuration in a shared file so both the edge handler and origin handler stay in sync:
+
+```ts title="lib/consent-config.ts"
+import type { C15TEdgeOptions } from '@c15t/backend/edge';
+
+export const consentConfig = {
+  trustedOrigins: ['https://myapp.com'],
+  policyPacks: [
+    {
+      id: 'eu_gdpr',
+      match: { countries: ['DE', 'FR', 'IT', 'ES', 'NL', 'PL'] },
+      consent: { model: 'opt-in' },
+      ui: { mode: 'banner' },
+    },
+    {
+      id: 'us_ca',
+      match: { regions: [{ country: 'US', region: 'CA' }] },
+      consent: { model: 'opt-out' },
+      ui: { mode: 'banner' },
+    },
+  ],
+  policySnapshot: {
+    signingKey: process.env.SNAPSHOT_KEY!,
+  },
+} satisfies C15TEdgeOptions;
+```
+
+### 2. Create edge middleware
+
+**Vercel Middleware**
+
+```ts title="middleware.ts"
+import { c15tEdgeInit } from '@c15t/backend/edge';
+import { consentConfig } from './lib/consent-config';
+
+const initHandler = c15tEdgeInit(consentConfig);
+
+export async function middleware(request: Request) {
+  const url = new URL(request.url);
+  if (url.pathname === '/api/c15t/init') {
+    return initHandler(request);
+  }
+}
+
+export const config = {
+  matcher: '/api/c15t/init',
+};
+```
+
+**Cloudflare Workers**
+
+```ts title="worker.ts"
+import { c15tEdgeInit } from '@c15t/backend/edge';
+import { consentConfig } from './lib/consent-config';
+
+const initHandler = c15tEdgeInit(consentConfig);
+
+export default {
+  async fetch(request: Request) {
+    const url = new URL(request.url);
+    if (url.pathname === '/api/c15t/init') {
+      return initHandler(request);
+    }
+    // Forward other requests to origin
+    return fetch(request);
+  },
+};
+```
+
+**Deno Deploy**
+
+```ts title="main.ts"
+import { c15tEdgeInit } from '@c15t/backend/edge';
+import { consentConfig } from './lib/consent-config.ts';
+
+const initHandler = c15tEdgeInit(consentConfig);
+
+Deno.serve(async (request) => {
+  const url = new URL(request.url);
+  if (url.pathname === '/api/c15t/init') {
+    return initHandler(request);
+  }
+  return new Response('Not found', { status: 404 });
+});
+```
+
+### 3. Keep your origin handler unchanged
+
+The origin API route still handles all database-dependent endpoints (`/subjects`, `/consents`, `/status`). The only difference is that `/init` requests no longer reach the origin — they're intercepted at the edge.
+
+```ts title="app/api/c15t/[[...path]]/route.ts"
+import { c15tInstance } from '@c15t/backend';
+import { consentConfig } from '@/lib/consent-config';
+
+const c15t = c15tInstance({
+  adapter: yourDbAdapter,
+  ...consentConfig,
+});
+
+export const { GET, POST } = c15t;
+```
+
+## Configuration
+
+`c15tEdgeInit` accepts `C15TEdgeOptions` — the same fields as `c15tInstance` minus the database-related options (`adapter`, `tablePrefix`, `basePath`, `openapi`, `ipAddress`, `apiKeys`, `background`).
+
+|Option|Required|Description|
+|--|--|--|
+|`trustedOrigins`|Yes|Allowed CORS origins — must match your origin handler|
+|`policyPacks`|No|Regional policy configuration|
+|`policySnapshot`|No|Signing key for policy snapshot tokens|
+|`iab`|No|IAB TCF configuration|
+|`i18n`|No|Translation profiles|
+|`branding`|No|Banner branding (default: `"c15t"`)|
+|`appName`|No|Application name (default: `"c15t"`)|
+|`tenantId`|No|Tenant ID for multi-tenant deployments|
+|`cache`|No|External cache adapter for GVL|
+|`disableGeoLocation`|No|Disable geo-location detection|
+|`telemetry`|No|OpenTelemetry configuration|
+|`logger`|No|Logger configuration|
+
+> ℹ️ **Info:**
+> The edge handler and origin handler must share the same policyPacks, policySnapshot, trustedOrigins, iab, and i18n configuration. If they diverge, /init will return policies that don't match what the database endpoints expect. Use a shared config file as shown above.
+
+## How it works
+
+The edge handler:
+
+1. **Reads geo headers** — Vercel sets `x-vercel-ip-country` and `x-vercel-ip-country-region` automatically. Cloudflare sets `cf-ipcountry`. The handler checks all common provider headers.
+2. **Resolves jurisdiction** — Maps the country/region to a jurisdiction code (GDPR, CCPA, UK\_GDPR, etc.)
+3. **Matches a policy pack** — Finds the first matching policy for the visitor's location
+4. **Resolves translations** — Picks the right language from `Accept-Language` and your i18n config
+5. **Signs a snapshot token** — Creates a JWT proving which policy was served (if `policySnapshot` is configured)
+6. **Handles CORS** — Validates the `Origin` header against `trustedOrigins` and sets appropriate headers
+
+All of this uses the same functions as the full `c15tInstance` — the edge handler is not a reimplementation, it's the same code without the database layer.
+
+## Caching considerations
+
+Edge isolates have short-lived memory. The in-memory GVL cache resets on each cold start. For production:
+
+* **Bundle GVL translations** using `iab.bundled` to avoid fetch latency entirely
+* **Use an external cache** (Upstash Redis, Cloudflare KV) via the `cache.adapter` option to share cached data across isolates — see the [Caching guide](/docs/self-host/guides/caching) for setup
+
+## Custom consent cookie — resolveConsent
+
+> ℹ️ **Info:**
+> Experimental — this API may change in future versions.
+
+If you manage your own consent cookie and just need to know **which categories to load** for a given visitor, use `resolveConsent` instead of `c15tEdgeInit`. It's a lightweight, fully synchronous function that returns the matched policy and default consent state — no translations, GVL, branding, or snapshot tokens.
+
+```ts title="middleware.ts"
+import { resolveConsent } from '@c15t/backend/edge';
+
+const policyPacks = [
+  {
+    id: 'eu_gdpr',
+    match: { countries: ['DE', 'FR', 'IT', 'ES'] },
+    consent: {
+      model: 'opt-in',
+      categories: ['necessary', 'marketing', 'measurement'],
+    },
+    ui: { mode: 'banner' },
+  },
+  {
+    id: 'us_default',
+    match: { isDefault: true },
+    consent: {
+      model: 'opt-out',
+      categories: ['necessary', 'marketing', 'measurement'],
+      gpc: true,
+    },
+    ui: { mode: 'banner' },
+  },
+];
+
+export function middleware(request: Request) {
+  const consent = resolveConsent(request, { policyPacks });
+
+  // consent.model       → "opt-in" | "opt-out" | "none" | "iab"
+  // consent.showBanner  → true
+  // consent.jurisdiction → "GDPR"
+  // consent.gpc         → false
+  // consent.defaults    → {
+  //   necessary:   { granted: true,  required: true  },
+  //   marketing:   { granted: false, required: false },
+  //   measurement: { granted: false, required: false },
+  // }
+
+  // Read your own cookie, merge with consent.defaults,
+  // decide which scripts/tags to load
+}
+```
+
+### Default consent by model
+
+|Model|`necessary`|Other categories|Notes|
+|--|--|--|--|
+|`opt-in`|granted, required|**not granted**|Unless listed in `preselectedCategories`|
+|`opt-out`|granted, required|**granted**|GPC signal can override `marketing`/`measurement` to not granted|
+|`none`|granted, required|**granted**|No banner shown|
+
+### `resolveConsent` vs `c15tEdgeInit`
+
+||`resolveConsent`|`c15tEdgeInit`|
+|--|--|--|
+|**Use case**|Custom consent cookie|Drop-in `/init` replacement|
+|**Sync**|Yes|No (async — signs JWT, fetches GVL)|
+|**Returns**|Policy + default consent state|Full `/init` JSON payload|
+|**CORS**|Not handled (your middleware)|Built-in|
+|**Translations**|Not included|Included|
+|**Snapshot token**|Not included|Included|
+
+## What stays on the origin
+
+Only `/init` moves to the edge. These endpoints still require the origin server:
+
+* `POST /subjects` — creates/updates consent subjects (needs DB)
+* `POST /consents` — records consent decisions (needs DB)
+* `GET /status` — checks current consent status (needs DB)
+
+The edge handler is a single-purpose optimization for the one endpoint that doesn't need persistent storage.