@consenti/api 0.5.0 → 0.6.0

package/dist/index.d.cts

@@ -140,8 +140,15 @@ type GeoResult = {
 };
 type CountryResolverFn = (ctx: {
     ip: string;
+    /** The widget's `navigator.language` (single tag), or — for requests without the widget's hints —
+     * the raw `Accept-Language` header value. */
     language: string;
+    /** Every language the visitor's browser prefers, most preferred first (the widget's
+     * `navigator.languages`; parsed from `Accept-Language` otherwise). Empty when unknown. */
+    languages: string[];
     timezone: string;
+    /** The locale the widget asked for (`core.locale`); `''` when the request carried none. */
+    locale: string;
 }) => Promise<GeoResult>;
 interface S3ApiConfig {
     enabled: boolean;
@@ -216,6 +223,10 @@ interface OptInStats {
 }
 interface ComplianceMapData {
     version: string;
+    /** `true` (default): this map replaces the embedded one entirely, so only the countries listed here
+     * resolve (server side). `false`: `countries` is merged over the embedded map — a listed country
+     * replaces its embedded entry wholesale, every unlisted country keeps its built-in mapping. */
+    override?: boolean;
     countries: Record<string, CountryComplianceEntry>;
 }
 interface CountryComplianceEntry {
@@ -239,8 +250,11 @@ interface ComplianceConfig {
     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'`. */
+     * fallback if absent), or an inline operator-supplied `ComplianceMapData` object. By default the
+     * supplied map replaces the embedded one; set `override: false` on the document to merge its
+     * `countries` over the embedded map instead (listed countries replace their embedded entry, the
+     * rest keep the built-in mapping). 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;
@@ -401,6 +415,9 @@ interface ConsentDbRecord {
     tenantId: string;
     visitorId: string;
     profileId: string;
+    /** The profile's `version` when this consent was last given — with `profileId`, pins the exact
+     * on-disk snapshot (the banner text the visitor saw). Absent on records from before it was tracked. */
+    profileVersion?: number;
     locale: string;
     consentJson: ConsentValue;
     gpcDetected: boolean;
@@ -421,6 +438,8 @@ interface ConsentHistoryEntry {
     tenantId: string;
     consentRecordId: string;
     visitorId: string;
+    /** The profile version in force for this change — see {@link ConsentDbRecord.profileVersion}. */
+    profileVersion?: number;
     oldJson: ConsentValue | null;
     newJson: ConsentValue;
     action: 'created' | 'updated' | 'withdrawn';
@@ -523,6 +542,7 @@ interface CreateConsentInput {
     tenantId: string;
     visitorId: string;
     profileId: string;
+    profileVersion?: number;
     locale: string;
     consentJson: ConsentValue;
     gpcDetected: boolean;
@@ -535,6 +555,7 @@ interface CreateConsentInput {
 }
 interface UpdateConsentInput {
     consentJson: ConsentValue;
+    profileVersion?: number;
     locale?: string;
     gpcDetected?: boolean;
     signature?: string;
@@ -1212,7 +1233,7 @@ declare class ProfileService {
      * unchanged from `previousVersion` by the worker — never silently dropped.
      */
     private writeLocaleFiles;
-    create(input: Omit<CreateProfileInput, 'tenantId'>): Promise<Profile>;
+    create(input: Omit<CreateProfileInput, 'tenantId'>, actorId?: string): 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
@@ -1220,16 +1241,16 @@ declare class ProfileService {
      * 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>;
+    copy(id: string, name?: string, actorId?: 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>;
+    update(id: string, input: UpdateProfileInput, actorId?: string): Promise<Profile>;
+    delete(id: string, actorId?: string): Promise<void>;
+    activate(id: string, actorId?: string): Promise<Profile>;
+    deactivate(id: string, actorId?: string): Promise<Profile>;
     private runDeactivate;
     get(id: string): Promise<Profile | null>;
     /**
@@ -1252,6 +1273,14 @@ declare class ProfileService {
      * tree is the only thing this reads.
      */
     listVersions(profileId: string): Promise<ProfileVersionEntry[]>;
+    /**
+     * The newest on-disk snapshot of a profile whose DB row has been deleted — what a surviving
+     * consent record's `profileId` resolves to. Null when nothing was ever written for that id.
+     * `version` is the one a consent record was given (`ConsentDbRecord.profileVersion`); records
+     * from before it was tracked have none, and so does a version whose files are gone — both
+     * resolve to the newest snapshot.
+     */
+    getArchivedSnapshot(profileId: string, version?: number): Promise<PublicProfileResponse | null>;
     /** Works for archived profiles too — see `listVersions()`. */
     getVersionFile(profileId: string, version: string, locale: string): Promise<string | null>;
     /**
@@ -1348,7 +1377,8 @@ declare class ConsentService {
     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 archivedSnapshot?;
+    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, archivedSnapshot?: ((profileId: string, version?: number) => Promise<PublicProfileResponse | null>) | undefined);
     private sign;
     /** Fails closed: no `storage` to check against means unconfirmed, never assumed confirmed. */
     private isTcfConfirmed;
@@ -1433,11 +1463,13 @@ declare class BetterSqlite3Adapter implements StorageAdapter {
     private config;
     private db;
     private cache;
+    private dbPath;
     constructor(config: StorageConfig);
     private stmt;
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     migrate(): Promise<void>;
+    private migrateToV2;
     private mapProfile;
     createProfile(data: CreateProfileInput): Promise<Profile>;
     updateProfile(id: string, data: UpdateProfileInput): Promise<Profile>;
@@ -1539,6 +1571,8 @@ declare class MongoDBAdapter implements StorageAdapter {
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     migrate(): Promise<void>;
+    /** Collections from before the `consenti_` prefix exist and no prefixed set does: stop, don't start empty. */
+    private refuseLegacyCollections;
     private createIndexes;
     private seed;
     createProfile(data: CreateProfileInput): Promise<Profile>;
@@ -1635,6 +1669,7 @@ declare class MySQLAdapter implements StorageAdapter {
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     migrate(): Promise<void>;
+    private migrateToV2;
     private seed;
     createProfile(data: CreateProfileInput): Promise<Profile>;
     updateProfile(id: string, data: UpdateProfileInput): Promise<Profile>;
@@ -1729,6 +1764,7 @@ declare class PostgreSQLAdapter implements StorageAdapter {
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     migrate(): Promise<void>;
+    private migrateToV2;
     private seedTx;
     createProfile(data: CreateProfileInput): Promise<Profile>;
     updateProfile(id: string, data: UpdateProfileInput): Promise<Profile>;

package/dist/index.d.ts

@@ -140,8 +140,15 @@ type GeoResult = {
 };
 type CountryResolverFn = (ctx: {
     ip: string;
+    /** The widget's `navigator.language` (single tag), or — for requests without the widget's hints —
+     * the raw `Accept-Language` header value. */
     language: string;
+    /** Every language the visitor's browser prefers, most preferred first (the widget's
+     * `navigator.languages`; parsed from `Accept-Language` otherwise). Empty when unknown. */
+    languages: string[];
     timezone: string;
+    /** The locale the widget asked for (`core.locale`); `''` when the request carried none. */
+    locale: string;
 }) => Promise<GeoResult>;
 interface S3ApiConfig {
     enabled: boolean;
@@ -216,6 +223,10 @@ interface OptInStats {
 }
 interface ComplianceMapData {
     version: string;
+    /** `true` (default): this map replaces the embedded one entirely, so only the countries listed here
+     * resolve (server side). `false`: `countries` is merged over the embedded map — a listed country
+     * replaces its embedded entry wholesale, every unlisted country keeps its built-in mapping. */
+    override?: boolean;
     countries: Record<string, CountryComplianceEntry>;
 }
 interface CountryComplianceEntry {
@@ -239,8 +250,11 @@ interface ComplianceConfig {
     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'`. */
+     * fallback if absent), or an inline operator-supplied `ComplianceMapData` object. By default the
+     * supplied map replaces the embedded one; set `override: false` on the document to merge its
+     * `countries` over the embedded map instead (listed countries replace their embedded entry, the
+     * rest keep the built-in mapping). 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;
@@ -401,6 +415,9 @@ interface ConsentDbRecord {
     tenantId: string;
     visitorId: string;
     profileId: string;
+    /** The profile's `version` when this consent was last given — with `profileId`, pins the exact
+     * on-disk snapshot (the banner text the visitor saw). Absent on records from before it was tracked. */
+    profileVersion?: number;
     locale: string;
     consentJson: ConsentValue;
     gpcDetected: boolean;
@@ -421,6 +438,8 @@ interface ConsentHistoryEntry {
     tenantId: string;
     consentRecordId: string;
     visitorId: string;
+    /** The profile version in force for this change — see {@link ConsentDbRecord.profileVersion}. */
+    profileVersion?: number;
     oldJson: ConsentValue | null;
     newJson: ConsentValue;
     action: 'created' | 'updated' | 'withdrawn';
@@ -523,6 +542,7 @@ interface CreateConsentInput {
     tenantId: string;
     visitorId: string;
     profileId: string;
+    profileVersion?: number;
     locale: string;
     consentJson: ConsentValue;
     gpcDetected: boolean;
@@ -535,6 +555,7 @@ interface CreateConsentInput {
 }
 interface UpdateConsentInput {
     consentJson: ConsentValue;
+    profileVersion?: number;
     locale?: string;
     gpcDetected?: boolean;
     signature?: string;
@@ -1212,7 +1233,7 @@ declare class ProfileService {
      * unchanged from `previousVersion` by the worker — never silently dropped.
      */
     private writeLocaleFiles;
-    create(input: Omit<CreateProfileInput, 'tenantId'>): Promise<Profile>;
+    create(input: Omit<CreateProfileInput, 'tenantId'>, actorId?: string): 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
@@ -1220,16 +1241,16 @@ declare class ProfileService {
      * 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>;
+    copy(id: string, name?: string, actorId?: 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>;
+    update(id: string, input: UpdateProfileInput, actorId?: string): Promise<Profile>;
+    delete(id: string, actorId?: string): Promise<void>;
+    activate(id: string, actorId?: string): Promise<Profile>;
+    deactivate(id: string, actorId?: string): Promise<Profile>;
     private runDeactivate;
     get(id: string): Promise<Profile | null>;
     /**
@@ -1252,6 +1273,14 @@ declare class ProfileService {
      * tree is the only thing this reads.
      */
     listVersions(profileId: string): Promise<ProfileVersionEntry[]>;
+    /**
+     * The newest on-disk snapshot of a profile whose DB row has been deleted — what a surviving
+     * consent record's `profileId` resolves to. Null when nothing was ever written for that id.
+     * `version` is the one a consent record was given (`ConsentDbRecord.profileVersion`); records
+     * from before it was tracked have none, and so does a version whose files are gone — both
+     * resolve to the newest snapshot.
+     */
+    getArchivedSnapshot(profileId: string, version?: number): Promise<PublicProfileResponse | null>;
     /** Works for archived profiles too — see `listVersions()`. */
     getVersionFile(profileId: string, version: string, locale: string): Promise<string | null>;
     /**
@@ -1348,7 +1377,8 @@ declare class ConsentService {
     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 archivedSnapshot?;
+    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, archivedSnapshot?: ((profileId: string, version?: number) => Promise<PublicProfileResponse | null>) | undefined);
     private sign;
     /** Fails closed: no `storage` to check against means unconfirmed, never assumed confirmed. */
     private isTcfConfirmed;
@@ -1433,11 +1463,13 @@ declare class BetterSqlite3Adapter implements StorageAdapter {
     private config;
     private db;
     private cache;
+    private dbPath;
     constructor(config: StorageConfig);
     private stmt;
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     migrate(): Promise<void>;
+    private migrateToV2;
     private mapProfile;
     createProfile(data: CreateProfileInput): Promise<Profile>;
     updateProfile(id: string, data: UpdateProfileInput): Promise<Profile>;
@@ -1539,6 +1571,8 @@ declare class MongoDBAdapter implements StorageAdapter {
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     migrate(): Promise<void>;
+    /** Collections from before the `consenti_` prefix exist and no prefixed set does: stop, don't start empty. */
+    private refuseLegacyCollections;
     private createIndexes;
     private seed;
     createProfile(data: CreateProfileInput): Promise<Profile>;
@@ -1635,6 +1669,7 @@ declare class MySQLAdapter implements StorageAdapter {
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     migrate(): Promise<void>;
+    private migrateToV2;
     private seed;
     createProfile(data: CreateProfileInput): Promise<Profile>;
     updateProfile(id: string, data: UpdateProfileInput): Promise<Profile>;
@@ -1729,6 +1764,7 @@ declare class PostgreSQLAdapter implements StorageAdapter {
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     migrate(): Promise<void>;
+    private migrateToV2;
     private seedTx;
     createProfile(data: CreateProfileInput): Promise<Profile>;
     updateProfile(id: string, data: UpdateProfileInput): Promise<Profile>;