@consenti/api 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,7 +1,46 @@
 import { EventEmitter } from 'node:events';
 import { IncomingMessage, ServerResponse } from 'node:http';
 
+/**
+ * Deep-partial with JSON Merge Patch (RFC 7396) delete semantics: any key may be
+ * set to `null` instead of its usual type to signal "delete this key" when the
+ * partial is applied with `deepMerge()` — `undefined`/omitted keeps the base
+ * value, `null` removes it. Only meaningful for object/map keys (e.g. removing
+ * a `CategoryMap`/`CookieMap` entry via `profileOverride`); array elements are
+ * merged positionally and don't support deletion this way.
+ */
+type DeepPartial<T> = T extends Function ? T : T extends Array<infer InferredArrayType> ? Array<DeepPartial<InferredArrayType>> : T extends ReadonlyArray<infer InferredReadonlyArrayType> ? ReadonlyArray<DeepPartial<InferredReadonlyArrayType>> : T extends object ? {
+    [Key in keyof T]?: DeepPartial<T[Key]> | null;
+} : T;
+
+/**
+ * Single source of truth for all compliance groups, regulations, and country mappings.
+ *
+ * This is DATA, not types. The `Compliance` and `ComplianceGroupId` literal types
+ * derived from the ID arrays below live in @consenti/types (packages/types/src/compliance.ts),
+ * via a type-only import — that keeps @consenti/types free of runtime code.
+ *
+ * ─── HOW TO UPDATE ────────────────────────────────────────────────────────────
+ *
+ * ADD A NEW REGULATION:
+ *   1. Add regulation ID string to `COMPLIANCE_REGULATION_IDS` below
+ *      (the `Compliance` type in @consenti/types auto-updates from it).
+ *   2. Add it to the appropriate group's `compliances` array below.
+ *   3. Add / update the country entry in `EMBEDDED_COMPLIANCE_MAP` below.
+ *   That is all — no other files need touching.
+ *
+ * ADD A NEW COMPLIANCE GROUP:
+ *   1. Add the kebab-case ID to `COMPLIANCE_GROUP_IDS` below.
+ *   2. Add a full group entry to `COMPLIANCE_GROUPS` below (label, compliances, flags).
+ *   3. Add a validation rule set to `COMPLIANCE_VALIDATION_RULES` below.
+ *   4. Map affected countries in `EMBEDDED_COMPLIANCE_MAP` to the new group.
+ *
+ * ADD OR UPDATE A COUNTRY:
+ *   Edit the entry in `EMBEDDED_COMPLIANCE_MAP.countries` below. That is the ONLY
+ *   place that needs changing for country-level jurisdiction updates.
+ */
 declare const COMPLIANCE_GROUP_IDS: readonly ["opt-in", "opt-out", "opt-out-strict", "opt-in-dpdpa", "opt-in-china", "opt-in-brazil", "general-privacy-consent", "notice-only"];
+declare const COOKIE_PURPOSE_IDS: readonly ["necessary", "functional", "preferences", "analytics", "marketing"];
 
 /**
  * Compliance-related literal types, derived from the regulation/group ID data
@@ -18,6 +57,20 @@ declare const COMPLIANCE_GROUP_IDS: readonly ["opt-in", "opt-out", "opt-out-stri
 
 type ComplianceGroupId = typeof COMPLIANCE_GROUP_IDS[number];
 
+/** Resolved content for one non-default locale — template shape merged with that locale's
+ * author text, computed client-side (dashboard) the same way the default locale's content on
+ * `StoredProfileJson` is. Never persisted in the DB row; `ProfileService` writes it straight to
+ * that locale's on-disk version file. Keyed by locale code on `CreateProfileInput`/
+ * `UpdateProfileInput.localeContent` — only locales actually touched this save need an entry;
+ * any other locale already in `profileJson.locales` is carried forward unchanged from the
+ * previous version. */
+interface LocaleContentInput {
+    mainBanner: MainBanner;
+    gpcBanner?: GpcBanner;
+    preferenceModal: PreferenceModal;
+    /** Only meaningful when the profile's `ageGate.enabled` is true. */
+    ageGateModal?: AgeGateModalContent;
+}
 interface StorageConfig {
     driver: 'sqlite' | 'better-sqlite3' | 'node-sqlite3-wasm' | 'node:sqlite' | 'mongodb' | 'mysql' | 'postgresql' | 'json';
     path?: string;
@@ -27,6 +80,20 @@ interface StorageConfig {
     port?: number;
     user?: string;
     password?: string;
+    /** Postgres/MySQL only. Max pool connections. Default: 10 (both drivers' own default — set
+     * explicitly here so it's a documented, tunable value rather than an implicit library default). */
+    poolMax?: number;
+    /**
+     * Postgres/MySQL only. Milliseconds before an in-flight query is aborted, so one slow/runaway
+     * query can't hold a pool connection indefinitely. Unset by default: a forced default could
+     * silently break legitimate long-running operations (e.g. exporting millions of records) that
+     * this project has no way to load-test — opt in once you've measured your own worst-case query.
+     */
+    statementTimeoutMs?: number;
+    /** Postgres only. Milliseconds a client may sit idle inside an open transaction before being
+     * terminated — protects against a `BEGIN` with no matching `COMMIT`/`ROLLBACK` holding a
+     * connection forever. Unset by default, same reasoning as `statementTimeoutMs`. */
+    idleInTransactionTimeoutMs?: number;
 }
 interface OidcConfig {
     issuer: string;
@@ -46,7 +113,7 @@ interface SamlConfig {
 }
 interface AuthConfig {
     mode: 'local' | 'jwt' | 'custom' | 'oidc' | 'saml';
-    jwtSecret?: string;
+    masterSecret?: string;
     validateUser?: (req: unknown) => Promise<AdminUser | null>;
     adminEmail?: string;
     adminPassword?: string;
@@ -62,6 +129,14 @@ type GeoResult = {
     country: string | null;
     region: string | null;
     locale: string | null;
+    /** Optional escape hatch: when set, `GeoResolverService` uses this compliance group directly
+     * instead of computing one from `country`/`region` against the jurisdiction map — for a
+     * provider that already carries legal-grade jurisdiction data (e.g. a paid geo-IP service) and
+     * needs to route a visitor into an operator-defined custom group the built-in map can't express.
+     * `country`/`region`/`locale` are still used for locale resolution and the `requiresSensitiveOptIn`
+     * region carve-out, which are independent of which group applies. Optional — omitting it (or
+     * returning `undefined`) preserves the existing country/region-map resolution exactly as before. */
+    complianceGroup?: string;
 };
 type CountryResolverFn = (ctx: {
     ip: string;
@@ -81,18 +156,33 @@ interface ProfileSummary {
     name: string;
     defaultLocale: string;
     complianceGroup: ComplianceGroupId | null;
-    version: number;
+    customComplianceGroup: string | null;
     isActive: boolean;
-    cookieTemplateName: string | null;
+    consentTemplateName: string | null;
     uiTemplateName: string | null;
     createdAt: string;
     updatedAt: string;
 }
+/**
+ * One snapshot in a profile's edit history. `Profile.id` is stable across edits; each save
+ * increments `Profile.version` in place and writes a new snapshot under that version number.
+ */
 interface ProfileVersionEntry {
     version: number;
     createdAt: string;
     locales: string[];
 }
+/**
+ * A profile-id directory found on disk with no matching DB row — the profile was deleted
+ * (or predates the current versioning model) but its version-snapshot history wasn't. Built
+ * from a directory listing only (id, version count, last-modified) — no file content is read
+ * until a specific version is opened via the normal version-history endpoints.
+ */
+interface ArchivedProfileSummary {
+    id: string;
+    versionCount: number;
+    lastModified: string;
+}
 interface OptInFilters {
     profileId?: string;
     complianceGroup?: string;
@@ -124,31 +214,49 @@ interface OptInStats {
     byLocale: Record<string, OptInByLocale>;
     byDate: OptInByDate[];
 }
-type ComplianceMapOverride = 'default' | ComplianceMapData | 'auto';
 interface ComplianceMapData {
     version: string;
     countries: Record<string, CountryComplianceEntry>;
 }
 interface CountryComplianceEntry {
     complianceGroup: ComplianceGroupId;
-    default: ComplianceGroupId;
-    description: string;
+    /** Fallback group used when only the country (not the region) is known. Defaults to
+     * `complianceGroup` when omitted — only set this explicitly when a region within this
+     * country can be stricter than the country-wide baseline (see `overriddenRegions`). */
+    default?: ComplianceGroupId;
+    description?: string;
     overriddenRegions?: Record<string, {
         complianceGroup: ComplianceGroupId;
-        description: string;
+        description?: string;
     }>;
 }
 interface ComplianceConfig {
-    /** @deprecated use type */
-    gdpr?: boolean;
-    /** @deprecated use type */
-    ccpa?: boolean;
+    /** Server-side GPC enforcement on `POST`/`PUT /consent`: re-applies GPC-driven denial when a
+     * write carries `gpcDetected`, independent of the widget's own client-side `gpcMode` handling.
+     * `false` disables this defense-in-depth check entirely. Default: enabled. */
     gpc?: boolean | 'strict';
     type?: ComplianceGroupId | 'auto';
-    /** @deprecated use 'default' instead of 'language' or 'timezone'; 'geoip' and 'hosted-geoip-lite' removed */
-    geoDataProvider?: 'default' | 'maxmind' | 'language' | 'timezone' | 'geoip' | 'hosted-geoip-lite' | CountryResolverFn;
-    autoComplianceMap?: ComplianceMapOverride;
-    complianceMapUrl?: string;
+    geoDataProvider?: 'default' | 'maxmind' | 'geoip' | 'hosted-geoip-lite' | CountryResolverFn;
+    /** `'default'` (embedded map, the default), a URL to fetch a JSON `ComplianceMapData` document
+     * from (refreshed in the background per the response's `Cache-Control`/`Expires` header, 24h
+     * fallback if absent), or an inline operator-supplied `ComplianceMapData` object. Invalid data
+     * from either a URL or an object logs an error and falls back to `'default'`. */
+    complianceMap?: 'default' | string | ComplianceMapData;
+    tcf?: TcfConfig;
+    gpp?: GppConfig;
+    /** Signs server-stored consent records (HMAC-SHA256 at create/update time, hex-encoded into
+     * `signature`, checked on `GET /consent/:visitorId/verify`), ownership cookies, and
+     * parental-consent request/resolve tokens (see `POST /consent/:visitorId/parental-consent-request`),
+     * and salts hashed IPs — independent of the widget's own cookie-signing
+     * (`core.cookieSigningKey`). Auto-generated in memory when unset, so all of the above are
+     * always active — but an auto-generated value isn't persisted, so a restart invalidates
+     * outstanding ownership cookies, in-flight parental-consent tokens, and (if compared across
+     * restarts) hashed-IP continuity. Set this explicitly for anything beyond local dev. */
+    dataSigningHash?: string;
+    dataRetention?: DataRetentionConfig;
+    /** Expiry window for parental-consent tokens issued by `POST /consent/:visitorId/parental-consent-request`.
+     * Default: 7 days. */
+    parentalConsentTokenTtlDays?: number;
 }
 interface DashboardConfig {
     enabled?: boolean;
@@ -157,15 +265,32 @@ interface DashboardConfig {
 interface MultiTenantConfig {
     enabled: boolean;
 }
-interface AgeGateConfig {
-    enabled: boolean;
-    minimumAge: number;
-    requireParentalConsent?: boolean;
-}
 interface TcfConfig {
     enabled: boolean;
     cmpId: number;
     cmpVersion: number;
+    /** ISO 3166-1 alpha-2 country code of the publisher (e.g. 'DE', 'FR'). Required for
+     * spec-correct binary TC-string encoding — without it, real encoding is skipped and
+     * Consenti falls back to the simplified (non-spec) TC string. No default: there is no
+     * honest country to assume on a publisher's behalf. */
+    publisherCC?: string;
+}
+/** IAB Global Privacy Platform (GPP), US National ("usnat") section only — the umbrella section
+ * most MSPA/programmatic US bidders read. Individual state sections (US-CA, US-CO, etc.) aren't
+ * encoded yet. Requires the optional `@iabgpp/cmpapi` peer dependency (see `gpp/gpp-string.ts`) —
+ * unlike TCF there's no simplified fallback format, since a non-spec GPP string has no consumer
+ * that would accept it: when the dependency isn't installed, `gppString`/`window.__gpp` are
+ * simply not produced. */
+interface GppConfig {
+    enabled: boolean;
+    cmpId: number;
+    cmpVersion: number;
+    /** MSPA "covered transaction" — whether this deployment's data transactions fall under MSPA
+     * signatory obligations. No honest default, so it's required rather than optional. */
+    mspaCoveredTransaction: boolean;
+    /** IAB's tri-state encoding for both MSPA fields: 0 = not applicable, 1 = yes, 2 = no. */
+    mspaOptOutOptionMode: 0 | 1 | 2;
+    mspaServiceProviderMode: 0 | 1 | 2;
 }
 interface DataRetentionConfig {
     purgeAfterDays: number;
@@ -191,15 +316,12 @@ interface ConsentiServerConfig {
     compliance?: ComplianceConfig;
     multiTenant?: MultiTenantConfig;
     plugins?: ConsentiServerPlugin[];
-    ageGate?: AgeGateConfig;
-    tcf?: TcfConfig;
-    dataRetention?: DataRetentionConfig;
     maxBodySize?: number;
     trustedProxies?: string[];
     branding?: BrandingConfig;
     s3Api?: S3ApiConfig;
     /** Called after every profile activate/deactivate/delete. isPurge=true means invalidate; false means warm. */
-    handleCache?: (paths: string[], currentVersion: number, isPurge: boolean) => void;
+    handleCache?: (paths: string[], profileId: string, isPurge: boolean) => void;
 }
 interface Tenant {
     id: string;
@@ -208,21 +330,69 @@ interface Tenant {
     createdAt: string;
     updatedAt: string;
 }
+/** Tenant-wide dashboard-managed defaults, shown on the API Config page. */
+interface TenantSettings {
+    /** Public API origin allowlist. Distinct from `ProfileConfig.allowedOrigins`, which the
+     * origin check on `POST /consent` prefers when a profile sets its own list; this is the
+     * fallback. The public API has no auth token, so this is its only access gate. */
+    allowedOrigins?: string[];
+    /** Admin API origin allowlist — an additional CORS-layer check on top of Bearer-token auth
+     * for browser-originated `/consenti/admin/v1/*` requests. Empty/unset means no restriction
+     * (Bearer token auth alone still applies); only enforced when the request carries an
+     * `Origin` header — server-to-server callers are unaffected. */
+    adminAllowedOrigins?: string[];
+    /** Whether this tenant has completed (or skipped) the first-run setup wizard. Gates the
+     * one-time `#/setup` redirect in the dashboard — never reset once true. Default: false. */
+    setupCompleted?: boolean;
+    /** Whether `POST /setup/seed-profiles` has been called at least once for this tenant (an
+     * empty `groups: []` call counts). `POST /setup/complete` rejects until this is true, closing
+     * the bypass where the wizard's step-1 skip (or a direct API call) could mark setup complete
+     * without ever passing through config review or the profile step. */
+    profilesSeeded?: boolean;
+    /** Last-confirmed TCF `{cmpId, cmpVersion}` registration snapshot, hashed rather than stored
+     * in full — the live values always come from the static `compliance.tcf` config, never the DB.
+     * A hash mismatch (including never having confirmed) means TCF is treated as unconfirmed and
+     * fails closed: no `window.__tcfapi`, no TC string, a logged server error. Re-confirming in the
+     * dashboard (against the cached IAB CMP List) writes a fresh hash here. */
+    tcfConfirmation?: RegistrationConfirmation;
+    /** Same governance shape as `tcfConfirmation`, for the GPP US National section's own
+     * `compliance.gpp.{cmpId, cmpVersion}`. Self-attestation only — IAB doesn't publish a
+     * CMP-List equivalent for GPP, so there's no external registry to validate against. */
+    gppConfirmation?: RegistrationConfirmation;
+}
+/** Hash-based confirmation record — proves a specific `{cmpId, cmpVersion}` config was reviewed
+ * and confirmed as registered, without persisting the config values themselves in the DB. */
+interface RegistrationConfirmation {
+    /** Hash of the confirmed `{cmpId, cmpVersion}` (and `publisherCC` for TCF). Compared against a
+     * fresh hash of the live static config on every check — any drift (including a first-ever
+     * check) means unconfirmed. */
+    configHash: string;
+    confirmedAt: string;
+    /** User id of the admin who checked the confirmation box. Undefined for confirmations made
+     * before this field existed. */
+    confirmedBy?: string;
+}
 interface ApiKey {
     id: string;
     tenantId: string;
     keyHash: string;
     name: string;
     isActive: boolean;
+    /** User id of the admin who created this key. Undefined for keys created before this field existed. */
+    createdBy?: string;
+    /** Optional expiry set at creation. Checked lazily at auth time and on list — no background sweep. */
+    expireBy?: string;
     createdAt: string;
+    updatedAt?: string;
 }
 interface Profile {
     id: string;
     tenantId: string;
     name: string;
     defaultLocale: string;
+    /** Starts at 1, incremented in place on every save. The row itself is mutated, never replaced — see {@link ProfileVersionEntry} for the on-disk snapshot history this produces. */
     version: number;
-    profileJson: ProfileConfig;
+    profileJson: StoredProfileJson;
     createdAt: string;
     updatedAt: string;
 }
@@ -231,7 +401,6 @@ interface ConsentDbRecord {
     tenantId: string;
     visitorId: string;
     profileId: string;
-    profileVersion: number;
     locale: string;
     consentJson: ConsentValue;
     gpcDetected: boolean;
@@ -239,6 +408,11 @@ interface ConsentDbRecord {
     ageVerified?: boolean;
     parentalConsentToken?: string;
     tcfString?: string;
+    gppString?: string;
+    /** HMAC-SHA256 signature over the record's core fields, hex-encoded — tamper-evidence for
+     * server-stored records via `dataSigningHash` (auto-generated when unset), independent of the
+     * widget's own cookie-signing (`core.cookieSigningKey`). */
+    signature?: string;
     createdAt: string;
     updatedAt: string;
 }
@@ -289,6 +463,22 @@ interface Permission {
     name: string;
     description?: string;
 }
+/** Proof that the consent banner was rendered to a visitor — recorded even if they never
+ * interact with it, distinct from (and never merged into) an actual consent decision. */
+interface NoticeShownRecord {
+    id: string;
+    tenantId: string;
+    visitorId: string;
+    profileId: string;
+    locale: string;
+    createdAt: string;
+}
+interface CreateNoticeShownInput {
+    tenantId: string;
+    visitorId: string;
+    profileId: string;
+    locale: string;
+}
 interface AuditLog {
     id: string;
     tenantId: string;
@@ -300,22 +490,39 @@ interface AuditLog {
     newData?: unknown;
     createdAt: string;
 }
+/** List-view shape for consents — omits the fields not shown in a table row (`consentJson`,
+ * `parentalConsentToken`, `tcfString`, `gppString`, `signature`), so paginated list queries don't
+ * have to pull those blobs off disk for every row. Fetch the full `ConsentDbRecord` via
+ * `getConsent(visitorId)` when a single record's full detail is actually needed (e.g. opening a
+ * detail modal). */
+type ConsentSummary = Omit<ConsentDbRecord, 'consentJson' | 'parentalConsentToken' | 'tcfString' | 'gppString' | 'signature'>;
+/** List-view shape for audit logs — omits `oldData`/`newData` (full before/after snapshots) for
+ * the same reason as `ConsentSummary`. Fetch the full `AuditLog` via `getAuditLogById(id)` when a
+ * single entry's full detail is needed. */
+type AuditLogSummary = Omit<AuditLog, 'oldData' | 'newData'>;
 interface CreateProfileInput {
     tenantId: string;
     name: string;
     defaultLocale: string;
-    profileJson: ProfileConfig;
+    profileJson: StoredProfileJson;
+    /** Non-default locales' resolved content for this save — see {@link LocaleContentInput}. */
+    localeContent?: Record<string, LocaleContentInput>;
 }
 interface UpdateProfileInput {
     name?: string;
     defaultLocale?: string;
-    profileJson?: ProfileConfig;
+    profileJson?: StoredProfileJson;
+    /** Explicit new version number — set by `ProfileService.update()` to `old.version + 1` for a content edit. Omitted for isActive-only flips (activate/deactivate), which leave the version unchanged. */
+    version?: number;
+    /** Non-default locales' resolved content for this save — see {@link LocaleContentInput}. Any
+     * locale in `profileJson.locales` not present here is carried forward unchanged from the
+     * previous version's on-disk file. */
+    localeContent?: Record<string, LocaleContentInput>;
 }
 interface CreateConsentInput {
     tenantId: string;
     visitorId: string;
     profileId: string;
-    profileVersion: number;
     locale: string;
     consentJson: ConsentValue;
     gpcDetected: boolean;
@@ -323,11 +530,14 @@ interface CreateConsentInput {
     ageVerified?: boolean;
     parentalConsentToken?: string;
     tcfString?: string;
+    gppString?: string;
+    signature?: string;
 }
 interface UpdateConsentInput {
     consentJson: ConsentValue;
     locale?: string;
     gpcDetected?: boolean;
+    signature?: string;
 }
 interface CreateVisitorInput {
     tenantId: string;
@@ -376,6 +586,8 @@ interface ConsentFilters {
     to?: string;
     page?: number;
     limit?: number;
+    /** Free-text search across visitorId, profileId, locale, source. */
+    q?: string;
 }
 interface VisitorFilters {
     tenantId: string;
@@ -383,6 +595,8 @@ interface VisitorFilters {
     to?: string;
     page?: number;
     limit?: number;
+    /** Free-text search across visitorId, country. */
+    q?: string;
 }
 interface AuditFilters {
     tenantId: string;
@@ -392,12 +606,24 @@ interface AuditFilters {
     to?: string;
     page?: number;
     limit?: number;
+    /** Free-text search across action, resourceType, resourceId, userId. */
+    q?: string;
+}
+/** Page of results plus the total row count matching the same filters (ignoring page/limit) —
+ * lets callers compute total page count for numbered pagination without a second round trip. */
+interface PagedResult<T> {
+    items: T[];
+    total: number;
+    page: number;
+    limit: number;
 }
 interface ConsentVerifyResult {
     valid: boolean;
-    reasons: Array<'profile_version_mismatch' | 'consent_expired' | 'hmac_invalid'>;
-    currentProfileVersion?: number;
-    consentProfileVersion?: number;
+    reasons: Array<'profile_changed' | 'consent_expired' | 'hmac_invalid'>;
+    /** The id of the profile currently active for this consent's compliance group, if any. */
+    currentProfileId?: string;
+    /** The id of the profile this consent was originally collected against. */
+    consentProfileId?: string;
 }
 type SafeAdminUser = Omit<AdminUser, 'passwordHash'>;
 interface CreateRoleInput {
@@ -438,6 +664,8 @@ interface CreateApiKeyInput {
     tenantId: string;
     name: string;
     keyHash: string;
+    createdBy?: string;
+    expireBy?: string;
 }
 interface CreateTenantInput {
     name: string;
@@ -459,22 +687,24 @@ interface StorageAdapter {
     findActiveProfileByComplianceGroup(tenantId: string, complianceGroup: string): Promise<Profile | null>;
     /** Lightweight list — no profile_json blob; single JOIN for template names. */
     listProfilesSummary(tenantId: string): Promise<ProfileSummary[]>;
-    findProfilesUsingCookieTemplate(templateId: string): Promise<ProfileSummary[]>;
+    findProfilesUsingConsentTemplate(templateId: string): Promise<ProfileSummary[]>;
     findProfilesUsingUITemplate(templateId: string): Promise<ProfileSummary[]>;
     getOptInStats(tenantId: string, filters: OptInFilters): Promise<OptInStats>;
     createConsent(data: CreateConsentInput): Promise<ConsentDbRecord>;
     updateConsent(visitorId: string, data: UpdateConsentInput): Promise<ConsentDbRecord>;
     deleteConsent(visitorId: string): Promise<void>;
     getConsent(visitorId: string): Promise<ConsentDbRecord | null>;
-    getConsents(filters: ConsentFilters): Promise<ConsentDbRecord[]>;
+    getConsents(filters: ConsentFilters): Promise<PagedResult<ConsentSummary>>;
     streamConsents(filters: ConsentFilters): AsyncIterable<ConsentDbRecord>;
     createVisitor(data: CreateVisitorInput): Promise<Visitor>;
     updateVisitor(visitorId: string, data: UpdateVisitorInput): Promise<Visitor>;
     deleteVisitor(visitorId: string): Promise<void>;
     getVisitor(visitorId: string): Promise<Visitor | null>;
-    getVisitors(filters: VisitorFilters): Promise<Visitor[]>;
+    getVisitors(filters: VisitorFilters): Promise<PagedResult<Visitor>>;
     getConsentHistory(visitorId: string): Promise<ConsentHistoryEntry[]>;
     streamAuditLogs(filters: AuditFilters): AsyncIterable<AuditLog>;
+    createNoticeShown(data: CreateNoticeShownInput): Promise<NoticeShownRecord>;
+    getNoticeShownForVisitor(visitorId: string): Promise<NoticeShownRecord[]>;
     getOverviewStats(tenantId: string): Promise<OverviewStats>;
     getCategoryStats(tenantId: string): Promise<CategoryStats>;
     getTimeline(tenantId: string, days?: number): Promise<TimelineEntry[]>;
@@ -484,17 +714,25 @@ interface StorageAdapter {
     createTenant(data: CreateTenantInput): Promise<Tenant>;
     updateTenant(id: string, data: UpdateTenantInput): Promise<Tenant>;
     deleteTenant(id: string): Promise<void>;
+    /** Returns `{}` (all fields unset) if no settings row exists yet for this tenant. */
+    getSettings(tenantId: string): Promise<TenantSettings>;
+    updateSettings(tenantId: string, data: Partial<TenantSettings>): Promise<TenantSettings>;
     createApiKey(data: CreateApiKeyInput): Promise<ApiKey>;
     getApiKeyByHash(keyHash: string): Promise<ApiKey | null>;
     revokeApiKey(id: string): Promise<void>;
+    /** Re-enables a previously revoked key (same hash, no new secret). Clears `expireBy` if it's
+     * in the past, so a lazily-expired key doesn't immediately re-expire on the next check. */
+    reactivateApiKey(id: string): Promise<void>;
+    /** Permanently removes the key row — unlike `revokeApiKey`, this cannot be undone. */
+    deleteApiKey(id: string): Promise<void>;
     getApiKeys(tenantId: string): Promise<ApiKey[]>;
     purgeExpiredConsents(olderThanDays: number): Promise<number>;
-    createCookieTemplate(data: CreateCookieTemplateInput): Promise<ServerCookieTemplate>;
-    updateCookieTemplate(id: string, data: UpdateCookieTemplateInput): Promise<ServerCookieTemplate>;
-    deleteCookieTemplate(id: string): Promise<void>;
-    getCookieTemplate(id: string): Promise<ServerCookieTemplate | null>;
-    getCookieTemplates(tenantId: string): Promise<ServerCookieTemplate[]>;
-    copyCookieTemplate(id: string, newName: string): Promise<ServerCookieTemplate>;
+    createConsentTemplate(data: CreateConsentTemplateInput): Promise<ServerConsentTemplate>;
+    updateConsentTemplate(id: string, data: UpdateConsentTemplateInput): Promise<ServerConsentTemplate>;
+    deleteConsentTemplate(id: string): Promise<void>;
+    getConsentTemplate(id: string): Promise<ServerConsentTemplate | null>;
+    getConsentTemplates(tenantId: string): Promise<ServerConsentTemplate[]>;
+    copyConsentTemplate(id: string, newName: string): Promise<ServerConsentTemplate>;
     createUITemplate(data: CreateUITemplateInput): Promise<ServerUITemplate>;
     updateUITemplate(id: string, data: UpdateUITemplateInput): Promise<ServerUITemplate>;
     deleteUITemplate(id: string): Promise<void>;
@@ -520,7 +758,8 @@ interface StorageAdapter {
     assignPermissionToRole(roleId: string, permissionId: string): Promise<void>;
     revokePermissionFromRole(roleId: string, permissionId: string): Promise<void>;
     createLog(data: CreateAuditLogInput): Promise<void>;
-    getLogs(filters: AuditFilters): Promise<AuditLog[]>;
+    getLogs(filters: AuditFilters): Promise<PagedResult<AuditLogSummary>>;
+    getAuditLogById(id: string): Promise<AuditLog | null>;
 }
 interface PluginContext {
     storage: StorageAdapter;
@@ -539,23 +778,54 @@ declare abstract class ConsentiServerPlugin {
     beforeUserCreate?(data: CreateUserInput): Promise<CreateUserInput>;
     afterUserCreate?(user: AdminUser): Promise<void>;
 }
+/**
+ * The server's stored shape of `Profile.profileJson` — extends the shared `ProfileConfig`
+ * (`./ui`, also used by `apps/ui`'s local `ConsentiProfile`/`registerProfile()` authoring, which
+ * genuinely needs the full multi-locale `translations`/`localeContents` blob for its own
+ * no-backend use case and must stay untouched).
+ *
+ * On the server, only `defaultLocale`'s own resolved content is ever stored here —
+ * `mainBanner`/`gpcBanner`/`preferenceModal` (inherited from `ProfileConfig` as-is: template shape
+ * merged with the author's text, optional fields simply omitted rather than blank — never a
+ * multi-locale map). Every other locale's content lives only in its own per-version JSON file on
+ * disk (`profiles/{tenant}/{id}/{version}/{locale}.json`, see `ProfileService`), never in the DB
+ * row — `translations`/`localeContents` (both full multi-locale blobs) are dropped entirely.
+ */
+interface StoredProfileJson extends Omit<ProfileConfig, 'translations' | 'localeContents'> {
+    /** Every locale this profile has content for — drives the dashboard's tab list. Content for any
+     * locale other than `defaultLocale` lives only in that locale's on-disk version file, not here. */
+    locales: string[];
+}
 
 type ConsentStatus = 'granted' | 'denied' | 'objected';
 type ConsentValue = Record<string, ConsentStatus>;
+type GpcMode = 'ignore' | 'honor' | 'strict';
+type LegalBasis = 'mandatory' | 'consent' | 'legitimate_interest';
+type CookiePurpose = typeof COOKIE_PURPOSE_IDS[number];
+/**
+ * A single consent parameter (tracker/cookie definition).
+ * Keyed by its own id inside `Record<string, Cookie>` — the map key IS the id,
+ * there is no `id` field on the value itself.
+ */
 interface Cookie {
-    id: string;
-    legalBasis?: 'mandatory' | 'consent' | 'legitimate_interest';
-    /** @deprecated use legalBasis: 'mandatory' */
-    mandatory?: boolean;
-    /** @deprecated use legalBasis */
-    type?: 'consent' | 'legitimate_interest';
+    purpose?: CookiePurpose;
     listenGpc?: boolean;
-    expiry?: number;
+    /**
+     * Pre-grant this parameter's default consent to 'granted' (instead of the
+     * compliance-group-driven default) when no stored decision exists yet.
+     * Only meaningful when the owning category's `legalBasis === 'consent'` —
+     * `mandatory`/`legitimate_interest` categories are already effectively
+     * pre-granted regardless of this flag. Never overrides an active GPC signal.
+     * Default: false.
+     */
+    preGrant?: boolean;
     tcfVendorId?: number;
     tcfPurposes?: number[];
     tcfSpecialFeatures?: number[];
     cpraCategory?: 'sale' | 'sharing' | 'sensitive';
 }
+/** `Cookie` keyed by its own id — the standard shape used everywhere a parameter list is passed around. */
+type CookieMap = Record<string, Cookie>;
 type ButtonStyle = 'primary' | 'secondary' | 'text' | 'accent';
 type ButtonAction = 'submit' | 'manage' | 'close' | 'custom' | 'link';
 interface Button {
@@ -564,8 +834,11 @@ interface Button {
     action: ButtonAction;
     cookies?: string[] | '*' | '!';
     url?: string;
-    type?: string;
 }
+/** `Button` keyed by its own id — e.g. `'accept-all'`. The map key IS the id, rendered as the DOM
+ * `id` (`consenti-btn-{id}`) so integrators can target specific buttons, and is what
+ * `profileOverride`'s `deepMerge` deletes by (`{ 'reject-optional': null }` removes one button). */
+type ButtonMap = Record<string, Button>;
 interface MainBanner {
     position: 'top' | 'bottom' | 'middle' | 'left-bottom' | 'right-bottom';
     overlayOpacity?: number;
@@ -574,34 +847,100 @@ interface MainBanner {
     heading?: string;
     headingTag?: string;
     htmlText: string;
-    buttons: Button[];
+    buttons: ButtonMap;
+    /** Stack buttons vertically below this viewport width in px. 0 or undefined = disabled. Default: 576. */
+    stackButtonsOnBreakpoint?: number;
+    /** Trap keyboard Tab focus within the consent root while this banner is visible. */
+    trapFocus?: boolean;
 }
 type GpcBanner = MainBanner;
+/**
+ * A consent category — the single source of legal basis for every parameter
+ * it lists in `cookies`. Keyed by its own id inside `Record<string, Category>` —
+ * the map key IS the id, there is no `id` field on the value itself.
+ *
+ * A parameter must belong to exactly one category (enforced at authoring time,
+ * not by this type) — that relationship is what `getCookieLegalBasis`/
+ * `isMandatoryCookie` (`@consenti/utils`) resolve at runtime.
+ */
 interface Category {
-    id: string;
     heading: string;
     headingTag?: string;
     htmlText: string;
-    mandatory?: boolean;
-    type?: 'consent' | 'legitimate_interest';
-    legitimateInterest?: {
-        enabled?: boolean;
-        description?: string;
-    };
+    legalBasis: LegalBasis;
+    /** Only meaningful when legalBasis === 'legitimate_interest' — the GDPR balancing-test justification shown to visitors. */
+    legitimateInterestDescription?: string;
+    /** IDs of the parameters (from the profile's `cookies` map) that belong to this category. */
     cookies: string[];
 }
+/** `Category` keyed by its own id — the standard shape used everywhere a category list is passed around. */
+type CategoryMap = Record<string, Category>;
 interface PreferenceModal extends Omit<MainBanner, "position"> {
     position?: 'left' | 'right' | 'center';
     subheading?: string;
-    categories: Category[];
+    categories: CategoryMap;
     persistent?: boolean;
     /** Screen width in px below which the modal expands to full screen. Default: 576. Set to 0 to disable. */
     mobileFullScreenBreakpoint?: number;
+    /** Label for the optional consent-receipt download checkbox (shown when `allowReceipt` is true). Falls back to a default when omitted. */
+    receiptLabel?: string;
+    /** Description shown beneath the consent-receipt checkbox. Falls back to a default when omitted. */
+    receiptDescription?: string;
+    /**
+     * Renders a "Forget me" control in the modal body, below the categories — only shown to
+     * visitors who already have a stored consent decision (nothing to erase otherwise). Wired to
+     * the same `DELETE /consent/:visitorId` erasure endpoint as `widget.deleteConsent()`, giving
+     * visitors self-service access to GDPR Art. 17 / CCPA-CPRA / LGPD Art. 18 / UK GDPR / DPDPA /
+     * KVKK / POPIA / PDPA-TH / APPI erasure-equivalent rights without the host wiring a link
+     * themselves. See the "Right to erasure" guide for the full compliance mapping.
+     */
+    showForgetMe?: boolean;
+    /** Label for the "Forget me" button (shown when `showForgetMe` is true). Falls back to a default when omitted. */
+    forgetMeLabel?: string;
+}
+/**
+ * A UI-template button definition. Keyed by its own machine id (e.g. `'accept-all'`) inside
+ * `TemplateButtonMap` — the map key IS the id, not display text. UI templates own layout/behavior
+ * only, never text. The visitor-facing label is authored per-locale on the profile instead
+ * (`LocaleTextContent.*.buttonLabels`, keyed by the same button id) and composed into a resolved
+ * `Button.text` at profile-build time. Distinct from `Button` (the resolved-profile shape), which
+ * always carries real `text`.
+ */
+interface TemplateButtonDef {
+    type?: ButtonStyle;
+    action: ButtonAction;
+    cookies?: string[] | '*' | '!';
+    url?: string;
+}
+/** `TemplateButtonDef` keyed by its own id — the standard shape everywhere a UI template's
+ * button set is passed around. */
+type TemplateButtonMap = Record<string, TemplateButtonDef>;
+interface TemplateBannerDef {
+    position: 'top' | 'bottom' | 'middle' | 'left-bottom' | 'right-bottom';
+    overlayOpacity?: number;
+    showClose?: boolean;
+    showLocaleSwitcher?: boolean;
+    headingTag?: string;
+    buttons: TemplateButtonMap;
+    stackButtonsOnBreakpoint?: number;
+    trapFocus?: boolean;
+}
+type TemplateGpcBannerDef = TemplateBannerDef;
+interface TemplateModalDef extends Omit<TemplateBannerDef, 'position'> {
+    position?: 'left' | 'right' | 'center';
+    persistent?: boolean;
+    hasSubheading?: boolean;
+    mobileFullScreenBreakpoint?: number;
+    /** Renders a "Forget me" control below the categories, for visitors who already have a stored
+     * consent decision. See {@link PreferenceModal.showForgetMe}. */
+    showForgetMe?: boolean;
 }
 interface LocaleTranslations {
-    mainBanner: MainBanner;
-    gpcBanner?: GpcBanner;
-    preferenceModal: PreferenceModal;
+    mainBanner: DeepPartial<MainBanner>;
+    gpcBanner?: DeepPartial<GpcBanner>;
+    preferenceModal: DeepPartial<PreferenceModal>;
+    /** Only meaningful when the profile's `ageGate.enabled` is true. */
+    ageGateModal?: DeepPartial<AgeGateModalContent>;
 }
 interface ProfileTranslations {
     [locale: string]: LocaleTranslations;
@@ -611,113 +950,201 @@ interface DpdpaConfig {
     grievanceEmail: string;
     purposeDescription?: string;
 }
+/**
+ * Per-profile age gate — GDPR Art. 8's consent age varies 13–16 by EU member state and DPDPA has
+ * its own child-data age rules, so one global age (the old `ConsentiServerConfig.ageGate`) was
+ * wrong for a multi-region deployment. Mirrors `dpdpa` exactly: profile-scoped, not global.
+ */
+interface AgeGateConfig {
+    enabled: boolean;
+    minimumAge: number;
+    requireParentalConsent?: boolean;
+}
+/** Per-locale age-gate modal text — translated the same way `mainBanner`/`preferenceModal`
+ * content is, unlike the widget's own hardcoded UI chrome (close button, locale switcher). */
+interface AgeGateModalContent {
+    heading?: string;
+    htmlText: string;
+    confirmButtonLabel: string;
+    denyButtonLabel: string;
+    parentalConsent: {
+        heading?: string;
+        htmlText: string;
+        confirmButtonLabel: string;
+    };
+}
 interface LocaleTextContent {
     mainBanner: {
         heading?: string;
         htmlText: string;
-        buttonLabels?: string[];
+        /** Keyed by the linked UI template's button id — was a positional array matched to
+         * `buttons[i]` by index; now matched by key, robust against button reordering. */
+        buttonLabels?: Record<string, string>;
     };
     gpcBanner: {
         heading?: string;
         htmlText: string;
-        buttonLabels?: string[];
+        buttonLabels?: Record<string, string>;
     };
     preferenceModal: {
         heading: string;
         subheading?: string;
         htmlText?: string;
-        buttonLabels?: string[];
-        categories: {
-            id: string;
+        buttonLabels?: Record<string, string>;
+        /** `legitimateInterestDescription` is only meaningful for categories whose legalBasis is 'legitimate_interest'; optional GDPR balancing-test text, translated per locale like heading/htmlText. */
+        categories: Record<string, {
             heading: string;
             htmlText: string;
-        }[];
+            legitimateInterestDescription?: string;
+        }>;
+        receiptLabel?: string;
+        receiptDescription?: string;
+        /** Per-locale override of `PreferenceModal.forgetMeLabel`; only meaningful when `showForgetMe` is true. */
+        forgetMeLabel?: string;
     };
+    /** Only meaningful when the profile's `ageGate.enabled` is true. */
+    ageGateModal?: AgeGateModalContent;
 }
 interface ProfileConfig {
-    cookies?: Cookie[];
+    id: string;
+    cookies?: CookieMap;
     defaultLocale: string;
+    /** Days until consent expires and the visitor is asked again (profile-wide). Default: 365. */
+    expiryDays?: number;
     translations?: ProfileTranslations;
-    gpcBanner?: boolean;
+    mainBanner: MainBanner;
+    gpcBanner?: GpcBanner;
+    preferenceModal: PreferenceModal;
     darkMode?: boolean;
     allowedOrigins?: string[];
     dpdpa?: DpdpaConfig;
+    ageGate?: AgeGateConfig;
+    /** Default locale's age-gate modal text — mirrors `mainBanner`/`preferenceModal` (inline,
+     * required-shape-when-present), not `dpdpa` (which has no locale text at all). Every other
+     * locale's `ageGateModal` lives in `localeContents`/`LocaleContentInput` like the rest of
+     * that locale's content. */
+    ageGateModal?: AgeGateModalContent;
     regulation?: 'gdpr' | 'ccpa' | 'cpra' | 'dpdpa' | 'uk-gdpr' | 'lgpd' | 'pipeda' | 'popia' | 'pdpa-th' | 'appi' | 'kvkk';
     regulations?: string[];
-    cookieTemplateId?: string;
+    consentTemplateId?: string;
     uiTemplateId?: string;
     localeContents?: Record<string, LocaleTextContent>;
-    complianceGroup?: string;
-    /** @deprecated use gpcMode */
-    gpcCompliance?: 'strict' | 'honor' | 'ignore';
-    gpcMode?: 'ignore' | 'honor' | 'strict';
+    complianceGroup?: ComplianceGroupId;
+    /**
+     * Free-form identifier (lower-kebab-case) for profiles that don't map to one of the
+     * built-in `complianceGroup` values — the identifier the widget's `compliance.type`
+     * config targets to fetch this profile. Participates in activation, deactivation, and
+     * "one active profile per group" conflict detection the same way `complianceGroup` does;
+     * no `COMPLIANCE_GROUPS` validation rules or GPC defaults apply to it, since none exist
+     * for a free-form name.
+     */
+    customComplianceGroup?: string;
+    /**
+     * Per-profile deltas applied on top of the consent template's authored `Cookie` values
+     * (e.g. an overridden `preGrant`) when resolving this profile — see the dashboard's Step 2
+     * pre-grant override UX. Keyed by cookie id; only the overridden fields need to be present.
+     */
+    cookiesOverride?: Record<string, Partial<Cookie>>;
+    /**
+     * Reserved for a future phase — stored but not yet applied when resolving a profile.
+     * Intended to mirror `cookiesOverride` for per-category deltas.
+     */
+    categoriesOverride?: Record<string, Partial<Category>>;
+    /**
+     * Reserved for a future phase — stored but not yet applied when resolving a profile.
+     * Intended to hold per-profile UI-template deltas.
+     */
+    uiOverride?: Record<string, unknown>;
+    /**
+     * When registered via `registerProfile()` and `complianceGroup` matches one of
+     * Consenti's built-in groups: `false` (default) fully replaces the built-in
+     * embedded profile for that group; `true` deep-merges this config onto the
+     * built-in profile instead (only meaningful together with `complianceGroup`).
+     */
+    deepMerge?: boolean;
+    gpcMode?: GpcMode;
     isActive?: boolean;
     hidePoweredBy?: boolean;
     allowReceipt?: boolean;
     /** Per-compliance extra config (e.g. DPDPA data fiduciary name). */
     complianceConfig?: Record<string, string>;
+    /** Show a metadata footer strip in the banner/modal with Consent ID, Date, Version, Privacy Settings link. */
+    showFooterMetadata?: boolean;
+    /** Apply WCAG 2.1 AA button sizing (44px min-height), visible focus rings, and screen-reader labels. */
+    enhanceAccessibility?: boolean;
 }
 interface ServerUITemplate {
     id: string;
     tenantId: string;
     name: string;
-    mainBanner: MainBanner;
-    gpcBanner: GpcBanner;
-    preferenceModal: PreferenceModal;
+    mainBanner: TemplateBannerDef;
+    gpcBanner: TemplateGpcBannerDef;
+    preferenceModal: TemplateModalDef;
     createdAt: string;
     updatedAt: string;
 }
-interface ServerCookieTemplate {
+interface ServerConsentTemplate {
     id: string;
     tenantId: string;
     name: string;
-    cookies: Cookie[];
+    cookies: CookieMap;
+    categories: CategoryMap;
     createdAt: string;
     updatedAt: string;
 }
-interface CreateCookieTemplateInput {
+interface CreateConsentTemplateInput {
     tenantId: string;
     name: string;
-    cookies: Cookie[];
+    cookies: CookieMap;
+    categories: CategoryMap;
 }
-interface UpdateCookieTemplateInput {
+interface UpdateConsentTemplateInput {
     name?: string;
-    cookies?: Cookie[];
+    cookies?: CookieMap;
+    categories?: CategoryMap;
 }
 interface CreateUITemplateInput {
     tenantId: string;
     name: string;
-    mainBanner: MainBanner;
-    gpcBanner: MainBanner;
-    preferenceModal: PreferenceModal;
+    mainBanner: TemplateBannerDef;
+    gpcBanner: TemplateGpcBannerDef;
+    preferenceModal: TemplateModalDef;
 }
 interface UpdateUITemplateInput {
     name?: string;
-    mainBanner?: MainBanner;
-    gpcBanner?: MainBanner;
-    preferenceModal?: PreferenceModal;
+    mainBanner?: TemplateBannerDef;
+    gpcBanner?: TemplateGpcBannerDef;
+    preferenceModal?: TemplateModalDef;
 }
 interface PublicProfileResponse {
     id: string;
+    /** Incremented in place on every save of this profile. */
+    version: number;
     name?: string;
     tenantId?: string;
-    version: number;
     defaultLocale: string;
     currentLocale: string;
     locales: string[];
-    cookies: Cookie[];
+    cookies: CookieMap;
+    /** Days until consent expires and the visitor is asked again (profile-wide). */
+    expiryDays?: number;
     mainBanner: MainBanner;
     gpcBanner?: GpcBanner;
     preferenceModal: PreferenceModal;
     resolvedComplianceGroup?: string;
-    complianceGroup?: string;
+    complianceGroup?: ComplianceGroupId;
     compliances?: string[];
     complianceConfig?: Record<string, string>;
     allowedOrigins?: string[];
-    gpcMode?: boolean | 'ignore' | 'honor' | 'strict';
+    gpcMode?: GpcMode;
     hidePoweredBy?: boolean;
     allowReceipt?: boolean;
     darkMode?: boolean;
+    dpdpa?: DpdpaConfig;
+    ageGate?: AgeGateConfig;
+    ageGateModal?: AgeGateModalContent;
+    showFooterMetadata?: boolean;
+    enhanceAccessibility?: boolean;
     createdAt?: string;
     updatedAt?: string;
 }
@@ -737,7 +1164,8 @@ declare class AuditRepo {
     private adapter;
     constructor(adapter: StorageAdapter);
     log(data: CreateAuditLogInput): Promise<void>;
-    list(filters: AuditFilters): Promise<AuditLog[]>;
+    list(filters: AuditFilters): Promise<PagedResult<AuditLogSummary>>;
+    get(id: string): Promise<AuditLog | null>;
 }
 
 declare class LocaleJsonCacheService {
@@ -760,23 +1188,118 @@ declare class ProfileService {
     private profilesDir?;
     private handleCache?;
     private s3Config?;
-    constructor(profiles: ProfileRepo, audit: AuditRepo, tenantId?: string, storage?: StorageAdapter | undefined, eventBus?: EventEmitter | undefined, localeCache?: LocaleJsonCacheService | undefined, profilesDir?: string | undefined, handleCache?: ((paths: string[], version: number, isPurge: boolean) => void) | undefined, s3Config?: S3ApiConfig | undefined);
-    private profileDir;
+    constructor(profiles: ProfileRepo, audit: AuditRepo, tenantId?: string, storage?: StorageAdapter | undefined, eventBus?: EventEmitter | undefined, localeCache?: LocaleJsonCacheService | undefined, profilesDir?: string | undefined, handleCache?: ((paths: string[], profileId: string, isPurge: boolean) => void) | undefined, s3Config?: S3ApiConfig | undefined);
+    /** Root directory holding every version snapshot of one logical profile, keyed by its stable id. */
+    private versionsRootDir;
     private complianceGroupDir;
+    /**
+     * The directory key used for activation/hot-serve writes and the "one active profile
+     * per group" conflict check — the real `complianceGroup` when set, otherwise the
+     * free-form `customComplianceGroup` (which the widget's `compliance.type` targets the
+     * same way). Compliance *validation* still only ever runs against a real `complianceGroup`.
+     */
+    private groupKey;
     private profileFilePaths;
+    /** Resolves this profile's cookie map (consent-template lookup + `cookiesOverride` applied) —
+     * the one piece of content still resolved live rather than baked at save time, since cookies
+     * are small and never the source of the row-size problem `mainBanner`/`preferenceModal` were. */
+    private resolveCookies;
+    /**
+     * Writes every locale's on-disk version file for one save (create or an edit) in a single
+     * atomic worker call — default locale content comes from `profile.profileJson` itself, every
+     * other touched locale from `localeContent`. A locale already in `profileJson.locales` but not
+     * present in `localeContent` (a tab the user never opened this session) is carried forward
+     * unchanged from `previousVersion` by the worker — never silently dropped.
+     */
+    private writeLocaleFiles;
     create(input: Omit<CreateProfileInput, 'tenantId'>): Promise<Profile>;
+    /**
+     * Duplicates a profile as a brand new, always-inactive profile (own `id`, `version` starts at
+     * 1 again). Delegates to {@link create} rather than copying on-disk files directly — the
+     * resolved-JSON snapshot embeds its own `id`/`version`, so it has to be regenerated for the
+     * new profile rather than byte-copied from the source's. Non-default locale content is read
+     * back off the source's current version files so the copy carries every locale forward too.
+     */
+    copy(id: string, name?: string): Promise<Profile>;
+    /**
+     * Mutates the existing row in place — `id` is stable across every edit, `version` is
+     * incremented. The prior state isn't kept as a separate DB row; its resolved-JSON snapshot
+     * on disk (see {@link listVersions}) is the audit trail for that edit.
+     */
     update(id: string, input: UpdateProfileInput): Promise<Profile>;
     delete(id: string): Promise<void>;
     activate(id: string): Promise<Profile>;
     deactivate(id: string): Promise<Profile>;
-    private runWrite;
-    get(id: string, locale?: string): Promise<Profile | null>;
+    private runDeactivate;
+    get(id: string): Promise<Profile | null>;
+    /**
+     * Resolves one locale's full public response. The default locale's content lives directly on
+     * the DB row (`profileJson.mainBanner`/`gpcBanner`/`preferenceModal`) — no template lookups, no
+     * live resolution. Any other locale's content lives only in that locale's on-disk version file;
+     * this reads it directly, falling back to the default locale's content if the file is missing
+     * (e.g. a locale listed but never actually authored yet). This method is not a hot path — the
+     * public `/profiles/:tenant/:group/:locale` route serves the static file directly and only
+     * falls back to this for previewing an inactive/versioned profile.
+     */
     getResolved(id: string, locale?: string): Promise<PublicProfileResponse | null>;
     findActiveByComplianceGroup(complianceGroup: string): Promise<Profile | null>;
     list(): Promise<Profile[]>;
     listSummary(): Promise<ProfileSummary[]>;
-    listVersions(profileId: string): ProfileVersionEntry[];
-    getVersionFile(profileId: string, version: number, locale: string): string | null;
+    /**
+     * Lists every version snapshot of `profileId` on disk (newest first), read straight from
+     * the version-directory tree — no DB query, `Profile.version` is just the current pointer.
+     * Works for archived profiles too (DB row deleted, files still on disk) — the directory
+     * tree is the only thing this reads.
+     */
+    listVersions(profileId: string): Promise<ProfileVersionEntry[]>;
+    /** Works for archived profiles too — see `listVersions()`. */
+    getVersionFile(profileId: string, version: string, locale: string): Promise<string | null>;
+    /**
+     * Profile-id directories on disk with no matching DB row — deleted profiles whose version
+     * snapshots `delete()` never removes. Directory-only read (id, version count, last-modified
+     * mtime) — no file content is opened here; that only happens once a specific version is
+     * requested via `getVersionFile()`, which works for these ids too.
+     */
+    listArchivedProfiles(): Promise<ArchivedProfileSummary[]>;
+    /** Strips display text from an embedded profile's button map — a `UITemplate`'s buttons own
+     * layout/behavior only, never text (button labels are authored per-locale on the profile
+     * instead, see `LocaleTextContent.*.buttonLabels`). */
+    private toTemplateButtonMap;
+    /** Builds a `UITemplate`'s structural definitions (position, buttons, close/locale-switcher
+     * flags) from an embedded profile's English translation — no heading/htmlText/button text,
+     * which stay inline on the seeded profile as per-locale content, never on the template. */
+    private buildSeedUiTemplatePayload;
+    /**
+     * Idempotently gets-or-creates the `ConsentTemplate` + `UITemplate` pair backing one seeded
+     * compliance group's profile, named consistently with the profile itself (`Default — {group}`).
+     * Looked up by name/tenant first so re-running the setup wizard never creates duplicates.
+     */
+    private getOrCreateSeedTemplates;
+    /**
+     * Seeds a default profile for a compliance group from the embedded English profile in
+     * `@consenti/utils`, merged with locale text overlays for de/es/fr/ja. Every locale — including
+     * non-English ones — is passed through `create()`'s normal `localeContent` path, the same as an
+     * author-submitted profile; there is no separate "seeded profile" code path for locale content
+     * anymore, which is what previously let a locale silently never make it into the served file.
+     * Only creates the profile if no active profile already exists for the compliance group.
+     * Safe to call repeatedly (idempotent).
+     *
+     * Also seeds (idempotently) a `ConsentTemplate`/`UITemplate` pair for the group and links the
+     * profile to both via `consentTemplateId`/`uiTemplateId` — same as a dashboard-authored profile
+     * is required to. The profile is a *snapshot*, not a live pointer: `cookies`/`mainBanner`/
+     * `gpcBanner`/`preferenceModal` stay fully resolved inline (DB row + on-disk locale files)
+     * exactly as before; the template ids are additive, purely for traceability and so the editor
+     * knows which template to re-offer on next edit. Editing the template later never silently
+     * changes this profile — only an explicit re-save of the profile itself does.
+     *
+     * @param complianceGroup - One of the 8 compliance group IDs.
+     */
+    seedDefaultProfile(complianceGroup: string): Promise<void>;
+    /**
+     * Seeds default profiles for all 8 compliance groups.
+     * Skips any group that already has an active profile (idempotent).
+     */
+    seedAllDefaults(): Promise<void>;
 }
 
 declare class ConsentRepo {
@@ -786,7 +1309,7 @@ declare class ConsentRepo {
     update(visitorId: string, data: UpdateConsentInput): Promise<ConsentDbRecord>;
     delete(visitorId: string): Promise<void>;
     get(visitorId: string): Promise<ConsentDbRecord | null>;
-    list(filters: ConsentFilters): Promise<ConsentDbRecord[]>;
+    list(filters: ConsentFilters): Promise<PagedResult<ConsentSummary>>;
 }
 
 declare class VisitorRepo {
@@ -822,7 +1345,25 @@ declare class ConsentService {
     private pluginEngine?;
     private eventBus?;
     private tcfConfig?;
-    constructor(consents: ConsentRepo, visitors: VisitorRepo, profiles: ProfileRepo, audit: AuditRepo, tenantId?: string, compliance?: ComplianceConfig | undefined, pluginEngine?: PluginEngine | undefined, eventBus?: EventEmitter | undefined, tcfConfig?: TcfConfig | undefined);
+    private storage?;
+    private dataSigningHash?;
+    private gppConfig?;
+    constructor(consents: ConsentRepo, visitors: VisitorRepo, profiles: ProfileRepo, audit: AuditRepo, tenantId?: string, compliance?: ComplianceConfig | undefined, pluginEngine?: PluginEngine | undefined, eventBus?: EventEmitter | undefined, tcfConfig?: TcfConfig | undefined, storage?: StorageAdapter | undefined, dataSigningHash?: string | undefined, gppConfig?: GppConfig | undefined);
+    private sign;
+    /** Fails closed: no `storage` to check against means unconfirmed, never assumed confirmed. */
+    private isTcfConfirmed;
+    /** Same fail-closed shape as isTcfConfirmed() — see registration-confirmation.ts. */
+    private isGppConfirmed;
+    /**
+     * Profiles created via the dashboard wizard reference a consent template (`consentTemplateId`)
+     * rather than embedding `cookies`/`preferenceModal.categories` directly on `profileJson` — those
+     * fields are only populated for the embedded/seeded default profiles (see
+     * `ProfileService.seedDefaultProfile`). Cookie/category membership and `legalBasis` are
+     * locale-independent, so the raw consent template's data is sufficient here — no need to
+     * resolve per-locale text via `ProfileService.getResolved()`. Mirrors the same fallback
+     * `ProfileService.getResolved()` and the admin route validators already apply.
+     */
+    private resolveTemplateData;
     create(input: Omit<CreateConsentInput, 'tenantId'>): Promise<ConsentDbRecord>;
     update(visitorId: string, input: UpdateConsentInput): Promise<ConsentDbRecord>;
     get(visitorId: string): Promise<ConsentDbRecord | null>;
@@ -834,7 +1375,8 @@ declare class VisitorService {
     private visitors;
     private tenantId;
     private eventBus?;
-    constructor(visitors: VisitorRepo, tenantId?: string, eventBus?: EventEmitter | undefined);
+    private dataSigningHash;
+    constructor(visitors: VisitorRepo, tenantId?: string, eventBus?: EventEmitter | undefined, dataSigningHash?: string);
     upsert(data: {
         visitorId: string;
         ip?: string;
@@ -904,19 +1446,23 @@ declare class BetterSqlite3Adapter implements StorageAdapter {
     getProfiles(tenantId: string): Promise<Profile[]>;
     findActiveProfileByComplianceGroup(tenantId: string, complianceGroup: string): Promise<Profile | null>;
     private mapConsent;
+    private static readonly CONSENT_SUMMARY_COLS;
+    private mapConsentSummary;
     createConsent(data: CreateConsentInput): Promise<ConsentDbRecord>;
     updateConsent(visitorId: string, data: UpdateConsentInput): Promise<ConsentDbRecord>;
     deleteConsent(visitorId: string): Promise<void>;
     getConsent(visitorId: string): Promise<ConsentDbRecord | null>;
-    getConsents(filters: ConsentFilters): Promise<ConsentDbRecord[]>;
+    getConsents(filters: ConsentFilters): Promise<PagedResult<ConsentSummary>>;
     streamConsents(filters: ConsentFilters): AsyncIterable<ConsentDbRecord>;
     getConsentHistory(visitorId: string): Promise<ConsentHistoryEntry[]>;
+    createNoticeShown(data: CreateNoticeShownInput): Promise<NoticeShownRecord>;
+    getNoticeShownForVisitor(visitorId: string): Promise<NoticeShownRecord[]>;
     private mapVisitor;
     createVisitor(data: CreateVisitorInput): Promise<Visitor>;
     updateVisitor(visitorId: string, data: UpdateVisitorInput): Promise<Visitor>;
     deleteVisitor(visitorId: string): Promise<void>;
     getVisitor(visitorId: string): Promise<Visitor | null>;
-    getVisitors(filters: VisitorFilters): Promise<Visitor[]>;
+    getVisitors(filters: VisitorFilters): Promise<PagedResult<Visitor>>;
     private mapUser;
     createUser(data: CreateUserInput): Promise<AdminUser>;
     updateUser(id: string, data: UpdateUserInput): Promise<AdminUser>;
@@ -937,7 +1483,10 @@ declare class BetterSqlite3Adapter implements StorageAdapter {
     assignRole(userId: string, roleId: string, tenantId?: string): Promise<void>;
     revokeRole(userId: string, roleId: string, tenantId?: string): Promise<void>;
     createLog(data: CreateAuditLogInput): Promise<void>;
-    getLogs(filters: AuditFilters): Promise<AuditLog[]>;
+    getLogs(filters: AuditFilters): Promise<PagedResult<AuditLogSummary>>;
+    getAuditLogById(id: string): Promise<AuditLog | null>;
+    private static readonly AUDIT_SUMMARY_COLS;
+    private mapAuditSummary;
     private mapAuditLog;
     streamAuditLogs(filters: AuditFilters): AsyncIterable<AuditLog>;
     getOverviewStats(tenantId: string): Promise<OverviewStats>;
@@ -949,19 +1498,23 @@ declare class BetterSqlite3Adapter implements StorageAdapter {
     createTenant(data: CreateTenantInput): Promise<Tenant>;
     updateTenant(id: string, data: UpdateTenantInput): Promise<Tenant>;
     deleteTenant(id: string): Promise<void>;
+    getSettings(tenantId: string): Promise<TenantSettings>;
+    updateSettings(tenantId: string, data: Partial<TenantSettings>): Promise<TenantSettings>;
     purgeExpiredConsents(olderThanDays: number): Promise<number>;
     private mapApiKey;
     createApiKey(data: CreateApiKeyInput): Promise<ApiKey>;
     getApiKeyByHash(keyHash: string): Promise<ApiKey | null>;
     revokeApiKey(id: string): Promise<void>;
+    reactivateApiKey(id: string): Promise<void>;
+    deleteApiKey(id: string): Promise<void>;
     getApiKeys(tenantId: string): Promise<ApiKey[]>;
-    private mapCookieTemplate;
-    createCookieTemplate(data: CreateCookieTemplateInput): Promise<ServerCookieTemplate>;
-    updateCookieTemplate(id: string, data: UpdateCookieTemplateInput): Promise<ServerCookieTemplate>;
-    deleteCookieTemplate(id: string): Promise<void>;
-    getCookieTemplate(id: string): Promise<ServerCookieTemplate | null>;
-    getCookieTemplates(tenantId: string): Promise<ServerCookieTemplate[]>;
-    copyCookieTemplate(id: string, newName: string): Promise<ServerCookieTemplate>;
+    private mapConsentTemplate;
+    createConsentTemplate(data: CreateConsentTemplateInput): Promise<ServerConsentTemplate>;
+    updateConsentTemplate(id: string, data: UpdateConsentTemplateInput): Promise<ServerConsentTemplate>;
+    deleteConsentTemplate(id: string): Promise<void>;
+    getConsentTemplate(id: string): Promise<ServerConsentTemplate | null>;
+    getConsentTemplates(tenantId: string): Promise<ServerConsentTemplate[]>;
+    copyConsentTemplate(id: string, newName: string): Promise<ServerConsentTemplate>;
     private mapUITemplate;
     createUITemplate(data: CreateUITemplateInput): Promise<ServerUITemplate>;
     updateUITemplate(id: string, data: UpdateUITemplateInput): Promise<ServerUITemplate>;
@@ -972,7 +1525,7 @@ declare class BetterSqlite3Adapter implements StorageAdapter {
     private mapProfileSummary;
     private readonly PROFILE_SUMMARY_SQL;
     listProfilesSummary(tenantId: string): Promise<ProfileSummary[]>;
-    findProfilesUsingCookieTemplate(templateId: string): Promise<ProfileSummary[]>;
+    findProfilesUsingConsentTemplate(templateId: string): Promise<ProfileSummary[]>;
     findProfilesUsingUITemplate(templateId: string): Promise<ProfileSummary[]>;
     getOptInStats(tenantId: string, filters: OptInFilters): Promise<OptInStats>;
 }
@@ -998,16 +1551,18 @@ declare class MongoDBAdapter implements StorageAdapter {
     updateConsent(visitorId: string, data: UpdateConsentInput): Promise<ConsentDbRecord>;
     deleteConsent(visitorId: string): Promise<void>;
     getConsent(visitorId: string): Promise<ConsentDbRecord | null>;
-    getConsents(filters: ConsentFilters): Promise<ConsentDbRecord[]>;
+    getConsents(filters: ConsentFilters): Promise<PagedResult<ConsentSummary>>;
     streamConsents(filters: ConsentFilters): AsyncIterable<ConsentDbRecord>;
     private buildConsentFilter;
     private writeHistory;
     getConsentHistory(visitorId: string): Promise<ConsentHistoryEntry[]>;
+    createNoticeShown(data: CreateNoticeShownInput): Promise<NoticeShownRecord>;
+    getNoticeShownForVisitor(visitorId: string): Promise<NoticeShownRecord[]>;
     createVisitor(data: CreateVisitorInput): Promise<Visitor>;
     updateVisitor(visitorId: string, data: UpdateVisitorInput): Promise<Visitor>;
     deleteVisitor(visitorId: string): Promise<void>;
     getVisitor(visitorId: string): Promise<Visitor | null>;
-    getVisitors(filters: VisitorFilters): Promise<Visitor[]>;
+    getVisitors(filters: VisitorFilters): Promise<PagedResult<Visitor>>;
     getOverviewStats(tenantId: string): Promise<OverviewStats>;
     getCategoryStats(tenantId: string): Promise<CategoryStats>;
     getTimeline(tenantId: string, days?: number): Promise<TimelineEntry[]>;
@@ -1030,26 +1585,32 @@ declare class MongoDBAdapter implements StorageAdapter {
     assignPermissionToRole(roleId: string, permissionId: string): Promise<void>;
     revokePermissionFromRole(roleId: string, permissionId: string): Promise<void>;
     createLog(data: CreateAuditLogInput): Promise<void>;
-    getLogs(filters: AuditFilters): Promise<AuditLog[]>;
+    getLogs(filters: AuditFilters): Promise<PagedResult<AuditLogSummary>>;
+    getAuditLogById(id: string): Promise<AuditLog | null>;
     streamAuditLogs(filters: AuditFilters): AsyncIterable<AuditLog>;
     private buildAuditFilter;
     getCountries(tenantId: string): Promise<CountryStat[]>;
     getGpcStats(tenantId: string): Promise<GpcStats>;
     getTenants(): Promise<Tenant[]>;
+    private mapApiKey;
     createApiKey(data: CreateApiKeyInput): Promise<ApiKey>;
     getApiKeyByHash(keyHash: string): Promise<ApiKey | null>;
     revokeApiKey(id: string): Promise<void>;
+    reactivateApiKey(id: string): Promise<void>;
+    deleteApiKey(id: string): Promise<void>;
     getApiKeys(tenantId: string): Promise<ApiKey[]>;
     createTenant(data: CreateTenantInput): Promise<Tenant>;
     updateTenant(id: string, data: UpdateTenantInput): Promise<Tenant>;
     deleteTenant(id: string): Promise<void>;
+    getSettings(tenantId: string): Promise<TenantSettings>;
+    updateSettings(tenantId: string, data: Partial<TenantSettings>): Promise<TenantSettings>;
     purgeExpiredConsents(olderThanDays: number): Promise<number>;
-    createCookieTemplate(): Promise<never>;
-    updateCookieTemplate(): Promise<never>;
-    deleteCookieTemplate(): Promise<void>;
-    getCookieTemplate(): Promise<never>;
-    getCookieTemplates(): Promise<never>;
-    copyCookieTemplate(): Promise<never>;
+    createConsentTemplate(): Promise<never>;
+    updateConsentTemplate(): Promise<never>;
+    deleteConsentTemplate(): Promise<void>;
+    getConsentTemplate(): Promise<never>;
+    getConsentTemplates(): Promise<never>;
+    copyConsentTemplate(): Promise<never>;
     createUITemplate(): Promise<never>;
     updateUITemplate(): Promise<never>;
     deleteUITemplate(): Promise<void>;
@@ -1057,7 +1618,7 @@ declare class MongoDBAdapter implements StorageAdapter {
     getUITemplates(): Promise<never>;
     copyUITemplate(): Promise<never>;
     listProfilesSummary(): Promise<never[]>;
-    findProfilesUsingCookieTemplate(): Promise<never[]>;
+    findProfilesUsingConsentTemplate(): Promise<never[]>;
     findProfilesUsingUITemplate(): Promise<never[]>;
     getOptInStats(): Promise<never>;
 }
@@ -1082,16 +1643,18 @@ declare class MySQLAdapter implements StorageAdapter {
     updateConsent(visitorId: string, data: UpdateConsentInput): Promise<ConsentDbRecord>;
     deleteConsent(visitorId: string): Promise<void>;
     getConsent(visitorId: string): Promise<ConsentDbRecord | null>;
-    getConsents(filters: ConsentFilters): Promise<ConsentDbRecord[]>;
+    getConsents(filters: ConsentFilters): Promise<PagedResult<ConsentSummary>>;
     streamConsents(filters: ConsentFilters): AsyncIterable<ConsentDbRecord>;
-    private buildConsentQuery;
+    private buildConsentWhere;
     private writeHistory;
     getConsentHistory(visitorId: string): Promise<ConsentHistoryEntry[]>;
+    createNoticeShown(data: CreateNoticeShownInput): Promise<NoticeShownRecord>;
+    getNoticeShownForVisitor(visitorId: string): Promise<NoticeShownRecord[]>;
     createVisitor(data: CreateVisitorInput): Promise<Visitor>;
     updateVisitor(visitorId: string, data: UpdateVisitorInput): Promise<Visitor>;
     deleteVisitor(visitorId: string): Promise<void>;
     getVisitor(visitorId: string): Promise<Visitor | null>;
-    getVisitors(filters: VisitorFilters): Promise<Visitor[]>;
+    getVisitors(filters: VisitorFilters): Promise<PagedResult<Visitor>>;
     getOverviewStats(tenantId: string): Promise<OverviewStats>;
     getCategoryStats(tenantId: string): Promise<CategoryStats>;
     getTimeline(tenantId: string, days?: number): Promise<TimelineEntry[]>;
@@ -1114,26 +1677,32 @@ declare class MySQLAdapter implements StorageAdapter {
     assignPermissionToRole(roleId: string, permissionId: string): Promise<void>;
     revokePermissionFromRole(roleId: string, permissionId: string): Promise<void>;
     createLog(data: CreateAuditLogInput): Promise<void>;
-    getLogs(filters: AuditFilters): Promise<AuditLog[]>;
+    getLogs(filters: AuditFilters): Promise<PagedResult<AuditLogSummary>>;
+    getAuditLogById(id: string): Promise<AuditLog | null>;
     streamAuditLogs(filters: AuditFilters): AsyncIterable<AuditLog>;
-    private buildAuditQuery;
+    private buildAuditWhere;
     getCountries(tenantId: string): Promise<CountryStat[]>;
     getGpcStats(tenantId: string): Promise<GpcStats>;
     getTenants(): Promise<Tenant[]>;
+    private mapApiKey;
     createApiKey(data: CreateApiKeyInput): Promise<ApiKey>;
     getApiKeyByHash(keyHash: string): Promise<ApiKey | null>;
     revokeApiKey(id: string): Promise<void>;
+    reactivateApiKey(id: string): Promise<void>;
+    deleteApiKey(id: string): Promise<void>;
     getApiKeys(tenantId: string): Promise<ApiKey[]>;
     createTenant(data: CreateTenantInput): Promise<Tenant>;
     updateTenant(id: string, data: UpdateTenantInput): Promise<Tenant>;
+    getSettings(tenantId: string): Promise<TenantSettings>;
+    updateSettings(tenantId: string, data: Partial<TenantSettings>): Promise<TenantSettings>;
     deleteTenant(id: string): Promise<void>;
     purgeExpiredConsents(olderThanDays: number): Promise<number>;
-    createCookieTemplate(): Promise<never>;
-    updateCookieTemplate(): Promise<never>;
-    deleteCookieTemplate(): Promise<void>;
-    getCookieTemplate(): Promise<never>;
-    getCookieTemplates(): Promise<never>;
-    copyCookieTemplate(): Promise<never>;
+    createConsentTemplate(): Promise<never>;
+    updateConsentTemplate(): Promise<never>;
+    deleteConsentTemplate(): Promise<void>;
+    getConsentTemplate(): Promise<never>;
+    getConsentTemplates(): Promise<never>;
+    copyConsentTemplate(): Promise<never>;
     createUITemplate(): Promise<never>;
     updateUITemplate(): Promise<never>;
     deleteUITemplate(): Promise<void>;
@@ -1141,7 +1710,7 @@ declare class MySQLAdapter implements StorageAdapter {
     getUITemplates(): Promise<never>;
     copyUITemplate(): Promise<never>;
     listProfilesSummary(): Promise<never[]>;
-    findProfilesUsingCookieTemplate(): Promise<never[]>;
+    findProfilesUsingConsentTemplate(): Promise<never[]>;
     findProfilesUsingUITemplate(): Promise<never[]>;
     getOptInStats(): Promise<never>;
 }
@@ -1165,16 +1734,18 @@ declare class PostgreSQLAdapter implements StorageAdapter {
     updateConsent(visitorId: string, data: UpdateConsentInput): Promise<ConsentDbRecord>;
     deleteConsent(visitorId: string): Promise<void>;
     getConsent(visitorId: string): Promise<ConsentDbRecord | null>;
-    getConsents(filters: ConsentFilters): Promise<ConsentDbRecord[]>;
+    getConsents(filters: ConsentFilters): Promise<PagedResult<ConsentSummary>>;
     streamConsents(filters: ConsentFilters): AsyncIterable<ConsentDbRecord>;
-    private buildConsentQuery;
+    private buildConsentWhere;
     private writeHistory;
     getConsentHistory(visitorId: string): Promise<ConsentHistoryEntry[]>;
+    createNoticeShown(data: CreateNoticeShownInput): Promise<NoticeShownRecord>;
+    getNoticeShownForVisitor(visitorId: string): Promise<NoticeShownRecord[]>;
     createVisitor(data: CreateVisitorInput): Promise<Visitor>;
     updateVisitor(visitorId: string, data: UpdateVisitorInput): Promise<Visitor>;
     deleteVisitor(visitorId: string): Promise<void>;
     getVisitor(visitorId: string): Promise<Visitor | null>;
-    getVisitors(filters: VisitorFilters): Promise<Visitor[]>;
+    getVisitors(filters: VisitorFilters): Promise<PagedResult<Visitor>>;
     getOverviewStats(tenantId: string): Promise<OverviewStats>;
     getCategoryStats(tenantId: string): Promise<CategoryStats>;
     getTimeline(tenantId: string, days?: number): Promise<TimelineEntry[]>;
@@ -1197,26 +1768,32 @@ declare class PostgreSQLAdapter implements StorageAdapter {
     assignPermissionToRole(roleId: string, permissionId: string): Promise<void>;
     revokePermissionFromRole(roleId: string, permissionId: string): Promise<void>;
     createLog(data: CreateAuditLogInput): Promise<void>;
-    getLogs(filters: AuditFilters): Promise<AuditLog[]>;
+    getLogs(filters: AuditFilters): Promise<PagedResult<AuditLogSummary>>;
+    getAuditLogById(id: string): Promise<AuditLog | null>;
     streamAuditLogs(filters: AuditFilters): AsyncIterable<AuditLog>;
-    private buildAuditQuery;
+    private buildAuditWhere;
     getCountries(tenantId: string): Promise<CountryStat[]>;
     getGpcStats(tenantId: string): Promise<GpcStats>;
     getTenants(): Promise<Tenant[]>;
+    private mapApiKey;
     createApiKey(data: CreateApiKeyInput): Promise<ApiKey>;
     getApiKeyByHash(keyHash: string): Promise<ApiKey | null>;
     revokeApiKey(id: string): Promise<void>;
+    reactivateApiKey(id: string): Promise<void>;
+    deleteApiKey(id: string): Promise<void>;
     getApiKeys(tenantId: string): Promise<ApiKey[]>;
     createTenant(data: CreateTenantInput): Promise<Tenant>;
     updateTenant(id: string, data: UpdateTenantInput): Promise<Tenant>;
     deleteTenant(id: string): Promise<void>;
+    getSettings(tenantId: string): Promise<TenantSettings>;
+    updateSettings(tenantId: string, data: Partial<TenantSettings>): Promise<TenantSettings>;
     purgeExpiredConsents(olderThanDays: number): Promise<number>;
-    createCookieTemplate(): Promise<never>;
-    updateCookieTemplate(): Promise<never>;
-    deleteCookieTemplate(): Promise<void>;
-    getCookieTemplate(): Promise<never>;
-    getCookieTemplates(): Promise<never>;
-    copyCookieTemplate(): Promise<never>;
+    createConsentTemplate(): Promise<never>;
+    updateConsentTemplate(): Promise<never>;
+    deleteConsentTemplate(): Promise<void>;
+    getConsentTemplate(): Promise<never>;
+    getConsentTemplates(): Promise<never>;
+    copyConsentTemplate(): Promise<never>;
     createUITemplate(): Promise<never>;
     updateUITemplate(): Promise<never>;
     deleteUITemplate(): Promise<void>;
@@ -1224,11 +1801,131 @@ declare class PostgreSQLAdapter implements StorageAdapter {
     getUITemplates(): Promise<never>;
     copyUITemplate(): Promise<never>;
     listProfilesSummary(): Promise<never[]>;
-    findProfilesUsingCookieTemplate(): Promise<never[]>;
+    findProfilesUsingConsentTemplate(): Promise<never[]>;
     findProfilesUsingUITemplate(): Promise<never[]>;
     getOptInStats(): Promise<never>;
 }
 
+/**
+ * ConsentAction — server-side counterpart to `@consenti/ui`'s `ConsentAction`.
+ *
+ * Watches a single consent parameter across *every* visitor's submission (not just one
+ * browser's own state) and fires `onGrant`/`onDeny` when that parameter's status actually
+ * changes — via the same `eventBus` `createConsenti()` already emits `consent:created`/
+ * `consent:updated` on. Useful for server-side integrations (CRM sync, suppression lists,
+ * downstream webhooks) that need to react to consent decisions without polling the database.
+ *
+ * There is no server equivalent of the widget's `ConsentScript` — injecting a `<script>` tag
+ * only makes sense in a browser DOM the server doesn't have. `services.consent.create()`/
+ * `.update()` are already the server-side "submit"/"update consent" methods this hook reacts to.
+ *
+ * @example
+ * ```ts
+ * import { createConsenti, ConsentAction } from '@consenti/api'
+ *
+ * const { eventBus } = createConsenti({ ... })
+ *
+ * new ConsentAction({
+ *   id: 'analytics_storage',
+ *   eventBus,
+ *   onGrant: ({ visitorId }) => crm.optIn(visitorId),
+ *   onDeny: ({ visitorId }) => crm.optOut(visitorId),
+ * })
+ * ```
+ */
+
+/** Passed to `onGrant`/`onDeny` — the transitioning parameter's status plus the full consent record. */
+interface ConsentActionParams {
+    visitorId: string;
+    cookieId: string;
+    status: ConsentStatus;
+    record: ConsentDbRecord;
+}
+/** Options for constructing a {@link ConsentAction} instance. */
+interface ConsentActionOptions {
+    /** The consent parameter ID to watch (e.g. `'analytics_storage'`). */
+    id: string;
+    /** The `eventBus` returned by `createConsenti()`. */
+    eventBus: EventEmitter;
+    /** Called when the parameter's status transitions to `'granted'`, for any visitor. */
+    onGrant?: (params: ConsentActionParams) => void;
+    /** Called when the parameter's status transitions away from `'granted'` (`'denied'` or `'objected'`). */
+    onDeny?: (params: ConsentActionParams) => void;
+}
+/**
+ * Watches a single consent parameter across every incoming `consent:created`/`consent:updated`
+ * event and fires `onGrant`/`onDeny` on transitions. Call {@link ConsentAction.destroy} to
+ * remove the event listeners when the hook is no longer needed.
+ */
+declare class ConsentAction {
+    private readonly options;
+    private readonly onCreated;
+    private readonly onUpdated;
+    constructor(options: ConsentActionOptions);
+    private fire;
+    /** Removes the event listeners. Call when the hook is no longer needed. */
+    destroy(): void;
+}
+
+/**
+ * CategoryAction — server-side counterpart to `@consenti/ui`'s `CategoryAction`.
+ *
+ * Same idea as {@link ConsentAction} but watches a whole category's rollup consent state
+ * (granted only when *every* cookie in the category is granted) instead of one parameter —
+ * matching the preference modal's tri-state rollup rule and the widget's `CategoryAction`.
+ *
+ * @example
+ * ```ts
+ * import { createConsenti, CategoryAction } from '@consenti/api'
+ *
+ * const { eventBus, services } = createConsenti({ ... })
+ *
+ * new CategoryAction({
+ *   categoryId: 'marketing',
+ *   eventBus,
+ *   profiles: services.profile,
+ *   onGrant: ({ visitorId }) => adsPlatform.optIn(visitorId),
+ *   onDeny: ({ visitorId }) => adsPlatform.optOut(visitorId),
+ * })
+ * ```
+ */
+
+/** Passed to `onGrant`/`onDeny` — the category's rollup status plus the full consent record. */
+interface CategoryActionParams {
+    visitorId: string;
+    categoryId: string;
+    status: ConsentStatus;
+    record: ConsentDbRecord;
+}
+/** Options for constructing a {@link CategoryAction} instance. */
+interface CategoryActionOptions {
+    /** The category ID to watch (e.g. `'marketing'`). */
+    categoryId: string;
+    /** The `eventBus` returned by `createConsenti()`. */
+    eventBus: EventEmitter;
+    /** The `services.profile` returned by `createConsenti()` — resolves which cookies belong to
+     * this category for the record's profile (categories are defined on the consent template). */
+    profiles: ProfileService;
+    /** Called when every cookie in the category transitions to `'granted'`. */
+    onGrant?: (params: CategoryActionParams) => void;
+    /** Called when the category transitions away from fully granted. */
+    onDeny?: (params: CategoryActionParams) => void;
+}
+/**
+ * Watches a category's rollup consent status across every incoming `consent:created`/
+ * `consent:updated` event and fires `onGrant`/`onDeny` on transitions. Call
+ * {@link CategoryAction.destroy} to remove the event listeners when no longer needed.
+ */
+declare class CategoryAction {
+    private readonly options;
+    private readonly onCreated;
+    private readonly onUpdated;
+    constructor(options: CategoryActionOptions);
+    private fire;
+    /** Removes the event listeners. Call when the hook is no longer needed. */
+    destroy(): void;
+}
+
 declare const dashboardDir: string;
 declare function createConsenti(userConfig: ConsentiServerConfig): {
     router: (req: IncomingMessage, res: ServerResponse, next: (err?: unknown) => void) => void;
@@ -1256,4 +1953,4 @@ declare function createConsenti(userConfig: ConsentiServerConfig): {
     destroy: () => Promise<void>;
 };
 
-export { type AdminUser, type AuditLog, type BrandingConfig, type ConsentDbRecord, type ConsentVerifyResult, type ConsentiServerConfig, MongoDBAdapter, MySQLAdapter, type Permission, PostgreSQLAdapter, type Profile, type Role, BetterSqlite3Adapter as SQLiteAdapter, type SafeAdminUser, type StorageAdapter, type Visitor, createConsenti, dashboardDir };
+export { type AdminUser, type AuditLog, type BrandingConfig, CategoryAction, type CategoryActionOptions, type CategoryActionParams, ConsentAction, type ConsentActionOptions, type ConsentActionParams, type ConsentDbRecord, type ConsentVerifyResult, type ConsentiServerConfig, MongoDBAdapter, MySQLAdapter, type Permission, PostgreSQLAdapter, type Profile, type Role, BetterSqlite3Adapter as SQLiteAdapter, type SafeAdminUser, type StorageAdapter, type Visitor, createConsenti, dashboardDir };