@consenti/api 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,205 +1,71 @@
 import { EventEmitter } from 'node:events';
 import { IncomingMessage, ServerResponse } from 'node:http';
 
-type ConsentStatus = 'granted' | 'denied' | 'objected';
-type ConsentValue = Record<string, ConsentStatus>;
-interface Cookie {
-    id: string;
-    type?: 'consent' | 'legitimate_interest';
-    mandatory?: boolean;
-    listenGpc?: boolean;
-    expiry?: number;
-    tcfVendorId?: number;
-    tcfPurposes?: number[];
-    cpraCategory?: 'sale' | 'sharing' | 'sensitive';
-}
-type ButtonStyle = 'primary' | 'secondary' | 'text' | 'accent';
-type ButtonAction = 'submit' | 'manage' | 'close' | 'custom' | 'link';
-interface Button {
-    text: string;
-    style: ButtonStyle;
-    action: ButtonAction;
-    cookies?: string[] | '*' | '!';
-    url?: string;
-}
-interface MainBanner {
-    position: 'top' | 'bottom' | 'middle' | 'left-bottom' | 'right-bottom';
-    overlayOpacity?: number;
-    showClose?: boolean;
-    showLocaleSwitcher?: boolean;
-    heading?: string;
-    headingTag?: string;
-    htmlText: string;
-    buttons: Button[];
-}
-type GpcBanner = MainBanner;
-interface Category {
-    id: string;
-    heading: string;
-    headingTag?: string;
-    htmlText: string;
-    mandatory?: boolean;
-    type?: 'consent' | 'legitimate_interest';
-    legitimateInterest?: {
-        enabled?: boolean;
-        description?: string;
-    };
-    cookies: string[];
-}
-interface PreferenceModal {
-    position?: 'left' | 'right' | 'center';
-    overlayOpacity?: number;
-    showClose?: boolean;
-    showLocaleSwitcher?: boolean;
-    heading?: string;
-    headingTag?: string;
-    subheading?: string;
-    htmlText?: string;
-    buttons: Button[];
-    categories: Category[];
-    persistent?: boolean;
-}
-interface LocaleTranslations {
-    mainBanner: MainBanner;
-    gpcBanner?: GpcBanner;
-    preferenceModal: PreferenceModal;
-}
-interface ProfileTranslations {
-    [locale: string]: LocaleTranslations;
-}
-interface DpdpaConfig {
-    dataFiduciary: string;
-    grievanceEmail: string;
-    purposeDescription?: string;
-}
-interface LocaleTextContent {
-    mainBanner: {
-        heading: string;
-        htmlText: string;
-        buttonLabels: string[];
-    };
-    gpcBanner: {
-        heading: string;
-        htmlText: string;
-        buttonLabels: string[];
-    };
-    preferenceModal: {
-        heading: string;
-        subheading?: string;
-        htmlText?: string;
-        buttonLabels: string[];
-        categories: Array<{
-            id: string;
-            heading: string;
-            htmlText: string;
-        }>;
-    };
-}
-interface ProfileConfig {
-    cookies?: Cookie[];
-    defaultLocale: string;
-    translations?: ProfileTranslations;
-    gpcBanner?: boolean;
-    darkMode?: boolean;
-    allowedOrigins?: string[];
-    dpdpa?: DpdpaConfig;
-    regulation?: 'gdpr' | 'ccpa' | 'cpra' | 'dpdpa' | 'uk-gdpr' | 'lgpd' | 'pipeda' | 'popia' | 'pdpa-th' | 'appi' | 'kvkk';
-    regulations?: string[];
-    cookieTemplateId?: string;
-    uiTemplateId?: string;
-    localeContents?: Record<string, LocaleTextContent>;
-}
-interface UITemplateButton {
-    text: string;
-    type: string;
-    action: 'submit' | 'custom' | 'manage' | 'close' | 'link';
-    cookies?: string | string[];
-    url?: string;
-}
-interface UITemplateBanner {
-    position: string;
-    overlayOpacity: number;
-    showClose: boolean;
-    showLocaleSwitcher?: boolean;
-    headingTag: string;
-    buttons: UITemplateButton[];
-}
-interface UITemplateCategory {
-    id: string;
-    headingTag: string;
-    mandatory: boolean;
-    type: 'consent' | 'legitimate_interest';
-    liEnabled: boolean;
-    cookies: string[];
-}
-interface UITemplateModal extends UITemplateBanner {
-    hasSubheading: boolean;
-    persistent: boolean;
-    showLocaleSwitcher?: boolean;
-    categories: UITemplateCategory[];
-}
-interface ServerUITemplate {
-    id: string;
-    tenantId: string;
-    name: string;
-    mainBanner: UITemplateBanner;
-    gpcBanner: UITemplateBanner;
-    preferenceModal: UITemplateModal;
-    createdAt: string;
-    updatedAt: string;
-}
-interface ServerCookieTemplate {
-    id: string;
-    tenantId: string;
-    name: string;
-    cookies: Cookie[];
-    createdAt: string;
-    updatedAt: string;
-}
-interface CreateCookieTemplateInput {
-    tenantId: string;
-    name: string;
-    cookies: Cookie[];
-}
-interface UpdateCookieTemplateInput {
-    name?: string;
-    cookies?: Cookie[];
-}
-interface CreateUITemplateInput {
-    tenantId: string;
-    name: string;
-    mainBanner: UITemplateBanner;
-    gpcBanner: UITemplateBanner;
-    preferenceModal: UITemplateModal;
-}
-interface UpdateUITemplateInput {
-    name?: string;
-    mainBanner?: UITemplateBanner;
-    gpcBanner?: UITemplateBanner;
-    preferenceModal?: UITemplateModal;
-}
-interface PublicProfileResponse {
-    id: string;
-    version: number;
-    defaultLocale: string;
-    currentLocale: string;
-    locales: string[];
-    cookies: Cookie[];
+/**
+ * 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;
+
+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
+ * that lives in @consenti/utils (packages/utils/src/compliance.ts).
+ *
+ * This import is type-only and fully erased at compile time — @consenti/types
+ * has no runtime dependency on @consenti/utils. The actual data (COMPLIANCE_GROUPS,
+ * EMBEDDED_COMPLIANCE_MAP, COMPLIANCE_VALIDATION_RULES, GPC_OPTIONS, etc.) lives in
+ * @consenti/utils; import it from there.
+ *
+ * HOW TO ADD A NEW REGULATION OR COMPLIANCE GROUP: see the header comment in
+ * packages/utils/src/compliance.ts — these types auto-update from that data.
+ */
+
+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;
 }
-
 interface StorageConfig {
     driver: 'sqlite' | 'better-sqlite3' | 'node-sqlite3-wasm' | 'node:sqlite' | 'mongodb' | 'mysql' | 'postgresql' | 'json';
     path?: string;
     uri?: string;
-    dbName?: string;
     database?: string;
     host?: string;
     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;
@@ -231,10 +97,112 @@ interface RateLimitConfig {
     windowMs?: number;
     maxRequests?: number;
 }
+type GeoResult = {
+    country: string | null;
+    region: string | null;
+    locale: string | null;
+};
+type CountryResolverFn = (ctx: {
+    ip: string;
+    language: string;
+    timezone: string;
+}) => Promise<GeoResult>;
+interface S3ApiConfig {
+    enabled: boolean;
+    region: string;
+    bucketName: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+}
+interface ProfileSummary {
+    id: string;
+    name: string;
+    defaultLocale: string;
+    complianceGroup: ComplianceGroupId | null;
+    customComplianceGroup: string | null;
+    isActive: boolean;
+    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;
+    from?: string;
+    to?: string;
+    locale?: string;
+}
+interface OptInByLocale {
+    total: number;
+    granted: number;
+    denied: number;
+    managed: number;
+}
+interface OptInByDate {
+    date: string;
+    total: number;
+    granted: number;
+    denied: number;
+    managed: number;
+}
+interface OptInStats {
+    total: number;
+    granted: number;
+    denied: number;
+    managed: number;
+    grantedPct: number;
+    deniedPct: number;
+    managedPct: number;
+    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;
+    overriddenRegions?: Record<string, {
+        complianceGroup: ComplianceGroupId;
+        description: string;
+    }>;
+}
 interface ComplianceConfig {
+    /** @deprecated use type */
     gdpr?: boolean;
+    /** @deprecated use type */
     ccpa?: boolean;
-    gpc?: boolean;
+    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;
 }
 interface DashboardConfig {
     enabled?: boolean;
@@ -255,6 +223,23 @@ interface TcfConfig {
 }
 interface DataRetentionConfig {
     purgeAfterDays: number;
+    /** When set, audit log entries older than this are purged on the same daily timer as consent
+     * record retention. Independent of `purgeAfterDays` since audit trails are often required to
+     * be kept longer than the consent records they reference for compliance/investigation
+     * purposes. Unset by default — audit logs are kept indefinitely unless explicitly configured. */
+    auditLogPurgeAfterDays?: number;
+}
+interface BrandingConfig {
+    /** Display name shown in the dashboard (login page, header, browser tab). Default: 'Consenti'. */
+    appName?: string;
+    /**
+     * Logo to display in the dashboard. Accepts a public URL (https://…) or a local
+     * filesystem path — when a path is given, the file is copied into the dashboard
+     * dist and served as a static asset automatically.
+     */
+    appLogoPath?: string;
+    /** When true, hides the "Powered by Consenti" badge in the dashboard. Default: false. */
+    hidePoweredBy?: boolean;
 }
 interface ConsentiServerConfig {
     basePath?: string;
@@ -270,6 +255,15 @@ interface ConsentiServerConfig {
     dataRetention?: DataRetentionConfig;
     maxBodySize?: number;
     trustedProxies?: string[];
+    branding?: BrandingConfig;
+    s3Api?: S3ApiConfig;
+    /** When set, every consent record is HMAC-SHA256 signed at create/update time (hex-encoded,
+     * stored in `signature`) and the signature is checked on `GET /consent/:visitorId/verify`.
+     * No-op and no schema burden when unset — opt-in tamper-evidence for server-stored records,
+     * independent of the widget's own cookie-signing (`core.cookieSigningKey`). */
+    consentSigningKey?: string;
+    /** Called after every profile activate/deactivate/delete. isPurge=true means invalidate; false means warm. */
+    handleCache?: (paths: string[], profileId: string, isPurge: boolean) => void;
 }
 interface Tenant {
     id: string;
@@ -278,21 +272,42 @@ 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/*` 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;
+}
 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;
 }
@@ -301,7 +316,6 @@ interface ConsentDbRecord {
     tenantId: string;
     visitorId: string;
     profileId: string;
-    profileVersion: number;
     locale: string;
     consentJson: ConsentValue;
     gpcDetected: boolean;
@@ -309,6 +323,10 @@ interface ConsentDbRecord {
     ageVerified?: boolean;
     parentalConsentToken?: string;
     tcfString?: string;
+    /** HMAC-SHA256 signature over the record's core fields, hex-encoded. Only present when
+     * `consentSigningKey` is configured — opt-in tamper-evidence for server-stored records,
+     * independent of the widget's own cookie-signing (`core.cookieSigningKey`). */
+    signature?: string;
     createdAt: string;
     updatedAt: string;
 }
@@ -343,6 +361,8 @@ interface AdminUser {
     isActive: boolean;
     totpEnabled?: boolean;
     totpSecret?: string;
+    /** Empty array = access to all tenants. Non-empty = restricted to listed tenant IDs. */
+    allowedTenants?: string[];
     createdAt: string;
     updatedAt: string;
 }
@@ -357,6 +377,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;
@@ -368,22 +404,38 @@ interface AuditLog {
     newData?: unknown;
     createdAt: string;
 }
+/** List-view shape for consents — omits the fields not shown in a table row (`consentJson`,
+ * `parentalConsentToken`, `tcfString`, `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' | '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;
@@ -391,11 +443,13 @@ interface CreateConsentInput {
     ageVerified?: boolean;
     parentalConsentToken?: string;
     tcfString?: string;
+    signature?: string;
 }
 interface UpdateConsentInput {
     consentJson: ConsentValue;
     locale?: string;
     gpcDetected?: boolean;
+    signature?: string;
 }
 interface CreateVisitorInput {
     tenantId: string;
@@ -417,6 +471,7 @@ interface CreateUserInput {
     name: string;
     email: string;
     passwordHash: string;
+    allowedTenants?: string[];
 }
 interface UpdateUserInput {
     name?: string;
@@ -425,6 +480,7 @@ interface UpdateUserInput {
     isActive?: boolean;
     totpSecret?: string | null;
     totpEnabled?: boolean;
+    allowedTenants?: string[];
 }
 interface CreateAuditLogInput {
     tenantId: string;
@@ -442,6 +498,8 @@ interface ConsentFilters {
     to?: string;
     page?: number;
     limit?: number;
+    /** Free-text search across visitorId, profileId, locale, source. */
+    q?: string;
 }
 interface VisitorFilters {
     tenantId: string;
@@ -449,6 +507,8 @@ interface VisitorFilters {
     to?: string;
     page?: number;
     limit?: number;
+    /** Free-text search across visitorId, country. */
+    q?: string;
 }
 interface AuditFilters {
     tenantId: string;
@@ -458,12 +518,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 {
@@ -504,6 +576,8 @@ interface CreateApiKeyInput {
     tenantId: string;
     name: string;
     keyHash: string;
+    createdBy?: string;
+    expireBy?: string;
 }
 interface CreateTenantInput {
     name: string;
@@ -522,19 +596,27 @@ interface StorageAdapter {
     deleteProfile(id: string): Promise<void>;
     getProfile(id: string): Promise<Profile | null>;
     getProfiles(tenantId: string): Promise<Profile[]>;
+    findActiveProfileByComplianceGroup(tenantId: string, complianceGroup: string): Promise<Profile | null>;
+    /** Lightweight list — no profile_json blob; single JOIN for template names. */
+    listProfilesSummary(tenantId: 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[]>;
@@ -544,17 +626,26 @@ 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>;
+    purgeExpiredAuditLogs(olderThanDays: number): Promise<number>;
+    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>;
@@ -580,7 +671,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;
@@ -599,6 +691,325 @@ 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 {
+    purpose?: CookiePurpose;
+    listenGpc?: boolean;
+    /**
+     * 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 {
+    text: string;
+    style: ButtonStyle;
+    action: ButtonAction;
+    cookies?: string[] | '*' | '!';
+    url?: 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;
+    showClose?: boolean;
+    showLocaleSwitcher?: boolean;
+    heading?: string;
+    headingTag?: string;
+    htmlText: string;
+    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 {
+    heading: string;
+    headingTag?: string;
+    htmlText: 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: 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;
+}
+/**
+ * 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;
+}
+interface LocaleTranslations {
+    mainBanner: DeepPartial<MainBanner>;
+    gpcBanner?: DeepPartial<GpcBanner>;
+    preferenceModal: DeepPartial<PreferenceModal>;
+}
+interface ProfileTranslations {
+    [locale: string]: LocaleTranslations;
+}
+interface DpdpaConfig {
+    dataFiduciary: string;
+    grievanceEmail: string;
+    purposeDescription?: string;
+}
+interface LocaleTextContent {
+    mainBanner: {
+        heading?: string;
+        htmlText: 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?: Record<string, string>;
+    };
+    preferenceModal: {
+        heading: string;
+        subheading?: string;
+        htmlText?: 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;
+    };
+}
+interface ProfileConfig {
+    id: string;
+    cookies?: CookieMap;
+    defaultLocale: string;
+    /** Days until consent expires and the visitor is asked again (profile-wide). Default: 365. */
+    expiryDays?: number;
+    translations?: ProfileTranslations;
+    mainBanner: MainBanner;
+    gpcBanner?: GpcBanner;
+    preferenceModal: PreferenceModal;
+    darkMode?: boolean;
+    allowedOrigins?: string[];
+    dpdpa?: DpdpaConfig;
+    regulation?: 'gdpr' | 'ccpa' | 'cpra' | 'dpdpa' | 'uk-gdpr' | 'lgpd' | 'pipeda' | 'popia' | 'pdpa-th' | 'appi' | 'kvkk';
+    regulations?: string[];
+    consentTemplateId?: string;
+    uiTemplateId?: string;
+    localeContents?: Record<string, LocaleTextContent>;
+    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: TemplateBannerDef;
+    gpcBanner: TemplateGpcBannerDef;
+    preferenceModal: TemplateModalDef;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ServerConsentTemplate {
+    id: string;
+    tenantId: string;
+    name: string;
+    cookies: CookieMap;
+    categories: CategoryMap;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateConsentTemplateInput {
+    tenantId: string;
+    name: string;
+    cookies: CookieMap;
+    categories: CategoryMap;
+}
+interface UpdateConsentTemplateInput {
+    name?: string;
+    cookies?: CookieMap;
+    categories?: CategoryMap;
+}
+interface CreateUITemplateInput {
+    tenantId: string;
+    name: string;
+    mainBanner: TemplateBannerDef;
+    gpcBanner: TemplateGpcBannerDef;
+    preferenceModal: TemplateModalDef;
+}
+interface UpdateUITemplateInput {
+    name?: string;
+    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;
+    defaultLocale: string;
+    currentLocale: string;
+    locales: string[];
+    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?: ComplianceGroupId;
+    compliances?: string[];
+    complianceConfig?: Record<string, string>;
+    allowedOrigins?: string[];
+    gpcMode?: GpcMode;
+    hidePoweredBy?: boolean;
+    allowReceipt?: boolean;
+    darkMode?: boolean;
+    dpdpa?: DpdpaConfig;
+    showFooterMetadata?: boolean;
+    enhanceAccessibility?: boolean;
+    createdAt?: string;
+    updatedAt?: string;
+}
 
 declare class ProfileRepo {
     private adapter;
@@ -608,13 +1019,25 @@ declare class ProfileRepo {
     delete(id: string): Promise<void>;
     get(id: string): Promise<Profile | null>;
     list(tenantId: string): Promise<Profile[]>;
+    findActiveByComplianceGroup(tenantId: string, complianceGroup: string): Promise<Profile | null>;
 }
 
 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 {
+    private readonly dir;
+    constructor(dir: string);
+    read(profileId: string, locale: string): PublicProfileResponse | null;
+    write(profileId: string, locale: string, response: PublicProfileResponse): void;
+    rebuild(profileId: string, responses: Map<string, PublicProfileResponse>): void;
+    invalidate(profileId: string): void;
+    private path;
 }
 
 declare class ProfileService {
@@ -622,13 +1045,101 @@ declare class ProfileService {
     private audit;
     private tenantId;
     private storage?;
-    constructor(profiles: ProfileRepo, audit: AuditRepo, tenantId?: string, storage?: StorageAdapter | undefined);
+    private eventBus?;
+    private localeCache?;
+    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[], 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>;
-    get(id: string, locale?: string): Promise<Profile | null>;
+    activate(id: string): Promise<Profile>;
+    deactivate(id: string): Promise<Profile>;
+    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[]>;
+    /**
+     * 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[]>;
+    /**
+     * 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).
+     *
+     * @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 {
@@ -638,7 +1149,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 {
@@ -674,7 +1185,20 @@ 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 consentSigningKey?;
+    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, consentSigningKey?: string | undefined);
+    private sign;
+    /**
+     * 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>;
@@ -685,7 +1209,8 @@ declare class ConsentService {
 declare class VisitorService {
     private visitors;
     private tenantId;
-    constructor(visitors: VisitorRepo, tenantId?: string);
+    private eventBus?;
+    constructor(visitors: VisitorRepo, tenantId?: string, eventBus?: EventEmitter | undefined);
     upsert(data: {
         visitorId: string;
         ip?: string;
@@ -721,12 +1246,14 @@ declare class UserService {
         email: string;
         password: string;
         roleId?: string;
+        allowedTenants?: string[];
     }, actorId?: string): Promise<SafeAdminUser>;
     update(id: string, input: {
         name?: string;
         email?: string;
         isActive?: boolean;
         password?: string;
+        allowedTenants?: string[];
     }, actorId?: string): Promise<SafeAdminUser>;
     delete(id: string, actorId?: string): Promise<void>;
     get(id: string): Promise<SafeAdminUser | null>;
@@ -751,20 +1278,25 @@ declare class BetterSqlite3Adapter implements StorageAdapter {
     deleteProfile(id: string): Promise<void>;
     getProfile(id: string): Promise<Profile | null>;
     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>;
@@ -785,7 +1317,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>;
@@ -797,19 +1332,24 @@ 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>;
+    purgeExpiredAuditLogs(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>;
@@ -817,6 +1357,12 @@ declare class BetterSqlite3Adapter implements StorageAdapter {
     getUITemplate(id: string): Promise<ServerUITemplate | null>;
     getUITemplates(tenantId: string): Promise<ServerUITemplate[]>;
     copyUITemplate(id: string, newName: string): Promise<ServerUITemplate>;
+    private mapProfileSummary;
+    private readonly PROFILE_SUMMARY_SQL;
+    listProfilesSummary(tenantId: string): Promise<ProfileSummary[]>;
+    findProfilesUsingConsentTemplate(templateId: string): Promise<ProfileSummary[]>;
+    findProfilesUsingUITemplate(templateId: string): Promise<ProfileSummary[]>;
+    getOptInStats(tenantId: string, filters: OptInFilters): Promise<OptInStats>;
 }
 
 declare class MongoDBAdapter implements StorageAdapter {
@@ -835,20 +1381,23 @@ declare class MongoDBAdapter implements StorageAdapter {
     deleteProfile(id: string): Promise<void>;
     getProfile(id: string): Promise<Profile | null>;
     getProfiles(tenantId: string): Promise<Profile[]>;
+    findActiveProfileByComplianceGroup(tenantId: string, complianceGroup: string): Promise<Profile | null>;
     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>;
     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[]>;
@@ -871,32 +1420,43 @@ 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>;
+    purgeExpiredAuditLogs(olderThanDays: number): Promise<number>;
+    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>;
     getUITemplate(): Promise<never>;
     getUITemplates(): Promise<never>;
     copyUITemplate(): Promise<never>;
+    listProfilesSummary(): Promise<never[]>;
+    findProfilesUsingConsentTemplate(): Promise<never[]>;
+    findProfilesUsingUITemplate(): Promise<never[]>;
+    getOptInStats(): Promise<never>;
 }
 
 declare class MySQLAdapter implements StorageAdapter {
@@ -914,20 +1474,23 @@ declare class MySQLAdapter implements StorageAdapter {
     deleteProfile(id: string): Promise<void>;
     getProfile(id: string): Promise<Profile | null>;
     getProfiles(tenantId: string): Promise<Profile[]>;
+    findActiveProfileByComplianceGroup(tenantId: string, complianceGroup: string): Promise<Profile | null>;
     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>;
-    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[]>;
@@ -950,32 +1513,43 @@ 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>;
+    purgeExpiredAuditLogs(olderThanDays: number): Promise<number>;
+    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>;
     getUITemplate(): Promise<never>;
     getUITemplates(): Promise<never>;
     copyUITemplate(): Promise<never>;
+    listProfilesSummary(): Promise<never[]>;
+    findProfilesUsingConsentTemplate(): Promise<never[]>;
+    findProfilesUsingUITemplate(): Promise<never[]>;
+    getOptInStats(): Promise<never>;
 }
 
 declare class PostgreSQLAdapter implements StorageAdapter {
@@ -992,20 +1566,23 @@ declare class PostgreSQLAdapter implements StorageAdapter {
     deleteProfile(id: string): Promise<void>;
     getProfile(id: string): Promise<Profile | null>;
     getProfiles(tenantId: string): Promise<Profile[]>;
+    findActiveProfileByComplianceGroup(tenantId: string, complianceGroup: string): Promise<Profile | null>;
     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>;
-    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[]>;
@@ -1028,39 +1605,170 @@ 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>;
+    purgeExpiredAuditLogs(olderThanDays: number): Promise<number>;
+    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>;
     getUITemplate(): Promise<never>;
     getUITemplates(): Promise<never>;
     copyUITemplate(): Promise<never>;
+    listProfilesSummary(): 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;
     handler: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
-    fastifyPlugin: (fastify: {
+    fastifyHandler: (fastify: {
         all: (path: string, handler: (req: {
             raw: IncomingMessage;
         }, reply: {
@@ -1078,8 +1786,9 @@ declare function createConsenti(userConfig: ConsentiServerConfig): {
         user: UserService;
     };
     storage: StorageAdapter;
-    eventBus: EventEmitter<[never]>;
+    eventBus: EventEmitter<any>;
+    ready: Promise<void>;
     destroy: () => Promise<void>;
 };
 
-export { type AdminUser, type AuditLog, 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 };