@cookiemunch/sdk 0.1.1 → 0.3.0

package/dist/index.d.ts

@@ -114,6 +114,38 @@ interface DsarRequest {
     /** 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;
 }
+/**
+ * How a rights-page requester was verified — on every answer of the public intake
+ * (`POST /api/v1/public/dsar`, `/verify`, `/resend`) and so in the `dsar.created` webhook payload.
+ * `email_code` on a 202: a code was mailed through your own provider; on a 201: the code matched.
+ * `none` with a `reason`: filed without verification — confirm the requester yourself. `none`
+ * without one: an opt-out, which needs no verification.
+ */
+type PublicVerification = {
+    method: 'session' | 'email_code' | 'account_link';
+} | {
+    method: 'none';
+    reason?: 'no_verification_configured' | 'mail_failed' | 'recipient_rejected';
+};
+/** A public intake that filed a request (201): also the `dsar.created` payload for one. */
+interface PublicDsarFiled {
+    id: string;
+    status: 'received' | 'verifying';
+    /** Epoch ms the statutory response is due. */
+    deadline: number;
+    /** Only when filed without verification; the same as `verification.method` `none` with a `reason`. */
+    unverified?: true;
+    verification: PublicVerification;
+}
+/** A public intake waiting for its email code (202). */
+interface PublicDsarPending {
+    pendingId: string;
+    expiresAt: number;
+    resendAfter?: number;
+    verification: {
+        method: 'email_code';
+    };
+}
 interface DsarCreate {
     type: DsarType;
     subjectEmail: string;
@@ -220,13 +252,13 @@ declare function verifyWebhookSignature(input: VerifyWebhookInput): boolean;
  * from the key, so callers never pass an orgId. `fetch` is injectable for testing
  * and non-browser/non-Node runtimes; it defaults to the global fetch.
  *
- *   const fc = createCookieMunch({ apiKey: 'fck_…', baseUrl: 'https://cmp.example.com' });
+ *   const fc = createCookieMunch({ apiKey: 'fck_…', baseUrl: 'https://api.cookiemunch.net' });
  *   const sites = await fc.sites.list();
  */
 
 interface CookieMunchOptions {
     apiKey: string;
-    /** e.g. "https://cmp.example.com" — the /v1 prefix is appended automatically. */
+    /** "https://api.cookiemunch.net" — the /v1 prefix is appended automatically. */
     baseUrl: string;
     /** Injectable for tests / custom runtimes. Defaults to the global fetch. */
     fetch?: typeof fetch;
@@ -240,7 +272,9 @@ interface CookieMunchOptions {
 declare class CookieMunchApiError extends Error {
     readonly status: number;
     readonly code?: string;
-    constructor(status: number, message: string, code?: string);
+    /** The parsed JSON error body, when there was one (e.g. `issues` on a 422). */
+    readonly body?: unknown;
+    constructor(status: number, message: string, code?: string, body?: unknown);
 }
 /** A cookie discovered on a site, classified into a consent category (wire shape of the
  *  cookie-declaration feed). Matches the server's CategorizedCookie schema. */
@@ -250,6 +284,11 @@ interface CategorizedCookie {
     domain?: string;
     provider?: string;
     purpose?: string;
+    /**
+     * The purpose by language (lowercase BCP-47 tag). On a declared row, the owner's; on a
+     * row the cookie database classified, the database's (empty: none yet).
+     */
+    purposes?: Record<string, string>;
     expiry?: string;
     /** Page URLs (multi-page scan) that set this cookie, earliest first. */
     foundOnPages?: string[];
@@ -257,8 +296,34 @@ 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 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. */
@@ -268,13 +333,21 @@ 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 {
     /** A standard category or one of the site's `categories.custom` ids. Not `unclassified`. */
     category: string;
-    /** Shown to visitors. */
+    /** Shown to visitors, and the fallback for any language `purposes` lacks. */
     purpose: string;
+    /**
+     * The purpose in other languages: `{ es: '…', 'pt-BR': '…' }` (BCP-47 language or
+     * language-region tags, stored lowercased; ≤50 languages, ≤1000 characters each).
+     * The banner, `data-cc="declaration"` and /cookie-declaration.js draw the visitor's.
+     */
+    purposes?: Record<string, string> | null;
     provider?: string;
     expiry?: string;
     domain?: string;
@@ -286,6 +359,23 @@ interface DeclaredCookie extends DeclaredCookieInput {
     name: string;
     updatedAt: number;
 }
+/** What a declaration write would change (`dryRun`). */
+interface DeclarationDiff {
+    added: DeclaredCookie[];
+    removed: DeclaredCookie[];
+    changed: Array<{
+        name: string;
+        before: DeclaredCookie;
+        after: DeclaredCookie;
+    }>;
+}
+/** The answer to a `dryRun` declaration write: nothing was stored. */
+interface DeclarationDryRun {
+    dryRun: true;
+    /** Every declaration the site would have. */
+    declared: DeclaredCookie[];
+    diff: DeclarationDiff;
+}
 /** A warning about a write: e.g. the category is switched off for the site. */
 interface DeclarationWarning {
     field: string;
@@ -312,9 +402,43 @@ 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;
+    /** Why it failed. */
+    error?: string;
+}
+/** Consent-button parity of the banner a real browser saw on the site (see ScanStatus). */
+interface ButtonParityScan {
+    url: string;
+    /** False when no visible consent accept control was found in a recognisable banner. */
+    bannerFound: boolean;
+    /**
+     * True when the checks ran: our embed, or a recognised banner with both Accept and Reject.
+     * False = not measured — no findings, `score` null. Absent on scans stored before it existed.
+     */
+    measured?: boolean;
+    /** `cookiemunch` = our embed; `other` = found by its button text. */
+    cmp: 'cookiemunch' | 'other' | null;
+    acceptFound: boolean;
+    rejectFound: boolean;
+    designWarnings: ButtonParityFinding[];
+    /** 0–100; null when no banner was found. */
+    score: number | null;
+    checkedAt?: number;
 }
 /** @deprecated The server returns {@link ScanStatus}; kept only for back-compat. */
 interface ScanResult {
@@ -388,6 +512,195 @@ interface ConfigDryRun {
     /** Every leaf that would change. */
     diff: ConfigChange[];
     warnings?: ConfigWarning[];
+    /** Consent-button parity of the would-be config (see {@link ButtonParityFinding}). */
+    designWarnings: ButtonParityFinding[];
+}
+/** The effective style of an Accept all / Reject all control. */
+interface ParityControlSummary {
+    id?: string;
+    label: string;
+    element: 'button' | 'link';
+    background?: string;
+    color?: string;
+    borderColor?: string;
+    borderWidth?: number;
+    fontSize?: number;
+    fontWeight?: number;
+    width?: number;
+    height?: number;
+}
+/**
+ * One way Accept all is pushed harder than Reject all (colour, size, placement, copy, custom
+ * CSS). Returned as `designWarnings` on every config read and write, and by `lintConfig`.
+ * A warning, never an error — the config is saved regardless. See /docs/fair-consent-buttons.
+ */
+interface ButtonParityFinding {
+    code: 'reject_missing_first_layer' | 'reject_missing_same_layer' | 'reject_hidden' | 'reject_below_fold' | 'reject_isolated' | 'reject_low_emphasis' | 'saturation_gap' | 'color_mismatch' | 'reject_text_low_contrast' | 'reject_styled_as_link' | 'font_size_gap' | 'font_weight_gap' | 'size_gap' | 'padding_gap' | 'border_mismatch' | 'reject_label_missing' | 'reject_label_long' | 'confirmshaming' | 'custom_css_asymmetric';
+    severity: 'warning' | 'notice';
+    layer: 'banner' | 'preferences' | 'modal' | 'popup' | 'bar' | 'inline' | 'custom';
+    accept: ParityControlSummary | null;
+    reject: ParityControlSummary | null;
+    metric: {
+        name: string;
+        accept?: number;
+        reject?: number;
+        value: number;
+        threshold: number;
+    };
+    detail: string;
+    fix: string;
+    where: {
+        view?: string;
+        variant?: string;
+        theme?: 'light' | 'dark';
+        breakpoint?: 'desktop' | 'mobile';
+        language?: string;
+        url?: string;
+    };
+}
+/** Reject all style values that would match the Accept all on the same layer. */
+interface SuggestedRejectStyle {
+    layer: string;
+    view?: string;
+    background?: string;
+    color?: string;
+    borderColor?: string;
+    borderWidth?: number;
+    fontSize?: number;
+    fontWeight?: number;
+    width?: number;
+    height?: number;
+}
+/** `POST /v1/sites/:cbid/config/lint` — nothing is saved. */
+interface ButtonParityLint {
+    /** `merged` = what PATCH would store (merged over the stored config); `replaced` = what PUT would store (`replace: true`). */
+    mode: 'merged' | 'replaced';
+    designWarnings: ButtonParityFinding[];
+    /** 100 minus 20 per warning and 5 per notice, floored at 0. */
+    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;
+    theme: {
+        preset: 'brand' | 'light' | 'dark' | 'custom';
+        width: 'narrow' | 'normal' | 'wide' | 'full';
+        density: 'compact' | 'comfortable' | 'spacious';
+        colorScheme: 'light' | 'dark' | 'auto';
+        scrollbar?: ScrollbarTheme;
+        [k: string]: unknown;
+    };
+    sections: Array<{
+        id: string;
+        type: string;
+        props: Record<string, unknown>;
+        hidden?: {
+            phone?: boolean;
+            desktop?: boolean;
+        };
+        style?: Record<string, unknown>;
+    }>;
+    form: {
+        requestTypes: Array<Record<string, unknown>>;
+        fields: Array<Record<string, unknown>>;
+        jurisdiction: 'auto' | 'ask' | 'hidden';
+        consentIdField: 'hidden' | 'optional' | 'required';
+        success: {
+            title?: string;
+            body?: string;
+        };
+        submitLabel?: string;
+    };
+    i18n: {
+        defaultLocale: string;
+        autoDetect: boolean;
+        overrides: Record<string, unknown>;
+    };
+    seo: {
+        title?: string;
+        description?: string;
+        favicon?: string;
+        image?: string;
+        index: boolean;
+    };
+    customCss?: string;
+}
+/** `message` is English; `code` (+ `params`) is stable, for your own wording or language. */
+interface RightsPageIssue {
+    path: string;
+    message: string;
+    code?: string;
+    params?: Record<string, string | number>;
+}
+interface RightsPageDraft {
+    cbid: string;
+    draft: RightsPageDocument;
+    version: number;
+    publishedAt: number | null;
+    updatedAt: number | null;
+    warnings: RightsPageIssue[];
+}
+interface RightsPageDryRun {
+    dryRun: true;
+    cbid: string;
+    draft: RightsPageDocument;
+    warnings: RightsPageIssue[];
+}
+/** Who published a version: `publishedBy` is an actor id; `publishedByEmail` names a dashboard user (null for an API key). */
+interface RightsPagePublisher {
+    publishedBy: string;
+    publishedByEmail: string | null;
+    publishedVia: 'dashboard' | 'api_key';
+}
+interface RightsPagePublished {
+    cbid: string;
+    page: RightsPageDocument;
+    version: number;
+    publishedAt: number;
+    publishedBy?: string | null;
+    publishedByEmail?: string | null;
+    publishedVia?: 'dashboard' | 'api_key' | null;
+}
+/**
+ * Optimistic concurrency for a draft write: the draft's `updatedAt` as you last read it (epoch ms or
+ * an ISO date; null = you saw no saved draft). A mismatch rejects with a 409 CookieMunchApiError whose
+ * body is RightsPageDraftConflict. Omitted: a full write (put) is last-write-wins; a patch merges onto the draft
+ * as it is when written, so a concurrent edit is not lost.
+ */
+interface RightsPageWriteOptions {
+    baseUpdatedAt?: number | string | null;
+}
+interface RightsPageDraftConflict {
+    error: 'draft_conflict';
+    draft: RightsPageDraft;
+}
+/** `draftUpdatedAt`: the draft's updatedAt after the call — pass it as the next `baseUpdatedAt`. */
+interface RightsPagePublishResult {
+    cbid: string;
+    version: number;
+    publishedAt: number;
+    draftUpdatedAt: number;
+    rolledBackTo?: number;
+}
+interface RightsPageVersions {
+    cbid: string;
+    versions: Array<{
+        version: number;
+        publishedAt: number;
+    } & RightsPagePublisher>;
 }
 /** Options for POST /v1/sites/:cbid/preview-token. All optional. */
 interface PreviewTokenOptions {
@@ -411,6 +724,70 @@ interface PreviewToken {
     /** The page with `cm_preview` / `cm_region` / `cm_lang` added. */
     previewUrl?: string;
 }
+/** A right a rights link may file (the hosted rights page's request-type kinds). */
+type RightKind = 'access' | 'erasure' | 'rectification' | 'portability' | 'restriction' | 'objection' | 'opt_out_sale' | 'opt_out_targeted' | 'limit_sensitive';
+/** Input for POST /v1/sites/:cbid/rights-links. */
+interface RightsLinkInput {
+    /** The signed-in person. `email` must be an address you have verified. */
+    subject: {
+        email: string;
+        userId?: string;
+    };
+    /** Limit the link to these rights. Default: every right the page offers. */
+    rights?: RightKind[];
+    /** Lifetime in seconds, 60..3600. Default 900. */
+    ttlSeconds?: number;
+}
+/** A signed, single-use link to the hosted rights page for one signed-in person. */
+interface RightsLink {
+    url: string;
+    /** Epoch milliseconds. */
+    expiresAt: number;
+}
+/** One DNS record to create, exactly as written. */
+interface DnsRecordInstruction {
+    type: 'CNAME' | 'TXT';
+    name: string;
+    value: string;
+}
+/** A custom hostname serving a site's rights page. */
+interface RightsPageDomain {
+    /** Lowercase ASCII form (punycode for an internationalised name). */
+    hostname: string;
+    /** As a person reads it. */
+    unicodeHostname: string;
+    cbid: string;
+    /** pending_dns → verifying → issuing → active, or error (see lastError). */
+    status: 'pending_dns' | 'verifying' | 'issuing' | 'active' | 'error';
+    certStatus: 'none' | 'pending' | 'issued' | 'failed';
+    createdAt: number;
+    verifiedAt?: number;
+    activatedAt?: number;
+    lastCheckedAt?: number;
+    /** dns_not_found | wrong_target | hostname_in_use | router_write_failed | certificate_not_issued | dns_changed | probe_failed */
+    lastError?: string;
+    url: string;
+    /** The records to create: the CNAME, or (apex / flattened / proxied) the TXT plus an ALIAS to the same target. */
+    /** `cname.value` is this domain's own `<token>.cname.cookiemunch.net` — unique to the claim; a CNAME to anything else does not verify it. */
+    dns: {
+        recommended: 'cname' | 'flattened';
+        cname: DnsRecordInstruction;
+        txt: DnsRecordInstruction;
+    };
+    /** Only on a verify that found no proof: what DNS answered. */
+    dnsSeen?: {
+        cnames: string[];
+        addresses: string[];
+        txt: string[];
+    };
+}
+/** The site's custom hostnames, the plan allowance (null = unlimited) and the org's usage. */
+interface RightsPageDomainList {
+    domains: RightsPageDomain[];
+    limit: number | null;
+    used: number;
+    target: string;
+}
 /** Options for the snippet endpoint. */
 interface SnippetOptions {
     /** Override the site's configured `blocking.mode`. Default: the config's. */
@@ -469,7 +846,8 @@ type FlowOp = {
  */
 type FlowOpResponse = {
     ok: true;
-    flow: Record<string, unknown>;
+    flow: Record<string, unknown>; /** Consent-button parity of the saved design. */
+    designWarnings?: ButtonParityFinding[];
 } | {
     ok: false;
     failedAt?: number;
@@ -625,6 +1003,150 @@ interface Org {
     plan: string;
     logoUrl: string | null;
 }
+type MailProviderKind = 'brevo' | 'sendgrid' | 'postmark' | 'resend' | 'ses' | 'smtp';
+/**
+ * The org's own mail provider for rights-request mail. The credential is never returned —
+ * `secretLast4` only. `sender` says whether verification codes go through it right now
+ * (`own`) or are not mailed at all (`none`): there is no shared sender for rights mail.
+ */
+interface MailProvider {
+    configured: boolean;
+    sender: 'own' | 'none';
+    provider?: MailProviderKind;
+    fromEmail?: string;
+    fromName?: string;
+    replyTo?: string;
+    ses?: {
+        region: string;
+        accessKeyId: string;
+    };
+    smtp?: {
+        host: string;
+        port: number;
+        security: 'tls' | 'starttls';
+        username: string;
+    };
+    secretLast4?: string;
+    status?: 'untested' | 'verified' | 'failing';
+    verifiedAt?: number | null;
+    lastTest?: {
+        ok: boolean;
+        at: number;
+        error?: string;
+    } | null;
+    updatedAt?: number;
+    /** Only on `set`: no verification codes are mailed until a test succeeds. */
+    note?: string;
+}
+/** Save a provider. `secret` is write-only; omit it to keep the stored one (same provider only). */
+interface MailProviderInput {
+    provider: MailProviderKind;
+    fromEmail: string;
+    fromName?: string | null;
+    replyTo?: string | null;
+    secret?: string;
+    ses?: {
+        region: string;
+        accessKeyId: string;
+    };
+    smtp?: {
+        host: string;
+        port: 25 | 465 | 587 | 2525;
+        security: 'tls' | 'starttls';
+        username: string;
+    };
+}
+type RightsCaptchaProvider = 'turnstile' | 'hcaptcha' | 'recaptcha_v2' | 'recaptcha_v3';
+/**
+ * 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.
+ */
+interface RightsCaptcha {
+    /** `site`: the site's own setting; `org`: the organisation default; `default`: neither (off). */
+    source: 'site' | 'org' | 'default';
+    mode: 'own' | 'off';
+    provider?: RightsCaptchaProvider;
+    siteKey?: string;
+    /** reCAPTCHA v3 only. */
+    minScore?: number;
+    secretSet: boolean;
+    secretLast4?: string;
+    status: 'verified' | 'disabled';
+    verifiedAt: number | null;
+    updatedAt: number | null;
+    /** Only when a `set` turned the captcha off: what that costs. */
+    warning?: string;
+}
+/**
+ * `own` needs provider, siteKey and (the first time) secret; the provider is asked to accept the secret before
+ * anything is saved (422 captcha_secret_invalid / 502 captcha_unreachable). `off` removes spam protection beyond
+ * the hidden spam-trap field, the rate limits and the email code.
+ */
+interface RightsCaptchaInput {
+    mode: 'own' | 'off';
+    provider?: RightsCaptchaProvider;
+    siteKey?: string;
+    /** Write-only. Omit to keep the stored one (same provider, same place). */
+    secret?: string;
+    /** reCAPTCHA v3 only: 0.1–0.9, default 0.5. */
+    minScore?: number;
+}
+type RightsIdentityType = 'clerk' | 'atlas' | 'oidc_jwt';
+/**
+ * The sign-in provider rights requests are verified with: a visitor signed in to your site is
+ * verified by their session, with no code mail. Nothing here is secret.
+ */
+interface RightsIdentity {
+    /** `site`: the site's own setting; `org`: the organisation default; `default`: neither (none). */
+    source: 'site' | 'org' | 'default';
+    configured: boolean;
+    type?: RightsIdentityType;
+    issuer?: string;
+    jwksUrl?: string;
+    audience?: string;
+    authorizedParties?: string[];
+    emailClaim?: string;
+    emailVerifiedClaim?: string;
+    sessionCookieName?: string;
+    /** Present (true) only when set: clerk/atlas tokens without the verified claim are accepted. */
+    trustEmailClaim?: true;
+    status: 'verified' | 'not_configured';
+    verifiedAt: number | null;
+    updatedAt: number | null;
+}
+/**
+ * The JWKS is fetched and checked before anything is saved (502 identity_jwks_unreachable /
+ * 422 identity_jwks_invalid). `authorizedParties` (your own origins) is required for clerk and atlas;
+ * oidc_jwt needs an `audience` or `authorizedParties`. Issuer and JWKS URL are https on a host name,
+ * never an IP address. The token must carry the email and a verified-email claim set to `true`
+ * (clerk/atlas with `trustEmailClaim`: the verified claim may be absent).
+ */
+interface RightsIdentityInput {
+    type: RightsIdentityType;
+    /** Exactly the token's `iss` (Clerk: your Frontend API URL). */
+    issuer: string;
+    /** Required for oidc_jwt; clerk/atlas default to `<issuer>/.well-known/jwks.json`. */
+    jwksUrl?: string;
+    audience?: string;
+    authorizedParties?: string[];
+    /** Default `email`. */
+    emailClaim?: string;
+    /** Default `email_verified`. */
+    emailVerifiedClaim?: string;
+    /** Default `__session`: the cookie the hosted page on your custom domain reads. */
+    sessionCookieName?: string;
+    /**
+     * clerk/atlas only, default false. True when your provider has no verified-email claim and every
+     * address it puts in the email claim is verified: a token without the verified claim is accepted.
+     */
+    trustEmailClaim?: boolean;
+}
+interface MailProviderTestResult {
+    ok: boolean;
+    sentTo: string;
+    error?: string;
+    mailProvider: MailProvider;
+}
 /** Change an org's name or logo. `logoUrl: null` removes the logo. */
 interface OrgUpdate {
     name?: string;
@@ -708,6 +1230,8 @@ interface BannerSummary {
     name: string;
     updatedAt: number;
     assignedCbids: string[];
+    /** How many warning-severity consent-button parity findings the design has (0 = fair). */
+    designWarningCount: number;
 }
 /** A full account-level banner record, including its config JSON. */
 interface BannerRecord {
@@ -717,6 +1241,8 @@ interface BannerRecord {
     json: SiteConfig;
     createdAt: number;
     updatedAt: number;
+    /** Consent-button parity findings in the design. Never blocks a save. */
+    designWarnings?: ButtonParityFinding[];
 }
 /**
  * Input for the public consent-log ingest endpoint (POST /api/v1/consent) — the
@@ -1002,6 +1528,48 @@ interface DsarExecutor {
     /** Open a sub-task automatically when a request reaches fulfilment. */
     auto: boolean;
     createdAt: number;
+    /** Where that system should send its completion webhooks. On every connection, secret or not. */
+    webhookUrl: string;
+}
+/** What a connection write would do (`?dryRun=1`). Nothing was stored. */
+interface DsarExecutorDryRun {
+    dryRun: true;
+    /** The connection as it would be, credentials excluded. A create has no `id` or `webhookUrl` yet. */
+    executor: Partial<DsarExecutor> & Record<string, unknown>;
+    /** Each field that would change. */
+    diff: ConfigChange[];
+    warnings?: Array<{
+        field: string;
+        reason: string;
+    }>;
+}
+/** Where a webhook check stopped. */
+type WebhookStage = 'configuration' | 'headers' | 'timestamp' | 'prefix' | 'signature';
+/** Which key a verified delivery matched: a `whsec_` secret's base64-decoded remainder, or the secret as typed. */
+type WebhookKeyForm = 'decoded' | 'raw';
+/** Whether a supplied delivery verified (`stage` and `reason` are null when it did). */
+interface ExecutorWebhookTestResult {
+    verified: boolean;
+    stage: WebhookStage | null;
+    reason: string | null;
+    /** Which key form matched; null when refused. */
+    keyForm: WebhookKeyForm | null;
+}
+/** One delivery to a connection's webhook. Never the secret, the signature or the body. */
+interface ExecutorWebhookDelivery {
+    id: string;
+    executorId: string;
+    at: number;
+    verified: boolean;
+    stage: WebhookStage | null;
+    reason: string | null;
+    /** The HTTP status we answered with. */
+    status: number;
+    /** The first 16 hex characters of SHA-256 over the raw body. */
+    bodySha256: string;
+    bodyBytes: number;
+    /** Which key form matched; null when refused (or logged before this was kept). Never the key. */
+    keyForm: WebhookKeyForm | null;
 }
 interface DsarExecutorInput {
     /** The name this connection answers to in a plan, e.g. `identity` or `crm`. */
@@ -1010,15 +1578,25 @@ interface DsarExecutorInput {
     baseUrl: string;
     /** Its API key. Stored encrypted; never returned. */
     secretKey: string;
-    /** The signing secret of its webhook endpoint. Optional — polling closes tasks without it. */
+    /**
+     * The signing secret of its webhook endpoint. Optional — polling closes tasks without it.
+     * 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;
     /** How to drive it. */
     profile: ExecutorProfile;
 }
-interface DsarExecutorCreated extends DsarExecutor {
-    /** Point the connected system's webhook endpoint here. */
-    webhookUrl: string;
+type DsarExecutorCreated = DsarExecutor;
+/** The fields `updateExecutor` may change. */
+interface DsarExecutorPatch {
+    profile?: unknown;
+    baseUrl?: string;
+    secretKey?: string;
+    webhookSecret?: string | null;
+    auto?: boolean;
 }
 /** One entry in a fulfilment task's status history. */
 interface DsarTaskEvent {
@@ -1182,9 +1760,33 @@ interface CookieMunchClient {
         dryRunConfig(cbid: string, config: Partial<SiteConfig>, opts?: {
             mode?: 'patch' | 'put';
         } & PutConfigOptions): Promise<ConfigDryRun>;
+        /**
+         * Check a proposed config for consent-button parity — an Accept all pushed harder than
+         * Reject all — without saving it. A partial v1 config is merged over the stored one (like
+         * PATCH); a v2 design, or `replace: true`, is linted as sent. Needs only `sites:read`.
+         */
+        lintConfig(cbid: string, config: Partial<SiteConfig>, opts?: {
+            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>;
@@ -1221,24 +1823,63 @@ interface CookieMunchClient {
         /**
          * Declare what one cookie is. Overrides scanned, observed and database classification
          * in the API, the preference modal and `data-cc="declaration"`. A name ending in `*`
-         * declares a prefix wildcard.
+         * declares a prefix wildcard. `dryRun` validates and returns the would-be list and a
+         * diff without storing anything.
          */
-        declareCookie(cbid: string, name: string, input: DeclaredCookieInput): Promise<{
+        declareCookie(cbid: string, name: string, input: DeclaredCookieInput, opts?: {
+            dryRun?: boolean;
+        }): Promise<{
             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[];
         }>;
         /** Remove a declaration; the scanned classification applies again. */
         undeclareCookie(cbid: string, name: string): Promise<void>;
-        /** Declare many at once (all-or-nothing). `replace` also removes declarations not listed. */
+        /** What removing a declaration would leave; nothing is removed. */
+        undeclareCookie(cbid: string, name: string, opts: {
+            dryRun: true;
+        }): Promise<DeclarationDryRun>;
+        /**
+         * Declare many at once (all-or-nothing). `replace` also removes declarations not listed;
+         * `dryRun` answers with what would be stored and a diff, storing nothing.
+         */
         declareCookies(cbid: string, cookies: Array<DeclaredCookieInput & {
             name: string;
         }>, opts?: {
             replace?: boolean;
+            dryRun?: boolean;
         }): Promise<{
             declared: DeclaredCookie[];
             saved: number;
             removed: number;
             warnings?: DeclarationWarning[];
+            dryRun?: true;
+            diff?: DeclarationDiff;
         }>;
         snippet(cbid: string, opts?: SnippetOptions): Promise<InstallSnippet>;
         /**
@@ -1352,6 +1993,38 @@ interface CookieMunchClient {
         }>;
         delete(id: string): Promise<void>;
     };
+    /** The hosted rights page (cookiemunch.net/r/<cbid> or the site's own domain). */
+    rightsPage: {
+        get(cbid: string): Promise<RightsPageDraft>;
+        /** Replace the draft. Nothing is live until publish(). `opts.baseUpdatedAt` refuses to overwrite a newer save (409 draft_conflict). */
+        put(cbid: string, page: RightsPageDocument, opts?: RightsPageWriteOptions): Promise<RightsPageDraft>;
+        /** Merge into the draft: objects merge, arrays replace, null removes. `opts.baseUpdatedAt` as on put(). */
+        patch(cbid: string, patch: Record<string, unknown>, opts?: RightsPageWriteOptions): Promise<RightsPageDraft>;
+        /** Validate a write without saving it. */
+        dryRun(cbid: string, page: Record<string, unknown>, opts?: {
+            mode?: 'patch' | 'put';
+        }): Promise<RightsPageDryRun>;
+        getPublished(cbid: string): Promise<RightsPagePublished>;
+        /**
+         * Publish the draft; it goes live at once. Pass `opts.baseUpdatedAt` (the draft's updatedAt
+         * as you read it) so only the draft you saw goes live: 409 draft_conflict otherwise.
+         */
+        publish(cbid: string, opts?: RightsPageWriteOptions): Promise<RightsPagePublishResult>;
+        versions(cbid: string): Promise<RightsPageVersions>;
+        /**
+         * Publish an earlier version again; it goes live at once and REPLACES the current draft
+         * (unpublished edits are lost). `opts.baseUpdatedAt` refuses with 409 if the draft moved.
+         */
+        rollback(cbid: string, version: number, opts?: RightsPageWriteOptions): Promise<RightsPagePublishResult>;
+        /** Custom hostnames serving the rights page, with the plan allowance. */
+        listDomains(cbid: string): Promise<RightsPageDomainList>;
+        /** Add a custom hostname (e.g. privacy.example.com); the answer carries the DNS records to create. */
+        addDomain(cbid: string, hostname: string): Promise<RightsPageDomain>;
+        /** Check it now: DNS while pending, the HTTPS answer once routed. Always the domain as it stands. */
+        verifyDomain(cbid: string, hostname: string): Promise<RightsPageDomain>;
+        /** Remove it: it stops being served and its certificate is not renewed. */
+        removeDomain(cbid: string, hostname: string): Promise<void>;
+    };
     /**
      * Identity resolution. Reads are POSTs on purpose: a person's identifiers travel in the
      * body, never a URL where they would land in access logs.
@@ -1546,13 +2219,21 @@ interface CookieMunchClient {
          * is kept unless you pass a new `secretKey` — so adding a field to a profile does not
          * cost you the connection or its id.
          */
-        updateExecutor(id: string, patch: {
-            profile?: unknown;
-            baseUrl?: string;
-            secretKey?: string;
-            webhookSecret?: string | null;
-            auto?: boolean;
-        }): Promise<DsarExecutor>;
+        updateExecutor(id: string, patch: DsarExecutorPatch): Promise<DsarExecutor>;
+        /** What `connectExecutor` would create, validated in full; nothing is stored (`?dryRun=1`). */
+        dryRunConnectExecutor(input: DsarExecutorInput): Promise<DsarExecutorDryRun>;
+        /** What `updateExecutor` would change, with a diff; the stored connection is untouched (`?dryRun=1`). */
+        dryRunUpdateExecutor(id: string, patch: DsarExecutorPatch): Promise<DsarExecutorDryRun>;
+        /**
+         * Would this webhook delivery verify? Runs the receiver's exact check on headers and a raw
+         * body you supply, acts on nothing, and names the stage that failed.
+         */
+        testExecutorWebhook(id: string, delivery: {
+            headers: Record<string, string>;
+            body: string;
+        }): Promise<ExecutorWebhookTestResult>;
+        /** The last 50 deliveries to a connection's webhook, newest first, each with its reason. */
+        executorWebhookDeliveries(id: string): Promise<ExecutorWebhookDelivery[]>;
         /** Disconnect a system; its open sub-tasks stop being driven. */
         disconnectExecutor(id: string): Promise<void>;
         /** The export bundle a connected system produced, fetched from it on demand. */
@@ -1619,6 +2300,35 @@ interface CookieMunchClient {
         get(): Promise<Org>;
         /** Rename the org or set its logo. Deleting the org is not available through the API. */
         update(patch: OrgUpdate): Promise<Org>;
+        /**
+         * Your own mail provider for rights-request mail. It carries verification codes once
+         * `test` succeeds; every `set` clears that. There is no shared sender: without one, requests
+         * are verified by your sign-in provider (`rightsIdentity`) or filed unverified for you to confirm.
+         */
+        mailProvider: {
+            get(): Promise<MailProvider>;
+            set(input: MailProviderInput): Promise<MailProvider>;
+            remove(): Promise<void>;
+            /** Send a test through your provider. `to` defaults to the reply-to, else the from address. */
+            test(to?: string): Promise<MailProviderTestResult>;
+        };
+        /**
+         * 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.
+         */
+        rightsCaptcha: {
+            get(): Promise<RightsCaptcha>;
+            set(input: RightsCaptchaInput): Promise<RightsCaptcha>;
+            /** Remove the default; answers the setting now in force (off). */
+            remove(): Promise<RightsCaptcha>;
+        };
+        /** The default sign-in provider rights requests are verified with, for every site without its own. */
+        rightsIdentity: {
+            get(): Promise<RightsIdentity>;
+            set(input: RightsIdentityInput): Promise<RightsIdentity>;
+            /** Remove the default; answers the setting now in force. */
+            remove(): Promise<RightsIdentity>;
+        };
     };
     /** The org's audit log, newest first. API actions appear as `apikey:<prefix>`. */
     audit(limit?: number): Promise<{
@@ -1676,6 +2386,34 @@ interface CookieMunchClient {
         /** Deliver a dead letter again, to the subscription as it is now. */
         replayDeadLetter(id: string): Promise<unknown>;
     };
+    /**
+     * Account-linked rights requests: a single-use link to the hosted rights page for a person your
+     * backend knows is signed in. The page locks their email and skips the code step. Requires dsar:write.
+     */
+    rightsLinks: {
+        create(cbid: string, input: RightsLinkInput): Promise<RightsLink>;
+    };
+    /**
+     * 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.
+     */
+    rightsCaptcha: {
+        get(cbid: string): Promise<RightsCaptcha>;
+        set(cbid: string, input: RightsCaptchaInput): Promise<RightsCaptcha>;
+        /** Remove the site's own setting: it inherits the organisation default again. Answers the setting now in force. */
+        remove(cbid: string): Promise<RightsCaptcha>;
+    };
+    /**
+     * A site's sign-in provider (Clerk, Atlas or any JWKS issuer): a visitor signed in to your site
+     * is verified by their session, with no code mail. A site without its own setting uses the
+     * organisation default (`org.rightsIdentity`). Requires sites:read / sites:write.
+     */
+    rightsIdentity: {
+        get(cbid: string): Promise<RightsIdentity>;
+        set(cbid: string, input: RightsIdentityInput): Promise<RightsIdentity>;
+        /** Remove the site's own setting: it inherits the organisation default again. */
+        remove(cbid: string): Promise<RightsIdentity>;
+    };
     /** One person's consent across every site in the org, by the subjectId your apps attach. */
     subjects: {
         /** Requires consent:read; not available to property-locked keys. */
@@ -1711,4 +2449,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 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 DeclarationWarning, type DeclaredCookie, type DeclaredCookieInput, type DsarCreate, type DsarEraseResult, type DsarExecutor, type DsarExecutorCreated, type DsarExecutorInput, 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 FlowIssue, type FlowOp, type FlowOpResponse, type FulfillmentOp, type Identifier, type Identity, type ImportedCookie, type ImportedDeclaration, type InstallSnippet, type LegalBasis, type LogQuery, type Member, type OptInMethod, type Org, type OrgUpdate, type PlanSource, type PolicyOptions, type PreferenceItem, type PreferenceRecord, type PreviewToken, type PreviewTokenOptions, type ProfileAttributeInput, type PutConfigOptions, type RangeQuery, type Regulation, type RegulationSummary, type RegulatoryFeedResult, type ResellerChild, type ResellerChildCreate, type ResellerChildList, type ResellerChildPatch, 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 SupportedLanguage, type Usage, type VendorInput, type VendorRecord, type VerifyResult, type VerifyWebhookInput, type WebhookCreate, type WebhookDeadLetter, 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 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 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 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 };