@cookiemunch/sdk 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -111,9 +111,41 @@ interface DsarRequest {
     /** Where the subject said they are, when the intake captured it. */
     jurisdiction?: string;
     note?: string;
-    /** A test request: off the SLA board, labelled, and deletable with `dsar.delete`. */
+    /** 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,14 +284,83 @@ 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;
-}
-/** A site's cookie declaration: the latest scan's categorized cookies. This is what
- *  GET /v1/sites/:cbid/cookies actually returns (a wrapper, not a bare array). */
+    /** Page URLs (multi-page scan) that set this cookie, earliest first. */
+    foundOnPages?: string[];
+    /** The site owner declared this cookie; it overrides the scan. */
+    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';
+}
+/** 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. */
 interface CookieDeclaration {
-    /** Epoch-ms of the latest scan, or 0 if none. */
+    /** Epoch-ms of the latest scan or declaration change, or 0 if none. */
     updatedAt: number;
     cookies: CategorizedCookie[];
+    /** The site owner's declarations, as stored. */
+    declared?: DeclaredCookie[];
+}
+/** 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, 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;
+    /** Treat the name as a prefix wildcard (a trailing `*` does the same). */
+    pattern?: boolean;
+}
+/** A stored declaration. */
+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;
+    reason: string;
+}
+/** What an import with `apply` declared, on top of what it read. */
+interface AppliedImport extends ImportedDeclaration {
+    applied: number;
+    skipped: Array<{
+        name: string;
+        reason: string;
+    }>;
+    warnings?: DeclarationWarning[];
 }
 /** @deprecated The server returns {@link CookieDeclaration}; kept only for back-compat. */
 interface SiteCookie {
@@ -274,6 +377,27 @@ interface ScanStatus {
     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;
+}
+/** 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 {
@@ -335,6 +459,10 @@ interface ConfigChange {
     from?: unknown;
     to?: unknown;
 }
+/** `PUT …/config` options. `keep: 'unspecified'` keeps the stored value of every top-level field the body omits. */
+interface PutConfigOptions {
+    keep?: 'unspecified';
+}
 /** What a config write would do (`?dryRun=1`) — nothing is saved. */
 interface ConfigDryRun {
     dryRun: true;
@@ -343,6 +471,182 @@ 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[];
+}
+/** 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';
+        [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 {
@@ -366,6 +670,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. */
@@ -424,7 +792,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;
@@ -580,6 +949,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;
@@ -663,6 +1176,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 {
@@ -672,6 +1187,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
@@ -957,6 +1474,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`. */
@@ -965,15 +1524,24 @@ 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 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 {
@@ -1116,17 +1684,35 @@ interface CookieMunchClient {
         get(cbid: string): Promise<Site>;
         delete(cbid: string): Promise<void>;
         getConfig(cbid: string): Promise<SiteConfig>;
-        /** Replaces the whole config — a top-level field you omit reverts to its default. */
-        putConfig(cbid: string, config: SiteConfig): Promise<SiteConfig>;
-        /** Changes some of the config — omitted fields keep their stored value. */
+        /**
+         * Replaces the whole config — a top-level field you omit reverts to its default. With
+         * `{ keep: 'unspecified' }` (`?keep=unspecified`) an omitted top-level field keeps its
+         * stored value instead; each field you send is still replaced whole, and one sent as
+         * `null` reverts to its default.
+         */
+        putConfig(cbid: string, config: SiteConfig, opts?: PutConfigOptions): Promise<SiteConfig>;
+        /**
+         * Changes some of the config — a JSON Merge Patch (RFC 7386): omitted fields keep their
+         * stored value, nested objects merge, and `null` removes a field (it takes its default):
+         * `{ banner: { i18n: { es: null } } }` drops the Spanish override. Arrays replace whole.
+         */
         patchConfig(cbid: string, config: Partial<SiteConfig>): Promise<SiteConfig>;
         /**
          * Preview a config write without saving it: the merged result and a diff. `mode: 'put'`
-         * previews a replace (the diff then lists everything that would revert to its default).
+         * previews a replace (the diff then lists everything that would revert to its default);
+         * add `keep: 'unspecified'` to preview a replace that keeps omitted fields.
          */
         dryRunConfig(cbid: string, config: Partial<SiteConfig>, opts?: {
             mode?: 'patch' | 'put';
-        }): Promise<ConfigDryRun>;
+        } & 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>;
@@ -1155,6 +1741,49 @@ interface CookieMunchClient {
          * wrong category is a tag firing against a refusal, so the result is for review.
          */
         importDeclaration(cbid: string, data: string): Promise<ImportedDeclaration>;
+        /**
+         * Import AND declare: every row that mapped to one of our categories and has a purpose
+         * is declared; the rest come back in `skipped`. Already-declared cookies are kept
+         * unless `overwrite`.
+         */
+        applyImport(cbid: string, data: string, opts?: {
+            overwrite?: boolean;
+        }): Promise<AppliedImport>;
+        /**
+         * 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. `dryRun` validates and returns the would-be list and a
+         * diff without storing anything.
+         */
+        declareCookie(cbid: string, name: string, input: DeclaredCookieInput, opts?: {
+            dryRun?: boolean;
+        }): Promise<{
+            cookie: DeclaredCookie;
+            warnings?: DeclarationWarning[];
+        } & Partial<DeclarationDryRun>>;
+        /** Remove a declaration; the scanned classification applies again. */
+        undeclareCookie(cbid: string, name: string): Promise<void>;
+        /** 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>;
         /**
          * Mint a short-lived signed token to see the banner as a visitor in a given region and
@@ -1235,6 +1864,15 @@ interface CookieMunchClient {
          * real request cannot be deleted (409 `not_a_test_request`); the deletion is audited.
          */
         delete(id: string): Promise<void>;
+        /**
+         * Mark a CLOSED request (completed or rejected) as a test, after the fact — for trials
+         * filed before `test` existed. An open one is refused (409 `request_not_closed`). Audited
+         * as `dsar.marked_test`; afterwards `delete` works on it. `changed` is false on a repeat.
+         */
+        markTest(id: string): Promise<{
+            request: DsarRequest;
+            changed: boolean;
+        }>;
     };
     vendors: {
         list(): Promise<ScoredVendor[]>;
@@ -1258,6 +1896,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.
@@ -1452,13 +2122,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. */
@@ -1525,6 +2203,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<{
@@ -1582,6 +2289,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. */
@@ -1617,4 +2352,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 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 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 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 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 };