@c15t/backend 2.0.0-rc.3 → 2.0.0-rc.5

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.

package/docs/guides/framework-integration.md

@@ -0,0 +1,142 @@
+---
+title: Framework Integration
+description: Mount the c15t consent backend in any JavaScript framework or runtime.
+---
+The c15t backend exposes a single handler with the signature `(request: Request) => Promise<Response>`. This is the standard Fetch API, so it works with any runtime that supports it — Node.js, Bun, Deno, and Cloudflare Workers.
+
+## Bun
+
+```ts title="server.ts"
+import { c15t } from './c15t';
+
+Bun.serve({
+  port: 3001,
+  fetch: c15t.handler,
+});
+```
+
+## Next.js (App Router)
+
+Create a catch-all API route that forwards requests to the handler:
+
+```ts title="src/app/api/c15t/[[...path]]/route.ts"
+import { c15t } from '@/lib/c15t';
+
+const handler = c15t.handler;
+
+export { handler as GET, handler as POST, handler as PUT, handler as PATCH, handler as DELETE };
+```
+
+> ℹ️ **Info:**
+> Use Next.js rewrites to proxy frontend requests through the same domain and avoid ad-blocker issues. See the Next.js Quickstart for the rewrite configuration.
+
+## Hono
+
+```ts title="server.ts"
+import { Hono } from 'hono';
+import { c15t } from './c15t';
+
+const app = new Hono();
+
+app.all('/api/c15t/*', (c) => c15t.handler(c.req.raw));
+
+export default app;
+```
+
+## Express
+
+```ts title="server.ts"
+import express from 'express';
+import { c15t } from './c15t';
+
+const app = express();
+
+app.all('/api/c15t/*', async (req, res) => {
+  const url = `${req.protocol}://${req.get('host')}${req.originalUrl}`;
+  const headers = new Headers();
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (value) headers.set(key, Array.isArray(value) ? value.join(', ') : value);
+  }
+
+  const request = new Request(url, {
+    method: req.method,
+    headers,
+    body: ['GET', 'HEAD'].includes(req.method) ? undefined : req,
+  });
+
+  const response = await c15t.handler(request);
+
+  res.status(response.status);
+  response.headers.forEach((value, key) => res.setHeader(key, value));
+  res.send(await response.text());
+});
+
+app.listen(3001);
+```
+
+## Fastify
+
+```ts title="server.ts"
+import Fastify from 'fastify';
+import { c15t } from './c15t';
+
+const app = Fastify();
+
+app.all('/api/c15t/*', async (req, reply) => {
+  const url = `${req.protocol}://${req.hostname}${req.url}`;
+  const request = new Request(url, {
+    method: req.method,
+    headers: new Headers(req.headers as Record<string, string>),
+    body: ['GET', 'HEAD'].includes(req.method) ? undefined : JSON.stringify(req.body),
+  });
+
+  const response = await c15t.handler(request);
+
+  reply.status(response.status);
+  response.headers.forEach((value, key) => reply.header(key, value));
+  reply.send(await response.text());
+});
+
+app.listen({ port: 3001 });
+```
+
+## Cloudflare Workers
+
+```ts title="worker.ts"
+import { c15t } from './c15t';
+
+export default {
+  async fetch(request: Request, env: Env) {
+    return c15t.handler(request);
+  },
+};
+```
+
+## Deno
+
+```ts title="server.ts"
+import { c15t } from './c15t.ts';
+
+Deno.serve({ port: 3001 }, c15t.handler);
+```
+
+## CORS
+
+The backend automatically handles CORS based on the `trustedOrigins` you configure:
+
+```ts
+c15tInstance({
+  trustedOrigins: [
+    'https://example.com',
+    'https://*.example.com', // wildcard subdomains
+  ],
+  // ...
+});
+```
+
+Features:
+
+* `www` variants are automatically allowed
+* Wildcard subdomain matching with `*`
+* `localhost` is allowed in development
+* Preflight `OPTIONS` requests are handled automatically

package/docs/guides/iab-tcf.md

@@ -0,0 +1,89 @@
+---
+title: IAB TCF Support
+description: Enable IAB Transparency and Consent Framework (TCF) support in your self-hosted backend.
+---
+The c15t backend optionally supports [IAB TCF v2.3](https://iabeurope.eu/transparency-consent-framework/), including Global Vendor List (GVL) management and TC String generation.
+
+## CMP Registration
+
+[consent.io](https://consent.io) is pending validation as an IAB Europe-registered CMP for c15t. Once approved, when using consent.io as your hosted backend, the CMP ID will be automatically provided to clients — no additional configuration needed.
+
+If you self-host and have your own CMP registration with IAB Europe, configure your CMP ID via `iab.cmpId`. This value is returned to clients in the `/init` response so they use the correct CMP identity in TC Strings.
+
+> ℹ️ **Info:**
+> A valid (non-zero) CMP ID is required for IAB TCF compliance. If neither the backend nor the client provides a CMP ID, IAB initialization will fail with an error.
+>
+> ℹ️ **Info:**
+> If you heavily customize or build your own IAB banner or dialog (rather than using the default IABConsentBanner and IABConsentDialog components provided by c15t), you cannot use consent.io's CMP ID. You must register your own CMP with IAB Europe and configure your CMP ID via iab.cmpId.
+
+## Enable IAB
+
+```ts title="c15t.ts"
+import { c15tInstance } from '@c15t/backend';
+
+export const c15t = c15tInstance({
+  // ...
+  iab: {
+    enabled: true,
+    cmpId: 10,                  // your registered CMP ID (consent.io provides this automatically)
+    vendorIds: [755, 52, 69],   // only include vendors you use
+  },
+});
+```
+
+The backend fetches the GVL from `https://gvl.consent.io` by default and caches it. The `/init` endpoint returns the filtered GVL and your CMP ID to the frontend.
+
+## Custom GVL Endpoint
+
+Point to your own GVL mirror:
+
+```ts
+iab: {
+  enabled: true,
+  endpoint: 'https://your-gvl-mirror.com',
+  vendorIds: [755, 52, 69],
+},
+```
+
+## Bundle GVL by Language
+
+Pre-bundle the GVL to avoid runtime fetches:
+
+```ts
+import gvlEn from './gvl/en.json';
+import gvlDe from './gvl/de.json';
+
+iab: {
+  enabled: true,
+  bundled: {
+    en: gvlEn,
+    de: gvlDe,
+  },
+},
+```
+
+> ℹ️ **Info:**
+> Bundling all required GVL translations can significantly increase your deployment size. On serverless environments like Cloudflare Workers — which have strict bundle size limits — this may cause deployments to fail. Consider bundling only the languages you need, or use the GVL endpoint with a cache adapter instead.
+
+## Custom Non-IAB Vendors
+
+Add your own vendors alongside IAB-registered ones:
+
+```ts
+iab: {
+  enabled: true,
+  vendorIds: [755],
+  customVendors: [
+    {
+      id: 'internal-analytics',
+      name: 'Our Analytics Platform',
+      privacyPolicyUrl: 'https://example.com/privacy',
+      purposes: [1, 8],
+    },
+  ],
+},
+```
+
+## TC String
+
+When IAB TCF is enabled, consent records include a `tcString` field — the encoded TC String that can be passed to vendors. The frontend SDKs handle this automatically when using `mode: 'hosted'`.

package/docs/guides/observability.md

@@ -0,0 +1,96 @@
+---
+title: Observability
+description: Add logging, metrics, and tracing to your self-hosted c15t backend.
+---
+The c15t backend supports structured logging and opt-in OpenTelemetry integration for production observability.
+
+## OpenTelemetry
+
+Telemetry is disabled by default. To enable it, pass your own tracer and meter instances:
+
+```ts title="c15t.ts"
+import { c15tInstance } from '@c15t/backend';
+import { trace, metrics } from '@opentelemetry/api';
+
+export const c15t = c15tInstance({
+  // ...
+  telemetry: {
+    enabled: true,
+    tracer: trace.getTracer('consent-api'),
+    meter: metrics.getMeter('consent-api'),
+    defaultAttributes: {
+      'service.name': 'consent-api',
+      environment: 'production',
+    },
+  },
+});
+```
+
+> ℹ️ **Info:**
+> You need to set up your own OpenTelemetry SDK and exporter (e.g. Jaeger, Datadog, Grafana). The c15t backend creates spans and metrics using the instances you provide.
+
+## Metrics
+
+When telemetry is enabled, the following metrics are recorded:
+
+### Business Metrics
+
+|Metric|Type|Description|
+|--|--|--|
+|`consentCreated`|Counter|Consent record created (by type, jurisdiction)|
+|`consentAccepted`|Counter|Consent accepted (by type)|
+|`consentRejected`|Counter|Consent rejected (by type)|
+|`subjectCreated`|Counter|New subject created|
+|`subjectLinked`|Counter|Subject linked to external ID|
+|`initCount`|Counter|`/init` endpoint called|
+
+### HTTP Metrics
+
+|Metric|Type|Description|
+|--|--|--|
+|`httpRequestDuration`|Histogram|Request duration (by method, route, status)|
+|`httpRequestCount`|Counter|Total requests|
+|`httpErrorCount`|Counter|Error responses|
+
+### Database Metrics
+
+|Metric|Type|Description|
+|--|--|--|
+|`dbQueryDuration`|Histogram|Query duration (by operation, entity)|
+|`dbQueryCount`|Counter|Total queries|
+|`dbErrorCount`|Counter|Query errors|
+
+### Cache Metrics
+
+|Metric|Type|Description|
+|--|--|--|
+|`cacheHit`|Counter|Cache hits (by layer)|
+|`cacheMiss`|Counter|Cache misses (by layer)|
+|`cacheLatency`|Histogram|Cache operation latency|
+
+## Tracing
+
+Every request creates a span with:
+
+* HTTP method and route
+* Response status code
+* Tenant ID (if multi-tenant)
+* API key authentication status
+* Geo-location resolution
+
+Child spans are created for database queries and cache operations.
+
+## Logging
+
+Configure the log level:
+
+```ts
+c15tInstance({
+  // ...
+  logger: {
+    level: 'info', // debug, info, warn, error
+  },
+});
+```
+
+Logs are structured (JSON-compatible) and include trace context when telemetry is enabled, making it easy to correlate logs with traces.