@cookiemunch/sdk 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 Every published release, newest first. Dates are the day the version was cut.
 
+## 0.8.0 (2026-10-30)
+
+- Added: `mintFrom` and `externalId` on the DSAR executor connect method: a partner with an `executorKeyUrl` mints the executor key, so `secretKey` is optional. The dry run's `mint` shows the plan.
+- Changed: a preset's `source` is typed `builtin | manifest | instance`.
+- Added: `integrations.connect(provider, { cbid, providerKey, connector? }, { dryRun? })`: one-call connect for an identity provider's privacy orchestrator (`POST /v1/integrations/{provider}/connect`).
+- Changed: `ProvisionRequestV2` names its block `stack` (same fields); its site tags are `stack_product`, `stack_env`, `stack_ref` and `stack_sandbox`. The trace header is `X-Trace-Id`.
+
+## 0.7.1 (2026-10-24)
+
+- Changed: `ConsentInsights.byLanguage` and `timeToDecision` are now filled in — opt-in by the banner's language, and a time-to-decision histogram with its median bucket — or `null` with `notRecorded` saying why.
+
 ## 0.7.0 (2026-10-24)
 
 - Added: `sandbox.get` / `create` / `delete` — a sandbox organisation made from yours: the same people and plan, never billed, test keys only, every rights request a test.
@@ -19,7 +30,7 @@ Every published release, newest first. Dates are the day the version was cut.
 - Added: keys — `keys.self()`, `keys.rollSelf()`, `keys.vend({ scopes, ttlSeconds })` (short-lived, at most 12 h), `keys.listStandard()`, `keys.revokeLeaked(report)`; keys can be minted with `scopes`, `cbids` and `expiresInDays`.
 - Added: `partnerLinks.list` / `create` / `revoke` (any partner, scoped), and `metadata.get` / `update` with `metadata` and `externalRef` on sites, webhooks, connections, rights requests and orgs; `?metadata[key]=` list filters; `deleteSandbox` on sandbox sites and orgs.
 - Added: `sites.cookieSuggestions` / `declareCookieSuggestions`, `importCookieManifest` (any vendor's embed manifest) and `removeCookiePreset` for custom presets; `embedManifest(cbid)`; first-class cookie presets for `referalli`, `firstpromoter`, `partnerstack`, `tapfiliate` and `impact` (`referally` is a deprecated alias).
-- Added: `sites.getBrand` / `setBrand` (DTCG brand.json import with a read-back), `consent.insights`, `categoryRegistry()`, `entitlements()`, `provisionEnv(ref)`, and `provision(input, { fromStep })` with the forgedeck (v2) body.
+- Added: `sites.getBrand` / `setBrand` (DTCG brand.json import with a read-back), `consent.insights`, `categoryRegistry()`, `entitlements()`, `provisionEnv(ref)`, and `provision(input, { fromStep })` with the version 2 body.
 - Added: `healthWaivers.list` / `set` / `remove`, `auditSink.get` / `set` / `remove` (CloudEvents), `webhooks.replay(id, since)`, `audit(limit, { actor: 'self' })`, `fulfillment.recheckExecutor` and `executorHealthHistory`.
 - Added: `readConsent(source, { requireSigned })`, `verifyDecisionSignature`, `verifyToken` (consent tokens, against the partner JWKS) and `consentSignaturePayload`.
 - Added: the `X-Secret-Recipient` option seals every once-shown secret; `Idempotency-Key` on creates.

package/dist/consent-sync.d.ts

@@ -0,0 +1,13 @@
+export 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;
+}
+export declare function mintConsentSyncToken(input: MintConsentSyncTokenInput): string;

package/dist/consent.d.ts

@@ -17,9 +17,9 @@
  * This module imports nothing — `@cookiemunch/sdk/consent` pulls in no API client.
  */
 /** The first-party cookie the embed writes (mirrors @cookiemunch/core COOKIE_NAME). */
-declare const CONSENT_COOKIE_NAME = "CookieMunch";
+export declare const CONSENT_COOKIE_NAME = "CookieMunch";
 /** A visitor's consent decision, read from the request cookie. `necessary` is always true. */
-interface ServerConsent {
+export interface ServerConsent {
     necessary: true;
     preferences: boolean;
     statistics: boolean;
@@ -43,7 +43,7 @@ interface ServerConsent {
     sig?: string;
 }
 /** The site's consent policy, so the server applies the same rules the embed does. */
-interface ReadConsentOptions {
+export interface ReadConsentOptions {
     /** Cookie name. Default `CookieMunch`. */
     cookieName?: string;
     /**
@@ -58,7 +58,7 @@ interface ReadConsentOptions {
     now?: number;
 }
 /** Where the platform's public signing keys come from, for signatures and consent tokens. */
-interface KeySetOptions {
+export interface KeySetOptions {
     /** A key set you already hold (`{ keys: [...] }`). Skips the fetch. */
     jwks?: JsonWebKeySet;
     /** Default `https://api.cookiemunch.net/v1/partner/jwks.json`. */
@@ -67,11 +67,11 @@ interface KeySetOptions {
     fetch?: typeof fetch;
 }
 /** `readConsent` with `requireSigned: true`: only a decision the API signed counts. */
-interface ReadSignedConsentOptions extends ReadConsentOptions, KeySetOptions {
+export interface ReadSignedConsentOptions extends ReadConsentOptions, KeySetOptions {
     requireSigned: true;
 }
 /** Anything we can pull a Cookie header off of. */
-type ConsentSource = string | null | undefined | {
+export type ConsentSource = string | null | undefined | {
     headers?: {
         cookie?: string | null;
         get?(name: string): string | null;
@@ -82,32 +82,32 @@ type ConsentSource = string | null | undefined | {
  * the embed reads: URL-encoded (or plain) strict JSON, and Cookiebot's relaxed object
  * literal — `{stamp:'…',necessary:true,…}` — left behind by a site migrating from Cookiebot.
  */
-declare function parseConsentValue(raw: string): ServerConsent | null;
+export declare function parseConsentValue(raw: string): ServerConsent | null;
 /**
  * Read the visitor's consent from a request: a raw `Cookie` header, a Node `req`, or a Fetch
  * `Request`. Returns null when there is no decision the embed would honour — no cookie, an
  * unparseable one, or (with the options) one made under an older version or past expiry.
  */
-declare function readConsent(source: ConsentSource, opts: ReadSignedConsentOptions): Promise<ServerConsent | null>;
-declare function readConsent(source: ConsentSource, opts?: ReadConsentOptions & {
+export declare function readConsent(source: ConsentSource, opts: ReadSignedConsentOptions): Promise<ServerConsent | null>;
+export declare function readConsent(source: ConsentSource, opts?: ReadConsentOptions & {
     requireSigned?: false;
 }): ServerConsent | null;
 /**
  * Read the visitor's consent from a request. The original spelling of {@link readConsent},
  * kept for existing callers; the second argument is the cookie name.
  */
-declare function getConsent(source: ConsentSource, cookieName?: string): ServerConsent | null;
+export declare function getConsent(source: ConsentSource, cookieName?: string): ServerConsent | null;
 /** Standard + custom consent categories. */
-type ConsentCategory = 'necessary' | 'preferences' | 'statistics' | 'marketing' | (string & {});
+export type ConsentCategory = 'necessary' | 'preferences' | 'statistics' | 'marketing' | (string & {});
 /**
  * Whether a category is allowed for this visitor. `necessary` is always allowed. A missing
  * consent (`null` — visitor hasn't decided) is treated as NOT allowed for non-necessary
  * categories (fail-closed / prior-blocking posture), matching the embed.
  */
-declare function isAllowed(consent: ServerConsent | null, category: ConsentCategory): boolean;
-declare const DEFAULT_JWKS_URL = "https://api.cookiemunch.net/v1/partner/jwks.json";
+export declare function isAllowed(consent: ServerConsent | null, category: ConsentCategory): boolean;
+export declare const DEFAULT_JWKS_URL = "https://api.cookiemunch.net/v1/partner/jwks.json";
 /** The fields of a decision its signature covers. */
-interface SignableDecision {
+export interface SignableDecision {
     stamp: string;
     ver: number;
     utc: number;
@@ -120,7 +120,7 @@ interface SignableDecision {
  * The exact line the API signs for a recorded decision. Identical to @cookiemunch/core's
  * `consentSignaturePayload` (a server test pins the two together).
  */
-declare function consentSignaturePayload(d: SignableDecision): string;
+export declare function consentSignaturePayload(d: SignableDecision): string;
 interface Jwk {
     kty?: string;
     crv?: string;
@@ -128,13 +128,13 @@ interface Jwk {
     kid?: string;
     alg?: string;
 }
-interface JsonWebKeySet {
+export interface JsonWebKeySet {
     keys: Jwk[];
 }
 /** Does the cookie's `sig` verify for this decision? False on anything malformed. */
-declare function verifyDecisionSignature(consent: ServerConsent, opts?: KeySetOptions): Promise<boolean>;
+export declare function verifyDecisionSignature(consent: ServerConsent, opts?: KeySetOptions): Promise<boolean>;
 /** What a consent token (`CookieMunch.getConsentToken()`) asserts. */
-interface ConsentTokenClaims {
+export interface ConsentTokenClaims {
     iss: string;
     /** The decision's stamp. */
     sub: string;
@@ -152,7 +152,7 @@ interface ConsentTokenClaims {
     iat: number;
     exp: number;
 }
-interface VerifyTokenOptions extends KeySetOptions {
+export interface VerifyTokenOptions extends KeySetOptions {
     /** Require the token to be for this site. */
     cbid?: string;
     /** Clock, epoch ms. Default `Date.now()`. */
@@ -164,6 +164,5 @@ interface VerifyTokenOptions extends KeySetOptions {
  * Verify a consent token from `CookieMunch.getConsentToken()` (CMU-F06) against the published
  * key set and return its claims. Throws on a bad signature, a wrong site, or an expired token.
  */
-declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<ConsentTokenClaims>;
-
-export { CONSENT_COOKIE_NAME, type ConsentCategory, type ConsentSource, type ConsentTokenClaims, DEFAULT_JWKS_URL, type JsonWebKeySet, type KeySetOptions, type ReadConsentOptions, type ReadSignedConsentOptions, type ServerConsent, type SignableDecision, type VerifyTokenOptions, consentSignaturePayload, getConsent, isAllowed, parseConsentValue, readConsent, verifyDecisionSignature, verifyToken };
+export declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<ConsentTokenClaims>;
+export {};

package/dist/executor-conformance.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The cm-standard-v2 executor conformance kit (CMU-X20).
+ *
+ * cm-standard-v2 is an open contract: any system that holds personal data can implement it and
+ * be driven by Cookie Munch with no code on our side (docs: cookiemunch.net/docs/executor-contract-v2).
+ * This kit checks an implementation rule by rule, and names the rule that fails. It is the same
+ * suite Cookie Munch runs on `POST /v1/dsar/executors/{id}/test {conformance: true}`, and the
+ * `cookiemunch executors conformance <baseUrl>` command runs it from a terminal or CI.
+ *
+ * It only ever touches the CANARY subject — an address no real person has. The contract asks every
+ * implementation to treat the canary as an existing synthetic person: it is found by its email and
+ * by its identity, requests on it move through the full state machine, and nothing real is ever
+ * erased. So the kit can check that an erasure waits for `executeAfter`, that a cancel leaves the
+ * person in place, and that an identity is never matched to someone else through a shared email —
+ * without a real person's data being anywhere near it.
+ *
+ * No dependencies: `fetch` only, so it runs in Node 18+, a browser, or an edge runtime.
+ */
+export type ConformanceStatus = 'pass' | 'fail' | 'skip';
+export interface ConformanceRuleResult {
+    /** A stable id, e.g. `requests.execute_after.scheduled`. */
+    id: string;
+    /** What the rule says, in one sentence. */
+    title: string;
+    status: ConformanceStatus;
+    /** What was seen, when it failed or was skipped. */
+    detail?: string;
+}
+export interface ConformanceReport {
+    /** True when no rule failed. */
+    ok: boolean;
+    passed: number;
+    failed: number;
+    skipped: number;
+    rules: ConformanceRuleResult[];
+    /** The `X-Version` the executor answered with, when it sent one. */
+    version?: string;
+}
+export interface ConformanceOptions {
+    /** The executor's base: the contract paths are `{baseUrl}/privacy/lookup` and so on. https (http only for localhost). */
+    baseUrl: string;
+    /** The credential Cookie Munch would send. */
+    secret: string;
+    /**
+     * The canary address: `canary-<16 hex>@canary.cookiemunch.net`, per organisation
+     * (`GET /v1/dsar/executors/presets` → `canaryEmail`).
+     */
+    canaryEmail: string;
+    /** How the secret is sent. Default `Authorization: Bearer {secret}`. */
+    auth?: {
+        header: string;
+        format: string;
+    };
+    /** Path prefix under baseUrl. Default `/privacy`. */
+    prefix?: string;
+    fetch?: typeof fetch;
+    now?: () => number;
+    /** A per-run tag for idempotency keys and case ids. Default random. */
+    runId?: string;
+}
+/** The issuer the canary identity carries. */
+export declare const CANARY_ISSUER = "https://canary.cookiemunch.net";
+/** The canary subject's identity, derived from its address. */
+export declare function canaryIdentityFor(canaryEmail: string): {
+    iss: string;
+    sub: string;
+    ext: string;
+};
+/** Every rule, in the order they run. */
+export declare const CONFORMANCE_RULES: ReadonlyArray<{
+    id: string;
+    title: string;
+}>;
+/** Run every rule against one executor. Never throws for an executor's answer; only for bad options. */
+export declare function runExecutorConformance(o: ConformanceOptions): Promise<ConformanceReport>;

package/dist/fd-consent.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Types for `window.__consent` (also `window.__fdConsent`, the same object under its first name), the shared
+ * consent API any embed can code against — a chat
+ * widget, a referral snippet, an analytics tag — whatever CMP the page runs. Cookie Munch sets
+ * it natively; `fd-consent-shim.js` sets the same object over Cookiebot, OneTrust or no CMP.
+ * Type-only: importing this module adds nothing to a bundle.
+ *
+ *   import type { FdConsent, FdConsentQueue } from '@cookiemunch/sdk';
+ *   const fd = (window.__consent ??= { q: [] });
+ *   if ('version' in fd) fd.on('change', (s) => …); else fd.q.push(['on', 'change', (s) => …]);
+ *
+ * `version` changes only with a breaking change; new members do not bump it.
+ */
+/** What caused a change. The same causes Cookie Munch's ledger records. */
+export type FdCause = 'replay' | 'accept' | 'decline' | 'selection' | 'withdraw' | 'implied' | 'sync' | 'request' | 'migrated';
+export interface FdSnapshot {
+    /** False until the visitor has answered. */
+    decided: boolean;
+    /** False when this visitor's region and the site's rules need no answer (a default applies). */
+    required: boolean;
+    /** Every category the site offers (standard, custom, reserved) and its answer. */
+    categories: Record<string, boolean>;
+    /** The decision's stamp (`CookieMunch.consentId()`), or null. */
+    stamp: string | null;
+    region: string;
+    /** A Global Privacy Control signal was seen. */
+    gpc: boolean;
+    /** ISO 8601, or null before a decision. */
+    decidedAt: string | null;
+}
+export interface FdRequestOptions {
+    /** One sentence in the page's language: what will be stored and why. Shown as the prompt's text. */
+    reason: string;
+    /** Who is asking: your vendor id. Recorded with the answer. */
+    vendor: string;
+}
+export interface FdConsent {
+    readonly version: 1;
+    /** `cookiemunch`, or `shim:cookiebot` / `shim:onetrust` / `shim:none`. */
+    readonly provider: string;
+    /** Resolves once a decision exists, or at once where the region needs none. */
+    ready(): Promise<FdSnapshot>;
+    /** true / false, or null while a required decision is pending. Never false for "not decided". */
+    has(category: string): boolean | null;
+    /** Fires once per decision (a returning visitor's as `replay`); a withdrawal synchronously. Returns unsubscribe. */
+    on(event: 'change', cb: (snapshot: FdSnapshot, cause: FdCause) => void): () => void;
+    /** Ask for one category at the moment you need it. Never re-asks a refusal; one prompt per category per page view. */
+    request(category: string, opts: FdRequestOptions): Promise<boolean>;
+    /** Not available yet: warns once and does nothing. */
+    identify(token: string): void;
+    layout: {
+        bottomInset(): number;
+        on(cb: (insetPx: number) => void): () => void;
+    };
+    /** Calls made on the queue before this existed ran in order; later pushes run at once. */
+    q: {
+        push(...calls: FdQueuedCall[]): number;
+    };
+}
+/** A call queued before the real object exists. */
+export type FdQueuedCall = ['on', 'change', (snapshot: FdSnapshot, cause: FdCause) => void] | ['ready', (snapshot: FdSnapshot) => void] | ['request', string, FdRequestOptions, (granted: boolean) => void] | ['identify', string];
+/** What an embed that loads first creates: `window.__consent = window.__consent || { q: [] }` (or the same under `__fdConsent`). */
+export interface FdConsentQueue {
+    q: FdQueuedCall[];
+}
+declare global {
+    interface Window {
+        /** The shared consent API (or, before Cookie Munch loads, a queue). */
+        __consent?: FdConsent | FdConsentQueue;
+        /** The same object as `__consent`, under its first name. Kept for good: existing embeds read it. */
+        __fdConsent?: FdConsent | FdConsentQueue;
+    }
+}

package/dist/index.cjs

@@ -465,7 +465,7 @@ async function exchangeOperatorToken(input) {
 }
 
 // src/index.ts
-var SDK_VERSION = "0.7.0";
+var SDK_VERSION = "0.8.0";
 var CookieMunchApiError = class extends Error {
   constructor(status, message, code, body) {
     super(message);
@@ -687,7 +687,7 @@ function createCookieMunch(opts) {
       listByTrace: (trace) => get(`/dsar${qs({ trace })}`),
       openCase: (input, o) => request("POST", "/dsar/requests", input, false, {
         ...o?.idempotencyKey ? { "Idempotency-Key": o.idempotencyKey } : {},
-        ...o?.trace ? { "X-ForgeDeck-Trace": o.trace } : {}
+        ...o?.trace ? { "X-Trace-Id": o.trace } : {}
       }),
       getCase: (id) => get(`/dsar/requests/${enc(id)}`),
       cancelCase: (id) => request("POST", `/dsar/requests/${enc(id)}/cancel`),
@@ -959,7 +959,8 @@ function createCookieMunch(opts) {
       set: (cbid, input) => request("PUT", `/sites/${enc(cbid)}/dsar-settings`, input)
     },
     integrations: {
-      subjectCard: (app, person) => get(`/integrations/${enc(app)}/card${qs(person)}`)
+      subjectCard: (app, person) => get(`/integrations/${enc(app)}/card${qs(person)}`),
+      connect: (provider, input, o) => request("POST", `/integrations/${enc(provider)}/connect${qs({ dryRun: o?.dryRun ? "1" : void 0 })}`, input)
     },
     subjects: {
       consent: (subjectId) => get(`/subjects/${enc(subjectId)}/consent`)