@checkbox-site/node 0.1.1 → 0.2.0

package/dist/generated/types.d.ts

@@ -17,6 +17,8 @@ export interface NextAction {
     operation_id?: string;
     /** The MCP tool that performs operation_id on the Checkbox MCP server (`call_api` when there is no dedicated tool). */
     mcp_tool?: string;
+    /** The HTTP method and path of operation_id, with path parameters in braces. */
+    endpoint?: string;
     /** Documentation or dashboard URL for the step, when there is one. */
     url?: string;
 }
@@ -32,6 +34,8 @@ export interface Error {
         message: string;
         /** The parameter the error relates to, when there is one. */
         param?: string;
+        /** What is missing or wrong, one entry each (terms_incomplete; and every problem of a parameter_invalid / parameter_missing request, so all can be fixed in one try). */
+        problems?: Array<string>;
         /** Link to the documentation of this error code. */
         doc_url: string;
         /** Id of the request (also in the Request-Id header). Quote it to support. */
@@ -49,10 +53,35 @@ export interface SetupNextAction {
     operation_id?: string;
     /** The MCP tool that performs operation_id (`call_api` when there is no dedicated tool). */
     mcp_tool?: string;
+    /** The HTTP method and path of operation_id, with path parameters in braces. */
+    endpoint?: string;
     /** The equivalent `checkbox` CLI command, when there is one. */
     command?: string;
     /** Documentation or dashboard URL for the step. */
     url?: string;
+    /** verify_domain with a started challenge: the DNS TXT record to add. */
+    dns?: {
+        /** Record type. */
+        type: "TXT";
+        /** Full record name. */
+        name: string;
+        /** Record value. */
+        value: string;
+    };
+    /** verify_domain with a started challenge: the file to serve instead of the DNS record. */
+    well_known?: {
+        /** Where to serve the file. */
+        url: string;
+        /** The file content. */
+        content: string;
+    };
+    /** verify_domain with a started challenge: or this meta tag on the homepage. The live snippet (install.script_tag) works too: Checkbox verifies the domain when it sees it. */
+    meta_tag?: {
+        /** The page Checkbox reads (the homepage of the domain). */
+        url: string;
+        /** The tag to put in its <head>. */
+        html: string;
+    };
 }
 /** A pending device login (RFC 8628 style). */
 export interface DeviceAuthorization {
@@ -96,11 +125,11 @@ export interface DeviceAuthorizationParams {
     package_manager?: string;
     /** Detected billing platform. */
     billing_platform?: string;
-    /** Business name (round 3: names the site and workspace instead of the host). */
+    /** Business name: names the site and workspace (instead of the host name). */
     merchant_name?: string;
     /** Also ask for live-mode keys (live mode activates after domain verification). */
     live?: boolean;
-    /** A HINT of the Stripe TEST key found in the project ("sk_test_…a1b2" — never the key). The human is asked once whether Checkbox may use it for synthetic test subscriptions. */
+    /** A HINT of the Stripe TEST key found in the project, never the key. Format: "sk_test_" or "rk_test_", the ellipsis character "…" (U+2026), then the key's last 4 characters, e.g. "sk_test_…a1b2". The human is asked once whether Checkbox may use it for synthetic test subscriptions. */
     stripe_test_key_hint?: string;
 }
 /** Keys issued after the human approved the device login. Returned exactly once. */
@@ -139,7 +168,7 @@ export interface DeviceToken {
     };
     next_action: SetupNextAction;
 }
-/** A subscription plan as the merchant sells it. */
+/** A subscription plan as the merchant sells it: name, amount (minor units), currency, interval, interval_count, trial_days and the intro_* promo fields, the same shape the checks accept (plan_name, price and intro_price are accepted as aliases). */
 export interface SetupPlan {
     /** Plan name. */
     name?: string;
@@ -153,11 +182,83 @@ export interface SetupPlan {
     interval_count?: number;
     /** Free-trial days (0 = none). */
     trial_days?: number;
+    /** Intro / first-period price in minor units (800 = $8.00 for the first period). Give one of intro_amount, intro_percent_off or intro_amount_off. */
+    intro_amount?: number;
+    /** Intro discount as a percentage off `amount` (a Stripe coupon's percent_off: 20 for 20% off). */
+    intro_percent_off?: number;
+    /** Intro discount as an amount off `amount`, in minor units (a Stripe coupon's amount_off). */
+    intro_amount_off?: number;
+    /** How many billing periods the intro price lasts (default 1). */
+    intro_periods?: number;
+    /** The billing platform's price id (Stripe price_…), so `amount` is compared with the connected Price. */
+    price_id?: string;
+    /** Alias of `name` (the name the checks also accept). */
+    plan_name?: string;
+    /** Alias of `amount` in MAJOR units (19 = $19.00); `amount` (minor units) is the canonical field. */
+    price?: number | string;
+    /** Alias of `intro_amount` in MAJOR units (8 = $8.00). */
+    intro_price?: number | string;
 }
+/** While the domain is not verified: the newest read-only scan of the site's own public pages (labeled "unverified scan": no checkout submitted, not evidence, replaced by the full scan after verification). Null otherwise. */
+export type UnverifiedScan = {
+    /** Read-only scan id (uscan_…). */
+    id: string;
+    /** Object type. */
+    object: "unverified_scan";
+    /** Always true: read before the domain was verified. Not evidence; no certificate, receipt or monitoring comes from it. */
+    unverified: true;
+    /** The label every surface shows with these results. */
+    label: "unverified scan";
+    /** queued, running, completed, failed, or skipped (e.g. the domain got verified first, so the full scan replaces it). */
+    status: "queued" | "running" | "completed" | "failed" | "skipped";
+    /** When it was queued. Unix timestamp in seconds. */
+    created: number;
+    /** When it finished. Unix timestamp in seconds. */
+    finished: number | null;
+    /** Every page considered (at most 20 loaded). */
+    pages: Array<{
+        /** Page URL. */
+        url: string;
+        /** home, pricing, terms, privacy, refund, cancellation, account or checkout. */
+        kind: string;
+        /** captured; skipped (robots.txt, not on the site's own domain, page limit, action link); failed. */
+        status: "captured" | "skipped" | "failed";
+        /** Why it was skipped or failed. */
+        reason?: string;
+    }>;
+    /** Checks on the loaded pages, in memory (not findings of the site). */
+    findings: Array<{
+        /** Check id. */
+        check_id: string;
+        /** Verdict on the loaded pages alone. */
+        status: "pass" | "fail" | "needs_review";
+        /** critical, high, medium or low. */
+        severity: string;
+        /** The check, in one line. */
+        title: string;
+    }>;
+    /** Counts. */
+    counts: {
+        /** Pages captured. */
+        pages_captured: number;
+        /** Pages skipped. */
+        pages_skipped: number;
+        /** Failing checks. */
+        failing: number;
+        /** Checks to review. */
+        needs_review: number;
+        /** Passing checks. */
+        passing: number;
+    };
+    /** Why it failed or was skipped. */
+    error: string | null;
+    /** What an unverified scan is (show it with the results). */
+    note: string;
+} | null;
 /** One step of the setup checklist. */
 export interface SetupStep {
     /** Stable step key. */
-    key: "account" | "site" | "snippet" | "policies" | "checks" | "lifecycle_test" | "fixes" | "domain" | "owner_notified";
+    key: "account" | "site" | "snippet" | "policies" | "checks" | "connect_billing" | "lifecycle_test" | "fixes" | "domain" | "owner_notified";
     /** Human-readable title. */
     title: string;
     /** done; pending (waiting on Checkbox or a deploy); action_required (the agent must act: see next_action); skipped; failed. */
@@ -222,22 +323,35 @@ export interface SetupSession {
         /** Plans. */
         plans: Array<SetupPlan>;
     };
+    /** Notes about this request's input (createSetupSession / updateSetupSession only; never stored): plan amounts below 100 minor units or different from the connected Stripe Price. */
+    warnings?: Array<{
+        /** Stable warning code. */
+        code: "plan_amount_looks_like_major_units" | "plan_amount_mismatch_stripe_price";
+        /** What looks wrong and what to send. */
+        message: string;
+        /** The parameter. */
+        param: string;
+    }>;
     /** Policy / pricing links Checkbox found in the site's HTML (terms_url, privacy_url, refund_url, cancellation_url, pricing_url, account_url). */
     discovered: Record<string, string>;
     /** Install details. */
     install: {
         /** The exact tag to put in <head> on every page. */
         script_tag: string | null;
-        /** Public snippet key of the site. */
+        /** The site's public snippet key: the data-key of script_tag (and the local part of inbound_email). Use only this key in the snippet tag. */
         snippet_key: string | null;
-        /** Test-mode publishable key (pk_test_…) for Checkbox Elements in the browser. */
+        /** A different key: the account's test-mode publishable key (pk_test_…) for Checkbox Elements (<checkbox-disclosure>) and consent receipts (data-publishable-key). Not the snippet's data-key. */
         publishable_key: string | null;
         /** BCC this address on subscription emails (acknowledgment, reminders) so they are checked. */
         inbound_email: string | null;
         /** File the agent added the snippet to. */
         installed_in: string | null;
-        /** Whether Checkbox saw the snippet on the live site at the last verify (null: not checked). */
+        /** Whether the snippet is live on the site: seen in the homepage at the last verify, or a capture it sent from a page of the site's verified domain (null: not checked). */
         detected_on_site: boolean | null;
+        /** How Checkbox knows the snippet is live: the tag in the homepage HTML, or its first capture from the site's domain. */
+        detected_via: "homepage" | "capture" | null;
+        /** The page of the snippet's first capture from the site's domain (detected_via capture). */
+        first_capture_url: string | null;
     };
     /** Policy documents Checkbox fetched (checked by terms.* checks). */
     policies: Array<{
@@ -245,14 +359,32 @@ export interface SetupSession {
         kind: string;
         /** URL fetched. */
         url: string;
-        /** Fetch result. */
-        status: "fetched" | "failed";
+        /** Fetch result. preview: read before the site's domain was verified (unverified preview): nothing was stored as evidence and only the Terms checks ran, in memory; it is fetched and stored once the domain is verified. */
+        status: "fetched" | "failed" | "preview";
         /** When it was fetched. Unix timestamp in seconds. */
         fetched: number;
         /** Why the fetch failed. */
         error: string | null;
         /** Evidence record of the stored page (ev_…). */
         evidence: string | null;
+        /** Not read (or only previewed) because the site's domain is not verified yet. */
+        held: boolean;
+        /** Unverified preview result (status preview), else null. */
+        preview: {
+            /** Always true: read before the domain was verified; nothing stored. */
+            unverified: true;
+            /** Terms checks on this page (none for a privacy policy). */
+            checks: Array<{
+                /** Check id. */
+                check_id: string;
+                /** Verdict on this page alone. */
+                status: "pass" | "fail" | "needs_review";
+                /** The check, in one line. */
+                summary: string;
+                /** One-sentence fix. */
+                fix?: string;
+            }>;
+        } | null;
     }>;
     /** Stripe test mode for lifecycle test runs. */
     stripe: {
@@ -287,20 +419,61 @@ export interface SetupSession {
         id: string;
         /** queued, running, succeeded, failed or canceled. */
         status: string;
+        /** The result in plain words, as the test run says it ("Finished with 2 warnings to review"). succeeded with warnings is not a clean pass. */
+        status_label?: string;
         /** When it started. Unix timestamp in seconds. */
         created: number;
     } | null;
+    /** The plans Checkbox judges the site against: the declared plans as reconciled with the connected Stripe Prices (Stripe wins), the plans the pay buttons sell and the account's Prices of a declared plan. Empty until a plan is known (updateSetupSession plans[], or connect Stripe). */
+    site_plans: Array<{
+        /** Plan name (or its price and interval). */
+        name: string;
+        /** The recurring price, formatted. */
+        price: string;
+        /** The recurring price in minor units (cents). */
+        amount: number;
+        /** Currency (lowercase ISO code). */
+        currency: string;
+        /** day, week, month or year. */
+        interval: string;
+        /** Intervals between charges. */
+        interval_count: number;
+        /** Free trial days on this plan (0: none). */
+        trial_days: number;
+        /** A lower first-period price, if any. */
+        intro_price: {
+            /** Intro price in minor units. */
+            amount: number;
+            /** Billing periods at the intro price. */
+            periods: number | null;
+        } | null;
+        /** Every Stripe Price id that names this plan. */
+        stripe_price_ids: Array<string>;
+        /** declared in setup, chosen in site facts, sold by the pay buttons, or read from the connected Stripe account. */
+        source: "declared" | "chosen" | "sold" | "stripe";
+    }>;
     /** Latest verdict of the test-mode site. */
     compliance: {
-        /** 0-100. */
-        score: number;
         /** When it was evaluated. Unix timestamp in seconds. */
         evaluated: number;
-        /** Open failing findings. */
+        /**
+         * Deprecated: open failing findings (per check). Read `label` (counted in tasks) and `todo` instead.
+         * @deprecated
+         */
         failing: number;
-        /** Open needs-review findings. */
+        /**
+         * Deprecated: open needs-review findings (per check). Read `label` (counted in tasks) and `todo` instead.
+         * @deprecated
+         */
         needs_review: number;
-        /** Most urgent open findings (details: retrieveFinding; ordered tasks: `checkbox plan --json`). */
+        /** The site roll-up label, the same everywhere (dashboard, plan, emails): "2 fixes needed · 1 your call", "Checks pass · 2 live checks pending". */
+        label: string | null;
+        /** The site roll-up status: needs_fix, your_call, incomplete, compliant or not_checked. */
+        status: string | null;
+        /**
+         * Deprecated: open findings (evidence). The to-do list is `todo` (the compliance plan's ordered open tasks).
+         * @deprecated
+         */
         top_findings: Array<{
             /** Unique identifier of the finding (fnd_…). */
             id: string;
@@ -313,14 +486,37 @@ export interface SetupSession {
             /** What is wrong. */
             title: string;
         }>;
+        /** The to-do list: the compliance plan's ordered open required tasks (same titles, order and counts as the dashboard, MCP get_site_status and the summary email). */
+        todo?: Array<{
+            /** Plan task id (task_…); its findings are the evidence. */
+            task: string;
+            /** Task key. */
+            key: string;
+            /** Task title, the same as in the plan. */
+            title: string;
+            /** The status the site roll-up counts the task under. */
+            status: "needs_fix" | "not_set_up" | "your_call" | "not_checked";
+            /** Needs a fix, Not set up yet, Your call or Not checked yet. */
+            label: string;
+        }>;
     } | null;
+    unverified_scan: UnverifiedScan;
     /** The setup checklist, in order. */
     steps: Array<SetupStep>;
     next_action: SetupNextAction;
     /** Whether the human got the summary email. */
     owner_notified: boolean;
-    /** The summary email: sent, or not_configured when this deployment has no SMTP (null before completeSetupSession). */
-    owner_email: "sent" | "not_configured" | null;
+    /** The summary email, sent only by completeSetupSession and built from the plan at that moment: sent (the mail server accepted it; see owner_email_detail.at), failed (not delivered; owner_email_detail.error says why, and the next completeSetupSession retries), or not_configured when this deployment has no SMTP. Null before completeSetupSession. */
+    owner_email: "sent" | "not_configured" | "failed" | null;
+    /** Delivery details of the summary email (null before completeSetupSession). */
+    owner_email_detail: {
+        /** When the summary was handed to the mail server (or failed), unix seconds. */
+        at: number | null;
+        /** Who it was sent to. */
+        to: string | null;
+        /** Why it failed (failed only). */
+        error: string | null;
+    } | null;
     /** Dashboard page with the setup timeline (for the human). */
     review_url: string;
 }
@@ -341,16 +537,16 @@ export interface SetupSessionUpdate {
     site_url?: string;
     /** Page where customers subscribe (pricing page or checkout). */
     checkout_url?: string;
-    /** Account page where subscribers manage / cancel. */
-    account_url?: string;
-    /** Terms of service page. Checkbox fetches and checks it. */
-    terms_url?: string;
-    /** Privacy policy page. */
-    privacy_url?: string;
-    /** Refund policy page. */
-    refund_url?: string;
-    /** Cancellation policy page (if separate from the Terms). */
-    cancellation_url?: string;
+    /** Account page where subscribers manage / cancel. null clears it. */
+    account_url?: string | null;
+    /** Terms of service page. Checkbox fetches and checks it. null clears it. */
+    terms_url?: string | null;
+    /** Privacy policy page. null clears it. */
+    privacy_url?: string | null;
+    /** Refund policy page. null clears it. */
+    refund_url?: string | null;
+    /** Cancellation policy page (if separate from the Terms). null clears it. */
+    cancellation_url?: string | null;
     /** Support address subscribers can write to. */
     support_email?: string;
     /** The brand subscribers know (it names the seller in generated disclosures and emails). Default: the site's host name, which the plan asks you to replace. */
@@ -375,7 +571,7 @@ export interface SetupSessionUpdate {
         env_file?: string;
         /** Static files directory (for /.well-known). */
         public_dir?: string;
-        /** Where checkout sessions / payment links are created. */
+        /** Where checkout sessions / payment links are created: an ARRAY of { file, kind, line?, snippet? } objects, one per place (not a string), e.g. [{"file": "app.py", "line": 40, "kind": "stripe_checkout_session"}]. */
         checkout_code?: Array<SetupCodeRef>;
         /** Where the subscribe / pay buttons are rendered. */
         pay_buttons?: Array<SetupCodeRef>;
@@ -413,6 +609,8 @@ export interface SetupVerification {
         snippet_detected: boolean | null;
         /** Why the site could not be loaded. */
         error: string | null;
+        /** Read as an unverified preview (domain not verified yet): one plain GET of the homepage for links and the snippet, nothing stored as evidence. */
+        preview: boolean;
     };
     /** Policies fetched now. */
     policies: Array<{
@@ -422,20 +620,64 @@ export interface SetupVerification {
         ok: boolean;
         /** Error. */
         error: string | null;
+        /** Read as an unverified preview (domain not verified yet): nothing stored. */
+        preview: boolean;
     }>;
     /** Synthetic-shopper scan. */
     scan: {
         /** Whether a scan was queued now. */
         queued: boolean;
-        /** The queued scan (scan_…). */
+        /** The queued scan (scan_…); with reason "already scanned", the newest scan (read it with retrieveScan). */
         scan: string | null;
         /** Why not. */
         reason: string | null;
     };
     /** Whether compliance was re-evaluated now. */
     evaluated: boolean;
+    /** The site's domain got verified during this call (e.g. the snippet is live on the homepage). */
+    domain_verified: {
+        /** The domain. */
+        domain: string;
+        /** snippet, meta_tag, dns_txt or well_known. */
+        method: string;
+    } | null;
+    /** While the domain is not verified: the read-only scan of the site's own public pages (no checkout submitted). */
+    unverified_scan: {
+        /** Whether a read-only (unverified) scan was queued now. */
+        queued: boolean;
+        /** Why not (limits: one per site per 24 h, three unverified sites per account in 30 days). */
+        reason: string | null;
+    } | null;
     setup_session: SetupSession;
 }
+/** Account default retention (sites without their own setting use it). */
+export interface Retention {
+    /** Years records are kept (consent receipts, disclosures as shown, passing check results, certificates, emails sent, confirmed cancellations, evidence-chain entries). Default 7. */
+    records_years: number;
+    /** Days superseded check results are kept after a later check replaces them (with their page captures and change history); only summary counts stay. Current results are not deleted. Default 30. */
+    superseded_results_days: number;
+    /**
+     * Deprecated: same as records_years.
+     * @deprecated
+     */
+    good_practice_years: number;
+    /**
+     * Deprecated: same as superseded_results_days.
+     * @deprecated
+     */
+    problem_history_days: number;
+}
+/** Account-wide legal hold: while active, nothing of this mode's data is deleted. */
+export interface LegalHold {
+    /** A legal hold suspends every automatic deletion and refuses deletions and retention shortening. */
+    active: boolean;
+    /** What the active hold was set on (an account hold covers every site). */
+    scope: "site" | "account" | null;
+    /** When the hold was turned on. Unix timestamp in seconds. */
+    set: number | null;
+    /** Note recorded with the hold. */
+    reason: string | null;
+}
 /** The Checkbox account behind the API key. */
 export interface Account {
     /** Unique identifier of the account (acct_…). */
@@ -488,10 +730,36 @@ export interface Account {
         /** Checkbox is free to use. */
         plan: "free";
     };
+    retention: Retention;
+    legal_hold: LegalHold;
     /** When the account was created. Unix timestamp in seconds. */
     created: number;
     next_action: NextAction | null;
 }
+/** Default retention for every site without its own setting. A longer period for superseded check results keeps a fuller timeline of changes to your site. */
+export interface RetentionParams {
+    /** Years records are kept (1-10). On a site, null returns to the account default. */
+    records_years?: number | null;
+    /** Days superseded check results are kept (7-730). On a site, null returns to the account default. */
+    superseded_results_days?: number | null;
+    /**
+     * Deprecated: use records_years.
+     * @deprecated
+     */
+    good_practice_years?: number | null;
+    /**
+     * Deprecated: use superseded_results_days.
+     * @deprecated
+     */
+    problem_history_days?: number | null;
+}
+/** Account-wide legal hold: suspends every deletion of the account's records until turned off. */
+export interface LegalHoldParams {
+    /** true turns the hold on, false turns it off. */
+    active: boolean;
+    /** Note stored with the hold (who asked, matter). */
+    reason?: string;
+}
 /** Business facts that decide which legal requirements apply. */
 export interface SiteFacts {
     /** The offer starts with a free trial. */
@@ -512,6 +780,8 @@ export interface SiteFacts {
     plan_price_id?: string;
     /** Accepted payment methods (debit / ACH bring in Reg E). */
     payment_methods?: Array<"card" | "debit" | "ach" | "wallet" | "other">;
+    /** Where shoppers pay and consent. stripe_checkout / payment_link: your pages redirect to a Stripe-hosted page, so consent is checked on Stripe (consent_collection and custom_text of your registered Checkout configs or Payment Links), and your pricing page needs no checkbox of its own. Unset: detected from pay buttons that link to checkout.stripe.com / buy.stripe.com. */
+    checkout_type?: "own_page" | "stripe_checkout" | "payment_link";
 }
 /** Scheduled monitoring. */
 export interface SiteMonitoring {
@@ -528,6 +798,11 @@ export interface SiteMonitoring {
     /** Domains to verify before Checkbox scans the site (first: createDomainVerification for the site's own domain). */
     verify_domains: Array<string>;
 }
+/** The retention in effect for the site. */
+export type SiteRetention = Retention & {
+    /** Both values come from the account default (no site override). */
+    inherited: boolean;
+};
 /** A live check Checkbox has not observed yet, and how it completes. */
 export interface PendingLiveCheck {
     /** What has not been observed yet. */
@@ -539,9 +814,31 @@ export interface PendingLiveCheck {
     /** ISO date when it completes on its own (a reminder window), when known. */
     due: string | null;
 }
+/** One plan / checkout of the site and its sign-up verdict. */
+export interface CheckoutVerdict {
+    /** Plan name, or the checkout when no plan was matched. */
+    name: string;
+    /** Where the purchase happens: own_page, stripe_checkout (your page → Stripe Checkout), payment_link, checkout_config (a registered Checkout Session config), stripe_hosted. */
+    kind: "own_page" | "stripe_checkout" | "payment_link" | "checkout_config" | "stripe_hosted";
+    /** The declared plan this checkout sells, when matched. */
+    plan: string | null;
+    /** User-facing status. needs_fix (a requirement is clearly not met: `compliance.fix` is the one change), pending_live_check (everything Checkbox can see is right; the live event has not been observed yet — counts as passing the checks), verified_live (observed live: proof run, real BCC'd send, Stripe-confirmed cancellation), your_call (a real decision for a person: `compliance.question`), compliant (passes; grey areas carry a `compliance.note`), not_applicable, not_set_up (no sign the email or setting exists yet: `compliance.fix` is the one-click way to set it up; never counts as passing the checks), not_checked (Checkbox has not tried it yet, e.g. the cancel flow: `compliance.fix` says how; never counts as passing the checks). */
+    status: "needs_fix" | "pending_live_check" | "verified_live" | "your_call" | "compliant" | "not_applicable" | "not_set_up" | "not_checked";
+    /** Label to show. */
+    label: string;
+    /** Sign-up checks still open on this checkout. */
+    open: Array<{
+        /** Check id. */
+        check_id: string;
+        /** Short check title. */
+        title: string;
+        /** User-facing status. needs_fix (a requirement is clearly not met: `compliance.fix` is the one change), pending_live_check (everything Checkbox can see is right; the live event has not been observed yet — counts as passing the checks), verified_live (observed live: proof run, real BCC'd send, Stripe-confirmed cancellation), your_call (a real decision for a person: `compliance.question`), compliant (passes; grey areas carry a `compliance.note`), not_applicable, not_set_up (no sign the email or setting exists yet: `compliance.fix` is the one-click way to set it up; never counts as passing the checks), not_checked (Checkbox has not tried it yet, e.g. the cancel flow: `compliance.fix` says how; never counts as passing the checks). */
+        status: "needs_fix" | "pending_live_check" | "verified_live" | "your_call" | "compliant" | "not_applicable" | "not_set_up" | "not_checked";
+    }>;
+}
 /** Roll-up of the user-facing statuses of the required checks. */
 export interface ComplianceRollup {
-    /** needs_fix (a required check needs a fix or something is not set up yet), your_call (a decision is needed), incomplete (only "not checked yet" items are left, e.g. the cancel flow was never tried), compliant (pending live checks count as compliant), not_checked (never evaluated). */
+    /** needs_fix (a required check needs a fix or something is not set up yet), your_call (a decision is needed), incomplete (only "not checked yet" items are left, e.g. the cancel flow was never tried), compliant (every required check passes; pending live checks count as passing), not_checked (never evaluated). */
     status: "needs_fix" | "your_call" | "incomplete" | "compliant" | "not_checked";
     /** Label to show. */
     label: string;
@@ -551,11 +848,11 @@ export interface ComplianceRollup {
         needs_fix: number;
         /** Decisions for a person. */
         your_call: number;
-        /** Compliant, live check pending. */
+        /** Checks pass, live check pending. */
         pending_live_check: number;
         /** Verified live. */
         verified_live: number;
-        /** Compliant. */
+        /** Checks pass. */
         compliant: number;
         /** Not applicable. */
         not_applicable: number;
@@ -569,20 +866,20 @@ export interface ComplianceRollup {
         /** Check id. */
         check_id: string;
     }>;
-    /** Recommended / extra items open (never block compliant). */
+    /** Recommended / extra items open (never block the checks from passing). */
     suggestions: number;
+    /** Per-plan / per-checkout verdicts, in the same vocabulary as the roll-up. Present when the site has two or more checkouts, or one on Stripe. */
+    checkouts?: Array<CheckoutVerdict>;
 }
 /** Latest verdict; null until the first evaluation. */
 export type SiteCompliance = {
-    /** Compliance score 0-100 (one decimal place). */
-    score: number;
     /** When the latest evaluation ran. Unix timestamp in seconds. */
     evaluated: number;
     /** Open findings whose latest status is fail. */
     open_findings: number;
     /** Open findings waiting for a human look. */
     needs_review: number;
-    /** User-facing roll-up of the required checks: needs_fix > your_call > compliant (pending live checks count as compliant). */
+    /** User-facing roll-up of the required checks: needs_fix > your_call > compliant (every required check passes; pending live checks count as passing). */
     status: "needs_fix" | "your_call" | "incomplete" | "compliant" | "not_checked";
     /** Label to show. */
     label: string;
@@ -599,6 +896,33 @@ export interface SiteInstall {
     /** Billing-platform webhook URLs (platform -> URL). */
     webhook_urls: Record<string, string>;
 }
+/** The site's Shopify store connection; null when the site neither uses platform shopify nor has a Shopify connection. */
+export type SiteShopify = {
+    /** How the store is connected. app: through the Checkbox Shopify app (Checkbox can publish the verified terms to the app block: publishShopifyTerms). own_app: with the store's own custom-app access token (read-only; use the standalone theme snippet). none: not connected (only the merchant can install the Checkbox app from the Shopify admin). */
+    connection: "app" | "own_app" | "none";
+    /** The store's myshopify.com domain, when connected. */
+    shop: string | null;
+    /** Status of the Shopify connection (connected, error, disconnected); null without one. */
+    status: string | null;
+    /** The newest publish of the verified renewal terms to the Checkbox app block; null when never published. Whether the block is placed on the theme shows in the scans (Checkbox does not read the theme). */
+    terms_published: {
+        /** The fix application that recorded the publish. */
+        application: string;
+        /** When the text was published. Unix timestamp in seconds. */
+        published: number;
+        /** sha256 of the published texts (disclosure + newline + consent label). */
+        sha256: string;
+    } | null;
+    /** Theme editor link that adds the "Renewal terms + consent" block to the product page (the merchant opens it once and clicks Save). Null without a connected store. */
+    theme_editor_url: string | null;
+} | null;
+/** The compliance status of the evaluation this scan produced (null until evaluated). Retrieve the evaluation for the checks and counts. */
+export type ScanCompliance = {
+    /** Roll-up status of that evaluation: needs_fix, your_call, incomplete, compliant or not_checked. */
+    status: "needs_fix" | "your_call" | "incomplete" | "compliant" | "not_checked";
+    /** The status label to show, counted in tasks ("2 fixes needed", "Checks pass"). */
+    label: string;
+} | null;
 /** Most recent scan (only with expand[]=latest_scan). */
 export interface Scan {
     /** Unique identifier of the scan (scan_…). */
@@ -621,8 +945,7 @@ export interface Scan {
     warnings: Array<string>;
     /** The evaluation this scan produced (null until evaluated). */
     evaluation: string | null;
-    /** Score of that evaluation (0-100, one decimal place). */
-    score: number | null;
+    compliance: ScanCompliance;
     /** When the scan started. Unix timestamp in seconds. */
     started: number | null;
     /** When the scan finished. Unix timestamp in seconds. */
@@ -640,10 +963,10 @@ export interface DomainVerification {
     site: string;
     /** Domain of the site URL. */
     domain: string | null;
-    /** not_started until createDomainVerification; verified once the TXT record or file was found. */
+    /** not_started until createDomainVerification; verified once the TXT record, the file, the live snippet or the meta tag was found. */
     status: "not_started" | "pending" | "verified";
-    /** How control was proven. */
-    method: "dns_txt" | "well_known" | null;
+    /** How control was proven: dns_txt, well_known, snippet (the site's Checkbox snippet live on https://<domain>/), meta_tag (<meta name="checkbox-verify"> on https://<domain>/) or shopify_install (the domain is the primary domain of a Shopify store that installed the Checkbox app and is connected to this site). */
+    method: "dns_txt" | "well_known" | "snippet" | "meta_tag" | "shopify_install" | null;
     /** When it was verified. Unix timestamp in seconds. */
     verified_at: number | null;
     /** Last check. Unix timestamp in seconds. */
@@ -666,6 +989,13 @@ export interface DomainVerification {
         /** Exact file contents. */
         contents: string;
     } | null;
+    /** Or add this meta tag to the homepage (option 3). Option 4: install the site's Checkbox snippet (install.script_tag) on the homepage; Checkbox verifies the domain when it sees it live. */
+    meta_tag: {
+        /** The page Checkbox reads (the site's homepage, redirects only within the domain). */
+        url: string;
+        /** Put this tag in the <head> of that page. */
+        html: string;
+    } | null;
     /** Configured scan URLs outside the verified domain (certificates cover only the domain). */
     scan_target_problems: Array<string>;
     /** Whether live mode is activated for the account. */
@@ -680,6 +1010,8 @@ export interface DomainVerification {
         operation_id?: string;
         /** The MCP tool that performs operation_id (`call_api` when there is no dedicated tool). */
         mcp_tool?: string;
+        /** The HTTP method and path of operation_id. */
+        endpoint?: string;
     } | null;
 }
 /** A subscription business Checkbox monitors. */
@@ -719,6 +1051,8 @@ export interface Site {
             login_url: string;
             /** Test subscriber email. */
             email: string;
+            /** The page that re-activates the test subscription before each cancellation test (null when none is set). */
+            reactivate_url: string | null;
         } | null;
         /** Number of explicit cancellation steps. */
         cancel_steps: number;
@@ -729,16 +1063,35 @@ export interface Site {
         /** The checkout page is the home page (checkout_url was omitted or set to the site root). Sign-up checks then judge the home page: set checkout_url to the page with the subscribe button unless the home page really has it. */
         homepage_as_checkout: boolean;
     };
+    /** Same as checkout.url, under the name updateSite / createSite take. */
+    checkout_url: string;
+    /** Same as checkout.account_url, under the name updateSite takes. */
+    account_url: string | null;
+    /** Same as checkout.terms_url, under the name updateSite takes. */
+    terms_url: string | null;
+    /** Same as checkout.test_account: the test account as saved (the password is write-only and never returned); null when none is set. */
+    test_account: {
+        /** Login page. */
+        login_url: string;
+        /** Test subscriber email. */
+        email: string;
+        /** The re-activation page (null when none is set). */
+        reactivate_url: string | null;
+    } | null;
     monitoring: SiteMonitoring;
     /** Which requirement tiers Checkbox shows (minimum: required only; balanced: + recommended suggestions; maximum: + extras). Only required items affect compliance. */
     protection_level: "minimum" | "balanced" | "maximum";
+    retention: SiteRetention;
+    legal_hold: LegalHold;
     compliance: SiteCompliance;
     install: SiteInstall;
+    shopify: SiteShopify;
     /** Archived (soft-deleted); evidence is retained. */
     archived: boolean;
     /** When the site was created. Unix timestamp in seconds. */
     created: number;
     latest_scan?: Scan;
+    unverified_scan: UnverifiedScan;
     domain_verification?: DomainVerification;
 }
 /** A page of sites, newest first. */
@@ -804,7 +1157,7 @@ export interface SiteTestAccount {
     password: string;
     /** Custom login steps. */
     login_steps?: Array<ScanStep>;
-    /** Optional page on your site that RE-ACTIVATES the test subscription (a test-only route). The cancellation test really cancels the test account; the scanner opens this page after logging in, before cancelling, so every scan starts subscribed. Without it, a scan after a completed cancellation reports "not observed: the test account has no active subscription" (needs review). (Round 3: renamed from reset_url, which meant the opposite of the proof run's stripe.cleanup_url.) */
+    /** Optional page on your site that RE-ACTIVATES the test subscription (a test-only route). The cancellation test really cancels the test account; the scanner opens this page after logging in, before cancelling, so every scan starts subscribed. Without it, a scan after a completed cancellation reports "not observed: the test account has no active subscription" (needs review). (Replaces reset_url, now a deprecated alias.) */
     reactivate_url?: string;
     /** Deprecated alias of reactivate_url. */
     reset_url?: string;
@@ -837,7 +1190,7 @@ export interface CreateSiteParams {
     devices?: Array<"desktop" | "mobile">;
     /** Scheduled re-scan interval (0 = off, minimum 60). Default 1440 in live mode, 0 in test mode. */
     monitoring_interval_minutes?: number;
-    /** Which requirement tiers Checkbox shows. minimum: the legal floor only (required items). balanced (default): required items plus recommended suggestions (consent receipts, a cancellation confirmation email…), collapsed and never blocking "compliant". maximum: everything, including extra protections (a separate checkbox per term, a pre-purchase summary). Only required items can make a site not compliant, at every level. */
+    /** Which requirement tiers Checkbox shows. minimum: the legal floor only (required items). balanced (default): required items plus recommended suggestions (consent receipts, a cancellation confirmation email…), collapsed and never blocking "Checks pass". maximum: everything, including extra protections (a separate checkbox per term, a pre-purchase summary). Only required items can keep a site's checks from passing, at every level. */
     protection_level?: "minimum" | "balanced" | "maximum";
 }
 export interface UpdateSiteParams {
@@ -868,8 +1221,19 @@ export interface UpdateSiteParams {
     devices?: Array<"desktop" | "mobile">;
     /** Scheduled re-scan interval (0 = off, minimum 60). Default 1440 in live mode, 0 in test mode. */
     monitoring_interval_minutes?: number;
-    /** Which requirement tiers Checkbox shows. minimum: the legal floor only (required items). balanced (default): required items plus recommended suggestions (consent receipts, a cancellation confirmation email…), collapsed and never blocking "compliant". maximum: everything, including extra protections (a separate checkbox per term, a pre-purchase summary). Only required items can make a site not compliant, at every level. */
+    /** Which requirement tiers Checkbox shows. minimum: the legal floor only (required items). balanced (default): required items plus recommended suggestions (consent receipts, a cancellation confirmation email…), collapsed and never blocking "Checks pass". maximum: everything, including extra protections (a separate checkbox per term, a pre-purchase summary). Only required items can keep a site's checks from passing, at every level. */
     protection_level?: "minimum" | "balanced" | "maximum";
+    /** The URLs nested as the site object returns them (checkout.url, checkout.account_url, checkout.terms_url); the flat fields win when both are given. */
+    checkout?: {
+        /** Same as checkout_url. */
+        url?: string;
+        /** Same as account_url. */
+        account_url?: string | null;
+        /** Same as terms_url. */
+        terms_url?: string | null;
+    };
+    retention?: RetentionParams;
+    legal_hold?: LegalHoldParams;
 }
 /** A billing-platform connection of a site. */
 export interface Integration {
@@ -887,13 +1251,55 @@ export interface Integration {
     last_synced: number | null;
     /** A problem worth fixing, e.g. a test-mode key on a live site. */
     warning: string | null;
+    /** Chargebee, Recurly and Paddle: the webhook to add by hand (Chargebee: Settings › Configure Chargebee › API Keys and Webhooks › Webhooks; Recurly: Integrations › Webhooks; Paddle: Events › Notifications › New destination, under Developer tools in older dashboards). Null for platforms whose webhook Checkbox registers itself. */
+    webhook_setup: {
+        /** Webhook URL to add in the platform. */
+        url: string;
+        /** Authentication the webhook uses: basic (enter the username and password below; Chargebee, Recurly) or signature (the platform signs deliveries with a secret key it makes, which you paste into Checkbox; Paddle). */
+        auth: "basic" | "signature";
+        /** Basic-auth username to enter. Null for signature auth. */
+        username: string | null;
+        /** Basic-auth password to enter. Treat it as a secret. Null for signature auth. */
+        password: string | null;
+        /** Events to select. */
+        events: Array<string>;
+        /** Webhook API version to choose. */
+        api_version: string | null;
+        /** Payload format to choose on the endpoint (Recurly: JSON). Null when the platform has no choice. */
+        payload_format: "json" | null;
+        /** Recurly and Paddle: whether the endpoint’s secret key is saved in Checkbox (dashboard › Billing connection › webhook), so every delivery’s signature is checked. Paddle deliveries are refused until it is. Null for platforms without signatures. */
+        signing_key_configured: boolean | null;
+        /** Paddle: whether a notification destination with this URL exists in Paddle (from the settings Checkbox last read; needs the Notification settings: Read permission). Null when unknown or for other platforms. */
+        destination_status: "found" | "inactive" | "missing" | null;
+        /** Paddle: events the destination does not send yet. Null when unknown or for other platforms. */
+        missing_events: Array<string> | null;
+    } | null;
 }
 export interface ConnectBillingPlatformParams {
     /** Billing platform. */
-    platform: "stripe" | "recharge" | "shopify";
-    /** Read-only credentials. Stripe: { "secretKey": "rk_test_…" } (a restricted key with read access; rk_test_ in test mode). Recharge: { "apiToken": "…" }. Shopify: { "shop": "store.myshopify.com", "accessToken": "shpat_…" }. */
+    platform: "stripe" | "recharge" | "shopify" | "chargebee" | "recurly" | "paddle";
+    /** Read-only credentials, in snake_case like the rest of the API (the camelCase spellings, secretKey / apiToken / accessToken / apiKey, are accepted too). Stripe: { "secret_key": "rk_test_…" } (a restricted key with read access; rk_test_ in test mode). Recharge: { "api_token": "…" }. Shopify: { "shop": "store.myshopify.com", "access_token": "shpat_…" }. Chargebee: { "site": "acme", "api_key": "live_…" } (the site name before .chargebee.com and a read-only API key). Recurly: { "api_key": "…", "region": "us" } (a private API key of the site; region "eu" for sites hosted in Recurly’s EU data centre, default "us"). Paddle: { "api_key": "pdl_live_apikey_…" } (a Paddle Billing API key with read permissions; sandbox keys, pdl_sdbx_…, read the sandbox; "environment": "live" or "sandbox" only for older keys without that prefix). Checkbox only reads. */
     credentials: Record<string, string>;
 }
+/** A queued re-read of the site's billing-platform settings, followed by a re-evaluation. */
+export interface BillingSync {
+    /** String representing the object's type. Always "billing_sync". */
+    object: "billing_sync";
+    /** The site whose billing settings are re-read. */
+    site: string;
+    /** One entry per connected billing platform. */
+    platforms: Array<{
+        /** The connected billing platform. */
+        platform: "stripe" | "shopify" | "recharge" | "chargebee" | "recurly" | "paddle" | "woocommerce" | "custom";
+        /** The re-read is queued; settings refresh within a minute. */
+        status: "queued";
+        /** When the settings were last read successfully. Unix timestamp in seconds. */
+        last_synced: number | null;
+        /** Why the last read failed, if it did. */
+        last_error: string | null;
+    }>;
+    next_action: NextAction;
+}
 /** A page of scans, newest first. */
 export interface ScanList {
     /** String representing the object's type. Always "list". */
@@ -917,8 +1323,10 @@ export interface CheckSummary {
     severity: "critical" | "high" | "medium" | "low";
     /** Lifecycle stage. */
     stage: "signup" | "confirmation" | "reminder" | "cancellation" | "config";
-    /** User-facing status. needs_fix (a clear violation: `compliance.fix` is the one change), pending_live_check (everything Checkbox can see is right; the live event has not been observed yet — counts as compliant), verified_live (observed live: proof run, real BCC'd send, Stripe-confirmed cancellation), your_call (a real decision for a person: `compliance.question`), compliant (passes; grey areas carry a `compliance.note`), not_applicable, not_set_up (no sign the email or setting exists yet: `compliance.fix` is the one-click way to set it up; never counts as compliant), not_checked (Checkbox has not tried it yet, e.g. the cancel flow: `compliance.fix` says how; never counts as compliant). */
+    /** User-facing status. needs_fix (a requirement is clearly not met: `compliance.fix` is the one change), pending_live_check (everything Checkbox can see is right; the live event has not been observed yet — counts as passing the checks), verified_live (observed live: proof run, real BCC'd send, Stripe-confirmed cancellation), your_call (a real decision for a person: `compliance.question`), compliant (passes; grey areas carry a `compliance.note`), not_applicable, not_set_up (no sign the email or setting exists yet: `compliance.fix` is the one-click way to set it up; never counts as passing the checks), not_checked (Checkbox has not tried it yet, e.g. the cancel flow: `compliance.fix` says how; never counts as passing the checks). */
     compliance_status: "needs_fix" | "pending_live_check" | "verified_live" | "your_call" | "compliant" | "not_applicable" | "not_set_up" | "not_checked";
+    /** The status in words to show a person ("Needs a fix", "Your call", "Not set up yet", "Not checked yet", "Checks pass"…). Show this, never the machine value. */
+    compliance_status_label: string;
 }
 /** A compliance verdict for a site at a point in time. */
 export interface Evaluation {
@@ -932,8 +1340,6 @@ export interface Evaluation {
     site: string;
     /** The scan row this evaluation belongs to. */
     scan: string;
-    /** Compliance score 0-100 (severity-weighted, one decimal place, e.g. 82.5). */
-    score: number;
     /** Legal catalog / rules version used. */
     rules_version: string;
     /** When it was evaluated. Unix timestamp in seconds. */
@@ -1048,13 +1454,13 @@ export interface VerdictEvidence {
 }
 /** What a person should do about one check (the user-facing layer over `status`). */
 export interface ComplianceInfo {
-    /** User-facing status. needs_fix (a clear violation: `compliance.fix` is the one change), pending_live_check (everything Checkbox can see is right; the live event has not been observed yet — counts as compliant), verified_live (observed live: proof run, real BCC'd send, Stripe-confirmed cancellation), your_call (a real decision for a person: `compliance.question`), compliant (passes; grey areas carry a `compliance.note`), not_applicable, not_set_up (no sign the email or setting exists yet: `compliance.fix` is the one-click way to set it up; never counts as compliant), not_checked (Checkbox has not tried it yet, e.g. the cancel flow: `compliance.fix` says how; never counts as compliant). */
+    /** User-facing status. needs_fix (a requirement is clearly not met: `compliance.fix` is the one change), pending_live_check (everything Checkbox can see is right; the live event has not been observed yet — counts as passing the checks), verified_live (observed live: proof run, real BCC'd send, Stripe-confirmed cancellation), your_call (a real decision for a person: `compliance.question`), compliant (passes; grey areas carry a `compliance.note`), not_applicable, not_set_up (no sign the email or setting exists yet: `compliance.fix` is the one-click way to set it up; never counts as passing the checks), not_checked (Checkbox has not tried it yet, e.g. the cancel flow: `compliance.fix` says how; never counts as passing the checks). */
     status: "needs_fix" | "pending_live_check" | "verified_live" | "your_call" | "compliant" | "not_applicable" | "not_set_up" | "not_checked";
-    /** Label to show: "Needs a fix", "Not set up yet", "Not checked yet", "Looks compliant — live check pending", "Verified live", "Your call", "Compliant", "Looks compliant", "Looks compliant with a note", "Not applicable". */
+    /** Label to show: "Needs a fix", "Not set up yet", "Not checked yet", "Checks pass · live check pending", "Verified live", "Your call", "Checks pass", "Checks pass with a note", "Not applicable". */
     label: string;
     /** Stable code of the mapping rule (docs/ACCURACY.md). */
     reason: string;
-    /** required (legal floor: the only tier that can make a site not compliant), recommended (lowers lawsuit risk, conversion-neutral), extra (maximum protection). */
+    /** required (legal floor: the only tier that can keep a site's checks from passing), recommended (clearer records beyond the legal floor, conversion-neutral), extra (maximum protection). */
     tier: "required" | "recommended" | "extra";
     /** needs_fix: the one change that fixes it. */
     fix: string | null;
@@ -1109,7 +1515,7 @@ export interface Finding {
     /** Check-specific details (failing regions/devices/URLs, measurements, quotes). */
     details: Record<string, unknown>;
     evidence: VerdictEvidence;
-    /** User-facing status. needs_fix (a clear violation: `compliance.fix` is the one change), pending_live_check (everything Checkbox can see is right; the live event has not been observed yet — counts as compliant), verified_live (observed live: proof run, real BCC'd send, Stripe-confirmed cancellation), your_call (a real decision for a person: `compliance.question`), compliant (passes; grey areas carry a `compliance.note`), not_applicable, not_set_up (no sign the email or setting exists yet: `compliance.fix` is the one-click way to set it up; never counts as compliant), not_checked (Checkbox has not tried it yet, e.g. the cancel flow: `compliance.fix` says how; never counts as compliant). */
+    /** User-facing status. needs_fix (a requirement is clearly not met: `compliance.fix` is the one change), pending_live_check (everything Checkbox can see is right; the live event has not been observed yet — counts as passing the checks), verified_live (observed live: proof run, real BCC'd send, Stripe-confirmed cancellation), your_call (a real decision for a person: `compliance.question`), compliant (passes; grey areas carry a `compliance.note`), not_applicable, not_set_up (no sign the email or setting exists yet: `compliance.fix` is the one-click way to set it up; never counts as passing the checks), not_checked (Checkbox has not tried it yet, e.g. the cancel flow: `compliance.fix` says how; never counts as passing the checks). */
     compliance_status: "needs_fix" | "pending_live_check" | "verified_live" | "your_call" | "compliant" | "not_applicable" | "not_set_up" | "not_checked";
     compliance: ComplianceInfo;
     /** Scan that produced the latest result. */
@@ -1192,14 +1598,16 @@ export interface Task {
     key: string;
     /** Short imperative title. */
     title: string;
-    /** open (apply the change), in_progress (an agent claimed it), verifying (a verification is waiting for a confirming observation), done, wont_fix (the merchant declined, with a reason), manual (needs a human answer: see question), pending_live_check (everything Checkbox can see is right; it waits for a live observation — see change for how it completes. Counts as compliant and never blocks the plan). */
+    /** open (apply the change), in_progress (an agent claimed it), verifying (a verification is waiting for a confirming observation), done, wont_fix (the merchant declined, with a reason), manual (needs a human answer: see question), pending_live_check (everything Checkbox can see is right; it waits for a live observation — see change for how it completes. Counts as passing the checks and never blocks the plan). */
     status: "open" | "in_progress" | "verifying" | "done" | "wont_fix" | "manual" | "pending_live_check";
     /** Strictest severity among the task's legal checks. */
     priority: "critical" | "high" | "medium" | "low";
-    /** required (the legal floor: the only tier that can keep the site from being compliant), recommended (lowers lawsuit risk, conversion-neutral; shown at protection level balanced and maximum, never blocks), extra (maximum protection only). Always present on API responses. */
+    /** required (the legal floor: the only tier that can keep the site's checks from passing), recommended (clearer records beyond the legal floor, conversion-neutral; shown at protection level balanced and maximum, never blocks), extra (maximum protection only). Always present on API responses. */
     tier?: "required" | "recommended" | "extra";
-    /** User-facing status. needs_fix (a clear violation: `compliance.fix` is the one change), pending_live_check (everything Checkbox can see is right; the live event has not been observed yet — counts as compliant), verified_live (observed live: proof run, real BCC'd send, Stripe-confirmed cancellation), your_call (a real decision for a person: `compliance.question`), compliant (passes; grey areas carry a `compliance.note`), not_applicable, not_set_up (no sign the email or setting exists yet: `compliance.fix` is the one-click way to set it up; never counts as compliant), not_checked (Checkbox has not tried it yet, e.g. the cancel flow: `compliance.fix` says how; never counts as compliant). */
+    /** User-facing status. needs_fix (a requirement is clearly not met: `compliance.fix` is the one change), pending_live_check (everything Checkbox can see is right; the live event has not been observed yet — counts as passing the checks), verified_live (observed live: proof run, real BCC'd send, Stripe-confirmed cancellation), your_call (a real decision for a person: `compliance.question`), compliant (passes; grey areas carry a `compliance.note`), not_applicable, not_set_up (no sign the email or setting exists yet: `compliance.fix` is the one-click way to set it up; never counts as passing the checks), not_checked (Checkbox has not tried it yet, e.g. the cancel flow: `compliance.fix` says how; never counts as passing the checks). */
     compliance_status?: "needs_fix" | "pending_live_check" | "verified_live" | "your_call" | "compliant" | "not_applicable" | "not_set_up" | "not_checked";
+    /** The status in words to show a person ("Needs a fix", "Your call", "Not set up yet", "Not checked yet", "Checks pass"…). Show this, never the machine value. */
+    compliance_status_label?: string;
     /** Position in the plan (1 = do first). Dependency-aware. */
     order: number;
     /** Legal checks this task makes pass. */
@@ -1223,7 +1631,7 @@ export interface Task {
     where: {
         /** Where the change is made. */
         kind: "code" | "stripe_setting" | "email_template" | "policy_page" | "dns" | "checkbox_setting" | "billing_platform";
-        /** Likely source file (reported by `checkbox init` / updateSetupSession, else a framework convention). */
+        /** Source file reported by `checkbox init` / updateSetupSession (null when none was reported: Checkbox does not guess file names; the root layout of a file-system router is named). */
         file_hint: string | null;
         /** Page (or settings page) where the problem was observed / the change is made. */
         url: string | null;
@@ -1308,6 +1716,15 @@ export interface Task {
         /** When it was requested. Unix timestamp in seconds. */
         created: number;
     } | null;
+    /** Email tasks on a site with several plans: the result of each plan's own email copy (verifyTask with plan). The copy check passes only when every plan passes; one plan's copy never covers another plan. */
+    plan_coverage?: Array<{
+        /** The plan, by name. */
+        plan: string;
+        /** That plan's copy: pass, fail, needs_review, or not_checked (no copy for this plan was verified yet). */
+        verdict: "pass" | "fail" | "needs_review" | "not_checked";
+        /** When that plan's copy was checked. Unix timestamp in seconds. */
+        checked_at: number | null;
+    }>;
     next_action: PlanNextAction;
     /** Email tasks only (null otherwise): what Checkbox has seen of this email. not_seen (nothing yet), template_checked (a template or sample passed the email checks, but Checkbox has not seen it sent for a real event: the task stays open), delivery_seen (captured from a real event: a test run, a notice for a real subscriber, or a BCC copy matching that subscriber's billing event). Only delivery_seen satisfies the task. */
     verification_level: "not_seen" | "template_checked" | "delivery_seen" | null;
@@ -1316,7 +1733,7 @@ export interface Task {
     /** When it was done. Unix timestamp in seconds. */
     done_at: number | null;
 }
-/** The ordered, machine-readable list of changes that makes a site compliant, recomputed from its latest evaluation. */
+/** The ordered, machine-readable list of changes that makes a site's checks pass, recomputed from its latest evaluation. */
 export interface CompliancePlan {
     /** Unique identifier of the compliance plan (plan_…). */
     id: string;
@@ -1328,14 +1745,16 @@ export interface CompliancePlan {
     site: string;
     /** action_required (an agent can apply open tasks now), verifying (changes applied; waiting for confirming observations), compliant (every required check passes or only waits for a live check — an automated assessment, not a legal determination; see compliance.pending_live_checks and coverage), blocked (only human answers ("Your call") or declined critical tasks remain). */
     status: "action_required" | "verifying" | "compliant" | "blocked";
-    /** Compliance score 0-100 of the latest evaluation. */
-    score: number | null;
+    /** The plan status in words to show a person: action_required "Fixes needed", verifying "Checking your changes", compliant "Checks pass", blocked "Your call". Show this, never the machine value (`compliant` is a status name, not a legal conclusion). */
+    status_label?: string;
     /** The evaluation the plan was built from (null before the first check). */
     evaluation: string | null;
     /** When that evaluation ran. Unix timestamp in seconds. */
     evaluated: number | null;
     /** Two or three sentences for an LLM: where the site stands and what comes next. */
     summary: string;
+    /** Declared plans (setup plans, i.e. your code) whose price, interval or trial differ from the billing platform's Price they map to. Checkbox checks and writes every fix from the Price, and the page task names the difference; update the page and setup plans, or the Price, so they agree. Absent when none. */
+    plan_terms_conflicts?: Array<string>;
     /** Tasks per status. */
     counts: {
         /** Open tasks. */
@@ -1346,7 +1765,7 @@ export interface CompliancePlan {
         verifying: number;
         /** Tasks waiting for a human answer. */
         manual: number;
-        /** Tasks that only wait for a live observation (count as compliant). */
+        /** Tasks that only wait for a live observation (count as passing the checks). */
         pending_live_check?: number;
         /** Done tasks. */
         done: number;
@@ -1361,13 +1780,13 @@ export interface CompliancePlan {
     groups: {
         /** Required tasks (the legal floor). */
         required: Array<string>;
-        /** Recommended suggestions (never block compliant). */
+        /** Recommended suggestions (never block the checks from passing). */
         recommended: Array<string>;
         /** Extra protections (maximum only). */
         extra: Array<string>;
     };
     compliance: ComplianceRollup | null;
-    /** What the assessment rests on. Tell the human about not_observed and attested items; never call the site "compliant" without them. */
+    /** What the assessment rests on. Tell the human about not_observed and attested items; never tell them the site "is compliant". */
     coverage: {
         /** Lifecycle stages Checkbox observed (signup, acknowledgment_email, reminders, cancellation, policies, billing_settings). */
         observed: Array<string>;
@@ -1379,11 +1798,11 @@ export interface CompliancePlan {
         billing_connected: boolean;
     };
     next_action: PlanNextAction;
-    /** Evidence level per required email kind. A plan is never compliant on template_checked emails. */
+    /** Evidence level per required email kind. A plan never reaches status compliant on template_checked emails. */
     email_verification: Array<{
         /** Email kind (acknowledgment, trial_ending, renewal_reminder, annual_terms, charge_notice, price_change, cancellation_confirmation). */
         kind: string;
-        /** not_seen, template_checked (template or sample only: never counted as compliant) or delivery_seen (sent for a real event). */
+        /** not_seen, template_checked (template or sample only: never counted as passing) or delivery_seen (sent for a real event). */
         verification_level: "not_seen" | "template_checked" | "delivery_seen";
         /** Why this level, in plain words. */
         reason: string;
@@ -1398,15 +1817,16 @@ export interface CompliancePlan {
     disclaimer: string;
     /** When the plan was computed. Unix timestamp in seconds. */
     generated: number;
+    unverified_scan?: UnverifiedScan;
     /** Optional improvements beyond compliance. Never tasks, never blocking, never counted toward compliance. */
     optional_improvements?: {
-        /** Compliant conversion suggestions for this site. */
+        /** Conversion suggestions for this site that keep the checks passing. */
         conversion_suggestions: {
             /** What they are. */
             description: string;
             /** Always false. */
             blocking: false;
-            /** Always false: they never change status, score or tasks. */
+            /** Always false: they never change the status or the tasks. */
             counts_toward_compliance: false;
             /** Operation that lists them. */
             operation_id: string;
@@ -1418,11 +1838,16 @@ export interface CompliancePlan {
     };
 }
 export interface UpdateTaskParams {
-    /** in_progress claims the task (other agents see it), wont_fix declines it (needs reason; a declined critical/high task keeps the plan from being compliant), not_applicable records that the task does not apply to this business (needs reason, e.g. "no price changes are planned"; the task closes as no_longer_applicable and does not block the plan), open clears any of them. */
+    /** in_progress claims the task (other agents see it), wont_fix declines it (needs reason; a declined critical/high task keeps the plan from reaching status compliant), not_applicable records that the task does not apply to this business (needs reason, e.g. "no price changes are planned"; the task closes as no_longer_applicable and does not block the plan), open clears any of them. */
     status: "open" | "in_progress" | "wont_fix" | "not_applicable";
     /** Why (required for wont_fix). */
     reason?: string;
 }
+/** The task after answerTask, with the confirmation link at the top level when the human must confirm. */
+export type AnsweredTask = Task & {
+    /** When the answer waits for the human: the link they open (signed in to Checkbox) to confirm it. Same as answer.pending_confirmation_url; null when nothing waits for confirmation. */
+    confirmation_url: string | null;
+};
 export interface AnswerTaskParams {
     /** One of the task's question.options (yes / no, or confirmed / needs_change). */
     answer: string;
@@ -1456,13 +1881,17 @@ export interface Verification {
     task: string | null;
     /** One task or the whole site. */
     scope: "task" | "site";
-    /** pending (waiting for the confirming scan / re-evaluation), passed (Checkbox observed the expected result), passed_with_gaps (nothing observed fails, but some checks could not be observed: observed missing_data — not verified), failed (it did not: see diff). */
-    status: "pending" | "passed" | "passed_with_gaps" | "failed";
+    /** pending (waiting for the confirming scan / re-evaluation), passed (Checkbox observed the expected result: every check passes or does not apply), passed_with_gaps (nothing observed fails, but some checks could not be observed: observed missing_data — not verified), passed_with_notes (nothing observed fails and the task counts as passing, but a check is still needs_review on a part that is not yours to change, such as Stripe's own page layout: see checks), not_checked (a task whose checks could only not be observed yet: nothing to change in the code; next_action says what evidence to provide), pending_live_check (an email whose content passes but that Checkbox has not seen sent for a real event yet: nothing to change; it completes on the first real send or a proof run), failed (it did not: see diff). */
+    status: "pending" | "passed" | "passed_with_gaps" | "passed_with_notes" | "not_checked" | "pending_live_check" | "failed";
     /** How it was re-checked. */
     method: "page_fetch" | "policy_refetch" | "stripe_params" | "email_copy" | "platform_sync" | "attestation" | "evaluation" | "test_run";
+    /** What this verification checked, in words: "the params you sent", "Checkout Sessions read from Stripe", "registered configs", "the HTML you sent", "the email copy you sent (plan …)", "the live page …, fetched now"… */
+    checked: string;
     /** The fast pre-check run immediately (seconds). A failing pre-check fails the verification at once. */
     precheck: {
-        /** static_fetch, html, stripe_params, email or policy_fetch. */
+        /** What the pre-check judged (as `checked`). */
+        checked: string;
+        /** static_fetch, html, stripe_params, email, policy_fetch, or billing_sync (Stripe was re-read before judging; its verdict is always needs_review and only carries the note: the re-evaluation decides). */
         source: string;
         /** Pre-check verdict for the task's checks. */
         verdict: "pass" | "fail" | "needs_review";
@@ -1470,6 +1899,26 @@ export interface Verification {
         url: string | null;
         /** What the pre-check can and cannot confirm. */
         note: string;
+        /** Email tasks on a site with several plans: each plan's copy result. A later verification only replaces the result of the plan it judged. */
+        plans?: Array<{
+            /** The plan, by name. */
+            plan: string;
+            /** That plan's copy: pass, fail, needs_review, or not_checked (no copy for this plan was verified yet). */
+            verdict: "pass" | "fail" | "needs_review" | "not_checked";
+            /** When that plan's copy was checked. Unix timestamp in seconds. */
+            checked_at: number | null;
+        }>;
+        /** Each pre-checked check of the task, compact (empty when the pre-check ran no engine check). */
+        checks: Array<{
+            /** Check id. */
+            check_id: string;
+            /** Pre-check result: pass, fail, needs_review or not_applicable. */
+            status: string;
+            /** What the pre-check found, in one line. */
+            reason: string;
+            /** How to fix it, in one line (absent when it passes). */
+            fix?: string;
+        }>;
     } | null;
     /** Confirming scan queued by the verification. */
     scan: string | null;
@@ -1479,6 +1928,8 @@ export interface Verification {
     diff: Array<VerificationCheck>;
     /** Plan status after this verification (null while pending). */
     plan_status: "action_required" | "verifying" | "compliant" | "blocked" | null;
+    /** The plan status in words to show a person: action_required "Fixes needed", verifying "Checking your changes", compliant "Checks pass", blocked "Your call". Show this, never the machine value (`compliant` is a status name, not a legal conclusion). */
+    plan_status_label?: string | null;
     next_action: PlanNextAction;
     /** When it was requested. Unix timestamp in seconds. */
     created: number;
@@ -1490,11 +1941,11 @@ export interface Verification {
 export interface VerifyTaskParams {
     /** page_fetch tasks: the rendered page HTML before you deploy, at most ~900 KB (request bodies are limited to 1 MB). Pre-check only; the confirming scan runs on the live page. */
     html?: string;
-    /** stripe_params tasks: exactly what your code now passes to stripe.checkout.sessions.create. */
+    /** stripe_params tasks and the sign-up tasks (signup_disclosure): exactly what your code now passes to stripe.checkout.sessions.create. Judged together with the page (any failing check fails the verification). A task that does not use it refuses it (parameter_invalid, naming the task that takes it). */
     stripe_checkout_session?: Record<string, unknown>;
     /** stripe_params tasks with several Checkout code paths (one per plan, e.g. monthly and annual-with-trial): every params object your code passes to stripe.checkout.sessions.create. The pre-check fails when any of them fails. Without either field, every registered config (newest per name) is checked. */
     stripe_checkout_sessions?: Array<Record<string, unknown>>;
-    /** email_copy tasks: the new email template (pre-check; the real email confirms). */
+    /** email_copy tasks: the new email template (pre-check; the real email confirms). On a site with several plans it is checked against every plan and passes when it matches one plan fully (pass plan or price_id to check one plan). */
     email?: {
         /** Email kind (default: from the task). */
         kind?: "acknowledgment" | "trial_reminder" | "renewal_reminder" | "price_change" | "annual_terms" | "charge_notice" | "cancellation_confirmation";
@@ -1505,6 +1956,10 @@ export interface VerifyTaskParams {
         /** HTML body. */
         html?: string;
     };
+    /** email_copy tasks: check the email against this plan only (its name, e.g. "Annual"). */
+    plan?: string;
+    /** email_copy tasks: check the email against the plan with this Stripe Price id only. */
+    price_id?: string;
     /** Re-check a task that is already done (or declined) instead of returning its last result: Checkbox evaluates the site again now and queues a confirming scan, so a regression shows up (pilot: a cancel page switched to phone-only stayed "passed"). */
     recheck?: boolean;
 }
@@ -1571,6 +2026,7 @@ export interface Fix {
     /** Why parts of the fix could not be generated (e.g. plan terms unknown). */
     problems: Array<string>;
     remediation: Remediation;
+    next_action: NextAction | null;
 }
 /** A page of fix plans. */
 export interface FixList {
@@ -1583,6 +2039,38 @@ export interface FixList {
     /** The URL of this list. */
     url: string;
 }
+/** The verified renewal terms published to the Checkbox Shopify app block (an app-owned metafield; nothing else in the store changes). */
+export interface ShopifyTermsPublication {
+    /** Id of the recorded fix application (the evidence trail of this publish). */
+    id: string;
+    /** String representing the object's type. Always "shopify_terms_publication". */
+    object: "shopify_terms_publication";
+    /** true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox). */
+    livemode: boolean;
+    /** The site. */
+    site: string;
+    /** The Shopify store (myshopify.com domain) the text was published to. */
+    shop: string;
+    /** The renewal disclosure the "Renewal terms + consent" block now shows (engine-verified). */
+    disclosure: string;
+    /** Label of the unchecked, required consent checkbox the block shows. */
+    consent_label: string;
+    /** sha256 of the published texts (disclosure + newline + consent label). */
+    sha256: string;
+    /** Sign-up checks the published text was verified against. */
+    check_ids: Array<string>;
+    /** When the text was published. Unix timestamp in seconds. */
+    published: number;
+    /** Theme editor link that adds the "Renewal terms + consent" block to the product page. The merchant opens it once and clicks Save (Checkbox never edits the theme). */
+    theme_editor_url: string;
+    next_action: NextAction;
+}
+export interface PublishShopifyTermsParams {
+    /** Billing-platform plan / price id to write the terms for (default: the plan Checkbox resolved for the site). */
+    plan?: string;
+    /** Cancellation URL to state (default: the hosted cancellation page or the declared account page). */
+    cancel_url?: string;
+}
 /** A record in the tamper-evident evidence vault. */
 export interface Evidence {
     /** Unique identifier of the evidence (ev_…). */
@@ -1721,7 +2209,7 @@ export interface NoticeSettings {
     subscribers: {
         /** Active subscriptions Checkbox knows from the billing platform. */
         active: number;
-        /** Of those, how many have a known email address (Checkbox can only send to these). */
+        /** Of those, how many Checkbox can email: an address on file, or a Stripe customer whose address it reads when sending. */
         with_email: number;
     } | null;
     /** Confirmed cancellation policy (required before notices go out). */
@@ -1767,8 +2255,12 @@ export interface NoticeSettings {
 export interface UpdateNoticeSettingsParams {
     /** merchant: you send the emails (Checkbox tracks them); checkbox: Checkbox sends them. Turning an enabled_kinds notice on implies checkbox. */
     mode?: "merchant" | "checkbox";
-    /** Notices to send (turning one on needs cancel_url, a confirmed policy and a connected Stripe/Recharge account). trial_reminder is accepted as an alias of trial_ending. */
+    /** The full list of notices Checkbox sends: replaces the current list, so a kind left out is turned off. To turn one on or off without touching the others, use add_kinds / remove_kinds. Turning one on needs cancel_url, a confirmed policy and a connected Stripe, Recharge, Chargebee, Recurly or Paddle account. trial_reminder is accepted as an alias of trial_ending. */
     enabled_kinds?: Array<"acknowledgment" | "trial_ending" | "renewal_reminder" | "annual_terms" | "price_change" | "cancellation_confirmation" | "charge_notice" | "trial_reminder">;
+    /** Notices to turn on, added to the ones already on (the others stay as they are). Same prerequisites as enabled_kinds. */
+    add_kinds?: Array<"acknowledgment" | "trial_ending" | "renewal_reminder" | "annual_terms" | "price_change" | "cancellation_confirmation" | "charge_notice" | "trial_reminder">;
+    /** Notices to turn off; the others stay as they are. */
+    remove_kinds?: Array<"acknowledgment" | "trial_ending" | "renewal_reminder" | "annual_terms" | "price_change" | "cancellation_confirmation" | "charge_notice" | "trial_reminder">;
     /** Brand name. */
     brand_name?: string | null;
     /** Product name. */
@@ -1897,9 +2389,9 @@ export interface DueNoticeList {
 export interface NoticeTemplate {
     /** Template id (`<variant>.v1`); due notices name the one they were rendered from. */
     id: string;
-    /** Notice kind. */
-    kind: "acknowledgment" | "trial_ending" | "renewal_reminder" | "annual_terms" | "price_change" | "cancellation_confirmation";
-    /** Variant within the kind (acknowledgment vs acknowledgment_trial, cancellation_confirmation vs _immediate). */
+    /** Notice kind (charge_notice: sent by you with each renewal charge; Checkbox does not schedule it). */
+    kind: "acknowledgment" | "trial_ending" | "renewal_reminder" | "annual_terms" | "price_change" | "cancellation_confirmation" | "charge_notice";
+    /** Variant within the kind (acknowledgment vs acknowledgment_trial, cancellation_confirmation vs _immediate, charge_notice_upcoming before a charge vs charge_notice after it). */
     variant: string;
     /** Human label. */
     label: string;
@@ -1917,7 +2409,7 @@ export interface NoticeTemplate {
     merge_fields: Array<string>;
     /** The kind to pass to checkEmail (/v1/checks/email) for this template. */
     check_kind: string;
-    /** BCC address for this kind (when ?site= is given). */
+    /** BCC address for this kind (when ?site= is given): the same address the plan's email task gives. A copy sent to it with the subscriber in To also confirms that subscriber's due notice of this kind. */
     bcc?: string;
 }
 /** Copy-ready templates for every required notice. */
@@ -1943,7 +2435,7 @@ export interface NoticeTemplateCheck {
     /** Always "notice_template_check". */
     object: "notice_template_check";
     /** Notice kind checked. */
-    kind: "acknowledgment" | "trial_ending" | "renewal_reminder" | "annual_terms" | "price_change" | "cancellation_confirmation";
+    kind: "acknowledgment" | "trial_ending" | "renewal_reminder" | "annual_terms" | "price_change" | "cancellation_confirmation" | "charge_notice";
     /** pass, fail or needs_review. */
     verdict: string;
     /** Verdict per engine check. */
@@ -1980,7 +2472,7 @@ export interface CheckNoticeTemplateParams {
     /** Site whose plan, brand, cancel URL and jurisdictions fill the merge fields and scope the check. */
     site: string;
     /** Which notice the template is for. */
-    kind: "acknowledgment" | "trial_ending" | "renewal_reminder" | "annual_terms" | "price_change" | "cancellation_confirmation";
+    kind: "acknowledgment" | "trial_ending" | "renewal_reminder" | "annual_terms" | "price_change" | "cancellation_confirmation" | "charge_notice";
     /** Your subject (merge fields allowed). */
     subject: string;
     /** Your plain-text body (merge fields allowed). */
@@ -2025,10 +2517,6 @@ export interface LawSiteImpact {
     site: string;
     /** What changed for the site. */
     summary: string;
-    /** Score before the change (0-100, one decimal place). */
-    score_before: number | null;
-    /** Score after re-evaluation (0-100, one decimal place). */
-    score_after: number | null;
     /** Checks whose result changed or that the change touches. */
     affected_checks: Array<{
         /** Check id. */
@@ -2113,7 +2601,7 @@ export interface CheckVerdict {
     /** Page checks on static HTML: the engine status on the estimated layout. */
     static_estimate?: "pass" | "fail" | "needs_review" | "not_applicable";
     evidence: VerdictEvidence;
-    /** User-facing status. needs_fix (a clear violation: `compliance.fix` is the one change), pending_live_check (everything Checkbox can see is right; the live event has not been observed yet — counts as compliant), verified_live (observed live: proof run, real BCC'd send, Stripe-confirmed cancellation), your_call (a real decision for a person: `compliance.question`), compliant (passes; grey areas carry a `compliance.note`), not_applicable, not_set_up (no sign the email or setting exists yet: `compliance.fix` is the one-click way to set it up; never counts as compliant), not_checked (Checkbox has not tried it yet, e.g. the cancel flow: `compliance.fix` says how; never counts as compliant). */
+    /** User-facing status. needs_fix (a requirement is clearly not met: `compliance.fix` is the one change), pending_live_check (everything Checkbox can see is right; the live event has not been observed yet — counts as passing the checks), verified_live (observed live: proof run, real BCC'd send, Stripe-confirmed cancellation), your_call (a real decision for a person: `compliance.question`), compliant (passes; grey areas carry a `compliance.note`), not_applicable, not_set_up (no sign the email or setting exists yet: `compliance.fix` is the one-click way to set it up; never counts as passing the checks), not_checked (Checkbox has not tried it yet, e.g. the cancel flow: `compliance.fix` says how; never counts as passing the checks). */
     compliance_status: "needs_fix" | "pending_live_check" | "verified_live" | "your_call" | "compliant" | "not_applicable" | "not_set_up" | "not_checked";
     compliance: ComplianceInfo;
 }
@@ -2133,16 +2621,22 @@ export interface CheckWarning {
     /** Related parameter. */
     param?: string;
 }
-/** A compliant replacement, verified by the engine. */
+/** A suggested replacement that passes the checks, verified by the engine. */
 export interface CheckReplacement {
-    /** Compliant disclosure generated from the plan terms (locked wording). */
+    /** Disclosure generated from the plan terms that passes the checks (locked wording). */
     disclosure_text: string;
     /** Label for the unchecked, required consent checkbox. */
     consent_label: string;
     /** Purchase button label that itself states the renewal. */
     button_text: string;
-    /** Drop-in markup: disclosure (set off in a box) + unchecked required checkbox + button. */
+    /** Drop-in markup: disclosure + unchecked required checkbox + button. When consent_on is set (the purchase completes on a Stripe Payment Link or Stripe Checkout), the terms only: no checkbox, no button. */
     html: string;
+    /** Set when consent is collected on the Stripe-hosted page, not on this page: html is then the terms only. */
+    consent_on?: "payment_link" | "stripe_checkout";
+    /** What html contains and what is still needed elsewhere (set with consent_on). */
+    note?: string;
+    /** The same markup as JSX for React / Next.js components (className, htmlFor, style objects, self-closed inputs); the text is unchanged. */
+    jsx?: string;
     /** Placeholders left to fill (e.g. {{cancel_url}}). */
     placeholders: Array<string>;
     /** The engine passes every targeted sign-up check on a page using this replacement. */
@@ -2196,17 +2690,19 @@ export interface DisclosureCheckResult {
     /** Not legal advice. */
     disclaimer: string;
     next_action: NextAction;
-    /** User-facing roll-up: needs_fix > your_call > incomplete > compliant (pending live checks count as compliant). `verdict` keeps the machine value. */
+    /** User-facing roll-up: needs_fix > your_call > incomplete > compliant (every required check passes; pending live checks count as passing). `verdict` keeps the machine value. */
     compliance_status: "needs_fix" | "your_call" | "incomplete" | "compliant" | "not_checked";
     compliance: ComplianceRollup;
     replacement: CheckReplacement;
 }
-/** A checkout disclosure to check before it ships. */
+/** A checkout disclosure to check before it ships. The plan fields (price, interval, cancel_url…) may also be nested under `terms` or `merchant`, as in the other checks. */
 export interface DisclosureCheckParams {
     /** The disclosure shown next to the purchase button, exactly as rendered. */
     text: string;
     /** Brand shown to subscribers; used in generated text. */
     merchant_name?: string;
+    /** Alias of merchant_name (the {{brand_name}} merge field). Send one of the two. */
+    brand_name?: string;
     /** Plan / product name. */
     plan_name?: string;
     /** Recurring price in major units (19.99). Or give `amount` in minor units. */
@@ -2221,6 +2717,16 @@ export interface DisclosureCheckParams {
     interval_count?: number;
     /** Free-trial length in days (0 or absent = no trial). */
     trial_days?: number;
+    /** Intro / first-period price in major units ("$34.50 for your first box, then $69 every 2 weeks"). Or give `intro_amount` in minor units. */
+    intro_price?: number | string;
+    /** Intro / first-period price in minor units. */
+    intro_amount?: number;
+    /** How many billing periods the intro price lasts (default 1). */
+    intro_periods?: number;
+    /** Intro discount as a percentage off the recurring price (a Stripe coupon's percent_off: 20 for "20% off your first month"). Lasts `intro_periods` billing periods. Give one of intro_price / intro_amount, intro_percent_off or intro_amount_off. */
+    intro_percent_off?: number;
+    /** Intro discount as an amount off in minor units (a Stripe coupon's amount_off: 200 for $2.00 off). Lasts `intro_periods` billing periods. */
+    intro_amount_off?: number;
     /** https URL where subscribers cancel online (used in generated text; a {{cancel_url}} placeholder otherwise). */
     cancel_url?: string;
     /** When a cancellation takes effect (default period_end). */
@@ -2315,7 +2821,7 @@ export interface StripeCheckoutSessionCheckResult {
     /** Not legal advice. */
     disclaimer: string;
     next_action: NextAction;
-    /** User-facing roll-up: needs_fix > your_call > incomplete > compliant (pending live checks count as compliant). `verdict` keeps the machine value. */
+    /** User-facing roll-up: needs_fix > your_call > incomplete > compliant (every required check passes; pending live checks count as passing). `verdict` keeps the machine value. */
     compliance_status: "needs_fix" | "your_call" | "incomplete" | "compliant" | "not_checked";
     compliance: ComplianceRollup;
     /** The fix. */
@@ -2346,10 +2852,12 @@ export interface StripeCheckoutSessionCheckResult {
         placeholders: Array<string>;
     };
 }
-/** What Stripe params do not say: merchant_name, cancel_url, and price / interval when line_items reference a Price id. */
+/** What Stripe params do not say: merchant_name, cancel_url, and price / interval when line_items reference a Price id. Also accepted as `terms`. Optional with `site`. */
 export interface CheckPlanTerms {
     /** Brand shown to subscribers; used in generated text. */
     merchant_name?: string;
+    /** Alias of merchant_name (the {{brand_name}} merge field). Send one of the two. */
+    brand_name?: string;
     /** Plan / product name. */
     plan_name?: string;
     /** Recurring price in major units (19.99). Or give `amount` in minor units. */
@@ -2364,6 +2872,16 @@ export interface CheckPlanTerms {
     interval_count?: number;
     /** Free-trial length in days (0 or absent = no trial). */
     trial_days?: number;
+    /** Intro / first-period price in major units ("$34.50 for your first box, then $69 every 2 weeks"). Or give `intro_amount` in minor units. */
+    intro_price?: number | string;
+    /** Intro / first-period price in minor units. */
+    intro_amount?: number;
+    /** How many billing periods the intro price lasts (default 1). */
+    intro_periods?: number;
+    /** Intro discount as a percentage off the recurring price (a Stripe coupon's percent_off: 20 for "20% off your first month"). Lasts `intro_periods` billing periods. Give one of intro_price / intro_amount, intro_percent_off or intro_amount_off. */
+    intro_percent_off?: number;
+    /** Intro discount as an amount off in minor units (a Stripe coupon's amount_off: 200 for $2.00 off). Lasts `intro_periods` billing periods. */
+    intro_amount_off?: number;
     /** https URL where subscribers cancel online (used in generated text; a {{cancel_url}} placeholder otherwise). */
     cancel_url?: string;
     /** When a cancellation takes effect (default period_end). */
@@ -2374,6 +2892,10 @@ export interface StripeCheckParams {
     /** Exactly the object your code passes to Stripe (checkout.sessions.create / paymentLinks.create), or a retrieved Payment Link. */
     params: Record<string, unknown>;
     merchant?: CheckPlanTerms;
+    /** A site of yours (site_…): the params are judged as verifyTask judges them — the plan each line_items Price sells (the connected Stripe Prices win over plans typed in setup), the site's merchant name, cancellation URL and jurisdictions; merchant fields you send other than the plan's price / interval / trial are kept. Without it, the params are judged with merchant only (or the one site of the account with Stripe connected when you pass plan). "none" judges only what you send. */
+    site?: string;
+    /** With a site: judge the params against this plan (name or Stripe Price id) instead of the plan their Price id sells. An unknown plan is refused with the list of plans. */
+    plan?: string;
     /** Where you sell: "all" (default) or state codes ("US-CA", "CA", "US-NY"; "US-FED" is always included). */
     jurisdictions?: "all" | Array<string>;
     /** Evaluate the law as of this date (YYYY-MM-DD, default today). */
@@ -2423,7 +2945,7 @@ export interface StripePaymentLinkCheckResult {
     /** Not legal advice. */
     disclaimer: string;
     next_action: NextAction;
-    /** User-facing roll-up: needs_fix > your_call > incomplete > compliant (pending live checks count as compliant). `verdict` keeps the machine value. */
+    /** User-facing roll-up: needs_fix > your_call > incomplete > compliant (every required check passes; pending live checks count as passing). `verdict` keeps the machine value. */
     compliance_status: "needs_fix" | "your_call" | "incomplete" | "compliant" | "not_checked";
     compliance: ComplianceRollup;
     /** The fix. */
@@ -2502,20 +3024,22 @@ export interface EmailCheckResult {
     /** Not legal advice. */
     disclaimer: string;
     next_action: NextAction;
-    /** User-facing roll-up: needs_fix > your_call > incomplete > compliant (pending live checks count as compliant). `verdict` keeps the machine value. */
+    /** User-facing roll-up: needs_fix > your_call > incomplete > compliant (every required check passes; pending live checks count as passing). `verdict` keeps the machine value. */
     compliance_status: "needs_fix" | "your_call" | "incomplete" | "compliant" | "not_checked";
     compliance: ComplianceRollup;
     /** The email kind checked. */
     email_kind: string;
+    /** With a site: the site's plan the email was judged against. */
+    plan?: string;
     /** Always template_checked: this checks the wording you send in, not that your system sends it. On the site, the email only counts once Checkbox sees it sent for a real event (delivery_seen: a test run, a notice for a real subscriber, or a BCC copy matching that subscriber's billing event). */
     verification_level: "template_checked";
     /** Requirements that make this email mandatory for this plan (empty: not legally required). */
     required_by: Array<string>;
-    /** A compliant template generated from the plan terms. */
+    /** A template generated from the plan terms that passes the checks. */
     template: {
-        /** Compliant subject. */
+        /** Subject that passes the checks. */
         subject: string;
-        /** Compliant plain-text body. */
+        /** Plain-text body that passes the checks. */
         text: string;
         /** The same body as HTML. */
         html: string;
@@ -2539,8 +3063,8 @@ export interface EmailCheckParams {
     text?: string;
     /** HTML body. */
     html?: string;
-    /** The plan the email is about (price, interval and cancel_url at least). */
-    terms: CheckPlanTerms & {
+    /** The plan the email is about (price, interval and cancel_url at least). Also accepted as `merchant`. Required unless a site with plan terms is used (`site`, or the one site of the account with Stripe connected): then the plan fields come from the price Stripe charges and the other fields (cancel_url, previous_price, support_contact) are kept. A price_change notice always takes the NEW price from here. */
+    terms?: CheckPlanTerms & {
         /** price_change only: the OLD price before the change, major units. price / amount is the NEW price the email announces. */
         previous_price?: number | string;
         /** Price before a price change, minor units. */
@@ -2548,6 +3072,10 @@ export interface EmailCheckParams {
         /** Support email / URL shown in the generated template. */
         support_contact?: string;
     };
+    /** A site of yours (site_…): the email is judged as verifyTask judges it, against the plan it names ("Annual") among the site's plans (the connected Stripe Prices win over plans typed in setup), with the site's jurisdictions. Without it, the one site of the account with Stripe connected is used when there is exactly one (the result says so in warnings, code site_from_stripe). "none" judges only the terms you send. */
+    site?: string;
+    /** With a site: the plan (name or Stripe Price id) the email is for, instead of the plan the email names. */
+    plan?: string;
     /** Where you sell: "all" (default) or state codes ("US-CA", "CA", "US-NY"; "US-FED" is always included). */
     jurisdictions?: "all" | Array<string>;
     /** Evaluate the law as of this date (YYYY-MM-DD, default today). */
@@ -2597,7 +3125,7 @@ export interface PageCheckResult {
     /** Not legal advice. */
     disclaimer: string;
     next_action: NextAction;
-    /** User-facing roll-up: needs_fix > your_call > incomplete > compliant (pending live checks count as compliant). `verdict` keeps the machine value. */
+    /** User-facing roll-up: needs_fix > your_call > incomplete > compliant (every required check passes; pending live checks count as passing). `verdict` keeps the machine value. */
     compliance_status: "needs_fix" | "your_call" | "incomplete" | "compliant" | "not_checked";
     compliance: ComplianceRollup;
     /** Whether html was given or fetched from url. */
@@ -2606,8 +3134,8 @@ export interface PageCheckResult {
     extraction: {
         /** How the page was read. */
         mode: "static_html";
-        /** Page URL used. */
-        url: string;
+        /** Page URL used (null when only html was sent: the page is built from the HTML you sent). */
+        url: string | null;
         /** Purchase buttons found (primary first). */
         purchase_buttons: Array<string>;
         /** Text blocks that read like subscription terms. */
@@ -2632,6 +3160,11 @@ export interface PageCheckResult {
         limitations: Array<string>;
     };
     replacement?: CheckReplacement;
+    /** With two or more plans: one verified replacement per plan, for that plan's own purchase button (never another plan's). */
+    plan_replacements?: Array<CheckReplacement & {
+        /** The plan this replacement is for (name, price, interval, trial). */
+        plan: string;
+    }>;
 }
 /** A checkout page to check. */
 export interface PageCheckParams {
@@ -2642,6 +3175,15 @@ export interface PageCheckParams {
     /** What the page is (default checkout). */
     page_kind?: "checkout" | "pricing";
     terms?: CheckPlanTerms;
+    /** Every plan a multi-plan pricing page sells (price or amount, interval, trial_days each; the same plan fields as setup plans[] in updateSetupSession). Each plan card / button is judged against its own plan; only a price no listed plan charges is a mismatch. Without it, one plan's `terms` leaves other plan cards' prices at needs_review (warning plans_partial). */
+    plans?: Array<CheckPlanTerms & {
+        /** Plan name, as in setup plans[] (updateSetupSession; alias of plan_name). */
+        name?: string;
+    }>;
+    /** Where the shopper pays: own_page (a form on this page), stripe_checkout or payment_link (a Stripe-hosted page that collects consent, so no checkbox is needed here). Inferred from a purchase link to buy.stripe.com / checkout.stripe.com when absent. */
+    checkout_type?: "own_page" | "stripe_checkout" | "payment_link";
+    /** A site of yours (site_…): the page is judged exactly as verifyTask judges it — against the site's plans (the connected Stripe Prices win over plans typed in setup), its jurisdictions and its checkout type. These replace terms, plans, jurisdictions and checkout_type when the site knows them. Without it, the one site of the account with Stripe connected gives the plans when there is exactly one (warning site_from_stripe says so). "none" judges only what you send. */
+    site?: string;
     /** Where you sell: "all" (default) or state codes ("US-CA", "CA", "US-NY"; "US-FED" is always included). */
     jurisdictions?: "all" | Array<string>;
     /** Evaluate the law as of this date (YYYY-MM-DD, default today). */
@@ -2659,9 +3201,9 @@ export interface ScheduledNotice {
     send_date: string;
     /** Recommended send time. Unix timestamp in seconds. */
     send_at: number;
-    /** Earliest compliant send time. Unix seconds. */
+    /** Earliest send time that meets the notice timing. Unix seconds. */
     window_opens_at: number;
-    /** Latest compliant send time. Unix seconds. */
+    /** Latest send time that meets the notice timing. Unix seconds. */
     window_closes_at: number;
     /** Days before the event (0 = right away). */
     days_before: number;
@@ -2673,6 +3215,8 @@ export interface ScheduledNotice {
     citations: Array<string>;
     /** No requirement states a window; Checkbox’s default window was used. */
     default_window: boolean;
+    /** Why the window is what it is when the states narrow it to a single day, and when to send. */
+    timing_note?: string;
 }
 /** When each legally required notice must be sent. */
 export interface NoticeScheduleResult {
@@ -2686,8 +3230,14 @@ export interface NoticeScheduleResult {
     created: number;
     /** Sign-up date planned for. */
     start_date: string;
+    /** With a site: the site's plan the notices were scheduled for. */
+    plan?: string;
     /** Every legally required notice, in send order. */
     notices: Array<ScheduledNotice>;
+    /** Notes about the input (e.g. an amount that looks like the wrong unit). */
+    warnings?: Array<CheckWarning>;
+    /** How days before are counted when Checkbox judges a send (the email checks, test runs and Notices use the same rule). */
+    rounding_rule: string;
     /** Notice kinds no applicable requirement demands for this plan. */
     not_required: Array<{
         /** Notice kind. */
@@ -2711,7 +3261,11 @@ export interface NoticeScheduleResult {
 }
 /** A subscription to plan the legally required notices for. */
 export interface NoticeScheduleParams {
-    terms: CheckPlanTerms;
+    terms?: CheckPlanTerms;
+    /** A site of yours (site_…): the plan's terms (Stripe Prices win over plans typed in setup) and jurisdictions come from the site. With several plans, name one with plan (or send terms). */
+    site?: string;
+    /** With a site: the plan (name or Stripe Price id) to schedule the notices for. An unknown plan is refused with the list of plans. */
+    plan?: string;
     /** Sign-up date of the subscription to plan for (default today). */
     start_date?: string;
     /** A planned price change to schedule the notice for. */
@@ -2746,7 +3300,7 @@ export interface SuggestionGuardrail {
     /** Catalog requirement ids the rule comes from. */
     requirement_ids: Array<string>;
 }
-/** One optional, compliant conversion suggestion. */
+/** One optional conversion suggestion that keeps the checks passing. */
 export interface Suggestion {
     /** Stable id of the suggestion in Checkbox’s library. */
     key: string;
@@ -2768,6 +3322,8 @@ export interface Suggestion {
         label: string;
         /** Your current copy (or a typical example). */
         text: string;
+        /** your_copy: the text is your own copy (captured by Checkbox or sent by you); example: typical copy, not yours (label it “Example”). */
+        source: "your_copy" | "example";
     };
     /** After. */
     after: {
@@ -2803,7 +3359,7 @@ export interface Suggestion {
         verified: boolean;
         /** Checks that did not pass (empty when verified). */
         open_checks: Array<string>;
-        /** The after-example's status roll-up (the same labels as compliance on sites and check results): compliant for every offered suggestion. */
+        /** The after-example's status roll-up (the same labels as compliance on sites and check results): compliant (checks pass) for every offered suggestion. */
         compliance_status: "needs_fix" | "your_call" | "incomplete" | "compliant" | "not_checked";
         /** Its label. */
         compliance_label: string;
@@ -2815,7 +3371,7 @@ export interface Suggestion {
     /** Placeholders you must fill (e.g. {{cancel_url}}). */
     placeholders: Array<string>;
 }
-/** Optional, compliant conversion suggestions for a checkout, Stripe Checkout, lifecycle emails and the cancellation flow. Never a compliance task. */
+/** Optional conversion suggestions that keep the checks passing, for a checkout, Stripe Checkout, lifecycle emails and the cancellation flow. Never a compliance task. */
 export interface SuggestionReport {
     /** Id of this report (sugr_…). Reports are computed on request and not stored. */
     id: string;
@@ -2829,7 +3385,7 @@ export interface SuggestionReport {
     site: string | null;
     /** Always true: suggestions are optional and never block anything. */
     optional: true;
-    /** Always false: suggestions never count for or against compliance, the score or the plan status. */
+    /** Always false: suggestions never count for or against compliance or the plan status. */
     counts_toward_compliance: false;
     /** One paragraph for an LLM or a human. */
     summary: string;
@@ -2853,7 +3409,7 @@ export interface SuggestionReport {
         observed: boolean;
         /** Failing checks that hold it. */
         held_by: Array<string>;
-        /** The status label of those checks ("Needs a fix"), or null. */
+        /** The status label of those checks ("1 fix needed", "2 fixes needed"), or null. */
         held_label: string | null;
         /** Suggestions offered for it. */
         offered: number;
@@ -2881,6 +3437,8 @@ export interface SuggestionReport {
         operation_id?: string;
         /** The MCP tool for operation_id. */
         mcp_tool?: string;
+        /** The HTTP method and path of operation_id. */
+        endpoint?: string;
     };
     /** Not legal advice; optional; results vary. */
     disclaimer: string;
@@ -2890,8 +3448,8 @@ export interface SuggestionsParams {
     terms?: CheckPlanTerms;
     /** Other plans you sell (enables “point to a cheaper plan” and plan-choice suggestions). */
     other_plans?: Array<CheckPlanTerms & {
-        /** Plan name shown to subscribers. */
-        name: string;
+        /** Plan name shown to subscribers (or give plan_name, as in the checks). */
+        name?: string;
     }>;
     /** Where you sell: "all" (default) or state codes ("US-CA", "CA", "US-NY"; "US-FED" is always included). */
     jurisdictions?: "all" | Array<string>;
@@ -2979,6 +3537,10 @@ export interface SuggestionsParams {
     trial_reminders?: boolean;
     /** Your site’s base URL (used in example links). */
     site_url?: string;
+    /** Where subscribers manage their subscription (restart and switch-plan links; never the cancel step). Default: derived from terms.cancel_url. */
+    account_url?: string;
+    /** You ship physical goods (boxes, deliveries): examples talk about the next box instead of access. Default: inferred from your plan names and copy. */
+    sells_goods?: boolean;
 }
 export interface ElementsRelease {
     /** Semver of the bundle. */
@@ -3066,6 +3628,12 @@ export interface DisclosureTerms {
     interval_count?: number;
     /** Free-trial length in days (0 or absent: no trial). */
     trial_days?: number;
+    /** Intro / first-period charge in minor units, stated before the regular price ("$34.50 for your first 2 weeks, then $69.00 every 2 weeks"). Must be below amount. */
+    intro_amount?: number;
+    /** How many billing periods the intro price lasts (default 1). */
+    intro_periods?: number;
+    /** The intro price as a percentage off amount (a coupon's percent_off), instead of intro_amount. Needs amount. */
+    intro_percent_off?: number;
     /** https address where subscribers cancel online. */
     cancel_url?: string;
     /** When a cancellation takes effect (default period_end). */
@@ -3134,7 +3702,7 @@ export interface Consent {
     client_timestamp: number | null;
     /** On-screen measurement summary (null for server-recorded consents). */
     presentation: {
-        /** Guard-rail violations measured on screen. */
+        /** Guard-rail issues measured on screen. */
         violations: Array<string>;
         /** Safe styles replaced the theme. */
         fallback_applied: boolean;
@@ -3225,7 +3793,7 @@ export interface ConsentPresentationInput {
         /** Viewport height (CSS px). */
         height: number;
     } | null;
-    /** Guard-rail violations the element detected. */
+    /** Guard-rail issues the element detected. */
     violations?: Array<string>;
     /** The element replaced the theme with safe styles. */
     fallback_applied?: boolean;
@@ -3480,7 +4048,7 @@ export interface Receipt {
         /** When it was signed (unix seconds). */
         signed: number | null;
     };
-    /** When the receipt is deleted under your retention setting. Unix timestamp in seconds. */
+    /** When the receipt is deleted: consent time plus your retention setting, pushed out to one year after its subscription ends when that is later (Cal. Bus. & Prof. Code § 17602(a)(6)). Unix timestamp in seconds. */
     retain_until: number;
     /** PNG of what the subscriber saw, re-rendered from the snapshot (renderReceipt, same auth). */
     render_url: string;
@@ -3590,7 +4158,7 @@ export interface ReceiptSettings {
     livemode: boolean;
     /** Receipts are collected. Off by default: turn on after adding the receipts paragraph to your privacy policy (browser receipts answer 403 receipts_disabled when off; Elements consents are recorded without a receipt). */
     enabled: boolean;
-    /** Days a receipt is kept (default 1461 = 4 years: the California Unfair Competition Law limitation period; pending attorney review). */
+    /** Days a receipt is kept (default 1461 = 4 years: the California Unfair Competition Law limitation period; adjust to your counsel's advice). */
     retention_days: number;
     /** Last change. Unix timestamp in seconds. */
     updated: number | null;
@@ -3598,7 +4166,7 @@ export interface ReceiptSettings {
 export interface ReceiptSettingsUpdateParams {
     /** Turn receipt collection on or off. */
     enabled?: boolean;
-    /** Days to keep receipts (30–3653). Applies to new receipts. */
+    /** Days to keep receipts (1096–3653, i.e. 3 to 10 years; California requires verification of consent to be kept at least three years, Cal. Bus. & Prof. Code § 17602(a)(6)). Applies to new receipts. */
     retention_days?: number;
 }
 /** A billing-platform TEST-mode key Checkbox uses for synthetic test subscriptions. Stored encrypted; never live mode. */
@@ -3662,6 +4230,10 @@ export interface StripeCheckoutConfig {
     params_hash: string;
     /** Parameters that were dropped because they are not mirrored (customer, URLs, metadata…). */
     ignored_params: Array<string>;
+    /** What Checkbox did not store or judge (ignored_params in words), and on registration which older configs this one replaced. */
+    warnings: Array<string>;
+    /** Registration only: older configs with the same name, or for the same Price ids, that this one replaced (deleted). */
+    replaced?: Array<string>;
     /** Up to 20 key/value string pairs you can attach to the object. */
     metadata: Record<string, string>;
     /** When the config was registered. Unix timestamp in seconds. */
@@ -3693,7 +4265,7 @@ export type TestRunRemediation = {
     summary: string;
     /** Steps to fix it. */
     steps: Array<string>;
-    /** Compliant copy to use, when there is one. */
+    /** Suggested copy that passes the checks, when there is one. */
     suggested_copy: string | null;
     /** Code that applies the fix, when there is one. */
     snippet: {
@@ -3726,8 +4298,8 @@ export interface TestRunStep {
     key: string;
     /** Human-readable step title. */
     title: string;
-    /** passed: observed, with evidence, and every judged check passed (never on an assumption); failed: a check failed or the step broke the run; warning: needs review — could not be fully observed or proven (see code and fix); skipped: not applicable or turned off. */
-    status: "pending" | "running" | "passed" | "failed" | "warning" | "skipped";
+    /** passed: observed, with evidence, and every judged check passed (never on an assumption); failed: a check failed or the step broke the run; warning: needs review — could not be fully observed or proven (see code and fix); skipped: not applicable or turned off; info: informational only (e.g. a bare Stripe-hosted test checkout that is not your checkout): its checks are listed but not counted and need no fix. */
+    status: "pending" | "running" | "passed" | "failed" | "warning" | "skipped" | "info";
     /** What was observed, in one or two sentences. */
     summary: string | null;
     /** When the step started. Unix timestamp in seconds. */
@@ -3770,10 +4342,29 @@ export interface TestRun {
     type: "stripe" | "generic";
     /** Stripe runs: mirror (Checkbox mirrors your checkout into test mode and moves a test clock through trial and renewal) or real_checkout (the shopper buys through YOUR checkout on your test deployment, so your own webhook handlers and email code fire: the proof that your real system works). null for generic runs. */
     mode: "mirror" | "real_checkout" | null;
-    /** succeeded means the run finished (steps may still have failing checks); failed means it stopped early (see failure). */
+    /** succeeded means the run finished and no step failed (steps may still have warnings to review); failed means it stopped early, or finished with a failed step (see failure and steps[].fix). */
     status: "queued" | "running" | "succeeded" | "failed" | "canceled";
+    /** The status in plain words, counting steps: "Finished with 6 warnings to review", "Finished with 1 failed step", "Finished: every observed step passed". succeeded with warnings is not a clean pass. */
+    status_label: string;
     /** Internal phase (prepare, checkout, await_ack, advance, settle, cancel, await_cancel_email, finalize, done). */
     phase: string;
+    /** While the run is queued or running: what it waits for and until when. null once it finished. */
+    waiting_for: {
+        /** What the run is waiting for, in plain words. */
+        what: string;
+        /** When the run stops waiting for it at the latest (null: unknown). Unix timestamp in seconds. */
+        until: number | null;
+        /** Test-clock time the run is at, or moving to (null without a test clock). Unix timestamp in seconds. */
+        clock_time: number | null;
+        /** The step the run is on (1-based), of steps_total steps that will run (skipped steps not counted). */
+        step: number | null;
+        /** Steps that will run. */
+        steps_total: number | null;
+        /** When the whole run is expected to be done, from typical step times (an estimate; a wait that runs long moves it later; null: none). Unix timestamp in seconds. */
+        eta: number | null;
+        /** Whole minutes until eta, from typical step times (null: no estimate). */
+        minutes_left: number | null;
+    } | null;
     /** Always true: runs use the billing platform's test mode; nothing is charged. */
     test_mode: true;
     /** Email address of the synthetic test subscriber; mail sent there is captured as evidence. */
@@ -3798,8 +4389,6 @@ export interface TestRun {
     } | null;
     /** Outcome of a finished run. */
     result: {
-        /** Compliance score (0-100) of the observed steps alone. */
-        score: number | null;
         /** Counts. */
         summary: {
             /** Checks that passed. */
@@ -3844,8 +4433,8 @@ export interface TestRun {
         subscription: string | null;
         /** Mirrored test-mode Checkout Session. */
         checkout_session: string | null;
-        /** Where the checkout configuration came from (mirror mode). */
-        mirrored_from: "registered" | "live" | "request" | "payment_link" | null;
+        /** Where the checkout configuration came from (mirror mode). stripe_session: the newest Checkout Session your code created, read with a test-mode monitoring key. */
+        mirrored_from: "registered" | "live" | "request" | "payment_link" | "stripe_session" | null;
         /** Registered config used (scc_…). */
         checkout_config: string | null;
         /** Compliance fingerprint of the mirrored checkout. */
@@ -3891,8 +4480,10 @@ export interface TestRun {
         cancellation: {
             /** Where the shopper cancelled. */
             via: "merchant_flow" | "stripe_portal" | "cancel_url";
-            /** false: nothing told Checkbox how customers cancel, so it used the Stripe portal (step warning cancel_flow_not_configured). */
+            /** false: nothing told Checkbox how customers cancel, so it used the Stripe portal (step warning cancel_flow_not_configured: the cancel itself worked). true also when inferred (inferred_from). */
             declared_by_merchant: boolean;
+            /** site_portal_link: no cancel_via was given, Stripe has cancellation on in the customer portal and your site links to it, so the portal was used as declared. registered_url: no cancel_via was given and the account or cancellation page you registered (account_url / cancellation_url) redirects or links to the Stripe customer portal, so the portal was used as declared. */
+            inferred_from?: "site_portal_link" | "registered_url" | null;
             /** Stripe showed a subscription set to cancel after the shopper's flow. */
             confirmed_in_stripe: boolean;
             /** The subscription Stripe showed canceled. */
@@ -3965,7 +4556,7 @@ export interface Event {
     id: string;
     /** String representing the object's type. Always "event". */
     object: "event";
-    /** Event type: site.score_changed, finding.created, finding.resolved, scan.completed, scan.failed, law.changed, certificate.issued, certificate.lapsed, certificate.revoked, notice.sent, notice.due, notice.overdue, consent.created, receipt.created, test_run.completed, test_run.failed, plan.updated, site.compliant, task.verified. */
+    /** Event type: site.compliance_changed, finding.created, finding.resolved, scan.completed, scan.failed, law.changed, certificate.issued, certificate.lapsed, certificate.revoked, notice.sent, notice.due, notice.overdue, consent.created, receipt.created, test_run.completed, test_run.failed, plan.updated, site.checks_passed, site.compliant (deprecated), task.verified. */
     type: string;
     /** API version used to render data.object. */
     api_version: string;
@@ -4008,18 +4599,32 @@ export interface Feedback {
     /** String representing the object's type. Always "feedback". */
     object: "feedback";
     /** Kind of feedback. */
-    type: "bug" | "idea" | "question";
+    type: "bug" | "idea" | "question" | "review";
     /** open until Checkbox staff reply or close it. */
     status: "open" | "replied" | "closed";
+    /** true when text that looked like a secret, card number or email address was replaced with [redacted] before it was stored. */
+    redacted: boolean;
     /** When it was received. Unix timestamp in seconds. */
     created: number;
 }
 export interface FeedbackParams {
-    /** bug: something is broken; idea: a missing feature or improvement; question: something unclear. Default idea. */
-    type?: "bug" | "idea" | "question";
-    /** What you tried, what happened and what you expected (at most 5000 characters). */
-    message: string;
-    /** Optional context that helps us reproduce it. */
+    /** bug: something is broken; idea: a missing feature or improvement; question: something unclear; review: a structured review of Checkbox the product (send only after the human said yes and saw the text; no site names, URLs, customer data, quotes of the site's pages or emails, or claims that the site broke a law). Default idea. */
+    type?: "bug" | "idea" | "question" | "review";
+    /** What you tried, what happened and what you expected (at most 5000 characters). Required except for type review. Secrets, card numbers and email addresses are replaced with [redacted]. */
+    message?: string;
+    /** type review (required): how likely the human is to recommend Checkbox, 0-10. */
+    score?: number;
+    /** type review: what worked, at most 5 short phrases. */
+    liked?: Array<string>;
+    /** type review: what did not work, at most 5 short phrases. */
+    disliked?: Array<string>;
+    /** type review: Checkbox verdicts the human believes were wrong, each "<check id>: <short reason about Checkbox's verdict>" (at most 5; the reason is kept to 200 characters). */
+    wrong_verdicts?: Array<string>;
+    /** type review: whether the human would keep using Checkbox. */
+    would_keep_using?: boolean;
+    /** type review: framework and billing, short. */
+    stack?: string;
+    /** Optional context that helps us reproduce it. For type review only agent and tool are kept (reviews never carry the site or request id). */
     context?: {
         /** Site id the feedback is about. */
         site?: string;
@@ -4031,6 +4636,25 @@ export interface FeedbackParams {
         agent?: string;
     };
 }
+/** The one-time prompt to ask the human for a review of the session. */
+export interface ReviewPrompt {
+    /** String representing the object's type. Always "review_prompt". */
+    object: "review_prompt";
+    /** The site. */
+    site: string;
+    /** true exactly once per site, while its plan status is compliant (checks pass): ask the human once whether they want to send a review. false afterwards. */
+    show: boolean;
+    /** Why show is true or false. */
+    reason: "first_time" | "already_shown" | "not_compliant";
+    /** The instruction for the agent when show is true; null otherwise. */
+    message: string | null;
+    /** When the prompt was first shown for this site (null before). Unix timestamp in seconds. */
+    shown_at: number | null;
+}
+export interface ReviewPromptParams {
+    /** What reached "Checks pass": the plan (retrieveCompliancePlan) or the verification of the last required task (verifyTask). Default plan_compliant. */
+    trigger?: "plan_compliant" | "last_task_verified";
+}
 /** A compliance plan without task content (webhook payload). */
 export interface CompliancePlanSummary {
     /** Unique identifier of the compliance plan (plan_…). */
@@ -4043,8 +4667,8 @@ export interface CompliancePlanSummary {
     site: string;
     /** action_required (an agent can apply open tasks now), verifying (changes applied; waiting for confirming observations), compliant (every required check passes or only waits for a live check — an automated assessment, not a legal determination; see compliance.pending_live_checks and coverage), blocked (only human answers ("Your call") or declined critical tasks remain). */
     status: "action_required" | "verifying" | "compliant" | "blocked";
-    /** Compliance score 0-100 of the latest evaluation. */
-    score: number | null;
+    /** The plan status in words to show a person: action_required "Fixes needed", verifying "Checking your changes", compliant "Checks pass", blocked "Your call". Show this, never the machine value (`compliant` is a status name, not a legal conclusion). */
+    status_label?: string;
     /** Two or three sentences for an LLM: where the site stands and what comes next. */
     summary: string;
     /** Tasks per status. */
@@ -4057,7 +4681,7 @@ export interface CompliancePlanSummary {
         verifying: number;
         /** Tasks waiting for a human answer. */
         manual: number;
-        /** Tasks that only wait for a live observation (count as compliant). */
+        /** Tasks that only wait for a live observation (count as passing the checks). */
         pending_live_check?: number;
         /** Done tasks. */
         done: number;
@@ -4065,7 +4689,7 @@ export interface CompliancePlanSummary {
         wont_fix: number;
     };
     next_action: PlanNextAction;
-    /** What the assessment rests on. Tell the human about not_observed and attested items; never call the site "compliant" without them. */
+    /** What the assessment rests on. Tell the human about not_observed and attested items; never tell them the site "is compliant". */
     coverage: {
         /** Lifecycle stages Checkbox observed (signup, acknowledgment_email, reminders, cancellation, policies, billing_settings). */
         observed: Array<string>;
@@ -4139,6 +4763,8 @@ export interface ListSetupSessionsParams {
 export interface UpdateAccountParams {
     /** API version to pin. */
     api_version?: string;
+    retention?: RetentionParams;
+    legal_hold?: LegalHoldParams;
 }
 /** Parameters of `sites.list()` (listSites). */
 export interface ListSitesParams {
@@ -4426,7 +5052,7 @@ export interface CreateTestRunParams {
         cancel_url?: string;
         /** Clicks that cancel in your flow (after login / cancel_url), e.g. [{ "action": "click", "text": "Cancel subscription" }, { "action": "click", "text": "Confirm" }]. */
         cancel_steps?: Array<ScanStep>;
-        /** How your customers cancel. Default: your flow when test_account / cancel_url / cancel_steps describe it, else the Stripe portal reported as a warning (cancel_flow_not_configured). */
+        /** How your customers cancel. Default: your flow when test_account / cancel_url / cancel_steps describe it; else the Stripe portal, taken as declared when Stripe has portal cancellation on and your site links to the portal, or when the account or cancellation page you registered redirects or links to the portal; otherwise reported as a warning (cancel_flow_not_configured: the cancel worked, but how your customers cancel was not given). */
         cancel_via?: "merchant_flow" | "stripe_portal";
         /** A test account the shopper logs into: to buy as a logged-in user (real_checkout) and to cancel through your in-app flow. Mail to its address counts when you BCC the site's Checkbox address. */
         test_account?: {
@@ -4443,9 +5069,9 @@ export interface CreateTestRunParams {
         payment_link?: string;
         /** real_checkout: the page of your TEST deployment that leads to your Stripe test-mode checkout (a pricing page, or a route that creates the Checkout Session and redirects). */
         checkout_url?: string;
-        /** real_checkout: clicks from checkout_url to the payment page, e.g. [{ "action": "click", "text": "Start free trial" }]. */
+        /** real_checkout: clicks from checkout_url to the payment page, e.g. [{ "action": "click", "text": "Start free trial" }]. In fill values, {{email}} is the run inbox and {{password}} is stripe.test_account.password when a test account is given, so an account created here can log in for the cancellation. */
         pre_checkout_steps?: Array<ScanStep>;
-        /** A page of your test deployment Checkbox opens before the checkout (after logging in) that CLEANS UP the test account (ends its subscription), so every run starts without one. Mirror mode opens it before cancelling the test account's subscription. (Round 3: renamed from reset_url, which meant the opposite of the site's test_account.reactivate_url.) */
+        /** A page of your test deployment Checkbox opens before the checkout (after logging in) that CLEANS UP the test account (ends its subscription), so every run starts without one. Mirror mode opens it before cancelling the test account's subscription. */
         cleanup_url?: string;
         /** Deprecated alias of cleanup_url. */
         reset_url?: string;
@@ -4487,11 +5113,16 @@ export interface ListTestRunsParams {
     /** Cursor: an object id; returns the objects before it (newer). */
     ending_before?: string;
 }
+/** Parameters of `testRuns.retrieve()` (retrieveTestRun). */
+export interface RetrieveTestRunParams {
+    /** Long-poll: wait up to this many seconds (0-30) for the run to move on (status, phase or a step changes) before answering. */
+    wait?: number | null;
+}
 /** Parameters of `webhookEndpoints.create()` (createWebhookEndpoint). */
 export interface CreateWebhookEndpointParams {
     /** HTTPS URL. */
     url: string;
-    /** Event types to send, or ["*"] for all: site.score_changed, finding.created, finding.resolved, scan.completed, scan.failed, law.changed, certificate.issued, certificate.lapsed, certificate.revoked, notice.sent, notice.due, notice.overdue, consent.created, receipt.created, test_run.completed, test_run.failed, plan.updated, site.compliant, task.verified. */
+    /** Event types to send, or ["*"] for all: site.compliance_changed, finding.created, finding.resolved, scan.completed, scan.failed, law.changed, certificate.issued, certificate.lapsed, certificate.revoked, notice.sent, notice.due, notice.overdue, consent.created, receipt.created, test_run.completed, test_run.failed, plan.updated, site.checks_passed, site.compliant (deprecated), task.verified. */
     enabled_events: Array<string>;
     /** Description. */
     description?: string;
@@ -4511,7 +5142,7 @@ export interface ListWebhookEndpointsParams {
 export interface UpdateWebhookEndpointParams {
     /** HTTPS URL. */
     url?: string;
-    /** Event types to send, or ["*"] for all: site.score_changed, finding.created, finding.resolved, scan.completed, scan.failed, law.changed, certificate.issued, certificate.lapsed, certificate.revoked, notice.sent, notice.due, notice.overdue, consent.created, receipt.created, test_run.completed, test_run.failed, plan.updated, site.compliant, task.verified. */
+    /** Event types to send, or ["*"] for all: site.compliance_changed, finding.created, finding.resolved, scan.completed, scan.failed, law.changed, certificate.issued, certificate.lapsed, certificate.revoked, notice.sent, notice.due, notice.overdue, consent.created, receipt.created, test_run.completed, test_run.failed, plan.updated, site.checks_passed, site.compliant (deprecated), task.verified. */
     enabled_events?: Array<string>;
     /** Description (null clears it). */
     description?: string | null;
@@ -4543,7 +5174,7 @@ export type PlanUpdatedEvent = Event & {
     type?: "plan.updated";
     data?: {
         object: CompliancePlanSummary;
-        /** plan.updated: the previous status and score. */
+        /** plan.updated: the previous status. */
         previous_attributes?: Record<string, unknown>;
     };
 };
@@ -4553,7 +5184,7 @@ export type TaskVerifiedEvent = Event & {
     type?: "task.verified";
     data?: {
         object: Verification;
-        /** plan.updated: the previous status and score. */
+        /** plan.updated: the previous status. */
         previous_attributes?: Record<string, unknown>;
     };
 };
@@ -4607,10 +5238,10 @@ export type TestRunFailedEvent = Event & {
         previous_attributes?: Record<string, unknown>;
     };
 };
-/** `site.score_changed`: A site's compliance score changed (data.previous_attributes.score has the old score). */
-export type SiteScoreChangedEvent = Event & {
+/** `site.compliance_changed`: A re-evaluation changed the site's check results; data.object is the site, with its current compliance status and label in data.object.compliance. */
+export type SiteComplianceChangedEvent = Event & {
     /** Event type. */
-    type?: "site.score_changed";
+    type?: "site.compliance_changed";
     data?: {
         object: Site;
         /** Previous values of changed fields. */
@@ -4637,7 +5268,7 @@ export type FindingResolvedEvent = Event & {
         previous_attributes?: Record<string, unknown>;
     };
 };
-/** `scan.completed`: A scan finished (the evaluation may follow in a separate site.score_changed event). */
+/** `scan.completed`: A scan finished (the evaluation may follow in a separate site.compliance_changed event). */
 export type ScanCompletedEvent = Event & {
     /** Event type. */
     type?: "scan.completed";
@@ -4717,7 +5348,17 @@ export type ConsentCreatedEvent = Event & {
         previous_attributes?: Record<string, unknown>;
     };
 };
-/** `site.compliant`: A site's compliance plan became compliant: nothing is left to apply, verify or answer; data.object is the site. */
+/** `site.checks_passed`: A site's compliance plan reached the status where its checks pass (plan status value `compliant`): nothing is left to apply, verify or answer; data.object is the site. Passing the checks is not a certification of legal compliance. */
+export type SiteChecksPassedEvent = Event & {
+    /** Event type. */
+    type?: "site.checks_passed";
+    data?: {
+        object: Site;
+        /** Previous values of changed fields. */
+        previous_attributes?: Record<string, unknown>;
+    };
+};
+/** `site.compliant`: Deprecated alias of site.checks_passed, kept so existing endpoints keep working: sent at the same moment with the same data.object. Subscribe to site.checks_passed instead (an endpoint on "*" receives both). */
 export type SiteCompliantEvent = Event & {
     /** Event type. */
     type?: "site.compliant";
@@ -4728,9 +5369,9 @@ export type SiteCompliantEvent = Event & {
     };
 };
 /** Every event Checkbox delivers to webhook endpoints, discriminated by `type`. */
-export type WebhookEvent = PlanUpdatedEvent | TaskVerifiedEvent | NoticeDueEvent | NoticeOverdueEvent | ReceiptCreatedEvent | TestRunCompletedEvent | TestRunFailedEvent | SiteScoreChangedEvent | FindingCreatedEvent | FindingResolvedEvent | ScanCompletedEvent | ScanFailedEvent | LawChangedEvent | CertificateIssuedEvent | CertificateLapsedEvent | CertificateRevokedEvent | NoticeSentEvent | ConsentCreatedEvent | SiteCompliantEvent;
+export type WebhookEvent = PlanUpdatedEvent | TaskVerifiedEvent | NoticeDueEvent | NoticeOverdueEvent | ReceiptCreatedEvent | TestRunCompletedEvent | TestRunFailedEvent | SiteComplianceChangedEvent | FindingCreatedEvent | FindingResolvedEvent | ScanCompletedEvent | ScanFailedEvent | LawChangedEvent | CertificateIssuedEvent | CertificateLapsedEvent | CertificateRevokedEvent | NoticeSentEvent | ConsentCreatedEvent | SiteChecksPassedEvent | SiteCompliantEvent;
 /** Every webhook event type. */
-export declare const WEBHOOK_EVENT_TYPES: readonly ["plan.updated", "task.verified", "notice.due", "notice.overdue", "receipt.created", "test_run.completed", "test_run.failed", "site.score_changed", "finding.created", "finding.resolved", "scan.completed", "scan.failed", "law.changed", "certificate.issued", "certificate.lapsed", "certificate.revoked", "notice.sent", "consent.created", "site.compliant"];
+export declare const WEBHOOK_EVENT_TYPES: readonly ["plan.updated", "task.verified", "notice.due", "notice.overdue", "receipt.created", "test_run.completed", "test_run.failed", "site.compliance_changed", "finding.created", "finding.resolved", "scan.completed", "scan.failed", "law.changed", "certificate.issued", "certificate.lapsed", "certificate.revoked", "notice.sent", "consent.created", "site.checks_passed", "site.compliant"];
 export type WebhookEventType = (typeof WEBHOOK_EVENT_TYPES)[number];
 /** Stable error codes (`error.code`), with HTTP status, type and meaning. Codes are never renamed. */
 export declare const ERROR_CODES: {
@@ -4777,7 +5418,7 @@ export declare const ERROR_CODES: {
     readonly test_key_missing: {
         readonly status: 400;
         readonly type: "invalid_request_error";
-        readonly description: "A Stripe test run needs a Stripe TEST-mode key stored for the site (createTestCredential).";
+        readonly description: "A Stripe test run needs a Stripe TEST-mode key stored for the site (a person adds it in the dashboard on the site's Proof page).";
     };
     readonly test_key_not_test_mode: {
         readonly status: 400;
@@ -4857,7 +5498,7 @@ export declare const ERROR_CODES: {
     readonly test_mode_scan_budget_exhausted: {
         readonly status: 429;
         readonly type: "rate_limit_error";
-        readonly description: "No longer returned (round 6): test mode has no scan budget for unverified domains any more, they are refused with test_mode_domain_unverified. Kept so older clients still recognise the code.";
+        readonly description: "No longer returned: test mode has no scan budget for unverified domains any more, they are refused with test_mode_domain_unverified. Kept so older clients still recognise the code.";
     };
     readonly domain_not_verified: {
         readonly status: 403;
@@ -4899,16 +5540,36 @@ export declare const ERROR_CODES: {
         readonly type: "invalid_request_error";
         readonly description: "The site already has a queued or running test run; wait for it (retrieveTestRun) or cancel it (cancelTestRun).";
     };
+    readonly legal_hold_active: {
+        readonly status: 409;
+        readonly type: "invalid_request_error";
+        readonly description: "A legal hold is on for the account or the site: deleting data and shortening retention are refused until it is turned off (updateAccount / updateSite legal_hold).";
+    };
     readonly idempotency_key_in_use: {
         readonly status: 409;
         readonly type: "idempotency_error";
         readonly description: "A request with this Idempotency-Key is still being processed; retry shortly.";
     };
+    readonly shopify_not_connected: {
+        readonly status: 409;
+        readonly type: "invalid_request_error";
+        readonly description: "The site's Shopify store is not connected through the Checkbox Shopify app, so Checkbox cannot publish to the app block. Only the merchant can connect it: install the Checkbox app from the Shopify admin and click \"Connect to Checkbox\" (`next_action` has the exact step).";
+    };
     readonly resource_archived: {
         readonly status: 410;
         readonly type: "invalid_request_error";
         readonly description: "The object is archived; restore it before changing it.";
     };
+    readonly terms_incomplete: {
+        readonly status: 422;
+        readonly type: "invalid_request_error";
+        readonly description: "Checkbox cannot write the exact, verified renewal terms yet: plan facts are missing (price, interval, trial, cancellation URL or merchant name). `problems` lists them; `next_action` names the call that sets them.";
+    };
+    readonly fix_verification_failed: {
+        readonly status: 422;
+        readonly type: "invalid_request_error";
+        readonly description: "The generated disclosure did not pass every sign-up check of the rules engine, so nothing was published. The message names the failing checks.";
+    };
     readonly body_too_large: {
         readonly status: 413;
         readonly type: "invalid_request_error";
@@ -4944,6 +5605,11 @@ export declare const ERROR_CODES: {
         readonly type: "permission_error";
         readonly description: "Consent receipts are turned off for this account (updateReceiptSettings enabled=true turns them on).";
     };
+    readonly platform_error: {
+        readonly status: 502;
+        readonly type: "api_error";
+        readonly description: "The merchant's platform (e.g. Shopify) refused or failed the change; nothing was recorded as applied. Retry later; `message` has the platform's answer.";
+    };
     readonly feature_unavailable: {
         readonly status: 503;
         readonly type: "api_error";