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

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.