@checkbox-site/node 0.2.3 → 0.2.5

package/dist/client.d.ts

@@ -45,7 +45,7 @@ export interface Checkbox extends ResourceInstances {
  */
 export declare class Checkbox implements RequestSender {
     #private;
-    static readonly VERSION = "0.2.3";
+    static readonly VERSION = "0.2.5";
     static readonly API_VERSION = "2026-10-30";
     static readonly errors: typeof errors;
     static readonly webhooks: Webhooks;

package/dist/generated/operations.d.ts

@@ -3356,7 +3356,7 @@ export declare class StripeCheckoutConfigsResource extends Resource {
     /**
      * Register the Checkout Session params your code uses.
      *
-     * Registers exactly the object your code passes to stripe.checkout.sessions.create (customer, URLs and secrets are not needed and are ignored; `warnings` says what was not stored). It is judged exactly like checkStripeCheckoutSession, discounts included. A config with the same name, or for the same Price ids, replaces the older one (`replaced`). Test runs mirror it into Stripe test mode; when it matches your latest live checkout, the scanned test page counts as an observation of your live checkout. Re-register after changing your checkout code, then call createTestRun.
+     * Registers exactly the object your code passes to stripe.checkout.sessions.create, as `params` (that object sent alone as the body is accepted too; customer, URLs and secrets are not needed and are ignored; `warnings` says what was not stored). It is judged exactly like checkStripeCheckoutSession, discounts included. A config with the same name, or for the same Price ids, replaces the older one (`replaced`). Test runs mirror it into Stripe test mode; when it matches your latest live checkout, the scanned test page counts as an observation of your live checkout. Re-register after changing your checkout code, then call createTestRun.
      *
      * @param site Unique identifier of the site (site_…).
      * @see POST /v1/sites/{site}/stripe_checkout_configs (operation `createStripeCheckoutConfig`, scope `test_runs:write`)

package/dist/generated/operations.js

@@ -2936,7 +2936,7 @@ export class StripeCheckoutConfigsResource extends Resource {
     /**
      * Register the Checkout Session params your code uses.
      *
-     * Registers exactly the object your code passes to stripe.checkout.sessions.create (customer, URLs and secrets are not needed and are ignored; `warnings` says what was not stored). It is judged exactly like checkStripeCheckoutSession, discounts included. A config with the same name, or for the same Price ids, replaces the older one (`replaced`). Test runs mirror it into Stripe test mode; when it matches your latest live checkout, the scanned test page counts as an observation of your live checkout. Re-register after changing your checkout code, then call createTestRun.
+     * Registers exactly the object your code passes to stripe.checkout.sessions.create, as `params` (that object sent alone as the body is accepted too; customer, URLs and secrets are not needed and are ignored; `warnings` says what was not stored). It is judged exactly like checkStripeCheckoutSession, discounts included. A config with the same name, or for the same Price ids, replaces the older one (`replaced`). Test runs mirror it into Stripe test mode; when it matches your latest live checkout, the scanned test page counts as an observation of your live checkout. Re-register after changing your checkout code, then call createTestRun.
      *
      * @param site Unique identifier of the site (site_…).
      * @see POST /v1/sites/{site}/stripe_checkout_configs (operation `createStripeCheckoutConfig`, scope `test_runs:write`)

package/dist/generated/types.d.ts

@@ -129,7 +129,7 @@ export interface DeviceAuthorizationParams {
     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, 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. */
+    /** A HINT of the Stripe restricted TEST key found in the project, never the key. Format: "rk_test_", the ellipsis character "…" (U+2026), then the key's last 4 characters, e.g. "rk_test_…a1b2". The human is asked once whether Checkbox may use it. Agents may store restricted test keys (rk_test_) only: an "sk_test_" hint (sent by older CLIs) is accepted and ignored, because a full secret key is refused on every path. */
     stripe_test_key_hint?: string;
 }
 /** Keys issued after the human approved the device login. Returned exactly once. */
@@ -255,6 +255,28 @@ export type UnverifiedScan = {
     /** What an unverified scan is (show it with the results). */
     note: string;
 } | null;
+/** Test mode only: the steps left before real customers are covered, with who takes each (the compliance plan's go_live). When next_action is done, report "set up in test mode; N steps before real customers" (go_live.summary), never a plain done. Null in live mode or before the first checks. */
+export type GoLive = {
+    /** Everything Checkbox observed came from Stripe test mode. */
+    mode: "test";
+    /** Heading. */
+    title: string;
+    /** One sentence before the steps. */
+    lead: string;
+    /** The steps, in order. */
+    steps: Array<{
+        /** Stable step key. */
+        key: "verify_domain" | "stripe_terms_url" | "live_stripe_key" | "live_checkout" | "promote_site";
+        /** Who takes the step: person (only the owner can: DNS, the Stripe Dashboard, live keys) or agent (a code change). */
+        who: "person" | "agent";
+        /** The step in plain words. */
+        text: string;
+        /** Where the person does it, when there is one fixed place. */
+        url?: string;
+    }>;
+    /** What the agent tells the person instead of "done": set up in test mode, N steps left before real customers. */
+    summary: string;
+} | null;
 /** One step of the setup checklist. */
 export interface SetupStep {
     /** Stable step key. */
@@ -390,7 +412,7 @@ export interface SetupSession {
     stripe: {
         /** Whether the human ticked “Let your agent store a Stripe test-mode key” on the approval page (device login or OAuth connection). False: the agent may not store one (createTestCredential answers test_key_declined); the human adds it in the dashboard. Sessions started with a key the human made in the dashboard: true. */
         test_key_consent: boolean;
-        /** Hint of the key the CLI found (never the key). */
+        /** Hint of the restricted test key the CLI found (never the key). */
         test_key_hint: string | null;
         /** Whether a Stripe test-mode key is stored for test runs. */
         test_credential_stored: boolean;
@@ -402,7 +424,7 @@ export interface SetupSession {
             recommended: boolean;
             /** Why. */
             reason: string;
-            /** Where to create it. */
+            /** Stripe API keys page (Test mode); click "Create restricted key" there. */
             create_url: string;
             /** The one key checklist: every permission Checkbox uses (checks, fixes after the human approves, test runs). */
             permissions: Array<{
@@ -419,7 +441,7 @@ export interface SetupSession {
     test_run: {
         /** Unique identifier of the test run (run_…). */
         id: string;
-        /** queued, running, succeeded, failed or canceled. */
+        /** queued, running, succeeded, incomplete (no step failed, but a step could not finish), 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;
@@ -503,6 +525,7 @@ export interface SetupSession {
         }>;
     } | null;
     unverified_scan: UnverifiedScan;
+    go_live: GoLive;
     /** The setup checklist, in order. */
     steps: Array<SetupStep>;
     next_action: SetupNextAction;
@@ -573,6 +596,8 @@ export interface SetupSessionUpdate {
         env_file?: string;
         /** Static files directory (for /.well-known). */
         public_dir?: string;
+        /** The email library the project sends with (nodemailer, resend, @sendgrid/mail…), or "none" when nothing in it sends email (a static site): the plan then offers Checkbox Notices first for the required emails. */
+        mailer?: string;
         /** 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. */
@@ -650,6 +675,7 @@ export interface SetupVerification {
         /** Why not (limits: one per site per 24 h, three unverified sites per account in 30 days). */
         reason: string | null;
     } | null;
+    next_action: SetupNextAction;
     setup_session: SetupSession;
 }
 /** Account default retention (sites without their own setting use it). */
@@ -1689,7 +1715,7 @@ export interface Task {
         /** What Checkbox must observe for the task to be done. */
         expected: string;
     };
-    /** What Checkbox needs before it can give the exact change (observation: it has not seen the page / email yet; facts: plan, price, cancel URL or merchant name). The title stays the same either way. */
+    /** What Checkbox needs before it can give the exact change or verify it (observation: it has not seen the page / email yet; facts: plan, price, cancel URL or merchant name; verify_domain: the site's domain is not verified yet, so Checkbox cannot visit it to verify this task: do the verify_domain task first). The title stays the same either way. */
     blocked_on: string | null;
     /** Done / declined tasks: verified (its checks pass), no_longer_applicable (its checks no longer apply, e.g. the data source changed), superseded, declined, decided (the owner confirmed a decision, e.g. New York notices by email only: closed, but its checks are not verified). */
     closed_reason: "verified" | "no_longer_applicable" | "superseded" | "declined" | "decided" | null;
@@ -1766,7 +1792,7 @@ 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";
-    /** The plan status in words to show a person: action_required "Fixes needed", verifying "Checking your changes", compliant "Checks pass", blocked "Your call"; while an agent works the site and everything left waits for a deploy or the owner (next_action done_for_now): "Waiting on deploy and you" or "Waiting on deploy". Show this, never the machine value (`compliant` is a status name, not a legal conclusion). */
+    /** The plan status in words to show a person, from the same counts as the summary ("1 fix needed · 2 to set up", "1 decision for you"; else action_required "Fixes needed", blocked "Your call"), "Checks still running (N)" while checks are still running (verifying), compliant "Checks pass"; while an agent works the site and everything left waits for a deploy or the owner (next_action done_for_now): "Waiting on deploy and you" or "Waiting on deploy". 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;
@@ -1837,6 +1863,7 @@ export interface CompliancePlan {
             on_answer: Record<string, string>;
         }>;
     };
+    go_live?: GoLive;
     /** 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). */
@@ -1899,7 +1926,7 @@ export interface VerificationCheck {
     check_id: string;
     /** Status the task needs. */
     expected: string;
-    /** Status observed (pass, fail, needs_review, not_applicable, unknown). */
+    /** Status observed (pass, fail, needs_review, missing_data, not_checked, not_applicable, unknown, or informational: a note on a part that is not yours to change, such as Stripe's own hosted page layout; it never holds a verification back). */
     observed: string;
     /** Where the observation comes from: evaluation, static_fetch, html, stripe_params, email, policy_fetch. */
     source: string;
@@ -1920,8 +1947,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: 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";
+    /** 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), superseded (this verification did not pass, but newer evidence, such as a test run or a later evaluation, settled the task since: see superseded and follow next_action; nothing to change for it). */
+    status: "pending" | "passed" | "passed_with_gaps" | "passed_with_notes" | "not_checked" | "pending_live_check" | "failed" | "superseded";
+    /** Set when newer evidence settled the task after this verification finished (status superseded). */
+    superseded?: {
+        /** The task's status in the current plan. */
+        task_status: string;
+        /** What settled the task: a test run (run_…) or the latest evaluation. */
+        by: string;
+        /** In words: what this verification found and what settled the task since. */
+        detail: string;
+    } | null;
     /** 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"… */
@@ -1951,7 +1987,7 @@ export interface Verification {
         checks: Array<{
             /** Check id. */
             check_id: string;
-            /** Pre-check result: pass, fail, needs_review or not_applicable. */
+            /** Pre-check result: pass, fail, needs_review, not_applicable, or informational (a note on Stripe's own hosted page layout: nothing to change, never holds the verification back). */
             status: string;
             /** What the pre-check found, in one line. */
             reason: string;
@@ -1967,7 +2003,7 @@ 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"; while an agent works the site and everything left waits for a deploy or the owner (next_action done_for_now): "Waiting on deploy and you" or "Waiting on deploy". Show this, never the machine value (`compliant` is a status name, not a legal conclusion). */
+    /** The plan status in words to show a person, from the same counts as the summary ("1 fix needed · 2 to set up", "1 decision for you"; else action_required "Fixes needed", blocked "Your call"), "Checks still running (N)" while checks are still running (verifying), compliant "Checks pass"; while an agent works the site and everything left waits for a deploy or the owner (next_action done_for_now): "Waiting on deploy and you" or "Waiting on deploy". 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. */
@@ -4425,7 +4461,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, 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. */
+    /** 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, required_notice_skipped, 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;
 }
@@ -4443,8 +4479,8 @@ 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 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";
+    /** succeeded means the run finished every step and no step failed (steps may still have warnings to review); incomplete means no step failed, but a step could not finish what it set out to observe (for example the online cancellation could not be completed): not a pass; failed means it stopped early, or finished with a failed step (see failure and steps[].fix). */
+    status: "queued" | "running" | "succeeded" | "incomplete" | "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). */
@@ -4480,7 +4516,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, 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. */
+        /** 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, required_notice_skipped, 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;
@@ -4523,6 +4559,17 @@ export interface TestRun {
             /** Why something was kept in the run report only. */
             notes: Array<string>;
         };
+        /** Notices Checkbox Notices owed the run's subscriber (an applicable law requires them) but skipped or failed to send. Not empty: the run is not a clean pass, and the setup is not "all set". */
+        notices_skipped: Array<{
+            /** Notice kind. */
+            kind: string;
+            /** skipped or failed. */
+            status: string;
+            /** Why Checkbox Notices did not send it. */
+            reason: string | null;
+            /** The step that reports it (now a warning, code required_notice_skipped). */
+            step: string;
+        }>;
     } | null;
     /** Stripe test-mode objects of the run (type stripe). */
     stripe: {
@@ -4768,7 +4815,7 @@ 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";
-    /** The plan status in words to show a person: action_required "Fixes needed", verifying "Checking your changes", compliant "Checks pass", blocked "Your call"; while an agent works the site and everything left waits for a deploy or the owner (next_action done_for_now): "Waiting on deploy and you" or "Waiting on deploy". Show this, never the machine value (`compliant` is a status name, not a legal conclusion). */
+    /** The plan status in words to show a person, from the same counts as the summary ("1 fix needed · 2 to set up", "1 decision for you"; else action_required "Fixes needed", blocked "Your call"), "Checks still running (N)" while checks are still running (verifying), compliant "Checks pass"; while an agent works the site and everything left waits for a deploy or the owner (next_action done_for_now): "Waiting on deploy and you" or "Waiting on deploy". 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;

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Version of this SDK (kept equal to packages/sdk-node/package.json "version"; a test checks it). */
-export declare const SDK_VERSION = "0.2.3";
+export declare const SDK_VERSION = "0.2.5";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Version of this SDK (kept equal to packages/sdk-node/package.json "version"; a test checks it). */
-export const SDK_VERSION = '0.2.3';
+export const SDK_VERSION = '0.2.5';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkbox-site/node",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Checkbox Node.js SDK: auto-renewal law and subscription compliance checks (FTC ROSCA, California ARL, New York and other state laws) for Stripe Checkout and other subscription checkouts. Zero dependencies. Published to npm as @checkbox-site/node.",
   "keywords": [
     "subscription",