deepline 0.1.104 → 0.1.105

package/dist/cli/index.mjs

@@ -216,10 +216,12 @@ var SDK_RELEASE = {
   // scrubbing, and word-boundary watch truncation.
   // 0.1.103 ships the refined SDK CLI command surface.
   // 0.1.104 ships postgres_fast suspension/billing parity and runtime worker hardening.
-  version: "0.1.104",
+  // 0.1.105 ships the billing catalog surface: billing plans, subscribe,
+  // subscription status/cancel, invoices, and the client.billing namespace.
+  version: "0.1.105",
   apiContract: "2026-06-dataset-column-cell-stale-hard-cutover",
   supportPolicy: {
-    latest: "0.1.104",
+    latest: "0.1.105",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53"
   }
@@ -350,7 +352,7 @@ var HttpClient = class {
             signal: controller.signal
           });
           clearTimeout(timeoutId);
-          if (response.status === 401 || response.status === 403) {
+          if (response.status === 401 || response.status === 403 && !options?.forbiddenAsApiError) {
             throw new AuthError();
           }
           if (response.status === 429) {
@@ -1442,6 +1444,9 @@ var INCLUDE_TOOL_METADATA_HEADER = "x-deepline-include-tool-metadata";
 var EXECUTE_RESPONSE_CONTRACT_HEADER = "x-deepline-execute-response-contract";
 var V2_EXECUTE_RESPONSE_CONTRACT = "v2-tool-response";
 var COMPILE_MANIFEST_RETRY_DELAYS_MS = [250, 1e3];
+var REGISTER_PLAY_ARTIFACTS_COMPILE_CONCURRENCY = 3;
+var REGISTER_PLAY_ARTIFACTS_MAX_BATCH_COUNT = 3;
+var REGISTER_PLAY_ARTIFACTS_MAX_BATCH_BYTES = 25e5;
 function sleep2(ms) {
   return new Promise((resolve16) => setTimeout(resolve16, ms));
 }
@@ -1454,6 +1459,45 @@ function isTransientCompileManifestError(error) {
     message
   );
 }
+async function mapWithConcurrency(items, concurrency, mapper) {
+  const results = new Array(items.length);
+  let nextIndex = 0;
+  const workerCount = Math.min(Math.max(1, concurrency), items.length);
+  await Promise.all(
+    Array.from({ length: workerCount }, async () => {
+      for (; ; ) {
+        const index = nextIndex;
+        nextIndex += 1;
+        if (index >= items.length) {
+          return;
+        }
+        results[index] = await mapper(items[index], index);
+      }
+    })
+  );
+  return results;
+}
+function jsonUtf8Bytes(value) {
+  return new TextEncoder().encode(JSON.stringify(value)).length;
+}
+function chunkRegisterPlayArtifacts(artifacts) {
+  const chunks = [];
+  let current = [];
+  for (const artifact of artifacts) {
+    const candidate = [...current, artifact];
+    const candidateTooLarge = candidate.length > REGISTER_PLAY_ARTIFACTS_MAX_BATCH_COUNT || jsonUtf8Bytes({ artifacts: candidate }) > REGISTER_PLAY_ARTIFACTS_MAX_BATCH_BYTES;
+    if (current.length > 0 && candidateTooLarge) {
+      chunks.push(current);
+      current = [artifact];
+    } else {
+      current = candidate;
+    }
+  }
+  if (current.length > 0) {
+    chunks.push(current);
+  }
+  return chunks;
+}
 var RUN_LOGS_PAGE_LIMIT = 1e3;
 function isRecord2(value) {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
@@ -1621,6 +1665,8 @@ var DeeplineClient = class {
   config;
   /** Canonical run lifecycle namespace backed by `/api/v2/runs`. */
   runs;
+  /** Billing namespace: subscription status/cancel and invoice history. */
+  billing;
   /**
    * Create a low-level SDK client.
    *
@@ -1641,6 +1687,16 @@ var DeeplineClient = class {
       exportDatasetRows: (input2) => this.getPlaySheetRows(input2),
       stop: (runId, options2) => this.stopRun(runId, options2)
     };
+    this.billing = {
+      plans: () => this.getBillingPlans(),
+      subscription: {
+        status: () => this.getBillingSubscriptionStatus(),
+        cancel: (options2) => this.cancelBillingSubscription(options2)
+      },
+      invoices: {
+        list: (options2) => this.listBillingInvoices(options2)
+      }
+    };
   }
   /** The resolved base URL this client is targeting (e.g. `"http://localhost:3000"`). */
   get baseUrl() {
@@ -2009,8 +2065,13 @@ var DeeplineClient = class {
    * first when a compiler manifest is not already supplied.
    */
   async registerPlayArtifacts(artifacts) {
-    const compiledArtifacts = await Promise.all(
-      artifacts.map(async (artifact) => ({
+    if (artifacts.length === 0) {
+      return this.http.post("/api/v2/plays/artifacts", { artifacts });
+    }
+    const compiledArtifacts = await mapWithConcurrency(
+      artifacts,
+      REGISTER_PLAY_ARTIFACTS_COMPILE_CONCURRENCY,
+      async (artifact) => ({
         ...artifact,
         compilerManifest: artifact.compilerManifest ?? await this.compilePlayManifest({
           name: artifact.name,
@@ -2018,11 +2079,20 @@ var DeeplineClient = class {
           sourceFiles: artifact.sourceFiles,
           artifact: artifact.artifact
         })
-      }))
+      })
     );
-    return this.http.post("/api/v2/plays/artifacts", {
-      artifacts: compiledArtifacts
-    });
+    const responses = [];
+    for (const chunk of chunkRegisterPlayArtifacts(compiledArtifacts)) {
+      responses.push(
+        await this.http.post("/api/v2/plays/artifacts", {
+          artifacts: chunk
+        })
+      );
+    }
+    return {
+      success: responses.every((response) => response.success),
+      artifacts: responses.flatMap((response) => response.artifacts)
+    };
   }
   /**
    * Compile a bundled play artifact into the server-side compiler manifest.
@@ -2995,6 +3065,61 @@ var DeeplineClient = class {
   // ——————————————————————————————————————————————————————————
   // Health
   // ——————————————————————————————————————————————————————————
+  /**
+   * Published plans plus the caller's active plan: prices, monthly grant
+   * credits, rollover policy, and which plans are open for subscription.
+   * Prefer `client.billing.plans()`.
+   *
+   * @returns Snake_case catalog from `GET /api/v2/billing/catalog/current`
+   */
+  async getBillingPlans() {
+    return this.http.get("/api/v2/billing/catalog/current");
+  }
+  /**
+   * Subscription state for the active workspace: active plan, whether a
+   * Stripe subscription backs it, renewal/cancellation facts, and remaining
+   * Deepline credit pools. Prefer `client.billing.subscription.status()`.
+   *
+   * @returns Snake_case subscription status from `GET /api/v2/billing/subscription/status`
+   */
+  async getBillingSubscriptionStatus() {
+    return this.http.get(
+      "/api/v2/billing/subscription/status"
+    );
+  }
+  /**
+   * Schedule subscription cancellation at period end, or reverse a pending
+   * cancellation with `{ undo: true }`. The customer keeps the cycle they
+   * paid for and every remaining credit — cancellation never claws back
+   * credits. Prefer `client.billing.subscription.cancel(...)`.
+   *
+   * @throws {@link DeeplineError} with `statusCode: 409` when the workspace
+   *   has no active subscription, and `statusCode: 502` when Stripe rejects
+   *   the update (the server message is preserved).
+   */
+  async cancelBillingSubscription(options) {
+    return this.http.post(
+      "/api/v2/billing/subscription/cancel",
+      { action: options?.undo ? "undo_cancel" : "cancel" }
+    );
+  }
+  /**
+   * Customer-facing billing history: subscription invoices plus one-time
+   * credit purchase receipts, newest first, with Stripe-hosted links.
+   * Prefer `client.billing.invoices.list(...)`.
+   *
+   * @param options.limit - Maximum entries to return (server clamps to 1–100, default 24).
+   */
+  async listBillingInvoices(options) {
+    const params = new URLSearchParams();
+    if (options?.limit !== void 0) {
+      params.set("limit", String(options.limit));
+    }
+    const suffix = Array.from(params).length > 0 ? `?${params.toString()}` : "";
+    return this.http.get(
+      `/api/v2/billing/invoices${suffix}`
+    );
+  }
   /**
    * Check API connectivity and server health.
    *
@@ -4131,6 +4256,56 @@ import { Command } from "commander";
 import { appendFile, mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
 import { dirname as dirname4, resolve as resolve3 } from "path";
 import { stringify as stringify2 } from "csv-stringify/sync";
+var SUBSCRIPTION_STATUS_NEXT_COMMAND = "deepline billing subscription status --json";
+var SUBSCRIPTION_CANCEL_PATH = "/api/v2/billing/subscription/cancel";
+function billingFailureFromError(error, options) {
+  if (error instanceof AuthError) {
+    return {
+      exitCode: 3,
+      code: "AUTH_ERROR",
+      message: error.message,
+      next: "deepline auth status --json"
+    };
+  }
+  if (!(error instanceof DeeplineError) || typeof error.statusCode !== "number") {
+    return null;
+  }
+  if (error.statusCode === 404 || error.statusCode === 409) {
+    return {
+      exitCode: 4,
+      code: options.notFoundCode,
+      message: error.message,
+      next: SUBSCRIPTION_STATUS_NEXT_COMMAND
+    };
+  }
+  if (error.statusCode >= 500) {
+    return {
+      exitCode: 5,
+      code: "BILLING_SERVER_ERROR",
+      message: error.message,
+      next: SUBSCRIPTION_STATUS_NEXT_COMMAND
+    };
+  }
+  return null;
+}
+function reportBillingFailure(failure, options) {
+  const textLines = [failure.message];
+  if (failure.next) {
+    textLines.push(`Next: ${failure.next}`);
+  }
+  printCommandEnvelope(
+    {
+      ok: false,
+      exitCode: failure.exitCode,
+      code: failure.code,
+      message: failure.message,
+      ...failure.next ? { next: failure.next } : {}
+    },
+    { json: options.json, text: `${textLines.join("\n")}
+` }
+  );
+  process.exitCode = failure.exitCode;
+}
 function humanize(value) {
   return String(value || "").split("_").filter(Boolean).map((token) => token[0]?.toUpperCase() + token.slice(1)).join(" ") || "Unknown";
 }
@@ -4406,6 +4581,273 @@ async function handleLedgerExportAll(options) {
     { json: options.json }
   );
 }
+function planPriceText(priceUsd, priceInterval) {
+  if (priceUsd === null || priceUsd === void 0) {
+    return "no list price";
+  }
+  return `$${priceUsd}${priceInterval ? `/${priceInterval}` : ""}`;
+}
+function planRolloverText(rollover) {
+  const mode = rollover?.mode ?? "none";
+  if (mode === "none") return "no rollover";
+  if (mode === "bounded") {
+    return `rollover up to ${rollover?.max_credits ?? "(unknown)"} credits`;
+  }
+  return `rollover ${mode}`;
+}
+async function handlePlans(options) {
+  const { http } = getAuthedHttpClient();
+  const payload = await http.get(
+    "/api/v2/billing/catalog/current"
+  );
+  const activePlan = payload.active_plan ?? {};
+  const plans = Array.isArray(payload.plans) ? payload.plans : [];
+  const metrics = Array.isArray(payload.metrics) ? payload.metrics : [];
+  const lines = [
+    `Catalog: ${payload.catalog_id ?? "(unknown)"} (version ${payload.catalog_version ?? "(unknown)"})`,
+    `Active plan: ${activePlan.public_name ?? "(unknown)"} (${activePlan.plan_version_id ?? "(unknown)"})`,
+    `Assigned by: ${activePlan.assigned_by ?? "default"} | subscription: ${activePlan.has_subscription ? "yes" : "no"}`,
+    ...plans.length === 0 ? ["Plans: none published"] : [
+      "Plans:",
+      ...plans.map(
+        (plan) => `${plan.public_name ?? "(unknown)"} (${plan.plan_version_id ?? "(unknown)"}) | ${planPriceText(plan.price_usd, plan.price_interval)} | ${plan.monthly_grant_credits ?? 0} credits/cycle | ${planRolloverText(plan.rollover)} | ${plan.acquirable ? "acquirable" : "not acquirable"}`
+      )
+    ],
+    ...metrics.length === 0 ? ["Metrics: none"] : [
+      "Metrics:",
+      ...metrics.map(
+        (metric) => `${metric.id ?? "(unknown)"} | ${metric.name ?? "(unknown)"}`
+      )
+    ]
+  ];
+  printCommandEnvelope(
+    {
+      ...payload,
+      render: { sections: [{ title: "billing plans", lines }] }
+    },
+    { json: options.json }
+  );
+}
+async function handleSubscribe(planVersionId, options) {
+  const { http } = getAuthedHttpClient();
+  const payload = await http.request(
+    "/api/v2/billing/subscription/checkout",
+    {
+      method: "POST",
+      body: { plan_version_id: planVersionId },
+      forbiddenAsApiError: true
+    }
+  );
+  const url = String(payload.checkout_url || "");
+  if (!options.json && options.open !== false && url) openInBrowser(url);
+  printCommandEnvelope(
+    {
+      ...payload,
+      render: {
+        sections: [
+          {
+            title: "billing subscribe",
+            lines: [url || "Subscription checkout session created."]
+          }
+        ]
+      }
+    },
+    { json: options.json }
+  );
+}
+async function handleSubscriptionStatus(options) {
+  const client2 = new DeeplineClient();
+  const payload = await client2.billing.subscription.status();
+  const pools = payload.credit_pools ?? [];
+  const lines = [
+    `Plan: ${payload.plan_name ?? "(unknown)"} (${payload.plan_version_id ?? "(unknown)"})`,
+    `Subscribed: ${payload.subscribed ? "yes" : "no"}`,
+    ...payload.cancel_at_period_end ? [
+      `Cancellation scheduled: ends ${payload.current_period_end ?? "(unknown)"} at period end (credits are kept)`
+    ] : [],
+    `Price: ${planPriceText(payload.price_usd, payload.price_interval)}`,
+    `Monthly grant: ${payload.monthly_grant_credits ?? 0} credits`,
+    `Pooled credits remaining: ${payload.pooled_credits_remaining ?? 0}`,
+    ...pools.length === 0 ? ["Credit pools: none"] : [
+      "Credit pools:",
+      ...pools.map(
+        (pool) => `${pool.pool ?? "(unknown)"} | ${pool.credits_remaining ?? 0}/${pool.credits_granted ?? 0} credits remaining | ${pool.source ?? "(unknown)"}`
+      )
+    ],
+    `Assigned by: ${payload.assigned_by ?? "default"}`
+  ];
+  printCommandEnvelope(
+    {
+      ...payload,
+      render: { sections: [{ title: "billing subscription", lines }] }
+    },
+    { json: options.json }
+  );
+}
+async function handleSubscriptionCancel(options) {
+  const client2 = new DeeplineClient();
+  const action = options.undo ? "undo_cancel" : "cancel";
+  if (options.dryRun) {
+    const status = await client2.billing.subscription.status();
+    if (!status.subscribed) {
+      reportBillingFailure(
+        {
+          exitCode: 4,
+          code: "NO_ACTIVE_SUBSCRIPTION",
+          message: "This workspace has no active subscription to cancel.",
+          next: SUBSCRIPTION_STATUS_NEXT_COMMAND
+        },
+        options
+      );
+      return;
+    }
+    const consequence = action === "cancel" ? `Would schedule cancellation at period end${status.current_period_end ? ` (${status.current_period_end})` : ""}. The subscription stays active until then and remaining credits are kept.` : "Would reverse the pending cancellation; the subscription would renew normally.";
+    printCommandEnvelope(
+      {
+        ok: true,
+        dry_run: true,
+        action,
+        plan_version_id: status.plan_version_id,
+        plan_name: status.plan_name,
+        cancel_at_period_end: status.cancel_at_period_end,
+        current_period_end: status.current_period_end,
+        consequence,
+        planned_request: {
+          method: "POST",
+          path: SUBSCRIPTION_CANCEL_PATH,
+          body: { action }
+        },
+        render: {
+          sections: [
+            {
+              title: "billing subscription cancel (dry run)",
+              lines: [
+                `Plan: ${status.plan_name} (${status.plan_version_id})`,
+                `Planned request: POST ${SUBSCRIPTION_CANCEL_PATH} {"action":"${action}"}`,
+                consequence,
+                "No request was sent. Re-run without --dry-run to apply."
+              ]
+            }
+          ]
+        }
+      },
+      { json: options.json }
+    );
+    return;
+  }
+  let result;
+  try {
+    result = await client2.billing.subscription.cancel({
+      undo: Boolean(options.undo)
+    });
+  } catch (error) {
+    const failure = billingFailureFromError(error, {
+      notFoundCode: "NO_ACTIVE_SUBSCRIPTION"
+    });
+    if (!failure) throw error;
+    reportBillingFailure(failure, options);
+    return;
+  }
+  const lines = options.undo ? [
+    "Pending cancellation reversed; the subscription will renew normally.",
+    `Subscription: ${result.subscription_id}`
+  ] : [
+    `Cancellation scheduled for subscription ${result.subscription_id}.`,
+    `The subscription stays active until ${result.current_period_end ?? "the end of the current billing period"}, then cancels at period end.`,
+    "Remaining credits are yours to keep \u2014 cancellation never removes credits.",
+    "Undo with: deepline billing subscription cancel --undo"
+  ];
+  printCommandEnvelope(
+    {
+      ok: true,
+      ...result,
+      render: {
+        sections: [{ title: "billing subscription cancel", lines }]
+      }
+    },
+    { json: options.json }
+  );
+}
+function invoiceAmountText(amountCents, currency) {
+  const value = (Number(amountCents ?? 0) / 100).toFixed(2);
+  return String(currency ?? "usd").toLowerCase() === "usd" ? `$${value}` : `${value} ${String(currency).toUpperCase()}`;
+}
+function invoiceDateText(createdAt) {
+  return String(createdAt ?? "").slice(0, 10);
+}
+function invoiceLine(entry, compact) {
+  const amount = invoiceAmountText(entry.amount_cents, entry.currency);
+  const link = entry.url ?? "(no link)";
+  if (compact) {
+    return [
+      entry.id,
+      invoiceDateText(entry.created_at),
+      amount,
+      entry.status,
+      link
+    ].join(" | ");
+  }
+  return [
+    invoiceDateText(entry.created_at),
+    entry.description,
+    amount,
+    entry.status,
+    link
+  ].join(" | ");
+}
+async function handleInvoices(options) {
+  let limit;
+  if (options.limit !== void 0) {
+    limit = Number.parseInt(options.limit, 10);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+      reportBillingFailure(
+        {
+          exitCode: 2,
+          code: "INVALID_LIMIT",
+          message: "--limit must be an integer between 1 and 100."
+        },
+        options
+      );
+      return;
+    }
+  }
+  const client2 = new DeeplineClient();
+  let payload;
+  try {
+    payload = await client2.billing.invoices.list(
+      limit === void 0 ? void 0 : { limit }
+    );
+  } catch (error) {
+    const failure = billingFailureFromError(error, {
+      notFoundCode: "NOT_FOUND"
+    });
+    if (!failure) throw error;
+    reportBillingFailure(failure, options);
+    return;
+  }
+  const entries = Array.isArray(payload.entries) ? payload.entries : [];
+  const compact = Boolean(options.compact);
+  const header = compact ? "id | date | amount | status | link" : "date | description | amount | status | link";
+  const lines = entries.length === 0 ? ["No invoices or receipts yet."] : [header, ...entries.map((entry) => invoiceLine(entry, compact))];
+  const envelope = compact ? {
+    org_id: payload.org_id,
+    count: entries.length,
+    entries: entries.map((entry) => ({
+      id: entry.id,
+      date: invoiceDateText(entry.created_at),
+      amount: invoiceAmountText(entry.amount_cents, entry.currency),
+      status: entry.status,
+      url: entry.url
+    }))
+  } : { ...payload, count: entries.length };
+  printCommandEnvelope(
+    {
+      ...envelope,
+      render: { sections: [{ title: "billing invoices", lines }] }
+    },
+    { json: options.json }
+  );
+}
 async function handleCheckout(options) {
   const { http } = getAuthedHttpClient();
   const payload = await http.post(
@@ -4454,19 +4896,33 @@ async function handleRedeemCode(code, options) {
   );
 }
 function registerBillingCommands(program) {
-  const billing = program.command("billing").description("Inspect balance, usage, limits, and checkout flows.").addHelpText(
+  const billing = program.command("billing").description("See your plan and credits, buy more, and manage billing.").addHelpText(
     "after",
     `
 Concepts:
   Billing commands show Deepline credits, not raw provider spend.
-  set-limit/off mutate the monthly workspace cap. checkout/redeem-code can open
-  a browser unless --no-open is set.
+  checkout/subscribe/redeem-code can open a browser unless --no-open is set.
 
 Examples:
+  # See where you stand
   deepline billing balance --json
   deepline billing usage --limit 20 --json
-  deepline billing set-limit 500 --json
+  deepline billing plans --json
+  deepline billing subscription status --json
+
+  # Buy credits or a plan
   deepline billing checkout --credits 1000 --no-open --json
+  deepline billing subscribe runtime-395-2026-07-v1 --no-open --json
+  deepline billing redeem-code --code ABC123 --no-open --json
+
+  # Manage
+  deepline billing subscription cancel --dry-run --json
+  deepline billing set-limit 500 --json
+
+  # Records
+  deepline billing invoices --limit 12 --json
+  deepline billing history --time 1m --json
+  deepline billing ledger export all --json
 `
   );
   billing.command("balance").description("Show current billing balance.").addHelpText(
@@ -4592,6 +5048,110 @@ Examples:
   deepline billing checkout --credits 1000 --discount-code LAUNCH --no-open
 `
   ).option("--tier <tierId>", "Named pricing tier").option("--credits <credits>", "Custom credit amount").option("--discount-code <code>", "Apply a discount code").option("--no-open", "Print the checkout URL without opening a browser").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleCheckout);
+  billing.command("plans").description("Show published plans and the plan you are on.").addHelpText(
+    "after",
+    `
+Notes:
+  Read-only. Answers "what plans exist and what am I on": each plan's price,
+  monthly grant credits, rollover policy, and whether it is open for
+  subscription, plus the catalog's usage metrics. All amounts are Deepline
+  credits and Deepline-facing USD, never raw provider spend. Subscribe to a
+  listed plan with: deepline billing subscribe <plan_version_id>
+
+Examples:
+  deepline billing plans
+  deepline billing plans --json
+`
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handlePlans);
+  billing.command("subscribe").description(
+    "Start a subscription checkout for a plan and optionally open it in your browser."
+  ).addHelpText(
+    "after",
+    `
+Notes:
+  Creates a Stripe subscription checkout session for the given plan version.
+  Opens the checkout URL in a browser unless --no-open is set. Fails loudly
+  with the server error when subscription checkout is not enabled or the plan
+  is not open for subscription.
+
+Examples:
+  deepline billing subscribe runtime-395-2026-07-v1
+  deepline billing subscribe runtime-395-2026-07-v1 --no-open --json
+`
+  ).argument("<plan_version_id>", "Plan version id from `billing plans`").option("--no-open", "Print the checkout URL without opening a browser").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleSubscribe);
+  billing.command("subscription").description("Inspect and manage subscription state for the workspace.").addHelpText(
+    "after",
+    `
+Examples:
+  deepline billing subscription status
+  deepline billing subscription status --json
+  deepline billing subscription cancel --dry-run
+  deepline billing subscription cancel --json
+  deepline billing subscription cancel --undo --json
+`
+  ).addCommand(
+    new Command("status").description("Show active plan, subscription state, and credit pools.").addHelpText(
+      "after",
+      `
+Notes:
+  Read-only. Shows the active plan, whether a Stripe subscription backs it,
+  scheduled cancellation state, and remaining Deepline credits per grant pool.
+
+Examples:
+  deepline billing subscription status
+  deepline billing subscription status --json
+`
+    ).option(
+      "--json",
+      "Emit JSON output. Also automatic when stdout is piped"
+    ).action(handleSubscriptionStatus)
+  ).addCommand(
+    new Command("cancel").description("Cancel the subscription at period end. Credits are kept.").addHelpText(
+      "after",
+      `
+Notes:
+  Mutates subscription state. Cancellation is always AT PERIOD END: the
+  subscription stays active until the end of the paid cycle and remaining
+  Deepline credits are kept \u2014 cancellation never removes credits. --undo
+  reverses a pending cancellation before the period ends. --dry-run reads
+  subscription status and prints the planned mutation without calling the
+  cancel endpoint.
+
+Exit codes:
+  0  cancellation scheduled (or reversed with --undo)
+  3  auth error
+  4  no active subscription to cancel
+  5  Stripe/server failure (the server message is preserved)
+
+Examples:
+  deepline billing subscription cancel --dry-run
+  deepline billing subscription cancel
+  deepline billing subscription cancel --undo
+  deepline billing subscription cancel --json
+`
+    ).option("--undo", "Reverse a pending cancellation before period end").option(
+      "--dry-run",
+      "Print the planned cancellation without calling the cancel endpoint"
+    ).option(
+      "--json",
+      "Emit JSON output. Also automatic when stdout is piped"
+    ).action(handleSubscriptionCancel)
+  );
+  billing.command("invoices").description("List subscription invoices and credit purchase receipts.").addHelpText(
+    "after",
+    `
+Notes:
+  Read-only. Shows customer-facing billing history from Stripe, newest first:
+  subscription invoices plus one-time Deepline credit purchase receipts, with
+  Stripe-hosted links. Amounts are what you paid \u2014 never provider spend.
+  --compact keeps id/date/amount/status/url only.
+
+Examples:
+  deepline billing invoices
+  deepline billing invoices --limit 12 --json
+  deepline billing invoices --compact --json
+`
+  ).option("--limit <n>", "Maximum entries to return (1-100, default 24)").option("--compact", "Keep only id, date, amount, status, and url").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleInvoices);
   billing.command("redeem-code").description("Redeem a billing code.").addHelpText(
     "after",
     `