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

package/dist-types/policies/builder.d.ts

@@ -0,0 +1,127 @@
+import type { PolicyConfig, PolicyModel, PolicyScopeMode, PolicyUiMode, PolicyUiSurfaceConfig } from '../types';
+/**
+ * High-level builder input for creating a backend policy config.
+ *
+ * @remarks
+ * This shape is intentionally flatter than {@link PolicyConfig} so backend
+ * configuration stays readable in `c15tInstance({ policyPacks })` setup files.
+ * Use the builder helpers to normalize this input into runtime-ready policy
+ * configs.
+ *
+ * @see {@link https://v2.c15t.com/docs/self-host/guides/policy-packs}
+ * @see {@link https://v2.c15t.com/docs/frameworks/react/concepts/policy-packs}
+ */
+export interface PolicyBuilderInput {
+    id: string;
+    /**
+     * @deprecated Metadata-only label. Not used at runtime, not sent to clients,
+     * and not fingerprinted. Will be removed in a future version.
+     */
+    name?: string;
+    countries?: string[];
+    regions?: Array<{
+        country: string;
+        region: string;
+    }>;
+    isDefault?: boolean;
+    model?: PolicyModel;
+    expiryDays?: number;
+    scopeMode?: PolicyScopeMode;
+    /**
+     * Consent categories scoped by the policy.
+     */
+    categories?: string[];
+    preselectedCategories?: string[];
+    /**
+     * Whether the policy should respect the Global Privacy Control signal.
+     */
+    gpc?: boolean;
+    uiMode?: PolicyUiMode;
+    banner?: PolicyUiSurfaceConfig;
+    dialog?: PolicyUiSurfaceConfig;
+    i18n?: {
+        language?: string;
+        messageProfile?: string;
+    };
+    proof?: {
+        storeIp?: boolean;
+        storeUserAgent?: boolean;
+        storeLanguage?: boolean;
+    };
+}
+/**
+ * Converts a single {@link PolicyBuilderInput} into a normalized
+ * backend-compatible {@link PolicyConfig}.
+ *
+ * @remarks
+ * Empty optional fields are removed from the final output, matcher input is
+ * merged into `match`, and duplicate string arrays are deduplicated.
+ *
+ * @see {@link https://v2.c15t.com/docs/self-host/guides/policy-packs}
+ */
+export declare function buildPolicyConfig(input: PolicyBuilderInput): PolicyConfig;
+/**
+ * Converts an ordered list of builder inputs into a policy pack.
+ *
+ * @remarks
+ * The resulting array preserves input order. That order matters because
+ * duplicate region/country matchers use first-match-wins semantics within the
+ * same matcher type.
+ *
+ * @see {@link https://v2.c15t.com/docs/self-host/guides/policy-packs}
+ */
+export declare function buildPolicyPack(inputs: PolicyBuilderInput[]): PolicyConfig[];
+/**
+ * Creates a policy pack and guarantees that it ends with a default policy.
+ *
+ * @remarks
+ * If the provided inputs already contain a default matcher, the pack is
+ * returned unchanged. Otherwise c15t appends either:
+ *
+ * - the supplied `defaultPolicy`, coerced to `match.isDefault = true`
+ * - or the built-in "World No Banner" fallback
+ *
+ * When `defaultPolicy` is provided, its `countries` and `regions` fields are
+ * stripped and replaced with `match.isDefault = true`.
+ *
+ * @see {@link https://v2.c15t.com/docs/self-host/guides/policy-packs}
+ */
+export declare function buildPolicyPackWithDefault(inputs: PolicyBuilderInput[], defaultPolicy?: PolicyBuilderInput): PolicyConfig[];
+/**
+ * Merges multiple policy packs or individual policies into a single pack.
+ *
+ * @remarks
+ * Useful for combining preset packs with custom policies without manual
+ * spread and deduplication. Policies are deduplicated by `id` — the first
+ * occurrence wins.
+ *
+ * @example
+ * ```ts
+ * import { composePacks, policyPackPresets, policyBuilder } from '@c15t/backend';
+ *
+ * const pack = composePacks(
+ *   [policyPackPresets.europeOptIn()],
+ *   [policyPackPresets.californiaOptOut()],
+ *   [policyBuilder.create({ id: 'custom', countries: ['JP'], model: 'opt-in' })],
+ *   [policyPackPresets.worldNoBanner()],
+ * );
+ * ```
+ *
+ * @see {@link https://v2.c15t.com/docs/self-host/guides/policy-packs}
+ */
+export declare function composePacks(...packs: PolicyConfig[][]): PolicyConfig[];
+/**
+ * Convenience namespace for the policy builder helpers.
+ *
+ * @remarks
+ * Useful when you prefer a grouped API such as `policyBuilder.createPack()`
+ * inside backend config files.
+ *
+ * @see {@link https://v2.c15t.com/docs/self-host/guides/policy-packs}
+ */
+export declare const policyBuilder: {
+    create: typeof buildPolicyConfig;
+    createPack: typeof buildPolicyPack;
+    createPackWithDefault: typeof buildPolicyPackWithDefault;
+    composePacks: typeof composePacks;
+};

package/dist-types/policies/defaults.d.ts

@@ -0,0 +1,2 @@
+export { policyPackPresets } from '../../../schema/dist-types/index.d.ts';
+export type { EuropePolicyMode, PolicyPackPresets } from '../../../schema/dist-types/types';

package/dist-types/policies/matchers.d.ts

@@ -0,0 +1,3 @@
+import type { PolicyMatch } from '../../../schema/dist-types/types';
+export { EEA_COUNTRY_CODES, EU_COUNTRY_CODES, POLICY_MATCH_DATASET_VERSION, policyMatchers, UK_COUNTRY_CODES, } from '../../../schema/dist-types/types';
+export type { PolicyMatch };

package/{dist → dist-types}/router.d.ts

@@ -7,4 +7,3 @@
  * @packageDocumentation
  */
 export { createConsentRoutes, createInitRoute, createStatusRoute, createSubjectRoutes, } from './routes';
-//# sourceMappingURL=router.d.ts.map

package/{dist → dist-types}/routes/consent.d.ts

@@ -13,4 +13,3 @@ export declare const createConsentRoutes: () => Hono<{
         c15tContext: C15TContext;
     };
 }, import("hono/types").BlankSchema, "/">;
-//# sourceMappingURL=consent.d.ts.map

package/{src/routes/index.ts → dist-types/routes/index.d.ts}

@@ -3,7 +3,6 @@
  *
  * @packageDocumentation
  */
-
 export { createConsentRoutes } from './consent';
 export { createInitRoute } from './init';
 export { createStatusRoute } from './status';

package/{dist → dist-types}/routes/init.d.ts

@@ -13,4 +13,3 @@ export declare const createInitRoute: (options: C15TOptions) => Hono<{
         c15tContext: C15TContext;
     };
 }, import("hono/types").BlankSchema, "/">;
-//# sourceMappingURL=init.d.ts.map

package/{dist → dist-types}/routes/status.d.ts

@@ -13,4 +13,3 @@ export declare const createStatusRoute: () => Hono<{
         c15tContext: C15TContext;
     };
 }, import("hono/types").BlankSchema, "/">;
-//# sourceMappingURL=status.d.ts.map

package/{dist → dist-types}/routes/subject.d.ts

@@ -13,4 +13,3 @@ export declare const createSubjectRoutes: () => Hono<{
         c15tContext: C15TContext;
     };
 }, import("hono/types").BlankSchema, "/">;
-//# sourceMappingURL=subject.d.ts.map

package/{dist → dist-types}/types/api.d.ts

@@ -28,4 +28,3 @@ export type ApiPathBase = `/api/c15t`;
  * ```
  */
 export type ApiPath = `${ApiPathBase}` | `${ApiPathBase}/consent` | `${ApiPathBase}/consent/:id` | `${ApiPathBase}/jurisdictions` | `${ApiPathBase}/jurisdictions/:code`;
-//# sourceMappingURL=api.d.ts.map

package/{dist → dist-types}/types/index.d.ts

@@ -1,6 +1,6 @@
-import type { createLogger, LoggerOptions } from '@c15t/logger';
-import { type Branding, type GlobalVendorList, type NonIABVendor } from '@c15t/schema/types';
-import type { Translations } from '@c15t/translations';
+import type { createLogger, LoggerOptions } from '../../../logger/dist-types/index.d.ts';
+import { type Branding, type GlobalVendorList, type NonIABVendor, type PolicyConfig } from '../../../schema/dist-types/types';
+import type { Translations } from '../../../translations/dist-types/index.d.ts';
 import type { Meter, Tracer } from '@opentelemetry/api';
 import type { FumaDB, InferFumaDB } from 'fumadb';
 import type { CacheAdapter } from '../cache/types';
@@ -141,7 +141,9 @@ export interface CacheOptions {
 export interface IABOptions {
     /**
      * Enable IAB TCF support.
-     * When false or not provided, /init returns gvl: null.
+     * 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).
      */
     enabled: true;
     /**
@@ -197,6 +199,84 @@ export interface IABOptions {
     customVendors?: NonIABVendor[];
 }
 type FumaDBSchema = InferFumaDB<typeof DB>['schemas'];
+export interface I18nMessageProfile {
+    /**
+     * Fallback language used when the requested language is not configured in
+     * this profile.
+     *
+     * @remarks
+     * This does not expand the profile's allowed languages. If the configured
+     * fallback is not present in the profile, c15t falls back to English when
+     * available, otherwise to the first configured language in the profile.
+     *
+     * @default "en"
+     */
+    fallbackLanguage?: string;
+    /**
+     * Translation overrides keyed by language code.
+     */
+    translations: Record<string, Partial<Translations>>;
+}
+export type I18nMessageProfiles = Record<string, I18nMessageProfile>;
+export interface I18nOptions {
+    /**
+     * Named translation catalogs grouped by profile.
+     *
+     * @example
+     * ```ts
+     * i18n: {
+     *   messages: {
+     *     default: {
+     *       translations: { en: { cookieBanner: { title: '...' } } },
+     *     },
+     *     us_ca: {
+     *       fallbackLanguage: 'en',
+     *       translations: { en: { cookieBanner: { title: '...' } } },
+     *     },
+     *   }
+     * }
+     * ```
+     */
+    messages?: I18nMessageProfiles;
+    /**
+     * Fallback profile used when a policy does not provide `messageProfile`.
+     * @default "default"
+     */
+    defaultProfile?: string;
+}
+export type { PolicyConfig, PolicyModel, PolicyPack, PolicyScopeMode, PolicyUiAction, PolicyUiActionDirection, PolicyUiActionGroup, PolicyUiMode, PolicyUiProfile, PolicyUiSurfaceConfig, } from '../../../schema/dist-types/types';
+export interface PolicySnapshotOptions {
+    /**
+     * Secret used for signing and verifying policy snapshot tokens.
+     */
+    signingKey: string;
+    /**
+     * How writes should behave when snapshot validation fails.
+     * @default "reject"
+     */
+    onValidationFailure?: 'reject' | 'resolve_current';
+    /**
+     * JWT issuer claim for snapshot tokens.
+     * @default "c15t"
+     */
+    issuer?: string;
+    /**
+     * JWT audience claim for snapshot tokens.
+     * When omitted, c15t derives a default snapshot audience and scopes it per tenant.
+     */
+    audience?: string;
+    /**
+     * Snapshot token lifetime in seconds.
+     * @default 1800 (30 minutes)
+     */
+    ttlSeconds?: number;
+}
+export interface BackgroundOptions {
+    /**
+     * Executes non-critical tasks after the response path has completed.
+     */
+    run: (task: () => Promise<void>) => void;
+}
 export interface C15TOptions {
     /**
      * The database adapter to use.
@@ -254,6 +334,8 @@ export interface C15TOptions {
     /**
      * Override base translations.
      *
+     * @deprecated Use `i18n.messages` instead. This alias is kept for compatibility.
+     *
      * @example
      * ```ts
      * {
@@ -263,6 +345,21 @@ export interface C15TOptions {
      * ```
      */
     customTranslations?: Record<string, Partial<Translations>>;
+    /**
+     * Internationalization message profiles used by runtime policies.
+     */
+    i18n?: I18nOptions;
+    /**
+     * Runtime regional policy pack resolved per request.
+     *
+     * @remarks
+     * Omit this field to keep legacy non-policy behavior. Pass `[]` to force
+     * explicit no-banner mode. In production, prefer including a default policy
+     * so unmatched traffic still resolves deterministically.
+     *
+     * @see {@link https://v2.c15t.com/docs/self-host/guides/policy-packs}
+     */
+    policyPacks?: PolicyConfig[];
     /**
      * Select which branding to show in the consent banner.
      * Use "none" to hide branding.
@@ -314,8 +411,16 @@ export interface C15TOptions {
      * @see {@link https://v2.c15t.com/docs/self-host/guides/iab-tcf}
      */
     iab?: IABOptions;
+    /**
+     * Optional signed policy snapshots used to keep /init and /subjects consistent.
+     */
+    policySnapshot?: PolicySnapshotOptions;
+    /**
+     * Optional background task runner for non-critical side effects.
+     */
+    background?: BackgroundOptions;
 }
-export interface C15TContext extends Omit<C15TOptions, 'ipAddress' | 'adapter' | 'logger' | 'tablePrefix' | 'tenantId'> {
+export interface C15TContext extends Omit<C15TOptions, 'ipAddress' | 'adapter' | 'logger' | 'tablePrefix'> {
     appName: string;
     logger: ReturnType<typeof createLogger>;
     registry: ReturnType<typeof createRegistry>;
@@ -336,4 +441,3 @@ export interface C15TContext extends Omit<C15TOptions, 'ipAddress' | 'adapter' |
 export type DeepPartial<T> = T extends (...args: unknown[]) => unknown ? T : T extends object ? {
     [K in keyof T]?: DeepPartial<T[K]>;
 } : T;
-//# sourceMappingURL=index.d.ts.map

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

@@ -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

@@ -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

@@ -1,4 +1,4 @@
-import { createLogger, type LoggerOptions } from '@c15t/logger';
+import { createLogger, type LoggerOptions } from '../../../logger/dist-types/index.d.ts';
 /**
  * Gets or creates a global logger instance
  *
@@ -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.6";

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,197 @@
+---
+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" \|undefined|Select which branding to show in the consent banner. 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|
+|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|
+
+#### `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
+
+`c15tEdgeInit()` from `@c15t/backend/edge` accepts a subset of `C15TOptions` — only the fields needed for consent policy resolution without a database. 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
+});
+```