@checkbox-site/node 0.1.0 → 0.1.1

package/dist/generated/types.d.ts

@@ -96,6 +96,8 @@ 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). */
+    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. */
@@ -292,8 +294,6 @@ export interface SetupSession {
     compliance: {
         /** 0-100. */
         score: number;
-        /** No critical/high failure open. */
-        insurable: boolean;
         /** When it was evaluated. Unix timestamp in seconds. */
         evaluated: number;
         /** Open failing findings. */
@@ -487,8 +487,6 @@ export interface Account {
     billing: {
         /** Checkbox is free to use. */
         plan: "free";
-        /** The compliance warranty is not offered yet (waitlist only; no coverage). */
-        warranty: "coming_soon";
     };
     /** When the account was created. Unix timestamp in seconds. */
     created: number;
@@ -510,6 +508,8 @@ export interface SiteFacts {
     notice_channel_email?: boolean;
     /** Price increases need consent or allow a refund (NY). */
     price_increase_consent_or_refund?: boolean;
+    /** The billing-platform price this checkout sells (e.g. a Stripe price id). Terms copy and the price cross-check use only this price; without it, a connected price never rewrites Terms copy or reopens a verified task. */
+    plan_price_id?: string;
     /** Accepted payment methods (debit / ACH bring in Reg E). */
     payment_methods?: Array<"card" | "debit" | "ach" | "wallet" | "other">;
 }
@@ -528,18 +528,65 @@ export interface SiteMonitoring {
     /** Domains to verify before Checkbox scans the site (first: createDomainVerification for the site's own domain). */
     verify_domains: Array<string>;
 }
+/** A live check Checkbox has not observed yet, and how it completes. */
+export interface PendingLiveCheck {
+    /** What has not been observed yet. */
+    what: string;
+    /** When / how it completes. */
+    completes: string;
+    /** How it completes: run_proof, bcc_real_sends, wait_for_event, connect_billing, resync_billing, scan, check_rendered_page, register_checkout, publish_policy. */
+    action: "run_proof" | "bcc_real_sends" | "wait_for_event" | "connect_billing" | "resync_billing" | "scan" | "check_rendered_page" | "register_checkout" | "publish_policy";
+    /** ISO date when it completes on its own (a reminder window), when known. */
+    due: string | null;
+}
+/** 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). */
+    status: "needs_fix" | "your_call" | "incomplete" | "compliant" | "not_checked";
+    /** Label to show. */
+    label: string;
+    /** Required checks per user-facing status. */
+    counts: {
+        /** Required checks that need a fix. */
+        needs_fix: number;
+        /** Decisions for a person. */
+        your_call: number;
+        /** Compliant, live check pending. */
+        pending_live_check: number;
+        /** Verified live. */
+        verified_live: number;
+        /** Compliant. */
+        compliant: number;
+        /** Not applicable. */
+        not_applicable: number;
+        /** Not set up yet (no sign the email or setting exists). */
+        not_set_up: number;
+        /** Not checked yet (Checkbox has not tried it). */
+        not_checked: number;
+    };
+    /** What each pending live check waits for and how it completes. */
+    pending_live_checks: Array<PendingLiveCheck & {
+        /** Check id. */
+        check_id: string;
+    }>;
+    /** Recommended / extra items open (never block compliant). */
+    suggestions: number;
+}
 /** Latest verdict; null until the first evaluation. */
 export type SiteCompliance = {
     /** Compliance score 0-100 (one decimal place). */
     score: number;
-    /** No critical/high obligation failing or unverified. */
-    insurable: boolean;
     /** 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). */
+    status: "needs_fix" | "your_call" | "incomplete" | "compliant" | "not_checked";
+    /** Label to show. */
+    label: string;
+    rollup: ComplianceRollup;
 } | null;
 /** What to install on the merchant site. */
 export interface SiteInstall {
@@ -576,8 +623,6 @@ export interface Scan {
     evaluation: string | null;
     /** Score of that evaluation (0-100, one decimal place). */
     score: number | null;
-    /** Insurable flag of that evaluation. */
-    insurable: boolean | null;
     /** When the scan started. Unix timestamp in seconds. */
     started: number | null;
     /** When the scan finished. Unix timestamp in seconds. */
@@ -681,8 +726,12 @@ export interface Site {
         account_url: string | null;
         /** Terms of service page read on every scan. */
         terms_url: string | null;
+        /** 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;
     };
     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";
     compliance: SiteCompliance;
     install: SiteInstall;
     /** Archived (soft-deleted); evidence is retained. */
@@ -755,7 +804,9 @@ 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 run starts subscribed. Without it, a run after a completed cancellation reports "already cancelled by an earlier scan" (needs review). */
+    /** 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.) */
+    reactivate_url?: string;
+    /** Deprecated alias of reactivate_url. */
     reset_url?: string;
 }
 export interface CreateSiteParams {
@@ -786,6 +837,8 @@ 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. */
+    protection_level?: "minimum" | "balanced" | "maximum";
 }
 export interface UpdateSiteParams {
     /** Display name. */
@@ -815,6 +868,8 @@ 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. */
+    protection_level?: "minimum" | "balanced" | "maximum";
 }
 /** A billing-platform connection of a site. */
 export interface Integration {
@@ -862,6 +917,8 @@ 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). */
+    compliance_status: "needs_fix" | "pending_live_check" | "verified_live" | "your_call" | "compliant" | "not_applicable" | "not_set_up" | "not_checked";
 }
 /** A compliance verdict for a site at a point in time. */
 export interface Evaluation {
@@ -877,8 +934,6 @@ export interface Evaluation {
     scan: string;
     /** Compliance score 0-100 (severity-weighted, one decimal place, e.g. 82.5). */
     score: number;
-    /** No critical/high check failing, no critical check undecided, no high check without evidence. */
-    insurable: boolean;
     /** Legal catalog / rules version used. */
     rules_version: string;
     /** When it was evaluated. Unix timestamp in seconds. */
@@ -896,8 +951,9 @@ export interface Evaluation {
         /** Checks that do not apply. */
         not_applicable: number;
     };
-    /** Checks that keep the site from being insurable. */
+    /** Blocking checks: critical or high-severity checks that fail, are undecided (critical) or lack evidence (high). */
     blockers: Array<CheckSummary>;
+    compliance: ComplianceRollup;
     /** Every check evaluated. */
     checks: Array<CheckSummary>;
 }
@@ -943,6 +999,78 @@ export type Remediation = {
         code: string;
     } | null;
 } | null;
+/** One piece of evidence a verdict relied on. */
+export interface EvidenceItem {
+    /** What kind of evidence: a captured page, an email, a billing-platform setting, a lifecycle event, a fetched policy document, a test cancellation, or the request input (preflight). */
+    source: "page" | "email" | "billing" | "event" | "policy" | "flow" | "input";
+    /** Id of the capture / email / event / evidence record. */
+    ref?: string;
+    /** Page URL. */
+    url?: string;
+    /** The exact text the verdict relied on. */
+    quote?: string;
+    /** The element on the page (CSS selector). */
+    selector?: string;
+    /** Where the element was, in page coordinates (the crop of the screenshot). */
+    rect?: {
+        /** Left edge (px). */
+        x: number;
+        /** Top edge (px, from the top of the page). */
+        y: number;
+        /** Width (px). */
+        width: number;
+        /** Height (px). */
+        height: number;
+    };
+    /** Billing-platform field the verdict read. */
+    field?: string;
+    /** Value of that field. */
+    value?: unknown;
+    /** Where it was seen (region and device, email subject, …). */
+    label?: string;
+    /** This item’s own outcome when the check judged several. */
+    status?: "pass" | "fail" | "needs_review" | "not_applicable";
+    /** What the check concluded from this item. */
+    detail?: string;
+    /** Evidence id of the page screenshot. */
+    screenshot_ref?: string;
+    /** When it was captured / received. */
+    at?: string;
+}
+/** What a verdict was based on. Never a pass without it; needs_review says what is missing. */
+export interface VerdictEvidence {
+    /** What the verdict rests on, in one line. */
+    summary: string;
+    /** The exact texts, elements, emails, settings and events relied on (failing / unclear first). */
+    items: Array<EvidenceItem>;
+    /** For needs_review: the missing piece that would decide it. */
+    missing?: string;
+}
+/** 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). */
+    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: 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). */
+    tier: "required" | "recommended" | "extra";
+    /** needs_fix: the one change that fixes it. */
+    fix: string | null;
+    /** A short note (grey area, stylistic suggestion). */
+    note: string | null;
+    pending_live_check: PendingLiveCheck | null;
+    /** your_call: the question. */
+    question: {
+        /** One plain-language question. */
+        text: string;
+        /** The answer Checkbox recommends. */
+        recommended: string;
+        /** Why a person has to decide. */
+        why: string;
+    } | null;
+}
 /** The latest result of one legal check for a site. */
 export interface Finding {
     /** Unique identifier of the finding (fnd_…). */
@@ -980,6 +1108,10 @@ export interface Finding {
     evidence_refs: Array<string>;
     /** 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). */
+    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. */
     scan: string | null;
     /** First time the check was evaluated. Unix timestamp in seconds. */
@@ -1060,10 +1192,14 @@ 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). */
-    status: "open" | "in_progress" | "verifying" | "done" | "wont_fix" | "manual";
+    /** 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). */
+    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. */
+    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). */
+    compliance_status?: "needs_fix" | "pending_live_check" | "verified_live" | "your_call" | "compliant" | "not_applicable" | "not_set_up" | "not_checked";
     /** Position in the plan (1 = do first). Dependency-aware. */
     order: number;
     /** Legal checks this task makes pass. */
@@ -1173,6 +1309,8 @@ export interface Task {
         created: 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;
     /** When the task first appeared. Unix timestamp in seconds. */
     first_seen: number;
     /** When it was done. Unix timestamp in seconds. */
@@ -1188,12 +1326,10 @@ export interface CompliancePlan {
     livemode: boolean;
     /** The site. */
     site: string;
-    /** action_required (an agent can apply open tasks now), verifying (changes applied; waiting for confirming observations), compliant (every applicable check Checkbox could observe passes — an automated assessment, not a legal determination; see coverage for what was not observed), blocked (only human answers or declined critical tasks remain). */
+    /** 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;
-    /** Preview flag the planned Checkbox Warranty will key on (no checks failing at high severity). No warranty or insurance is offered yet; this is not an underwriting decision. */
-    insurable: boolean | null;
     /** The evaluation the plan was built from (null before the first check). */
     evaluation: string | null;
     /** When that evaluation ran. Unix timestamp in seconds. */
@@ -1210,6 +1346,8 @@ export interface CompliancePlan {
         verifying: number;
         /** Tasks waiting for a human answer. */
         manual: number;
+        /** Tasks that only wait for a live observation (count as compliant). */
+        pending_live_check?: number;
         /** Done tasks. */
         done: number;
         /** Declined tasks. */
@@ -1217,6 +1355,18 @@ export interface CompliancePlan {
     };
     /** Tasks in the order to do them (done tasks last). */
     tasks: Array<Task>;
+    /** The site's protection level: minimum lists required tasks only; balanced adds recommended suggestions; maximum adds extras. Only required tasks change the plan status. */
+    protection_level: "minimum" | "balanced" | "maximum";
+    /** Task ids grouped by tier, in plan order. */
+    groups: {
+        /** Required tasks (the legal floor). */
+        required: Array<string>;
+        /** Recommended suggestions (never block compliant). */
+        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. */
     coverage: {
         /** Lifecycle stages Checkbox observed (signup, acknowledgment_email, reminders, cancellation, policies, billing_settings). */
@@ -1229,12 +1379,43 @@ export interface CompliancePlan {
         billing_connected: boolean;
     };
     next_action: PlanNextAction;
+    /** Evidence level per required email kind. A plan is never 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). */
+        verification_level: "not_seen" | "template_checked" | "delivery_seen";
+        /** Why this level, in plain words. */
+        reason: string;
+        /** The email the level rests on (the delivered one, else the newest). */
+        email: string | null;
+        /** delivery_seen only: the real event the email came from. */
+        basis: "test_run" | "synthetic_signup" | "checkbox_sent" | "notice_due" | "billing_event" | null;
+    }>;
     /** Rules / catalog version of the evaluation. */
     rules_version: string | null;
     /** Automated assessment; not legal advice. */
     disclaimer: string;
     /** When the plan was computed. Unix timestamp in seconds. */
     generated: number;
+    /** Optional improvements beyond compliance. Never tasks, never blocking, never counted toward compliance. */
+    optional_improvements?: {
+        /** Compliant conversion suggestions for this site. */
+        conversion_suggestions: {
+            /** What they are. */
+            description: string;
+            /** Always false. */
+            blocking: false;
+            /** Always false: they never change status, score or tasks. */
+            counts_toward_compliance: false;
+            /** Operation that lists them. */
+            operation_id: string;
+            /** MCP tool that lists them. */
+            mcp_tool: string;
+            /** HTTP endpoint. */
+            endpoint: string;
+        };
+    };
 }
 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. */
@@ -1275,8 +1456,8 @@ 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), failed (it did not: see diff). */
-    status: "pending" | "passed" | "failed";
+    /** 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";
     /** How it was re-checked. */
     method: "page_fetch" | "policy_refetch" | "stripe_params" | "email_copy" | "platform_sync" | "attestation" | "evaluation" | "test_run";
     /** The fast pre-check run immediately (seconds). A failing pre-check fails the verification at once. */
@@ -1311,6 +1492,8 @@ export interface VerifyTaskParams {
     html?: string;
     /** stripe_params tasks: exactly what your code now passes to stripe.checkout.sessions.create. */
     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?: {
         /** Email kind (default: from the task). */
@@ -1457,7 +1640,7 @@ export interface EvidenceChainVerification {
     /** Current chain head hash. */
     head: string | null;
 }
-/** A signed monitoring certificate: the site met every critical and high obligation for the required streak of days. It is not insurance. */
+/** A signed monitoring certificate: for the required streak of days the site passed the checks Checkbox ran for every critical and high obligation (emails count only when seen sent for a real event, never on templates alone). It records what was monitored and when; it is not legal advice and not a legal opinion that the site is compliant. */
 export interface Certificate {
     /** Unique identifier of the certificate (cert_…). */
     id: string;
@@ -1467,13 +1650,13 @@ export interface Certificate {
     livemode: boolean;
     /** Certified site. */
     site: string;
-    /** active while monitoring keeps the site insurable; lapses automatically otherwise. */
+    /** active while monitoring keeps passing the checks Checkbox runs (no critical or high obligation failing or unproven); lapses automatically otherwise. */
     status: "active" | "lapsed" | "revoked" | "superseded";
     /** Verified domain frozen into the certificate. */
     domain: string;
     /** Issue time. Unix timestamp in seconds. */
     issued: number;
-    /** Expiry (renewed automatically while compliant). Unix timestamp in seconds. */
+    /** Expiry (renewed automatically while the site keeps passing the checks Checkbox runs). Unix timestamp in seconds. */
     valid_until: number;
     /** Last renewal. Unix timestamp in seconds. */
     renewed: number | null;
@@ -1483,7 +1666,7 @@ export interface Certificate {
     public_reason: string | null;
     /** Public verification page. */
     verify_url: string;
-    /** Trust badge for the merchant site. */
+    /** Monitoring badge for the merchant site: it links to the verification page, which says what was checked and when. It does not say the site is legally compliant. */
     badge: {
         /** Badge image. */
         svg_url: string;
@@ -1519,7 +1702,7 @@ export interface NoticeSettings {
     /** The site's inbound address. Copies to it confirm a notice only when your sending domain authenticates them (DKIM/SPF, a trusted sending domain) and they go to the subscriber; to confirm any copy, BCC each due notice's own bcc address instead (listDueNotices / the notice.due webhook). */
     bcc: string;
     /** mode checkbox: the notices Checkbox sends for the merchant. */
-    enabled_kinds: Array<"acknowledgment" | "trial_ending" | "renewal_reminder" | "annual_terms" | "price_change">;
+    enabled_kinds: Array<"acknowledgment" | "trial_ending" | "renewal_reminder" | "annual_terms" | "price_change" | "cancellation_confirmation" | "charge_notice">;
     /** Brand shown in notices (defaults to the site name). */
     brand_name: string | null;
     /** Product name used in notices. */
@@ -1534,6 +1717,13 @@ export interface NoticeSettings {
     brand_color: string | null;
     /** Mailbox name of the sender. */
     from_local_part: string;
+    /** Who Checkbox can send notices to (null when unknown). */
+    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). */
+        with_email: number;
+    } | null;
     /** Confirmed cancellation policy (required before notices go out). */
     policy: {
         /** When a cancellation takes effect. */
@@ -1560,7 +1750,7 @@ export interface NoticeSettings {
     /** Every notice kind. */
     kinds: Array<{
         /** Notice kind. */
-        kind: "acknowledgment" | "trial_ending" | "renewal_reminder" | "annual_terms" | "price_change";
+        kind: "acknowledgment" | "trial_ending" | "renewal_reminder" | "annual_terms" | "price_change" | "cancellation_confirmation" | "charge_notice";
         /** Label. */
         label: string;
         /** What it is and when it is sent. */
@@ -1578,7 +1768,7 @@ 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. */
-    enabled_kinds?: Array<"acknowledgment" | "trial_ending" | "renewal_reminder" | "annual_terms" | "price_change" | "trial_reminder">;
+    enabled_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. */
@@ -1922,6 +2112,10 @@ export interface CheckVerdict {
     fix?: string;
     /** 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). */
+    compliance_status: "needs_fix" | "pending_live_check" | "verified_live" | "your_call" | "compliant" | "not_applicable" | "not_set_up" | "not_checked";
+    compliance: ComplianceInfo;
 }
 /** Verdict per legal requirement. */
 export type CheckRequirementVerdict = CheckRequirementRef & {
@@ -2002,6 +2196,9 @@ 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. */
+    compliance_status: "needs_fix" | "your_call" | "incomplete" | "compliant" | "not_checked";
+    compliance: ComplianceRollup;
     replacement: CheckReplacement;
 }
 /** A checkout disclosure to check before it ships. */
@@ -2118,6 +2315,9 @@ 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. */
+    compliance_status: "needs_fix" | "your_call" | "incomplete" | "compliant" | "not_checked";
+    compliance: ComplianceRollup;
     /** The fix. */
     correction: {
         /** JSON Patch turning params into corrected_params (empty: nothing to change). */
@@ -2223,6 +2423,9 @@ 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. */
+    compliance_status: "needs_fix" | "your_call" | "incomplete" | "compliant" | "not_checked";
+    compliance: ComplianceRollup;
     /** The fix. */
     correction: {
         /** JSON Patch turning params into corrected_params (empty: nothing to change). */
@@ -2299,8 +2502,13 @@ 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. */
+    compliance_status: "needs_fix" | "your_call" | "incomplete" | "compliant" | "not_checked";
+    compliance: ComplianceRollup;
     /** The email kind checked. */
     email_kind: 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. */
@@ -2389,6 +2597,9 @@ 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. */
+    compliance_status: "needs_fix" | "your_call" | "incomplete" | "compliant" | "not_checked";
+    compliance: ComplianceRollup;
     /** Whether html was given or fetched from url. */
     source: "html" | "url";
     /** What was read from the page. */
@@ -2439,7 +2650,7 @@ export interface PageCheckParams {
 /** One notice to send. */
 export interface ScheduledNotice {
     /** Notice kind. */
-    kind: "acknowledgment" | "trial_ending" | "renewal_reminder" | "annual_terms" | "price_change";
+    kind: "acknowledgment" | "trial_ending" | "renewal_reminder" | "annual_terms" | "price_change" | "cancellation_confirmation" | "charge_notice";
     /** What the notice announces. */
     occasion: string;
     /** Date of the event (YYYY-MM-DD, UTC). */
@@ -2519,6 +2730,256 @@ export interface NoticeScheduleParams {
     /** Evaluate the law as of this date (YYYY-MM-DD, default today). */
     as_of?: string;
 }
+/** RFC 6902 operation. */
+export interface SuggestionPatchOp {
+    /** JSON Patch operation. */
+    op: "add" | "replace" | "remove";
+    /** JSON Pointer. */
+    path: string;
+    /** Value. */
+    value?: unknown;
+}
+/** A legal guardrail the suggestion respects. */
+export interface SuggestionGuardrail {
+    /** What the change must respect, in plain words. */
+    rule: string;
+    /** Catalog requirement ids the rule comes from. */
+    requirement_ids: Array<string>;
+}
+/** One optional, compliant conversion suggestion. */
+export interface Suggestion {
+    /** Stable id of the suggestion in Checkbox’s library. */
+    key: string;
+    /** String representing the object's type. Always "suggestion". */
+    object: "suggestion";
+    /** Where it applies. */
+    surface: "checkout_page" | "stripe_checkout" | "acknowledgment_email" | "trial_reminder_email" | "renewal_reminder_email" | "price_change_email" | "cancellation_flow" | "cancellation_confirmation_email";
+    /** What to change. */
+    title: string;
+    /** Why it commonly helps conversion or retention (no invented figures). */
+    why: string;
+    /** detected: your observed copy lacks it; recommended: the surface was not observed but it fits your plan. */
+    match: "detected" | "recommended";
+    /** Why it applies to you. */
+    reason: string;
+    /** Before. */
+    before: {
+        /** What is shown. */
+        label: string;
+        /** Your current copy (or a typical example). */
+        text: string;
+    };
+    /** After. */
+    after: {
+        /** What is shown. */
+        label: string;
+        /** The improved copy, from your plan terms. */
+        text: string;
+    };
+    /** How to apply it. */
+    apply: {
+        /** Kind of change. */
+        type: "replace_text" | "insert_text" | "replace_email" | "stripe_params" | "flow_change" | "settings";
+        /** Where to make it. */
+        where: string;
+        /** The exact copy / markup / JSON to apply. */
+        content: string;
+        /** stripe_params: RFC 6902 patch for the params your code passes to Stripe. */
+        json_patch?: Array<SuggestionPatchOp>;
+        /** One or two sentences an agent can follow literally. */
+        instructions: string;
+    };
+    /** What must be true before you use it (never claim it otherwise). */
+    preconditions: Array<string>;
+    /** Legal guardrails (catalog ids) the change must respect. */
+    guardrails: Array<SuggestionGuardrail>;
+    /** The engine check of the after-example (only verified suggestions are offered). */
+    verification: {
+        /** The check the after-example was run through. */
+        operation_id: "checkDisclosure" | "checkStripeCheckoutSession" | "checkEmail" | "cancellation_flow_model";
+        /** Verdict of that check. */
+        verdict: "pass" | "fail" | "needs_review" | "not_applicable";
+        /** Nothing fails and nothing new needs review. */
+        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. */
+        compliance_status: "needs_fix" | "your_call" | "incomplete" | "compliant" | "not_checked";
+        /** Its label. */
+        compliance_label: string;
+        /** Jurisdictions checked. */
+        jurisdictions: "all" | Array<string>;
+        /** How it was checked. */
+        note: string;
+    } | null;
+    /** 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. */
+export interface SuggestionReport {
+    /** Id of this report (sugr_…). Reports are computed on request and not stored. */
+    id: string;
+    /** String representing the object's type. Always "suggestion_report". */
+    object: "suggestion_report";
+    /** true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox). */
+    livemode: boolean;
+    /** When it was computed. Unix seconds. */
+    created: number;
+    /** The site (GET /v1/sites/:site/suggestions), or null for POST /v1/suggestions. */
+    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. */
+    counts_toward_compliance: false;
+    /** One paragraph for an LLM or a human. */
+    summary: string;
+    /** Jurisdictions the examples were checked for. */
+    jurisdictions: "all" | Array<string>;
+    /** Date the law was evaluated at. */
+    as_of: string;
+    /** Version of the suggestion library. */
+    library_version: string;
+    /** Rules engine version. */
+    rules_version: string;
+    /** Legal catalog version. */
+    catalog_version: string;
+    /** Per surface. */
+    surfaces: Array<{
+        /** Surface. */
+        surface: "checkout_page" | "stripe_checkout" | "acknowledgment_email" | "trial_reminder_email" | "renewal_reminder_email" | "price_change_email" | "cancellation_flow" | "cancellation_confirmation_email";
+        /** offered; held (a compliance check on it fails: fix that first); none (nothing to suggest). */
+        status: "offered" | "held" | "none";
+        /** Checkbox saw this surface (or you sent it). */
+        observed: boolean;
+        /** Failing checks that hold it. */
+        held_by: Array<string>;
+        /** The status label of those checks ("Needs a fix"), or null. */
+        held_label: string | null;
+        /** Suggestions offered for it. */
+        offered: number;
+    }>;
+    /** Offered suggestions: detected gaps in your own copy first. */
+    suggestions: Array<Suggestion>;
+    /** Suggestions that would apply but are withheld, and why. */
+    withheld: Array<{
+        /** Suggestion key. */
+        key: string;
+        /** Surface. */
+        surface: "checkout_page" | "stripe_checkout" | "acknowledgment_email" | "trial_reminder_email" | "renewal_reminder_email" | "price_change_email" | "cancellation_flow" | "cancellation_confirmation_email";
+        /** Title. */
+        title: string;
+        /** Why it is not offered to you (a guardrail, a failing check, or an untrue precondition). */
+        reason: string;
+    }>;
+    /** Next step. */
+    next_action: {
+        /** What to do next. */
+        type: "apply_suggestion" | "fix_compliance_first" | "none";
+        /** One or two sentences for an agent. */
+        message: string;
+        /** The operation to call next, when there is one. */
+        operation_id?: string;
+        /** The MCP tool for operation_id. */
+        mcp_tool?: string;
+    };
+    /** Not legal advice; optional; results vary. */
+    disclaimer: string;
+}
+/** What to suggest improvements for: the same inputs as /v1/checks/*, any subset. */
+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;
+    }>;
+    /** 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). */
+    as_of?: string;
+    /** Only suggest for these surfaces (default: all). */
+    surfaces?: Array<"checkout_page" | "stripe_checkout" | "acknowledgment_email" | "trial_reminder_email" | "renewal_reminder_email" | "price_change_email" | "cancellation_flow" | "cancellation_confirmation_email">;
+    /** Your own checkout: the same fields as checkDisclosure (without the plan terms, which go in terms). */
+    disclosure?: {
+        /** The disclosure shown next to the purchase button, exactly as rendered. */
+        text: string;
+        /** Label of the purchase button. */
+        button_text?: string;
+        /** Other text next to the button (order summary). */
+        order_summary?: string;
+        /** Where and how the disclosure is shown (as in checkDisclosure). */
+        placement?: {
+            /** Shown above the purchase button (default true). */
+            above_button?: boolean;
+            /** On the same page as the payment form (default true). */
+            same_page_as_payment?: boolean;
+            /** Font size (default 14). */
+            font_size_px?: number;
+            /** WCAG contrast ratio. */
+            contrast_ratio?: number;
+            /** Bold / semibold. */
+            bold?: boolean;
+            /** Set off in a box. */
+            boxed?: boolean;
+            /** Surrounding body text size (default 14). */
+            body_font_size_px?: number;
+        };
+        /** The consent checkbox (as in checkDisclosure). */
+        consent?: {
+            /** There is a renewal consent checkbox. */
+            checkbox: boolean;
+            /** Ticked by default. */
+            prechecked?: boolean;
+            /** Its label. */
+            label?: string;
+            /** Required to submit (default true). */
+            required?: boolean;
+        };
+    };
+    /** Your checkout page HTML (as in checkPage; html only). */
+    page?: {
+        /** Rendered checkout page HTML (as in checkPage). */
+        html: string;
+        /** Where the page lives (resolves relative links). */
+        url?: string;
+    };
+    /** Stripe Checkout Session params (as in checkStripeCheckoutSession; plan terms in terms). */
+    stripe_checkout_session?: {
+        /** Exactly what your code passes to stripe.checkout.sessions.create. */
+        params: Record<string, unknown>;
+    };
+    /** Lifecycle emails (as in checkEmail; plan terms in terms). */
+    emails?: Array<{
+        /** Which lifecycle email (as in checkEmail). */
+        kind: "acknowledgment" | "trial_reminder" | "trial_ending" | "renewal_reminder" | "price_change" | "annual_terms" | "charge_notice" | "cancellation_confirmation";
+        /** Subject line. */
+        subject: string;
+        /** Plain-text body. */
+        text?: string;
+        /** HTML body. */
+        html?: string;
+        /** price_change only: the old price, major units. */
+        previous_price?: number | string;
+    }>;
+    /** Your cancellation flow as a subscriber sees it. */
+    cancellation_flow?: {
+        /** Screens from the account page to the confirmation, in order. */
+        steps: Array<{
+            /** What the screen says. */
+            text: string;
+            /** Buttons and links on the screen. */
+            buttons?: Array<string>;
+            /** The screen shows a retention (save) offer or pause option. */
+            offer?: boolean;
+        }>;
+        /** A confirmation is shown at the end (default true). */
+        confirmation_shown?: boolean;
+    };
+    /** You send a trial-ending reminder to every trial subscriber (false withholds suggestions that promise one). */
+    trial_reminders?: boolean;
+    /** Your site’s base URL (used in example links). */
+    site_url?: string;
+}
 export interface ElementsRelease {
     /** Semver of the bundle. */
     version: string;
@@ -3261,11 +3722,11 @@ export type TestRunFix = {
 } | null;
 /** One observed lifecycle step of a test run. */
 export interface TestRunStep {
-    /** Stable step key: credentials, checkout_config, checkout_page, subscribe, acknowledgment_email, trial_reminder, renewal, cancel_online, cancellation_email, cleanup. */
+    /** Stable step key: credentials, checkout_config, checkout_page, subscribe, acknowledgment_email, trial_reminder, renewal, cancel_online, cancellation_email, webhooks (real_checkout), cleanup. */
     key: string;
     /** Human-readable step title. */
     title: string;
-    /** passed: observed and compliant; failed: a check failed or the step broke the run; warning: could not be fully observed (see code and fix); skipped: not applicable or turned off. */
+    /** 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";
     /** What was observed, in one or two sentences. */
     summary: string | null;
@@ -3291,7 +3752,7 @@ export interface TestRunStep {
     observations: Record<string, unknown>;
     /** Evidence records (screenshots, page captures, raw emails) behind the step. */
     evidence: Array<string>;
-    /** Warning or failure code of the step (stable): key_missing, key_not_test_mode, key_invalid, key_permission_missing, checkout_config_missing, price_not_in_test_mode, checkout_session_failed, checkout_page_unreadable, checkout_not_completed, subscription_create_failed, test_clock_failed, no_email_received_within, reminder_not_received, portal_not_configured, cancel_not_completed, cancellation_email_not_received, scan_config_missing, domain_not_verified, scanner_failed, stripe_api_error, timeout, canceled, internal_error. */
+    /** Warning or failure code of the step (stable): key_missing, key_not_test_mode, key_invalid, key_permission_missing, checkout_config_missing, price_not_in_test_mode, checkout_session_failed, checkout_page_unreadable, checkout_not_completed, subscription_create_failed, test_clock_failed, no_email_received_within, reminder_not_received, portal_not_configured, cancel_not_completed, cancellation_email_not_received, checkout_url_missing, real_checkout_not_completed, payment_link_not_found, webhook_not_delivered, reminder_outside_window, reminder_timing_not_observed, cancel_flow_not_configured, cancel_not_confirmed_in_stripe, acknowledgment_content_incomplete, cancel_replaced_by_other_subscription, not_judged, scan_config_missing, domain_not_verified, scanner_failed, stripe_api_error, timeout, canceled, internal_error. */
     code: string | null;
     fix: TestRunFix;
 }
@@ -3307,6 +3768,8 @@ export interface TestRun {
     site: string;
     /** stripe: Stripe test mode with a test clock; generic: any site with a test coupon / test account (no time travel). */
     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). */
     status: "queued" | "running" | "succeeded" | "failed" | "canceled";
     /** Internal phase (prepare, checkout, await_ack, advance, settle, cancel, await_cancel_email, finalize, done). */
@@ -3325,7 +3788,7 @@ export interface TestRun {
     steps: Array<TestRunStep>;
     /** Why the run stopped (failed / canceled runs). */
     failure: {
-        /** Stable failure code: key_missing, key_not_test_mode, key_invalid, key_permission_missing, checkout_config_missing, price_not_in_test_mode, checkout_session_failed, checkout_page_unreadable, checkout_not_completed, subscription_create_failed, test_clock_failed, no_email_received_within, reminder_not_received, portal_not_configured, cancel_not_completed, cancellation_email_not_received, scan_config_missing, domain_not_verified, scanner_failed, stripe_api_error, timeout, canceled, internal_error. */
+        /** Stable failure code: key_missing, key_not_test_mode, key_invalid, key_permission_missing, checkout_config_missing, price_not_in_test_mode, checkout_session_failed, checkout_page_unreadable, checkout_not_completed, subscription_create_failed, test_clock_failed, no_email_received_within, reminder_not_received, portal_not_configured, cancel_not_completed, cancellation_email_not_received, checkout_url_missing, real_checkout_not_completed, payment_link_not_found, webhook_not_delivered, reminder_outside_window, reminder_timing_not_observed, cancel_flow_not_configured, cancel_not_confirmed_in_stripe, acknowledgment_content_incomplete, cancel_replaced_by_other_subscription, not_judged, scan_config_missing, domain_not_verified, scanner_failed, stripe_api_error, timeout, canceled, internal_error. */
         code: string;
         /** What went wrong. */
         message: string;
@@ -3381,8 +3844,8 @@ export interface TestRun {
         subscription: string | null;
         /** Mirrored test-mode Checkout Session. */
         checkout_session: string | null;
-        /** Where the checkout configuration came from. */
-        mirrored_from: "registered" | "live" | "request" | null;
+        /** Where the checkout configuration came from (mirror mode). */
+        mirrored_from: "registered" | "live" | "request" | "payment_link" | null;
         /** Registered config used (scc_…). */
         checkout_config: string | null;
         /** Compliance fingerprint of the mirrored checkout. */
@@ -3392,6 +3855,52 @@ export interface TestRun {
         /** Whether the test clock (with its customer and subscription) was deleted. */
         cleaned_up: boolean;
     } | null;
+    /** What the run proves and the evidence beyond the steps (Stripe runs). */
+    proof: {
+        /** The run mode. */
+        mode: "mirror" | "real_checkout";
+        /** What this run is evidence of, and what it is not, in one sentence. */
+        what_it_proves: string;
+        /** Notices mode of the site at the run: checkbox (Checkbox Notices sends; the run exercises them), merchant (you send; the run watches for yours) or off. */
+        notices: "checkbox" | "merchant" | "off" | null;
+        /** Who was expected to send the lifecycle emails. */
+        notices_sender: "checkbox" | "merchant" | null;
+        /** Payment Link mirrored or bought through (plink_…). */
+        payment_link: string | null;
+        /** Your Stripe test-mode webhook endpoints (host only) when the key may read them. */
+        webhook_endpoints: Array<{
+            /** Host of the endpoint URL (the path is not shown). */
+            host: string;
+            /** Event types it listens for ("*" = all). */
+            enabled_events: Array<string>;
+            /** enabled or disabled. */
+            status: string;
+        }>;
+        /** Stripe events of the run's subscription (evidence). pending_webhooks > 0: an endpoint did not acknowledge it. */
+        stripe_events: Array<{
+            /** Stripe event id (test mode). */
+            id: string;
+            /** Stripe event type. */
+            type: string;
+            /** When Stripe created it (unix seconds). */
+            created: number;
+            /** Deliveries Stripe still had pending when Checkbox looked (0 = acknowledged by every endpoint, or no endpoint). */
+            pending_webhooks: number | null;
+        }>;
+        /** How the cancellation was attempted and what Stripe showed. */
+        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). */
+            declared_by_merchant: boolean;
+            /** Stripe showed a subscription set to cancel after the shopper's flow. */
+            confirmed_in_stripe: boolean;
+            /** The subscription Stripe showed canceled. */
+            subscription: string | null;
+            /** Why Stripe could not be checked, when it could not. */
+            note: string | null;
+        } | null;
+    } | null;
     next_action: NextAction;
 }
 /** A page of test runs, newest first. */
@@ -3456,7 +3965,7 @@ export interface Event {
     id: string;
     /** String representing the object's type. Always "event". */
     object: "event";
-    /** Event type: site.score_changed, site.insurable_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.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. */
     type: string;
     /** API version used to render data.object. */
     api_version: string;
@@ -3532,12 +4041,10 @@ export interface CompliancePlanSummary {
     livemode: boolean;
     /** The site. */
     site: string;
-    /** action_required (an agent can apply open tasks now), verifying (changes applied; waiting for confirming observations), compliant (every applicable check Checkbox could observe passes — an automated assessment, not a legal determination; see coverage for what was not observed), blocked (only human answers or declined critical tasks remain). */
+    /** 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;
-    /** Preview flag the planned Checkbox Warranty will key on (no checks failing at high severity). No warranty or insurance is offered yet; this is not an underwriting decision. */
-    insurable: boolean | null;
     /** Two or three sentences for an LLM: where the site stands and what comes next. */
     summary: string;
     /** Tasks per status. */
@@ -3550,6 +4057,8 @@ export interface CompliancePlanSummary {
         verifying: number;
         /** Tasks waiting for a human answer. */
         manual: number;
+        /** Tasks that only wait for a live observation (count as compliant). */
+        pending_live_check?: number;
         /** Done tasks. */
         done: number;
         /** Declined tasks. */
@@ -3576,7 +4085,7 @@ export interface CompliancePlanSummary {
         /** Task key. */
         key: string;
         /** Task status. */
-        status: "open" | "in_progress" | "verifying" | "done" | "wont_fix" | "manual";
+        status: "open" | "in_progress" | "verifying" | "done" | "wont_fix" | "manual" | "pending_live_check";
         /** Priority. */
         priority: "critical" | "high" | "medium" | "low";
         /** Title. */
@@ -3594,7 +4103,7 @@ export interface Notice {
     /** The site. */
     site: string;
     /** Notice kind. */
-    kind: "acknowledgment" | "trial_ending" | "renewal_reminder" | "annual_terms" | "price_change";
+    kind: "acknowledgment" | "trial_ending" | "renewal_reminder" | "annual_terms" | "price_change" | "cancellation_confirmation" | "charge_notice";
     /** Delivery status. */
     status: "claimed" | "sent" | "failed" | "bounced" | "skipped";
     /** Billing platform of the subscription. */
@@ -3813,6 +4322,11 @@ export interface ListLawUpdatesParams {
     /** Only changes on or after this date (YYYY-MM-DD). */
     since?: string;
 }
+/** Parameters of `suggestions.forSite()` (listSiteSuggestions). */
+export interface ListSiteSuggestionsParams {
+    /** Comma-separated surfaces to include (default all). */
+    surfaces?: string;
+}
 /** Parameters of `consents.list()` (listConsents). */
 export interface ListConsentsParams {
     /** Number of objects to return, 1-100 (default 10). */
@@ -3884,6 +4398,8 @@ export interface ListStripeCheckoutConfigsParams {
 }
 /** Parameters of `testRuns.create()` (createTestRun). */
 export interface CreateTestRunParams {
+    /** Stripe runs. mirror (default): Checkbox mirrors your checkout into test mode and moves a test clock through every legal notice window. real_checkout ("Run proof"): the shopper buys through YOUR checkout on your test deployment (stripe.checkout_url or stripe.payment_link) with card 4242 and the run inbox, so your own webhook handlers and email code fire; Checkbox watches the inbox, Stripe's events and your cancel flow. Needs your test deployment on Stripe TEST keys with a test-mode webhook endpoint. */
+    mode?: "mirror" | "real_checkout";
     /** stripe (default when a Stripe test key is stored or the site uses Stripe) or generic (test coupon / test account, no time travel). */
     type?: "stripe" | "generic";
     /** How long to wait for each email (acknowledgment, reminders, cancellation), 15-900 seconds (default 120). */
@@ -3896,7 +4412,7 @@ export interface CreateTestRunParams {
     region?: "US-FED" | "US-AL" | "US-AK" | "US-AZ" | "US-AR" | "US-CA" | "US-CO" | "US-CT" | "US-DE" | "US-DC" | "US-FL" | "US-GA" | "US-HI" | "US-ID" | "US-IL" | "US-IN" | "US-IA" | "US-KS" | "US-KY" | "US-LA" | "US-ME" | "US-MD" | "US-MA" | "US-MI" | "US-MN" | "US-MS" | "US-MO" | "US-MT" | "US-NE" | "US-NV" | "US-NH" | "US-NJ" | "US-NM" | "US-NY" | "US-NC" | "US-ND" | "US-OH" | "US-OK" | "US-OR" | "US-PA" | "US-RI" | "US-SC" | "US-SD" | "US-TN" | "US-TX" | "US-UT" | "US-VT" | "US-VA" | "US-WA" | "US-WV" | "US-WI" | "US-WY";
     /** Stripe options. */
     stripe?: {
-        /** Registered checkout config (scc_…) to mirror; default: the newest one, else your latest live Checkout Session. */
+        /** Registered checkout config (scc_…) to mirror; default: the newest one, else your latest live Checkout Session. "none" skips the registered configs (mirror your live checkout, stripe.price or stripe.payment_link instead). */
         checkout_config?: string;
         /** A test-mode price to subscribe to when nothing is registered. */
         price?: string;
@@ -3906,8 +4422,33 @@ export interface CreateTestRunParams {
         price_map?: Record<string, string>;
         /** Steps that complete your hosted checkout with card 4242 4242 4242 4242 when it differs from Stripe's default page. */
         checkout_steps?: Array<ScanStep>;
-        /** Cancel on your own page instead of the Stripe customer portal (it must work for the test subscriber). */
+        /** Your cancellation page (after login with test_account, or public). Checkbox never falls back to the Stripe portal when your flow fails. */
         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). */
+        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?: {
+            /** Login page of the test account on your (test) deployment. */
+            login_url: string;
+            /** Its email; "{{inbox}}" = the run inbox (the account the shopper creates at checkout). */
+            email: string;
+            /** Its password (stored encrypted, never returned). Generated for "{{inbox}}" accounts when omitted. */
+            password?: string;
+            /** Custom login steps ({{email}}, {{password}}). */
+            login_steps?: Array<ScanStep>;
+        };
+        /** A Stripe Payment Link (plink_… or its buy.stripe.com URL): mirror mode mirrors its prices, custom_text, consent_collection and trial; real_checkout buys through it (test-mode links only). */
+        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" }]. */
+        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.) */
+        cleanup_url?: string;
+        /** Deprecated alias of cleanup_url. */
+        reset_url?: string;
     };
     /** Generic (non-Stripe) options. */
     generic?: {
@@ -3950,7 +4491,7 @@ export interface ListTestRunsParams {
 export interface CreateWebhookEndpointParams {
     /** HTTPS URL. */
     url: string;
-    /** Event types to send, or ["*"] for all: site.score_changed, site.insurable_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.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. */
     enabled_events: Array<string>;
     /** Description. */
     description?: string;
@@ -3970,7 +4511,7 @@ export interface ListWebhookEndpointsParams {
 export interface UpdateWebhookEndpointParams {
     /** HTTPS URL. */
     url?: string;
-    /** Event types to send, or ["*"] for all: site.score_changed, site.insurable_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.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. */
     enabled_events?: Array<string>;
     /** Description (null clears it). */
     description?: string | null;
@@ -4076,16 +4617,6 @@ export type SiteScoreChangedEvent = Event & {
         previous_attributes?: Record<string, unknown>;
     };
 };
-/** `site.insurable_changed`: A site became insurable or stopped being insurable. */
-export type SiteInsurableChangedEvent = Event & {
-    /** Event type. */
-    type?: "site.insurable_changed";
-    data?: {
-        object: Site;
-        /** Previous values of changed fields. */
-        previous_attributes?: Record<string, unknown>;
-    };
-};
 /** `finding.created`: A check started failing (new finding, or a resolved / passing one failing again). */
 export type FindingCreatedEvent = Event & {
     /** Event type. */
@@ -4197,9 +4728,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 | SiteInsurableChangedEvent | FindingCreatedEvent | FindingResolvedEvent | ScanCompletedEvent | ScanFailedEvent | LawChangedEvent | CertificateIssuedEvent | CertificateLapsedEvent | CertificateRevokedEvent | NoticeSentEvent | ConsentCreatedEvent | SiteCompliantEvent;
+export type WebhookEvent = PlanUpdatedEvent | TaskVerifiedEvent | NoticeDueEvent | NoticeOverdueEvent | ReceiptCreatedEvent | TestRunCompletedEvent | TestRunFailedEvent | SiteScoreChangedEvent | FindingCreatedEvent | FindingResolvedEvent | ScanCompletedEvent | ScanFailedEvent | LawChangedEvent | CertificateIssuedEvent | CertificateLapsedEvent | CertificateRevokedEvent | NoticeSentEvent | ConsentCreatedEvent | 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", "site.insurable_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.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 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: {