@cookiemunch/sdk 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -390,6 +390,20 @@ interface VerifyWebhookInput {
  */
 declare function verifyWebhookSignature(input: VerifyWebhookInput): boolean;
 
+interface MintConsentSyncTokenInput {
+    /** The site's consent-sync secret (`cmss_…`). */
+    secret: string;
+    /** The site the token is for. A token for one site is refused by every other. */
+    cbid: string;
+    /** Who is signed in: 1–128 of `A-Z a-z 0-9 . _ : @ + / = ~ -`. Use an opaque id. */
+    subject: string;
+    /** Lifetime in seconds. Default 3600; at most 86400 (Cookie Munch refuses longer). */
+    ttlSeconds?: number;
+    /** Current time in ms (injectable for tests). */
+    now?: number;
+}
+declare function mintConsentSyncToken(input: MintConsentSyncTokenInput): string;
+
 /**
  * @cookiemunch/sdk — a small, typed REST client for the Cookie Munch Developer API
  * (the /v1 surface). Construct it with an API key; the org is derived server-side
@@ -400,6 +414,11 @@ declare function verifyWebhookSignature(input: VerifyWebhookInput): boolean;
  *   const sites = await fc.sites.list();
  */
 
+/**
+ * This package's version, sent in the default User-Agent. Cloudflare answers a request with
+ * no recognisable User-Agent with `403 error code: 1010`; a test pins this to package.json.
+ */
+declare const SDK_VERSION = "0.5.0";
 interface CookieMunchOptions {
     apiKey: string;
     /** "https://api.cookiemunch.net" — the /v1 prefix is appended automatically. */
@@ -411,12 +430,14 @@ interface CookieMunchOptions {
      * declare is refused (`400 unknown_field`, with `field`) instead of ignored. Catches typos.
      */
     strictUnknownFields?: boolean;
+    /** The `User-Agent` sent on every request. Default `cookiemunch-js/<version>`. */
+    userAgent?: string;
 }
 /**
  * Thrown for any non-2xx response. `message` is the server's `error` field when present;
  * `code` is populated from the server's `code` field whenever the error body carries one
- * (e.g. banner-library conflicts, docs-admin checks) — not only for scoped-key
- * (`insufficient_scope`) responses. It's `undefined` when the body has no `code`.
+ * (e.g. `forbidden` on a scope failure, whose `message` is `insufficient_scope`,
+ * or `banner_in_use` on a banner-library conflict). It's `undefined` when the body has no `code`.
  */
 declare class CookieMunchApiError extends Error {
     readonly status: number;
@@ -448,9 +469,12 @@ interface CategorizedCookie {
     /**
      * Why a person should look at it. Visitors see unclassified and category ones under
      * "Unclassified"; `retired_but_seen` = retired, but a crawl or a visit saw it since, so the
-     * site still sets it and it is listed again.
+     * site still sets it and it is listed again. `awaiting_corroboration` / `suspicious_report` =
+     * only visitors reported it (not enough of them yet, or in one injection-shaped report), owner
+     * views only; `foreign_cmp` = another consent platform's cookie, filed unclassified;
+     * `not_seen_recently` = unseen for the site's `staleAfterDays`, owner views only.
      */
-    review?: 'unclassified' | 'category_disabled' | 'category_unknown' | 'retired_but_seen';
+    review?: 'unclassified' | 'category_disabled' | 'category_unknown' | 'retired_but_seen' | 'awaiting_corroboration' | 'suspicious_report' | 'foreign_cmp' | 'not_seen_recently';
     /** Epoch-ms a crawl or a real visit last saw it. Absent on older rows. */
     lastSeenAt?: number;
     /** Owner views only: the site owner retired this cookie (see `sites.retireCookie`). */
@@ -529,7 +553,7 @@ interface DeclaredCookie extends DeclaredCookieInput {
     vendor?: string;
 }
 /** A platform whose cookies and storage a preset declares. */
-type CookiePresetVendor = 'atlas' | 'forumulate' | 'chatly' | 'cookiemunch';
+type CookiePresetVendor = 'atlas' | 'forumulate' | 'chatly' | 'cookiemunch' | 'referally';
 /** Where a vendor's live manifest will come from, and whether it exists yet. */
 interface CookiePresetManifest {
     status: 'builtin' | 'waiting_on_vendor';
@@ -537,13 +561,15 @@ interface CookiePresetManifest {
     item?: string;
     contract?: string;
 }
-/** Preset parameters: Atlas `frontendApiHost`/`crossSubdomainCookies`; Chatly `publicId`/`dragging`/`category`. */
+/** Preset parameters: Atlas `frontendApiHost`/`crossSubdomainCookies`; Chatly `publicId`/`dragging`/`category`; Referally `cookieDomain`/`cookieDays`/`category`. */
 interface CookiePresetParams {
     frontendApiHost?: string;
     crossSubdomainCookies?: boolean;
     publicId?: string;
     dragging?: boolean;
     category?: string;
+    cookieDomain?: string;
+    cookieDays?: number;
 }
 /** One preset in GET /v1/sites/:cbid/cookies/presets. */
 interface CookiePreset {
@@ -1315,6 +1341,38 @@ type RightsCaptchaProvider = 'turnstile' | 'hcaptcha' | 'recaptcha_v2' | 'recapt
  * The rights page's captcha in force: your own keys (`own`, recommended) or none (`off`, the default).
  * Cookie Munch's own captcha is never used on rights pages. The secret is never returned.
  */
+/** Whether hosted consent sync is set up for a site. The secret itself is never read back. */
+interface ConsentSyncSecret {
+    cbid: string;
+    configured: boolean;
+    secretLast4: string | null;
+    /** Epoch ms the current secret was minted. */
+    createdAt: number | null;
+}
+/**
+ * Who a preference-centre token is for: a site of your organisation and exactly one of `email`
+ * (resolved as the emailed preference link resolves it) or `subjectId`.
+ */
+type CenterTokenInput = {
+    cbid: string;
+    ttlSeconds?: number;
+} & ({
+    email: string;
+    subjectId?: never;
+} | {
+    subjectId: string;
+    email?: never;
+});
+/** A preference-centre token. A credential: hand it to `CookieMunch.setSubjectToken`, never put it in a shared URL or a log. */
+interface CenterToken {
+    token: string;
+    /** ISO 8601. */
+    expiresAt: string;
+}
+/** A freshly minted or rotated consent-sync secret: `secret` is shown this once. */
+interface ConsentSyncSecretMinted extends ConsentSyncSecret {
+    secret: string;
+}
 interface RightsCaptcha {
     /** `site`: the site's own setting; `org`: the organisation default; `default`: neither (off). */
     source: 'site' | 'org' | 'default';
@@ -1395,6 +1453,24 @@ interface RightsIdentityInput {
      */
     trustEmailClaim?: boolean;
 }
+/** The organisation's own data-controller identity (GET /v1/org/controller). */
+interface OrgControllerIdentity {
+    /** False when none is set; then only `updatedAt` (null) is present. */
+    set: boolean;
+    legalName?: string;
+    contactEmail?: string;
+    address?: string;
+    /** The Data Protection Officer: a name, an email address, or both. */
+    dpoContact?: string;
+    updatedAt: number | null;
+}
+/** Replaces the identity: a field left out is removed. `legalName` is required. */
+interface OrgControllerInput {
+    legalName: string;
+    contactEmail?: string;
+    address?: string;
+    dpoContact?: string;
+}
 interface MailProviderTestResult {
     ok: boolean;
     sentTo: string;
@@ -2250,7 +2326,7 @@ interface CookieMunchClient {
             dryRun: true;
             retired: RetiredCookie[];
         }>;
-        /** Every declaration preset (atlas, forumulate, chatly, cookiemunch): params, what it declared here, manifest status. */
+        /** Every declaration preset (atlas, forumulate, chatly, cookiemunch, referally): params, what it declared here, manifest status. */
         cookiePresets(cbid: string): Promise<{
             presets: CookiePreset[];
         }>;
@@ -2705,6 +2781,16 @@ interface CookieMunchClient {
         /** One subject's record. A subject with none has empty `purposes`. */
         get(subjectId: string): Promise<PreferenceRecord>;
     };
+    /** The hosted preference centre, opened for a visitor your server has signed in. */
+    preferenceCenter: {
+        /**
+         * Mint a preference-centre token (POST /v1/preference-center/tokens) for the page to pass to
+         * `CookieMunch.setSubjectToken`. Server-side only: the token opens that subject's subscriptions
+         * and profile until `expiresAt`. `ttlSeconds` defaults to 3600, at most 86400. Needs
+         * subscriptions:write and profile:write, plus identity:read when minting by email.
+         */
+        mintToken(input: CenterTokenInput): Promise<CenterToken>;
+    };
     members: {
         list(): Promise<Member[]>;
         invite(email: string, role: string): Promise<{
@@ -2773,6 +2859,17 @@ interface CookieMunchClient {
             /** Send a test through your provider. `to` defaults to the reply-to, else the from address. */
             test(to?: string): Promise<MailProviderTestResult>;
         };
+        /**
+         * Your organisation's own data-controller identity: who every rights notice names, before any site config
+         * `controller` block. Needed for a notice on a request filed without a cbid when you have several sites.
+         * An unscoped key, or `rights:write`.
+         */
+        controller: {
+            get(): Promise<OrgControllerIdentity>;
+            /** Replace it: a field left out is removed. */
+            set(input: OrgControllerInput): Promise<OrgControllerIdentity>;
+            remove(): Promise<void>;
+        };
         /**
          * The default captcha for your rights pages, for every site without its own (`rightsCaptcha`): your own
          * keys (recommended) or off. Without one, rights pages have no captcha.
@@ -2854,6 +2951,18 @@ interface CookieMunchClient {
     rightsLinks: {
         create(cbid: string, input: RightsLinkInput): Promise<RightsLink>;
     };
+    /**
+     * A site's consent-sync signing secret: your server signs consent-sync tokens with it
+     * (`mintConsentSyncToken`) so a visitor's decision syncs across their browsers. `rotate` mints the
+     * first one or replaces it (the old one stops at once) and is the only time the secret is returned.
+     * Reading needs sites:read; rotate and remove need sites:write and consent:write.
+     */
+    consentSyncSecret: {
+        get(cbid: string): Promise<ConsentSyncSecret>;
+        rotate(cbid: string): Promise<ConsentSyncSecretMinted>;
+        /** Turn hosted consent sync off for the site. */
+        remove(cbid: string): Promise<ConsentSyncSecret>;
+    };
     /**
      * A site's rights-page captcha: your own Turnstile, hCaptcha or reCAPTCHA keys (recommended), or off. A site
      * without its own setting uses the organisation default (`org.rightsCaptcha`), else off. Requires sites:read / sites:write.
@@ -2910,4 +3019,4 @@ interface CookieMunchClient {
 }
 declare function createCookieMunch(opts: CookieMunchOptions): CookieMunchClient;
 
-export { type AbResult, type AccountOrg, type AccountOrgs, type AdPersonalizationInput, type AiInspectInput, type AiInspectResult, type ApiKey, type ApiKeyIssueInput, type ApiKeyIssued, type ApiKeyPrefix, type ApiKeyReport, type ApiKeyUpdate, type AppliedImport, type AssetUpload, type AuditEntry, type BannerRecord, type BannerSummary, type BlockedReport, type BrandExtractionResult, type BrandKit, type BrandKitCreate, type BrandSuggestion, type BulkSiteInput, type BulkSiteResult, type ButtonParityFinding, type ButtonParityLint, type ButtonParityScan, type CategorizedCookie, type ChildKeyInput, type ConfigChange, type ConfigDryRun, type ConfigWarning, type ConsentDay, type ConsentDecisionInput, type ConsentIngestInput, type ConsentLogRow, type CookieDeclaration, CookieMunchApiError, type CookieMunchClient, type CookieMunchOptions, type CookiePreset, type CookiePresetManifest, type CookiePresetParams, type CookiePresetResult, type CookiePresetVendor, type CspSources, type DeclarationDiff, type DeclarationDryRun, type DeclarationWarning, type DeclaredCookie, type DeclaredCookieInput, type DnsRecordInstruction, type DsarCreate, type DsarEraseResult, type DsarExecutor, type DsarExecutorCreated, type DsarExecutorDryRun, type DsarExecutorInput, type DsarExecutorPatch, type DsarExecutorPresetInput, type DsarExportResult, type DsarRequest, type DsarStatus, type DsarTask, type DsarTaskEvent, type DsarTaskExport, type DsarTaskLogEntry, type DsarTaskOutcome, type DsarType, type EnforcementRuleInput, type ExecutorHealth, type ExecutorPresetName, type ExecutorPresetUpgrade, type ExecutorPresets, type ExecutorProfile, type ExecutorTestInput, type ExecutorTestResult, type ExecutorWebhookDelivery, type ExecutorWebhookTestResult, type FlowIssue, type FlowOp, type FlowOpResponse, type FulfillmentOp, type HealthRow, type Identifier, type Identity, type ImportedCookie, type ImportedDeclaration, type InstallSnippet, type IntegrationHealthReport, type LegalBasis, type LogQuery, type MailProvider, type MailProviderInput, type MailProviderKind, type MailProviderTestResult, type Member, type ObservedPurgeResult, type OptInMethod, type Org, type OrgUpdate, type ParityControlSummary, type PartnerCatalogEntry, type PartnerId, type PartnerLink, type PartnerLinkCreate, type PlanSource, type PolicyOptions, type PreferenceItem, type PreferenceRecord, type PreviewToken, type PreviewTokenOptions, type ProfileAttributeInput, type ProvisionRequest, type ProvisionResult, type ProvisionStep, type PublicDsarFiled, type PublicDsarPending, type PublicVerification, type PutConfigOptions, type RangeQuery, type Regulation, type RegulationSummary, type RegulatoryFeedResult, type ResellerChild, type ResellerChildCreate, type ResellerChildList, type ResellerChildPatch, type RetiredCookie, type RightKind, type RightsCaptcha, type RightsCaptchaInput, type RightsCaptchaProvider, type RightsIdentity, type RightsIdentityInput, type RightsIdentityType, type RightsLink, type RightsLinkInput, type RightsPageDocument, type RightsPageDomain, type RightsPageDomainList, type RightsPageDraft, type RightsPageDraftConflict, type RightsPageDryRun, type RightsPageIssue, type RightsPagePublishResult, type RightsPagePublished, type RightsPagePublisher, type RightsPageVersions, type RightsPageWriteOptions, type RiskScore, type RopaEntry, type RopaInput, type ScanResult, type ScanStatus, type ScoredVendor, type ScrollbarTheme, type SessionAnalysisInput, type SignedReceipt, type Site, type SiteConfig, type SiteCookie, type SiteCreate, type SiteFlow, type SiteUpdate, type SiteUpdateResult, type SnippetOptions, type StorageType, type SubscriptionTopicInput, type SuggestedRejectStyle, type SupportedLanguage, type Usage, type VendorInput, type VendorRecord, type VerifyResult, type VerifyWebhookInput, type WebhookCreate, type WebhookDeadLetter, type WebhookKeyForm, type WebhookStage, type WebhookSubscription, type WebhookTestResult, type WebhookUpdate, createCookieMunch, verifyWebhookSignature };
+export { type AbResult, type AccountOrg, type AccountOrgs, type AdPersonalizationInput, type AiInspectInput, type AiInspectResult, type ApiKey, type ApiKeyIssueInput, type ApiKeyIssued, type ApiKeyPrefix, type ApiKeyReport, type ApiKeyUpdate, type AppliedImport, type AssetUpload, type AuditEntry, type BannerRecord, type BannerSummary, type BlockedReport, type BrandExtractionResult, type BrandKit, type BrandKitCreate, type BrandSuggestion, type BulkSiteInput, type BulkSiteResult, type ButtonParityFinding, type ButtonParityLint, type ButtonParityScan, type CategorizedCookie, type CenterToken, type CenterTokenInput, type ChildKeyInput, type ConfigChange, type ConfigDryRun, type ConfigWarning, type ConsentDay, type ConsentDecisionInput, type ConsentIngestInput, type ConsentLogRow, type ConsentSyncSecret, type ConsentSyncSecretMinted, type CookieDeclaration, CookieMunchApiError, type CookieMunchClient, type CookieMunchOptions, type CookiePreset, type CookiePresetManifest, type CookiePresetParams, type CookiePresetResult, type CookiePresetVendor, type CspSources, type DeclarationDiff, type DeclarationDryRun, type DeclarationWarning, type DeclaredCookie, type DeclaredCookieInput, type DnsRecordInstruction, type DsarCreate, type DsarEraseResult, type DsarExecutor, type DsarExecutorCreated, type DsarExecutorDryRun, type DsarExecutorInput, type DsarExecutorPatch, type DsarExecutorPresetInput, type DsarExportResult, type DsarRequest, type DsarStatus, type DsarTask, type DsarTaskEvent, type DsarTaskExport, type DsarTaskLogEntry, type DsarTaskOutcome, type DsarType, type EnforcementRuleInput, type ExecutorHealth, type ExecutorPresetName, type ExecutorPresetUpgrade, type ExecutorPresets, type ExecutorProfile, type ExecutorTestInput, type ExecutorTestResult, type ExecutorWebhookDelivery, type ExecutorWebhookTestResult, type FlowIssue, type FlowOp, type FlowOpResponse, type FulfillmentOp, type HealthRow, type Identifier, type Identity, type ImportedCookie, type ImportedDeclaration, type InstallSnippet, type IntegrationHealthReport, type LegalBasis, type LogQuery, type MailProvider, type MailProviderInput, type MailProviderKind, type MailProviderTestResult, type Member, type MintConsentSyncTokenInput, type ObservedPurgeResult, type OptInMethod, type Org, type OrgControllerIdentity, type OrgControllerInput, type OrgUpdate, type ParityControlSummary, type PartnerCatalogEntry, type PartnerId, type PartnerLink, type PartnerLinkCreate, type PlanSource, type PolicyOptions, type PreferenceItem, type PreferenceRecord, type PreviewToken, type PreviewTokenOptions, type ProfileAttributeInput, type ProvisionRequest, type ProvisionResult, type ProvisionStep, type PublicDsarFiled, type PublicDsarPending, type PublicVerification, type PutConfigOptions, type RangeQuery, type Regulation, type RegulationSummary, type RegulatoryFeedResult, type ResellerChild, type ResellerChildCreate, type ResellerChildList, type ResellerChildPatch, type RetiredCookie, type RightKind, type RightsCaptcha, type RightsCaptchaInput, type RightsCaptchaProvider, type RightsIdentity, type RightsIdentityInput, type RightsIdentityType, type RightsLink, type RightsLinkInput, type RightsPageDocument, type RightsPageDomain, type RightsPageDomainList, type RightsPageDraft, type RightsPageDraftConflict, type RightsPageDryRun, type RightsPageIssue, type RightsPagePublishResult, type RightsPagePublished, type RightsPagePublisher, type RightsPageVersions, type RightsPageWriteOptions, type RiskScore, type RopaEntry, type RopaInput, SDK_VERSION, type ScanResult, type ScanStatus, type ScoredVendor, type ScrollbarTheme, type SessionAnalysisInput, type SignedReceipt, type Site, type SiteConfig, type SiteCookie, type SiteCreate, type SiteFlow, type SiteUpdate, type SiteUpdateResult, type SnippetOptions, type StorageType, type SubscriptionTopicInput, type SuggestedRejectStyle, type SupportedLanguage, type Usage, type VendorInput, type VendorRecord, type VerifyResult, type VerifyWebhookInput, type WebhookCreate, type WebhookDeadLetter, type WebhookKeyForm, type WebhookStage, type WebhookSubscription, type WebhookTestResult, type WebhookUpdate, createCookieMunch, mintConsentSyncToken, verifyWebhookSignature };

package/dist/index.d.ts

@@ -390,6 +390,20 @@ interface VerifyWebhookInput {
  */
 declare function verifyWebhookSignature(input: VerifyWebhookInput): boolean;
 
+interface MintConsentSyncTokenInput {
+    /** The site's consent-sync secret (`cmss_…`). */
+    secret: string;
+    /** The site the token is for. A token for one site is refused by every other. */
+    cbid: string;
+    /** Who is signed in: 1–128 of `A-Z a-z 0-9 . _ : @ + / = ~ -`. Use an opaque id. */
+    subject: string;
+    /** Lifetime in seconds. Default 3600; at most 86400 (Cookie Munch refuses longer). */
+    ttlSeconds?: number;
+    /** Current time in ms (injectable for tests). */
+    now?: number;
+}
+declare function mintConsentSyncToken(input: MintConsentSyncTokenInput): string;
+
 /**
  * @cookiemunch/sdk — a small, typed REST client for the Cookie Munch Developer API
  * (the /v1 surface). Construct it with an API key; the org is derived server-side
@@ -400,6 +414,11 @@ declare function verifyWebhookSignature(input: VerifyWebhookInput): boolean;
  *   const sites = await fc.sites.list();
  */
 
+/**
+ * This package's version, sent in the default User-Agent. Cloudflare answers a request with
+ * no recognisable User-Agent with `403 error code: 1010`; a test pins this to package.json.
+ */
+declare const SDK_VERSION = "0.5.0";
 interface CookieMunchOptions {
     apiKey: string;
     /** "https://api.cookiemunch.net" — the /v1 prefix is appended automatically. */
@@ -411,12 +430,14 @@ interface CookieMunchOptions {
      * declare is refused (`400 unknown_field`, with `field`) instead of ignored. Catches typos.
      */
     strictUnknownFields?: boolean;
+    /** The `User-Agent` sent on every request. Default `cookiemunch-js/<version>`. */
+    userAgent?: string;
 }
 /**
  * Thrown for any non-2xx response. `message` is the server's `error` field when present;
  * `code` is populated from the server's `code` field whenever the error body carries one
- * (e.g. banner-library conflicts, docs-admin checks) — not only for scoped-key
- * (`insufficient_scope`) responses. It's `undefined` when the body has no `code`.
+ * (e.g. `forbidden` on a scope failure, whose `message` is `insufficient_scope`,
+ * or `banner_in_use` on a banner-library conflict). It's `undefined` when the body has no `code`.
  */
 declare class CookieMunchApiError extends Error {
     readonly status: number;
@@ -448,9 +469,12 @@ interface CategorizedCookie {
     /**
      * Why a person should look at it. Visitors see unclassified and category ones under
      * "Unclassified"; `retired_but_seen` = retired, but a crawl or a visit saw it since, so the
-     * site still sets it and it is listed again.
+     * site still sets it and it is listed again. `awaiting_corroboration` / `suspicious_report` =
+     * only visitors reported it (not enough of them yet, or in one injection-shaped report), owner
+     * views only; `foreign_cmp` = another consent platform's cookie, filed unclassified;
+     * `not_seen_recently` = unseen for the site's `staleAfterDays`, owner views only.
      */
-    review?: 'unclassified' | 'category_disabled' | 'category_unknown' | 'retired_but_seen';
+    review?: 'unclassified' | 'category_disabled' | 'category_unknown' | 'retired_but_seen' | 'awaiting_corroboration' | 'suspicious_report' | 'foreign_cmp' | 'not_seen_recently';
     /** Epoch-ms a crawl or a real visit last saw it. Absent on older rows. */
     lastSeenAt?: number;
     /** Owner views only: the site owner retired this cookie (see `sites.retireCookie`). */
@@ -529,7 +553,7 @@ interface DeclaredCookie extends DeclaredCookieInput {
     vendor?: string;
 }
 /** A platform whose cookies and storage a preset declares. */
-type CookiePresetVendor = 'atlas' | 'forumulate' | 'chatly' | 'cookiemunch';
+type CookiePresetVendor = 'atlas' | 'forumulate' | 'chatly' | 'cookiemunch' | 'referally';
 /** Where a vendor's live manifest will come from, and whether it exists yet. */
 interface CookiePresetManifest {
     status: 'builtin' | 'waiting_on_vendor';
@@ -537,13 +561,15 @@ interface CookiePresetManifest {
     item?: string;
     contract?: string;
 }
-/** Preset parameters: Atlas `frontendApiHost`/`crossSubdomainCookies`; Chatly `publicId`/`dragging`/`category`. */
+/** Preset parameters: Atlas `frontendApiHost`/`crossSubdomainCookies`; Chatly `publicId`/`dragging`/`category`; Referally `cookieDomain`/`cookieDays`/`category`. */
 interface CookiePresetParams {
     frontendApiHost?: string;
     crossSubdomainCookies?: boolean;
     publicId?: string;
     dragging?: boolean;
     category?: string;
+    cookieDomain?: string;
+    cookieDays?: number;
 }
 /** One preset in GET /v1/sites/:cbid/cookies/presets. */
 interface CookiePreset {
@@ -1315,6 +1341,38 @@ type RightsCaptchaProvider = 'turnstile' | 'hcaptcha' | 'recaptcha_v2' | 'recapt
  * The rights page's captcha in force: your own keys (`own`, recommended) or none (`off`, the default).
  * Cookie Munch's own captcha is never used on rights pages. The secret is never returned.
  */
+/** Whether hosted consent sync is set up for a site. The secret itself is never read back. */
+interface ConsentSyncSecret {
+    cbid: string;
+    configured: boolean;
+    secretLast4: string | null;
+    /** Epoch ms the current secret was minted. */
+    createdAt: number | null;
+}
+/**
+ * Who a preference-centre token is for: a site of your organisation and exactly one of `email`
+ * (resolved as the emailed preference link resolves it) or `subjectId`.
+ */
+type CenterTokenInput = {
+    cbid: string;
+    ttlSeconds?: number;
+} & ({
+    email: string;
+    subjectId?: never;
+} | {
+    subjectId: string;
+    email?: never;
+});
+/** A preference-centre token. A credential: hand it to `CookieMunch.setSubjectToken`, never put it in a shared URL or a log. */
+interface CenterToken {
+    token: string;
+    /** ISO 8601. */
+    expiresAt: string;
+}
+/** A freshly minted or rotated consent-sync secret: `secret` is shown this once. */
+interface ConsentSyncSecretMinted extends ConsentSyncSecret {
+    secret: string;
+}
 interface RightsCaptcha {
     /** `site`: the site's own setting; `org`: the organisation default; `default`: neither (off). */
     source: 'site' | 'org' | 'default';
@@ -1395,6 +1453,24 @@ interface RightsIdentityInput {
      */
     trustEmailClaim?: boolean;
 }
+/** The organisation's own data-controller identity (GET /v1/org/controller). */
+interface OrgControllerIdentity {
+    /** False when none is set; then only `updatedAt` (null) is present. */
+    set: boolean;
+    legalName?: string;
+    contactEmail?: string;
+    address?: string;
+    /** The Data Protection Officer: a name, an email address, or both. */
+    dpoContact?: string;
+    updatedAt: number | null;
+}
+/** Replaces the identity: a field left out is removed. `legalName` is required. */
+interface OrgControllerInput {
+    legalName: string;
+    contactEmail?: string;
+    address?: string;
+    dpoContact?: string;
+}
 interface MailProviderTestResult {
     ok: boolean;
     sentTo: string;
@@ -2250,7 +2326,7 @@ interface CookieMunchClient {
             dryRun: true;
             retired: RetiredCookie[];
         }>;
-        /** Every declaration preset (atlas, forumulate, chatly, cookiemunch): params, what it declared here, manifest status. */
+        /** Every declaration preset (atlas, forumulate, chatly, cookiemunch, referally): params, what it declared here, manifest status. */
         cookiePresets(cbid: string): Promise<{
             presets: CookiePreset[];
         }>;
@@ -2705,6 +2781,16 @@ interface CookieMunchClient {
         /** One subject's record. A subject with none has empty `purposes`. */
         get(subjectId: string): Promise<PreferenceRecord>;
     };
+    /** The hosted preference centre, opened for a visitor your server has signed in. */
+    preferenceCenter: {
+        /**
+         * Mint a preference-centre token (POST /v1/preference-center/tokens) for the page to pass to
+         * `CookieMunch.setSubjectToken`. Server-side only: the token opens that subject's subscriptions
+         * and profile until `expiresAt`. `ttlSeconds` defaults to 3600, at most 86400. Needs
+         * subscriptions:write and profile:write, plus identity:read when minting by email.
+         */
+        mintToken(input: CenterTokenInput): Promise<CenterToken>;
+    };
     members: {
         list(): Promise<Member[]>;
         invite(email: string, role: string): Promise<{
@@ -2773,6 +2859,17 @@ interface CookieMunchClient {
             /** Send a test through your provider. `to` defaults to the reply-to, else the from address. */
             test(to?: string): Promise<MailProviderTestResult>;
         };
+        /**
+         * Your organisation's own data-controller identity: who every rights notice names, before any site config
+         * `controller` block. Needed for a notice on a request filed without a cbid when you have several sites.
+         * An unscoped key, or `rights:write`.
+         */
+        controller: {
+            get(): Promise<OrgControllerIdentity>;
+            /** Replace it: a field left out is removed. */
+            set(input: OrgControllerInput): Promise<OrgControllerIdentity>;
+            remove(): Promise<void>;
+        };
         /**
          * The default captcha for your rights pages, for every site without its own (`rightsCaptcha`): your own
          * keys (recommended) or off. Without one, rights pages have no captcha.
@@ -2854,6 +2951,18 @@ interface CookieMunchClient {
     rightsLinks: {
         create(cbid: string, input: RightsLinkInput): Promise<RightsLink>;
     };
+    /**
+     * A site's consent-sync signing secret: your server signs consent-sync tokens with it
+     * (`mintConsentSyncToken`) so a visitor's decision syncs across their browsers. `rotate` mints the
+     * first one or replaces it (the old one stops at once) and is the only time the secret is returned.
+     * Reading needs sites:read; rotate and remove need sites:write and consent:write.
+     */
+    consentSyncSecret: {
+        get(cbid: string): Promise<ConsentSyncSecret>;
+        rotate(cbid: string): Promise<ConsentSyncSecretMinted>;
+        /** Turn hosted consent sync off for the site. */
+        remove(cbid: string): Promise<ConsentSyncSecret>;
+    };
     /**
      * A site's rights-page captcha: your own Turnstile, hCaptcha or reCAPTCHA keys (recommended), or off. A site
      * without its own setting uses the organisation default (`org.rightsCaptcha`), else off. Requires sites:read / sites:write.
@@ -2910,4 +3019,4 @@ interface CookieMunchClient {
 }
 declare function createCookieMunch(opts: CookieMunchOptions): CookieMunchClient;
 
-export { type AbResult, type AccountOrg, type AccountOrgs, type AdPersonalizationInput, type AiInspectInput, type AiInspectResult, type ApiKey, type ApiKeyIssueInput, type ApiKeyIssued, type ApiKeyPrefix, type ApiKeyReport, type ApiKeyUpdate, type AppliedImport, type AssetUpload, type AuditEntry, type BannerRecord, type BannerSummary, type BlockedReport, type BrandExtractionResult, type BrandKit, type BrandKitCreate, type BrandSuggestion, type BulkSiteInput, type BulkSiteResult, type ButtonParityFinding, type ButtonParityLint, type ButtonParityScan, type CategorizedCookie, type ChildKeyInput, type ConfigChange, type ConfigDryRun, type ConfigWarning, type ConsentDay, type ConsentDecisionInput, type ConsentIngestInput, type ConsentLogRow, type CookieDeclaration, CookieMunchApiError, type CookieMunchClient, type CookieMunchOptions, type CookiePreset, type CookiePresetManifest, type CookiePresetParams, type CookiePresetResult, type CookiePresetVendor, type CspSources, type DeclarationDiff, type DeclarationDryRun, type DeclarationWarning, type DeclaredCookie, type DeclaredCookieInput, type DnsRecordInstruction, type DsarCreate, type DsarEraseResult, type DsarExecutor, type DsarExecutorCreated, type DsarExecutorDryRun, type DsarExecutorInput, type DsarExecutorPatch, type DsarExecutorPresetInput, type DsarExportResult, type DsarRequest, type DsarStatus, type DsarTask, type DsarTaskEvent, type DsarTaskExport, type DsarTaskLogEntry, type DsarTaskOutcome, type DsarType, type EnforcementRuleInput, type ExecutorHealth, type ExecutorPresetName, type ExecutorPresetUpgrade, type ExecutorPresets, type ExecutorProfile, type ExecutorTestInput, type ExecutorTestResult, type ExecutorWebhookDelivery, type ExecutorWebhookTestResult, type FlowIssue, type FlowOp, type FlowOpResponse, type FulfillmentOp, type HealthRow, type Identifier, type Identity, type ImportedCookie, type ImportedDeclaration, type InstallSnippet, type IntegrationHealthReport, type LegalBasis, type LogQuery, type MailProvider, type MailProviderInput, type MailProviderKind, type MailProviderTestResult, type Member, type ObservedPurgeResult, type OptInMethod, type Org, type OrgUpdate, type ParityControlSummary, type PartnerCatalogEntry, type PartnerId, type PartnerLink, type PartnerLinkCreate, type PlanSource, type PolicyOptions, type PreferenceItem, type PreferenceRecord, type PreviewToken, type PreviewTokenOptions, type ProfileAttributeInput, type ProvisionRequest, type ProvisionResult, type ProvisionStep, type PublicDsarFiled, type PublicDsarPending, type PublicVerification, type PutConfigOptions, type RangeQuery, type Regulation, type RegulationSummary, type RegulatoryFeedResult, type ResellerChild, type ResellerChildCreate, type ResellerChildList, type ResellerChildPatch, type RetiredCookie, type RightKind, type RightsCaptcha, type RightsCaptchaInput, type RightsCaptchaProvider, type RightsIdentity, type RightsIdentityInput, type RightsIdentityType, type RightsLink, type RightsLinkInput, type RightsPageDocument, type RightsPageDomain, type RightsPageDomainList, type RightsPageDraft, type RightsPageDraftConflict, type RightsPageDryRun, type RightsPageIssue, type RightsPagePublishResult, type RightsPagePublished, type RightsPagePublisher, type RightsPageVersions, type RightsPageWriteOptions, type RiskScore, type RopaEntry, type RopaInput, type ScanResult, type ScanStatus, type ScoredVendor, type ScrollbarTheme, type SessionAnalysisInput, type SignedReceipt, type Site, type SiteConfig, type SiteCookie, type SiteCreate, type SiteFlow, type SiteUpdate, type SiteUpdateResult, type SnippetOptions, type StorageType, type SubscriptionTopicInput, type SuggestedRejectStyle, type SupportedLanguage, type Usage, type VendorInput, type VendorRecord, type VerifyResult, type VerifyWebhookInput, type WebhookCreate, type WebhookDeadLetter, type WebhookKeyForm, type WebhookStage, type WebhookSubscription, type WebhookTestResult, type WebhookUpdate, createCookieMunch, verifyWebhookSignature };
+export { type AbResult, type AccountOrg, type AccountOrgs, type AdPersonalizationInput, type AiInspectInput, type AiInspectResult, type ApiKey, type ApiKeyIssueInput, type ApiKeyIssued, type ApiKeyPrefix, type ApiKeyReport, type ApiKeyUpdate, type AppliedImport, type AssetUpload, type AuditEntry, type BannerRecord, type BannerSummary, type BlockedReport, type BrandExtractionResult, type BrandKit, type BrandKitCreate, type BrandSuggestion, type BulkSiteInput, type BulkSiteResult, type ButtonParityFinding, type ButtonParityLint, type ButtonParityScan, type CategorizedCookie, type CenterToken, type CenterTokenInput, type ChildKeyInput, type ConfigChange, type ConfigDryRun, type ConfigWarning, type ConsentDay, type ConsentDecisionInput, type ConsentIngestInput, type ConsentLogRow, type ConsentSyncSecret, type ConsentSyncSecretMinted, type CookieDeclaration, CookieMunchApiError, type CookieMunchClient, type CookieMunchOptions, type CookiePreset, type CookiePresetManifest, type CookiePresetParams, type CookiePresetResult, type CookiePresetVendor, type CspSources, type DeclarationDiff, type DeclarationDryRun, type DeclarationWarning, type DeclaredCookie, type DeclaredCookieInput, type DnsRecordInstruction, type DsarCreate, type DsarEraseResult, type DsarExecutor, type DsarExecutorCreated, type DsarExecutorDryRun, type DsarExecutorInput, type DsarExecutorPatch, type DsarExecutorPresetInput, type DsarExportResult, type DsarRequest, type DsarStatus, type DsarTask, type DsarTaskEvent, type DsarTaskExport, type DsarTaskLogEntry, type DsarTaskOutcome, type DsarType, type EnforcementRuleInput, type ExecutorHealth, type ExecutorPresetName, type ExecutorPresetUpgrade, type ExecutorPresets, type ExecutorProfile, type ExecutorTestInput, type ExecutorTestResult, type ExecutorWebhookDelivery, type ExecutorWebhookTestResult, type FlowIssue, type FlowOp, type FlowOpResponse, type FulfillmentOp, type HealthRow, type Identifier, type Identity, type ImportedCookie, type ImportedDeclaration, type InstallSnippet, type IntegrationHealthReport, type LegalBasis, type LogQuery, type MailProvider, type MailProviderInput, type MailProviderKind, type MailProviderTestResult, type Member, type MintConsentSyncTokenInput, type ObservedPurgeResult, type OptInMethod, type Org, type OrgControllerIdentity, type OrgControllerInput, type OrgUpdate, type ParityControlSummary, type PartnerCatalogEntry, type PartnerId, type PartnerLink, type PartnerLinkCreate, type PlanSource, type PolicyOptions, type PreferenceItem, type PreferenceRecord, type PreviewToken, type PreviewTokenOptions, type ProfileAttributeInput, type ProvisionRequest, type ProvisionResult, type ProvisionStep, type PublicDsarFiled, type PublicDsarPending, type PublicVerification, type PutConfigOptions, type RangeQuery, type Regulation, type RegulationSummary, type RegulatoryFeedResult, type ResellerChild, type ResellerChildCreate, type ResellerChildList, type ResellerChildPatch, type RetiredCookie, type RightKind, type RightsCaptcha, type RightsCaptchaInput, type RightsCaptchaProvider, type RightsIdentity, type RightsIdentityInput, type RightsIdentityType, type RightsLink, type RightsLinkInput, type RightsPageDocument, type RightsPageDomain, type RightsPageDomainList, type RightsPageDraft, type RightsPageDraftConflict, type RightsPageDryRun, type RightsPageIssue, type RightsPagePublishResult, type RightsPagePublished, type RightsPagePublisher, type RightsPageVersions, type RightsPageWriteOptions, type RiskScore, type RopaEntry, type RopaInput, SDK_VERSION, type ScanResult, type ScanStatus, type ScoredVendor, type ScrollbarTheme, type SessionAnalysisInput, type SignedReceipt, type Site, type SiteConfig, type SiteCookie, type SiteCreate, type SiteFlow, type SiteUpdate, type SiteUpdateResult, type SnippetOptions, type StorageType, type SubscriptionTopicInput, type SuggestedRejectStyle, type SupportedLanguage, type Usage, type VendorInput, type VendorRecord, type VerifyResult, type VerifyWebhookInput, type WebhookCreate, type WebhookDeadLetter, type WebhookKeyForm, type WebhookStage, type WebhookSubscription, type WebhookTestResult, type WebhookUpdate, createCookieMunch, mintConsentSyncToken, verifyWebhookSignature };

package/dist/index.js

@@ -26,7 +26,23 @@ function verifyWebhookSignature(input) {
   return timingSafeEqual(got, want);
 }
 
+// src/consent-sync.ts
+import { createHmac as createHmac2 } from "crypto";
+var SUBJECT_RE = /^[A-Za-z0-9._:@+/=~-]{1,128}$/;
+function mintConsentSyncToken(input) {
+  if (!input.secret) throw new Error("mintConsentSyncToken: secret is required");
+  if (!input.cbid) throw new Error("mintConsentSyncToken: cbid is required");
+  if (!SUBJECT_RE.test(input.subject)) throw new Error("mintConsentSyncToken: subject must be 1\u2013128 characters of A-Z a-z 0-9 . _ : @ + / = ~ -");
+  const ttl = Math.floor(input.ttlSeconds ?? 3600);
+  if (!(ttl >= 1 && ttl <= 86400)) throw new Error("mintConsentSyncToken: ttlSeconds must be between 1 and 86400");
+  const iat = Math.floor((input.now ?? Date.now()) / 1e3);
+  const payload = Buffer.from(JSON.stringify({ c: input.cbid, s: input.subject, iat, exp: iat + ttl })).toString("base64url");
+  const sig = createHmac2("sha256", input.secret).update(`cms1.${payload}`).digest("base64url");
+  return `cms1.${payload}.${sig}`;
+}
+
 // src/index.ts
+var SDK_VERSION = "0.5.0";
 var CookieMunchApiError = class extends Error {
   constructor(status, message, code, body) {
     super(message);
@@ -53,7 +69,7 @@ function createCookieMunch(opts) {
   const doFetch = opts.fetch ?? globalThis.fetch;
   if (!doFetch) throw new Error("No fetch available; pass { fetch } in CookieMunchOptions.");
   async function request(method, path, body, raw = false) {
-    const headers = { Authorization: `Bearer ${opts.apiKey}` };
+    const headers = { Authorization: `Bearer ${opts.apiKey}`, "User-Agent": opts.userAgent ?? `cookiemunch-js/${SDK_VERSION}` };
     if (opts.strictUnknownFields && method !== "GET") headers["Prefer"] = "strict-unknown-fields";
     const init = { method, headers };
     if (body !== void 0) {
@@ -328,6 +344,9 @@ function createCookieMunch(opts) {
       save: (subjectId, purposes) => request("POST", "/preferences", { subjectId, purposes }),
       get: (subjectId) => get(`/preferences/${enc(subjectId)}`)
     },
+    preferenceCenter: {
+      mintToken: (input) => request("POST", "/preference-center/tokens", input)
+    },
     members: {
       list: () => get("/members"),
       invite: (email, role) => request("POST", "/members", { email, role }),
@@ -358,6 +377,13 @@ function createCookieMunch(opts) {
         },
         test: (to) => request("POST", "/org/mail-provider/test", to ? { to } : {})
       },
+      controller: {
+        get: () => get("/org/controller"),
+        set: (input) => request("PUT", "/org/controller", input),
+        remove: async () => {
+          await request("DELETE", "/org/controller");
+        }
+      },
       rightsCaptcha: {
         get: () => get("/org/rights-captcha"),
         set: (input) => request("PUT", "/org/rights-captcha", input),
@@ -406,6 +432,11 @@ function createCookieMunch(opts) {
     rightsLinks: {
       create: (cbid, input) => request("POST", `/sites/${enc(cbid)}/rights-links`, input)
     },
+    consentSyncSecret: {
+      get: (cbid) => get(`/sites/${enc(cbid)}/consent-sync-secret`),
+      rotate: (cbid) => request("POST", `/sites/${enc(cbid)}/consent-sync-secret`),
+      remove: (cbid) => request("DELETE", `/sites/${enc(cbid)}/consent-sync-secret`)
+    },
     rightsCaptcha: {
       get: (cbid) => get(`/sites/${enc(cbid)}/rights-captcha`),
       set: (cbid, input) => request("PUT", `/sites/${enc(cbid)}/rights-captcha`, input),
@@ -436,9 +467,11 @@ function createCookieMunch(opts) {
 export {
   CONSENT_COOKIE_NAME,
   CookieMunchApiError,
+  SDK_VERSION,
   createCookieMunch,
   getConsent,
   isAllowed,
+  mintConsentSyncToken,
   parseConsentValue,
   readConsent,
   verifyWebhookSignature