@cookiemunch/sdk 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -57,6 +57,144 @@ interface Site {
     cbid: string;
     orgId: string;
     domain: string;
+    /** The business name data subjects see on the rights page, in notices and the policy. Absent: the domain is shown. */
+    name?: string;
+    /** Other hosts serving the site: accepted consent-ingest origins, never verified claims. */
+    aliases?: string[];
+    verified?: boolean;
+}
+/** PATCH /v1/sites/{cbid} — rename or move a site. `name: null` clears the name; `aliases: []` clears them. */
+interface SiteUpdate {
+    domain?: string;
+    name?: string | null;
+    aliases?: string[];
+}
+interface SiteUpdateResult {
+    dryRun?: true;
+    site: Site;
+    diff: Array<{
+        field: 'domain' | 'name' | 'aliases' | 'verified';
+        before: unknown;
+        after: unknown;
+    }>;
+    effects: {
+        /** `reset`: the domain moved; verify the new one. */
+        verification: 'kept' | 'reset';
+        scanTarget: string;
+        previewDefaultUrl: string;
+        displayName: string;
+        /** Custom rights-page hostnames no longer under the domain or an alias (left in place). */
+        staleRightsDomains: string[];
+    };
+    warnings?: Array<{
+        field: string;
+        reason: string;
+    }>;
+}
+/** One row of GET /v1/integration-health. `ok: null` = the check could not run (see `detail`). */
+interface HealthRow {
+    check: string;
+    ok: boolean | null;
+    severity: 'error' | 'warning' | 'info';
+    subject: string;
+    fixHint?: string;
+    detail?: string;
+    lastCheckedAt: number;
+}
+interface IntegrationHealthReport {
+    cbid: string;
+    checkedAt: number;
+    ok: boolean;
+    counts: {
+        error: number;
+        warning: number;
+        notChecked: number;
+    };
+    checks: HealthRow[];
+}
+/** POST /v1/provision. Secrets are used for the request only and never returned. */
+interface ProvisionRequest {
+    product: string;
+    domain: string;
+    name?: string;
+    aliases?: string[];
+    cbid?: string;
+    /** `frontendApiHost` (e.g. auth.example.com) lets provision declare Atlas's sign-in cookies on the site. */
+    atlas?: {
+        secretKey: string;
+        cookieConsent?: boolean;
+        dsrWebhook?: boolean;
+        frontendApiHost?: string;
+    };
+    forumulate?: {
+        token: string;
+        orgId: string;
+        consent?: boolean;
+        executorKey?: boolean;
+        label?: string;
+    };
+    rightsApi?: {
+        baseUrl: string;
+        secretKey: string;
+        profilePreset?: string;
+    };
+}
+interface ProvisionStep {
+    step: string;
+    status: 'created' | 'updated' | 'unchanged' | 'would_create' | 'would_update' | 'skipped' | 'waiting' | 'failed' | 'passed';
+    detail?: string;
+    diff?: Array<{
+        field: string;
+        before: unknown;
+        after: unknown;
+    }>;
+    waitingOn?: string;
+}
+interface ProvisionResult {
+    dryRun: boolean;
+    product: string;
+    cbid: string | null;
+    steps: ProvisionStep[];
+    summary: {
+        changed: number;
+        unchanged: number;
+        waiting: number;
+        failed: number;
+    };
+}
+type PartnerId = 'forumulate' | 'atlas';
+interface PartnerLinkCreate {
+    partner: PartnerId;
+    /** The partner's id for the receiving account (a Forumulate organisation id, an Atlas instance id). */
+    externalId: string;
+    label?: string;
+    events?: Array<'consent.recorded' | 'consent.withdrawn'>;
+}
+interface PartnerLink {
+    id: string;
+    cbid: string;
+    partner: PartnerId;
+    externalId: string;
+    label?: string;
+    events: string[];
+    status: 'active' | 'waiting_on_partner' | 'revoked';
+    /** e.g. "Forumulate (docs) — receiving consent events". */
+    summary: string;
+    waitingOn?: string;
+    createdAt: number;
+    createdBy?: string;
+    revokedAt?: number;
+    revokedBy?: string | null;
+    lastDeliveryAt: number | null;
+    lastError: string | null;
+}
+interface PartnerCatalogEntry {
+    id: PartnerId;
+    label: string;
+    externalIdLabel: string;
+    events: string[];
+    available: boolean;
+    waitingOn?: string;
 }
 interface SiteCreate {
     domain: string;
@@ -110,7 +248,10 @@ interface DsarRequest {
     dueAt: number;
     /** Where the subject said they are, when the intake captured it. */
     jurisdiction?: string;
+    /** INTERNAL: intake note plus the audit lines `/erase` and `/export` append. Never shown to the subject. */
     note?: string;
+    /** The line the subject reads in the response notice. */
+    messageToSubject?: string;
     /** A test request: off the SLA board, labelled, and deletable with `dsar.delete`. A closed request can be marked one with `dsar.markTest`. */
     test?: boolean;
 }
@@ -158,7 +299,10 @@ interface DsarCreate {
      * shares one `regulation` for the deadline.
      */
     jurisdiction?: string;
+    /** INTERNAL: kept on the request, never shown to the subject. */
     note?: string;
+    /** The one free-text line the subject reads in the notice (≤2000 chars; an API key or key prefix is refused). */
+    messageToSubject?: string;
     /** The property this request belongs to; decides which connected systems answer it. */
     cbid?: string;
     /** The subject's consent-receipt id. */
@@ -262,6 +406,11 @@ interface CookieMunchOptions {
     baseUrl: string;
     /** Injectable for tests / custom runtimes. Defaults to the global fetch. */
     fetch?: typeof fetch;
+    /**
+     * Send `Prefer: strict-unknown-fields` on every write: a body field the operation does not
+     * declare is refused (`400 unknown_field`, with `field`) instead of ignored. Catches typos.
+     */
+    strictUnknownFields?: boolean;
 }
 /**
  * Thrown for any non-2xx response. `message` is the server's `error` field when present;
@@ -296,8 +445,48 @@ interface CategorizedCookie {
     declared?: boolean;
     /** A declared `prefix*` wildcard row that no observed cookie matched yet. */
     pattern?: boolean;
-    /** Why a person should look at it. Visitors see such cookies under "Unclassified". */
-    review?: 'unclassified' | 'category_disabled' | 'category_unknown';
+    /**
+     * 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.
+     */
+    review?: 'unclassified' | 'category_disabled' | 'category_unknown' | 'retired_but_seen';
+    /** 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`). */
+    retired?: {
+        at: number;
+        renamedTo?: string;
+        note?: string;
+        by?: string;
+        pattern?: string;
+    };
+    /** A cookie (default, also when absent) or a key in browser storage. */
+    type?: StorageType;
+    /** Where the row came from: a real visit, a crawl, the owner (`api`) or a vendor preset (`import`). */
+    source?: 'embed' | 'scan' | 'api' | 'import';
+    /** Epoch-ms it was first stored. Absent on rows from before provenance was recorded. */
+    firstSeen?: number;
+    /** Distinct visits that reported it. */
+    visits?: number;
+    /** Owner views only: reported by a real visit, but not yet by enough distinct visits to be listed publicly. */
+    quarantined?: boolean;
+    /** "Declared by <vendor>": the vendor preset that declared it. */
+    vendor?: string;
+}
+/** What a declaration row describes. */
+type StorageType = 'cookie' | 'localStorage' | 'sessionStorage' | 'indexedDB';
+/** A cookie the site owner retired: the site renamed or stopped setting it. */
+interface RetiredCookie {
+    /** Exact name, or a `prefix*` wildcard. */
+    name: string;
+    /** Epoch-ms it was retired; anything seen after this brings it back. */
+    at: number;
+    renamedTo?: string;
+    note?: string;
+    /** `apikey:<prefix>` or a dashboard user id. */
+    by?: string;
+    pattern?: boolean;
 }
 /** A site's cookie declaration: the latest scan and observed visits with the site's own
  *  declarations on top. This is what GET /v1/sites/:cbid/cookies returns. */
@@ -307,6 +496,8 @@ interface CookieDeclaration {
     cookies: CategorizedCookie[];
     /** The site owner's declarations, as stored. */
     declared?: DeclaredCookie[];
+    /** The site's retirements, as stored (owner views only). */
+    retired?: RetiredCookie[];
 }
 /** What the site owner says a cookie is (PUT /v1/sites/:cbid/cookies/:name). */
 interface DeclaredCookieInput {
@@ -325,11 +516,70 @@ interface DeclaredCookieInput {
     domain?: string;
     /** Treat the name as a prefix wildcard (a trailing `*` does the same). */
     pattern?: boolean;
+    /** A cookie (default) or a key in localStorage, sessionStorage or IndexedDB. */
+    type?: StorageType;
 }
 /** A stored declaration. */
 interface DeclaredCookie extends DeclaredCookieInput {
     name: string;
     updatedAt: number;
+    /** `import` when a vendor preset wrote it. */
+    source?: 'import';
+    /** The vendor whose preset declared it. */
+    vendor?: string;
+}
+/** A platform whose cookies and storage a preset declares. */
+type CookiePresetVendor = 'atlas' | 'forumulate' | 'chatly' | 'cookiemunch';
+/** Where a vendor's live manifest will come from, and whether it exists yet. */
+interface CookiePresetManifest {
+    status: 'builtin' | 'waiting_on_vendor';
+    waitingOn?: string;
+    item?: string;
+    contract?: string;
+}
+/** Preset parameters: Atlas `frontendApiHost`/`crossSubdomainCookies`; Chatly `publicId`/`dragging`/`category`. */
+interface CookiePresetParams {
+    frontendApiHost?: string;
+    crossSubdomainCookies?: boolean;
+    publicId?: string;
+    dragging?: boolean;
+    category?: string;
+}
+/** One preset in GET /v1/sites/:cbid/cookies/presets. */
+interface CookiePreset {
+    vendor: CookiePresetVendor;
+    params: Array<{
+        name: string;
+        type: string;
+        required: boolean;
+        description?: string;
+    }>;
+    applied: boolean;
+    declared: string[];
+    manifest: CookiePresetManifest;
+}
+/** What applying a preset declared. */
+interface CookiePresetResult {
+    vendor: CookiePresetVendor;
+    cookies: DeclaredCookie[];
+    removed: string[];
+    skipped?: Array<{
+        name: string;
+        reason: string;
+    }>;
+    note?: string;
+    manifest: CookiePresetManifest;
+    dryRun?: true;
+    declared?: DeclaredCookie[];
+    diff?: DeclarationDiff;
+}
+/** What removing observed rows removed (or, with `dryRun`, would). */
+interface ObservedPurgeResult {
+    removed: string[];
+    count: number;
+    since?: number;
+    until?: number;
+    dryRun?: true;
 }
 /** What a declaration write would change (`dryRun`). */
 interface DeclarationDiff {
@@ -374,11 +624,26 @@ interface SiteCookie {
 }
 /** Cookie-scan status, from GET /v1/sites/:cbid/scan. */
 interface ScanStatus {
+    /** `scanning` while the last scan is queued or crawling. Kept for older clients; read `state`. */
     status: 'idle' | 'scanning';
     /** Epoch-ms of the last completed scan, or null. */
     lastScannedAt: number | null;
     /** What the last scan saw of the live banner's Accept all / Reject all. Absent until measured. */
     buttonParity?: ButtonParityScan;
+    /** Where the last scan is. Absent when the site was never scanned. */
+    state?: 'queued' | 'scanning' | 'done' | 'failed';
+    scanId?: string;
+    startedAt?: number;
+    finishedAt?: number;
+    durationMs?: number;
+    /** Cookies this crawl saw (the stored list also keeps earlier finds: `keptFromEarlier`). */
+    cookieCount?: number;
+    keptFromEarlier?: number;
+    pagesVisited?: number;
+    /** Where the site's address redirected to (its canonical host), when it did. */
+    finalUrl?: string;
+    /** Why it failed. */
+    error?: string;
 }
 /** Consent-button parity of the banner a real browser saw on the site (see ScanStatus). */
 interface ButtonParityScan {
@@ -539,6 +804,18 @@ interface ButtonParityLint {
     score: number;
     suggestedReject: SuggestedRejectStyle[];
 }
+/**
+ * Scrollbars on the surfaces Cookie Munch renders — the same shape on the banner theme (`theme.scrollbar`)
+ * and the rights-page theme. Colours are #hex, rgb() or hsl(); width is clamped to 4–16, radius to 0–999.
+ */
+interface ScrollbarTheme {
+    style: 'themed' | 'thin' | 'native' | 'hidden';
+    thumb?: string;
+    thumbHover?: string;
+    track?: string;
+    width?: number;
+    radius?: number;
+}
 /** The hosted rights page document. See docs/rights-page for each section type's props. */
 interface RightsPageDocument {
     v: 1;
@@ -547,6 +824,7 @@ interface RightsPageDocument {
         width: 'narrow' | 'normal' | 'wide' | 'full';
         density: 'compact' | 'comfortable' | 'spacious';
         colorScheme: 'light' | 'dark' | 'auto';
+        scrollbar?: ScrollbarTheme;
         [k: string]: unknown;
     };
     sections: Array<{
@@ -686,9 +964,12 @@ interface RightsLinkInput {
 }
 /** A signed, single-use link to the hosted rights page for one signed-in person. */
 interface RightsLink {
+    /** `https://<customDomain>/?t=…`, or `https://cookiemunch.net/r/<cbid>?t=…` when `customDomain` is null. */
     url: string;
     /** Epoch milliseconds. */
     expiresAt: number;
+    /** The site's active custom rights-page host the link opens on, or null. */
+    customDomain: string | null;
 }
 /** One DNS record to create, exactly as written. */
 interface DnsRecordInstruction {
@@ -831,6 +1112,31 @@ interface Member {
 interface ApiKeyPrefix {
     prefix: string;
     createdAt?: number;
+    /** Epoch ms the key stops working; null = never. */
+    expiresAt?: number | null;
+    name?: string | null;
+    /** null = full access. */
+    scopes?: string[] | null;
+    cbids?: string[] | null;
+    /** Epoch ms it last authenticated a request (recorded at most hourly); null = not since recording began. */
+    lastUsedAt?: number | null;
+}
+/** GET /v1/keys/report — key hygiene. */
+interface ApiKeyReport {
+    generatedAt: number;
+    unusedDays: number;
+    expiringDays: number;
+    unused: Array<ApiKeyPrefix & {
+        reason: string;
+    }>;
+    broad: Array<ApiKeyPrefix & {
+        reason: string;
+    }>;
+    expiringSoon: Array<ApiKeyPrefix & {
+        reason: string;
+    }>;
+    noExpiry: number;
+    total: number;
 }
 /** A newly issued key. `key` is returned ONCE and never again. Returned by keys.issue(). */
 interface ApiKeyIssued {
@@ -866,6 +1172,8 @@ interface ApiKeyIssueInput {
     cbids?: string[];
     /** Expire the key after this many days (1–3650). */
     expiresInDays?: number;
+    /** Or when it expires: epoch ms or an ISO date-time (not with expiresInDays). Omit both: never. */
+    expiresAt?: number | string;
 }
 /** Org usage/quota summary. Matches the server's Usage schema. */
 interface Usage {
@@ -1114,6 +1422,8 @@ interface ApiKeyUpdate {
     name?: string;
     scopes?: string[];
     cbids?: string[];
+    /** A new expiry (epoch ms or ISO date-time), or null to remove it. */
+    expiresAt?: number | string | null;
 }
 /** An image to upload: base64 (or a `data:` URL) plus its type. */
 interface AssetUpload {
@@ -1413,6 +1723,11 @@ interface ExecutorProfile {
             statusPath: string;
             values: string[];
         };
+        /** How this system says the person was already removed; closes the task as `already_erased`. Checked before `noMatch`. */
+        alreadyErased?: {
+            statusPath: string;
+            values: string[];
+        };
     };
     /** Response header carrying the system's version, recorded in the task log. Default `X-Version`. */
     versionHeader?: string;
@@ -1446,6 +1761,23 @@ interface ExecutorProfile {
         failed: string[];
     };
     idempotencyHeader?: string;
+    /**
+     * An identity platform's app grant, revoked on erasure before anything else: look it up by
+     * `{email}`, then end it with `{grant}`. A test looks it up but never revokes it.
+     */
+    grantRevoke?: {
+        lookup: {
+            method: 'GET' | 'POST';
+            path: string;
+            body?: unknown;
+            grantIdPath: string;
+        };
+        revoke: {
+            method: 'POST' | 'DELETE';
+            path: string;
+            body?: unknown;
+        };
+    };
     /** How that system signs its webhooks, if it sends any. */
     webhook?: {
         algorithm: 'hmac-sha256';
@@ -1473,9 +1805,80 @@ interface DsarExecutor {
     hasWebhookSecret: boolean;
     /** Open a sub-task automatically when a request reaches fulfilment. */
     auto: boolean;
+    /** What the subject reads on this system's notice line when it holds nothing about them. */
+    subjectNote?: string;
     createdAt: number;
     /** Where that system should send its completion webhooks. On every connection, secret or not. */
     webhookUrl: string;
+    /**
+     * The last canary health check (hourly, and on `testExecutor(id, { canary: true })`). null
+     * until the first; cleared when the address, profile or key changes.
+     */
+    health: ExecutorHealth | null;
+    /** The preset it was built from; absent when hand-written. */
+    preset?: ExecutorPresetName;
+    presetVersion?: number;
+    /** Newer than `presetVersion`: `upgradeExecutorPreset` applies it. */
+    presetLatestVersion?: number;
+    /** The non-secret params it was built with, e.g. `{ orgId }`. */
+    presetParams?: Record<string, string>;
+    /** How the stored address and profile differ from what its preset version builds. Empty: unmodified. */
+    presetDiff?: ConfigChange[];
+}
+/** A connection's last canary health check. */
+interface ExecutorHealth {
+    lastCheckedAt: number;
+    ok: boolean;
+    verdict: string;
+    /** e.g. `base_url_redirects`, `credential_unavailable`. */
+    code?: string;
+}
+/** A preset's name, as `executorPresets()` lists them. Not enumerated here: presets are data. */
+type ExecutorPresetName = string;
+/**
+ * Connect a system from a versioned preset instead of a hand-written profile. Each preset
+ * lists the params it takes (`executorPresets()`); a preset waiting on another platform is
+ * refused with `preset_waiting_on_platform`.
+ */
+interface DsarExecutorPresetInput {
+    preset: ExecutorPresetName;
+    presetVersion?: number;
+    secretKey: string;
+    system?: string;
+    baseUrl?: string;
+    orgId?: string;
+    atlasIdAppId?: string;
+    webhookSecret?: string;
+    auto?: boolean;
+    cbid?: string;
+}
+/** What `upgradeExecutorPreset` takes: a version, a preset to adopt, or params to add. */
+interface ExecutorPresetUpgrade {
+    preset?: ExecutorPresetName;
+    presetVersion?: number;
+    orgId?: string;
+    atlasIdAppId?: string;
+}
+/** The presets, which are usable now, and this org's canary address. */
+interface ExecutorPresets {
+    canaryEmail: string;
+    presets: Array<{
+        name: ExecutorPresetName;
+        title: string;
+        latestVersion: number;
+        defaultSystem?: string;
+        params: Array<{
+            name: string;
+            required: boolean;
+            description: string;
+        }>;
+        available: boolean;
+        waitingOn?: {
+            platform: string;
+            items: string[];
+            operations: string[];
+        };
+    }>;
 }
 /** What a connection write would do (`?dryRun=1`). Nothing was stored. */
 interface DsarExecutorDryRun {
@@ -1526,11 +1929,14 @@ interface DsarExecutorInput {
     secretKey: string;
     /**
      * The signing secret of its webhook endpoint. Optional — polling closes tasks without it.
-     * A `whsec_<base64>` secret verifies a delivery signed with either the base64-decoded bytes
-     * or the literal string; anything else only with its UTF-8 bytes.
+     * A `whsec_<base64>` secret (standard base64 or base64url, padded or not) verifies a delivery
+     * signed with either the base64-decoded bytes or the literal string; anything else only with
+     * its UTF-8 bytes.
      */
     webhookSecret?: string;
     auto?: boolean;
+    /** What the subject reads when this system holds nothing about them (≤500 chars, never a key). */
+    subjectNote?: string;
     /** How to drive it. */
     profile: ExecutorProfile;
 }
@@ -1542,6 +1948,8 @@ interface DsarExecutorPatch {
     secretKey?: string;
     webhookSecret?: string | null;
     auto?: boolean;
+    /** null removes it. */
+    subjectNote?: string | null;
 }
 /** One entry in a fulfilment task's status history. */
 interface DsarTaskEvent {
@@ -1554,12 +1962,12 @@ interface DsarTaskEvent {
     externalRef?: string;
 }
 /** What a task's answer means for the person. `exported` only once the export was fetched. */
-type DsarTaskOutcome = 'located' | 'exported' | 'erased' | 'no_record' | 'done_without_artifact' | 'not_applicable';
+type DsarTaskOutcome = 'located' | 'exported' | 'erased' | 'no_record' | 'done_without_artifact' | 'not_applicable' | 'already_erased' | 'external_identity';
 /** One request made to a connected system on a task's behalf, credentials removed. Kept 30 days. */
 interface DsarTaskLogEntry {
     id?: string;
     system?: string;
-    step: 'lookup' | 'open' | 'poll' | 'export';
+    step: 'lookup' | 'open' | 'poll' | 'export' | 'grant';
     method: string;
     path: string;
     /** Absent when the system never answered. */
@@ -1573,6 +1981,11 @@ interface DsarTaskLogEntry {
     error?: string;
     /** The system's version header on this answer. */
     version?: string;
+    /** This answer was a redirect (origin and path; never the query). Only same-origin, method-keeping ones are followed. */
+    redirect?: {
+        status: number;
+        location: string;
+    };
     at: number;
 }
 /** One fulfilment task with its history and its upstream request log. */
@@ -1618,11 +2031,21 @@ interface ExecutorTestResult {
     /** One sentence: what a real request would have done. */
     verdict: string;
     ok: boolean;
+    /** Why not, when there is a code: `base_url_redirects` — the baseUrl redirected; the verdict names the status and target. */
+    code?: string;
+    /** The subject's app grant at an identity platform, when the profile has a grant step. Never revoked by a test. */
+    grant?: string;
+    /** Present when the test used the org canary address, with the address in `email`. */
+    canary?: boolean;
+    email?: string;
     /** Every upstream answer, as the system gave it (credentials removed). */
     exchanges: DsarTaskLogEntry[];
 }
 interface ExecutorTestInput {
-    email: string;
+    /** The address to look up. Required unless `canary` is true. */
+    email?: string;
+    /** Use this org's canary address — no real person. A canary `locate` also updates `health`. */
+    canary?: boolean;
     /** Default `locate`. */
     operation?: 'locate' | 'export' | 'erase';
     /** For `export` only: open a real export and poll it once. An erasure is never sent. */
@@ -1682,7 +2105,31 @@ interface CookieMunchClient {
         list(): Promise<Site[]>;
         create(input: SiteCreate): Promise<Site>;
         get(cbid: string): Promise<Site>;
+        /**
+         * Rename or move a site: domain, display name, aliases. The cbid and the consent ledger stay; a domain
+         * move clears verification. `{ dryRun: true }` answers with the diff and stores nothing.
+         */
+        update(cbid: string, patch: SiteUpdate, opts?: {
+            dryRun?: boolean;
+        }): Promise<SiteUpdateResult>;
         delete(cbid: string): Promise<void>;
+        /** Partner platforms granted this site's consent events, and the partners on offer. */
+        listPartners(cbid: string): Promise<{
+            links: PartnerLink[];
+            partners: PartnerCatalogEntry[];
+        }>;
+        /** Grant a partner (Forumulate, Atlas) the site's consent events — no secret is created. Idempotent. */
+        linkPartner(cbid: string, input: PartnerLinkCreate, opts?: {
+            dryRun?: boolean;
+        }): Promise<{
+            change: 'created' | 'updated' | 'unchanged';
+            link: PartnerLink;
+            dryRun?: true;
+        }>;
+        /** Revoke a partner link: deliveries stop at once. */
+        unlinkPartner(cbid: string, linkId: string): Promise<{
+            link: PartnerLink;
+        }>;
         getConfig(cbid: string): Promise<SiteConfig>;
         /**
          * Replaces the whole config — a top-level field you omit reverts to its default. With
@@ -1714,8 +2161,24 @@ interface CookieMunchClient {
             replace?: boolean;
         }): Promise<ButtonParityLint>;
         cookies(cbid: string): Promise<CookieDeclaration>;
-        scan(cbid: string): Promise<ScanStatus>;
-        scanStatus(cbid: string): Promise<ScanStatus>;
+        /**
+         * Start a cookie crawl. Answers at once with `scanId` and `state: 'queued'`; `wait`
+         * (seconds, ≤60) holds the request until the scan is done or failed.
+         */
+        scan(cbid: string, opts?: {
+            wait?: number;
+        }): Promise<ScanStatus>;
+        /** The last scan's state. `wait` (seconds, ≤60) holds the request until a running scan settles. */
+        scanStatus(cbid: string, opts?: {
+            wait?: number;
+        }): Promise<ScanStatus>;
+        /**
+         * Resolve once the site's scan is done or failed (read `state` and `error`), long-polling
+         * the server. At `timeoutMs` (default 120 000) it resolves with the still-running state.
+         */
+        waitForScan(cbid: string, opts?: {
+            timeoutMs?: number;
+        }): Promise<ScanStatus>;
         ab(cbid: string): Promise<AbResult[]>;
         /** Generate the site's privacy and cookie policy, as Markdown. */
         policy(cbid: string, opts?: PolicyOptions): Promise<string>;
@@ -1761,6 +2224,69 @@ interface CookieMunchClient {
             cookie: DeclaredCookie;
             warnings?: DeclarationWarning[];
         } & Partial<DeclarationDryRun>>;
+        /**
+         * Retire a cookie the site renamed or stopped setting: it leaves the banner's list,
+         * `data-cc="declaration"` and the public feed, and stays listed for you with `retired`.
+         * A name ending in `*` retires every cookie with that prefix. If a crawl or a visit sees
+         * it again afterwards it is listed again, flagged `review: 'retired_but_seen'`.
+         */
+        retireCookie(cbid: string, name: string, input?: {
+            renamedTo?: string;
+            note?: string;
+        }, opts?: {
+            dryRun?: boolean;
+        }): Promise<{
+            cookie: RetiredCookie;
+            matched: string[];
+            dryRun?: true;
+            retired?: RetiredCookie[];
+        }>;
+        /** Un-retire a cookie: it is listed again everywhere. */
+        unretireCookie(cbid: string, name: string): Promise<void>;
+        /** What un-retiring would leave; nothing is removed. */
+        unretireCookie(cbid: string, name: string, opts: {
+            dryRun: true;
+        }): Promise<{
+            dryRun: true;
+            retired: RetiredCookie[];
+        }>;
+        /** Every declaration preset (atlas, forumulate, chatly, cookiemunch): params, what it declared here, manifest status. */
+        cookiePresets(cbid: string): Promise<{
+            presets: CookiePreset[];
+        }>;
+        /**
+         * Apply (or re-sync) a vendor preset: declares what that platform writes, marked
+         * `vendor`. Names you declared yourself are kept (`skipped`). `dryRun` stores nothing.
+         */
+        applyCookiePreset(cbid: string, vendor: CookiePresetVendor, params?: CookiePresetParams, opts?: {
+            dryRun?: boolean;
+        }): Promise<CookiePresetResult>;
+        /** Remove every declaration a vendor preset made. */
+        removeCookiePreset(cbid: string, vendor: CookiePresetVendor, opts?: {
+            dryRun?: boolean;
+        }): Promise<{
+            vendor: CookiePresetVendor;
+            removed: string[];
+            dryRun?: true;
+            declared?: DeclaredCookie[];
+            diff?: DeclarationDiff;
+        }>;
+        /** Remove every stored (scanned or observed) row of this name. A declaration of it stays. */
+        deleteObservedCookie(cbid: string, name: string): Promise<void>;
+        /** What deleting it would remove; nothing is removed. */
+        deleteObservedCookie(cbid: string, name: string, opts: {
+            dryRun: true;
+        }): Promise<ObservedPurgeResult>;
+        /**
+         * Purge observed since T: remove every row a real visit first reported at or after
+         * `since` (and before `until`). Crawled rows and declarations stay. ISO-8601 or epoch ms.
+         */
+        purgeObservedCookies(cbid: string, input: {
+            since: string | number;
+            until?: string | number;
+        }, opts?: {
+            dryRun?: boolean;
+        }): Promise<ObservedPurgeResult>;
         /** Remove a declaration; the scanned classification applies again. */
         undeclareCookie(cbid: string, name: string): Promise<void>;
         /** What removing a declaration would leave; nothing is removed. */
@@ -1844,7 +2370,10 @@ interface CookieMunchClient {
         create(input: DsarCreate): Promise<{
             request: DsarRequest;
         }>;
-        advance(id: string, toStatus: DsarStatus): Promise<{
+        /** `opts.messageToSubject` replaces the line the subject reads in the notice — for a rejection, why. */
+        advance(id: string, toStatus: DsarStatus, opts?: {
+            messageToSubject?: string;
+        }): Promise<{
             request: DsarRequest;
         }>;
         /** The subject-facing response notice for a request, as plain text. */
@@ -2116,7 +2645,7 @@ interface CookieMunchClient {
          * Connect one. The secret is stored encrypted and never returned; the response carries
          * the URL to point that system's webhook at.
          */
-        connectExecutor(input: DsarExecutorInput): Promise<DsarExecutorCreated>;
+        connectExecutor(input: DsarExecutorInput | DsarExecutorPresetInput): Promise<DsarExecutorCreated>;
         /**
          * Change a connection in place. Only what you send changes, and the stored credential
          * is kept unless you pass a new `secretKey` — so adding a field to a profile does not
@@ -2124,7 +2653,22 @@ interface CookieMunchClient {
          */
         updateExecutor(id: string, patch: DsarExecutorPatch): Promise<DsarExecutor>;
         /** What `connectExecutor` would create, validated in full; nothing is stored (`?dryRun=1`). */
-        dryRunConnectExecutor(input: DsarExecutorInput): Promise<DsarExecutorDryRun>;
+        dryRunConnectExecutor(input: DsarExecutorInput | DsarExecutorPresetInput): Promise<DsarExecutorDryRun>;
+        /** The versioned presets, whether each is usable now (or waits on another platform), and the org canary address. */
+        executorPresets(): Promise<ExecutorPresets>;
+        /**
+         * Rebuild a connection from its preset's latest version (or `presetVersion`), keeping its id
+         * and credentials; or adopt a preset on a hand-written one by naming it. Answers with `diff`.
+         */
+        upgradeExecutorPreset(id: string, input?: ExecutorPresetUpgrade): Promise<DsarExecutor & {
+            diff: ConfigChange[];
+            warnings?: Array<{
+                field: string;
+                reason: string;
+            }>;
+        }>;
+        /** What `upgradeExecutorPreset` would change; nothing is stored (`?dryRun=1`). */
+        dryRunUpgradeExecutorPreset(id: string, input?: ExecutorPresetUpgrade): Promise<DsarExecutorDryRun>;
         /** What `updateExecutor` would change, with a diff; the stored connection is untouched (`?dryRun=1`). */
         dryRunUpdateExecutor(id: string, patch: DsarExecutorPatch): Promise<DsarExecutorDryRun>;
         /**
@@ -2196,8 +2740,22 @@ interface CookieMunchClient {
         update(prefix: string, patch: ApiKeyUpdate): Promise<{
             ok: true;
         }>;
+        /** Key hygiene: keys unused for `unusedDays` (default 90), broad keys, keys expiring within `expiringDays` (default 14). */
+        report(opts?: {
+            unusedDays?: number;
+            expiringDays?: number;
+        }): Promise<ApiKeyReport>;
     };
     usage(): Promise<Usage>;
+    /** Every link a site's privacy wiring depends on, one row each with `ok` and a fix hint. `cbid` may be omitted with one site. */
+    integrationHealth(cbid?: string): Promise<IntegrationHealthReport>;
+    /**
+     * Wire a product's privacy in one call: the site, connected systems, Atlas and Forumulate. Idempotent;
+     * `{ dryRun: true }` writes nothing anywhere. No secret appears in the answer.
+     */
+    provision(input: ProvisionRequest, opts?: {
+        dryRun?: boolean;
+    }): Promise<ProvisionResult>;
     /** The key's organisation. Requires an unscoped key that is not property-locked. */
     org: {
         get(): Promise<Org>;
@@ -2352,4 +2910,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 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 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 DsarExportResult, type DsarRequest, type DsarStatus, type DsarTask, type DsarTaskEvent, type DsarTaskExport, type DsarTaskLogEntry, type DsarTaskOutcome, type DsarType, type EnforcementRuleInput, type ExecutorProfile, type ExecutorTestInput, type ExecutorTestResult, type ExecutorWebhookDelivery, type ExecutorWebhookTestResult, type FlowIssue, type FlowOp, type FlowOpResponse, type FulfillmentOp, type Identifier, type Identity, type ImportedCookie, type ImportedDeclaration, type InstallSnippet, type LegalBasis, type LogQuery, type MailProvider, type MailProviderInput, type MailProviderKind, type MailProviderTestResult, type Member, type OptInMethod, type Org, type OrgUpdate, type ParityControlSummary, type PlanSource, type PolicyOptions, type PreferenceItem, type PreferenceRecord, type PreviewToken, type PreviewTokenOptions, type ProfileAttributeInput, 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 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 SessionAnalysisInput, type SignedReceipt, type Site, type SiteConfig, type SiteCookie, type SiteCreate, type SiteFlow, type SnippetOptions, 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 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 };