deepline 0.1.194 → 0.1.196

package/dist/cli/index.mjs

@@ -608,10 +608,10 @@ var SDK_RELEASE = {
   // 0.1.154 removes the short-lived generated enrich StepOptions recompute
   // fields shipped in 0.1.153.
   // 0.1.175 ships loud `deepline enrich` empty-waterfall reporting.
-  version: "0.1.194",
+  version: "0.1.196",
   apiContract: "2026-06-dataset-handle-results-hard-cutover",
   supportPolicy: {
-    latest: "0.1.194",
+    latest: "0.1.196",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53",
     commandMinimumSupported: [
@@ -1002,8 +1002,8 @@ var HttpClient = class {
             }
             const errorValue = typeof parsed === "object" && parsed && "error" in parsed ? parsed.error : void 0;
             const msg = typeof errorValue === "string" ? errorValue : errorValue && typeof errorValue === "object" && "message" in errorValue && typeof errorValue.message === "string" ? errorValue.message : typeof parsed === "object" && parsed && "message" in parsed && typeof parsed.message === "string" ? parsed.message : `HTTP ${response.status}`;
-            const apiErrorCode = errorValue && typeof errorValue === "object" && typeof errorValue.code === "string" ? errorValue.code : typeof parsed === "object" && parsed && typeof parsed.code === "string" ? parsed.code : "API_ERROR";
-            lastError = new DeeplineError(msg, response.status, apiErrorCode, {
+            const apiErrorCode2 = errorValue && typeof errorValue === "object" && typeof errorValue.code === "string" ? errorValue.code : typeof parsed === "object" && parsed && typeof parsed.code === "string" ? parsed.code : "API_ERROR";
+            lastError = new DeeplineError(msg, response.status, apiErrorCode2, {
               response: parsed
             });
             if (retryableApiError && attempt < maxRetries) {
@@ -2539,6 +2539,7 @@ var DeeplineClient = class {
       stopAll: (options2) => this.stopAllRuns(options2)
     };
     this.billing = {
+      topUp: (options2) => this.topUpBillingBalance(options2),
       plans: () => this.getBillingPlans(),
       subscription: {
         status: () => this.getBillingSubscriptionStatus(),
@@ -4220,6 +4221,28 @@ var DeeplineClient = class {
   async getBillingPlans() {
     return this.http.get("/api/v2/billing/catalog/current");
   }
+  /**
+   * Charge the saved payment method and add Deepline credits to the active
+   * workspace. Prefer `client.billing.topUp(...)`.
+   *
+   * @throws {@link DeeplineError} with `statusCode: 409` when checkout is
+   *   required because the workspace has no saved payment method or the card
+   *   requires confirmation.
+   */
+  async topUpBillingBalance(options) {
+    return this.http.post(
+      "/api/v2/billing/top-up",
+      {
+        credits: options.credits,
+        ...options.idempotencyKey ? { idempotency_key: options.idempotencyKey } : {}
+      },
+      void 0,
+      // The idempotency key makes a retry at the product layer safe, but the
+      // CLI should not hide ambiguous local delivery failures behind implicit
+      // transport retries for a payment mutation.
+      { maxRetries: 0, exactUrlOnly: true }
+    );
+  }
   /**
    * Subscription state for the active workspace: active plan, whether a
    * Stripe subscription backs it, renewal/cancellation facts, and remaining
@@ -5723,11 +5746,14 @@ Examples:
 
 // src/cli/commands/billing.ts
 import { Command } from "commander";
+import { randomUUID } from "crypto";
 import { appendFile, mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
 import { dirname as dirname5, 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";
+var BILLING_TOP_UP_PATH = "/api/v2/billing/top-up";
+var DEFAULT_BALANCE_RECOVERY_CREDITS = 100;
 function billingFailureFromError(error, options) {
   if (error instanceof AuthError) {
     return {
@@ -5776,6 +5802,107 @@ function reportBillingFailure(failure, options) {
   );
   process.exitCode = failure.exitCode;
 }
+function parseTopUpCredits(raw) {
+  const trimmed = String(raw ?? "").trim();
+  if (!/^\d+$/.test(trimmed)) return null;
+  const parsed = Number(trimmed);
+  if (!Number.isSafeInteger(parsed) || parsed <= 0) return null;
+  return parsed;
+}
+function topUpIdempotencyKey(raw) {
+  if (typeof raw === "string") {
+    const trimmed = raw.trim();
+    if (trimmed) return trimmed.slice(0, 120);
+  }
+  return `cli_topup:${Date.now()}:${randomUUID()}`;
+}
+function checkoutCommandForCredits(credits) {
+  return `deepline billing checkout --credits ${credits} --no-open --json`;
+}
+function approvedTopUpCommandForCredits(credits) {
+  return `deepline billing top-up ${credits} --json`;
+}
+function balanceRecoveryForCredits(credits = DEFAULT_BALANCE_RECOVERY_CREDITS) {
+  return {
+    recommended_credits: credits,
+    requires_user_approval: true,
+    message: "Ask the user whether they want to add Deepline credits before taking payment-related action.",
+    top_up_command: approvedTopUpCommandForCredits(credits),
+    checkout_command: checkoutCommandForCredits(credits)
+  };
+}
+function shellQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function topUpRetryCommand(credits, idempotencyKey) {
+  return `deepline billing top-up ${credits} --idempotency-key ${shellQuote(idempotencyKey)} --json`;
+}
+function apiErrorCode(error) {
+  const response = error.details?.response;
+  if (response && typeof response === "object" && !Array.isArray(response)) {
+    const code = response.code;
+    if (typeof code === "string" && code.trim()) {
+      return code.trim();
+    }
+  }
+  return error.code ?? "BILLING_API_ERROR";
+}
+function billingTopUpFailureFromError(error, input2) {
+  if (error instanceof AuthError || error instanceof ConfigError) {
+    return {
+      exitCode: 3,
+      code: "AUTH_ERROR",
+      message: error.message,
+      next: "deepline auth status --json"
+    };
+  }
+  if (!(error instanceof DeeplineError) || typeof error.statusCode !== "number") {
+    if (error instanceof DeeplineError) {
+      return {
+        exitCode: 5,
+        code: "TOP_UP_STATUS_UNKNOWN",
+        message: `${error.message} The top-up may have reached Deepline. Retry only with the same idempotency key to avoid a duplicate charge.`,
+        next: topUpRetryCommand(input2.credits, input2.idempotencyKey)
+      };
+    }
+    return null;
+  }
+  const code = apiErrorCode(error);
+  if (error.statusCode === 400) {
+    return {
+      exitCode: 2,
+      code: "INVALID_CREDITS",
+      message: error.message,
+      next: "deepline billing plans --json"
+    };
+  }
+  if (error.statusCode === 409) {
+    const checkoutNext = checkoutCommandForCredits(input2.credits);
+    return {
+      exitCode: 4,
+      code: code === "requires_action" ? "PAYMENT_REQUIRES_ACTION" : "MISSING_PAYMENT_METHOD",
+      message: error.message,
+      next: checkoutNext
+    };
+  }
+  if (error.statusCode === 402) {
+    return {
+      exitCode: 5,
+      code: "PAYMENT_FAILED",
+      message: error.message,
+      next: checkoutCommandForCredits(input2.credits)
+    };
+  }
+  if (error.statusCode >= 500) {
+    return {
+      exitCode: 5,
+      code: "BILLING_SERVER_ERROR",
+      message: `${error.message} Retry only with the same idempotency key to avoid a duplicate charge.`,
+      next: topUpRetryCommand(input2.credits, input2.idempotencyKey)
+    };
+  }
+  return null;
+}
 function humanize(value) {
   return String(value || "").split("_").filter(Boolean).map((token) => token[0]?.toUpperCase() + token.slice(1)).join(" ") || "Unknown";
 }
@@ -5873,13 +6000,29 @@ async function handleBalance(options) {
     "/api/v2/billing/balance"
   );
   const status = String(payload.balance_status || "");
-  const lines = status === "no_billing" ? [
-    "Balance: 0 credits",
-    "Billing: No billing account or payment method set up for this workspace."
-  ] : [`Balance: ${payload.balance ?? "(unknown)"} credits`];
+  const needsCredits = status === "no_billing" || status === "zero_balance" || status === "payment_method_only";
+  const recovery = needsCredits ? balanceRecoveryForCredits() : null;
+  const lines = [`Balance: ${payload.balance ?? "(unknown)"} credits`];
+  if (status === "no_billing") {
+    lines.push(
+      "Billing: No billing account or payment method set up for this workspace."
+    );
+  } else if (status === "zero_balance") {
+    lines.push("Billing: This workspace has no Deepline credits available.");
+  } else if (status === "payment_method_only") {
+    lines.push(
+      "Billing: A payment method is saved, but this workspace has no Deepline credits available."
+    );
+  }
+  if (recovery) {
+    lines.push(recovery.message);
+    lines.push(`If the user approves, run: ${recovery.top_up_command}`);
+    lines.push(`If checkout is required, run: ${recovery.checkout_command}`);
+  }
   printCommandEnvelope(
     {
       ...payload,
+      ...recovery ? { recovery } : {},
       render: { sections: [{ title: "billing balance", lines }] }
     },
     { json: options.json }
@@ -6373,6 +6516,99 @@ async function handleCheckout(options) {
     { json: options.json }
   );
 }
+async function handleTopUp(creditsRaw, options) {
+  const credits = parseTopUpCredits(creditsRaw);
+  if (credits === null) {
+    reportBillingFailure(
+      {
+        exitCode: 2,
+        code: "INVALID_CREDITS",
+        message: "<credits> must be a positive integer Deepline credit amount.",
+        next: "deepline billing plans --json"
+      },
+      options
+    );
+    return;
+  }
+  const idempotencyKey = topUpIdempotencyKey(options.idempotencyKey);
+  if (options.dryRun) {
+    printCommandEnvelope(
+      {
+        ok: true,
+        dry_run: true,
+        credits,
+        idempotency_key: idempotencyKey,
+        planned_request: {
+          method: "POST",
+          path: BILLING_TOP_UP_PATH,
+          body: { credits, idempotency_key: idempotencyKey }
+        },
+        render: {
+          sections: [
+            {
+              title: "billing top-up (dry run)",
+              lines: [
+                `Credits: ${credits}`,
+                `Idempotency key: ${idempotencyKey}`,
+                `Planned request: POST ${BILLING_TOP_UP_PATH}`,
+                "No payment request was sent. Re-run without --dry-run to apply."
+              ]
+            }
+          ]
+        }
+      },
+      { json: options.json }
+    );
+    return;
+  }
+  const client2 = new DeeplineClient();
+  let payload;
+  try {
+    payload = await client2.billing.topUp({ credits, idempotencyKey });
+  } catch (error) {
+    const failure = billingTopUpFailureFromError(error, {
+      credits,
+      idempotencyKey
+    });
+    if (!failure) throw error;
+    reportBillingFailure(failure, options);
+    return;
+  }
+  const amountText = invoiceAmountText(payload.amount_cents, payload.currency);
+  const paymentLabel = payload.payment_method?.label ?? [
+    payload.payment_method?.brand ? humanize(payload.payment_method.brand) : null,
+    payload.payment_method?.last4 ? `ending in ${payload.payment_method.last4}` : null
+  ].filter(Boolean).join(" ");
+  const compactEnvelope = {
+    ok: true,
+    credits: payload.credits,
+    amount_cents: payload.amount_cents,
+    currency: payload.currency,
+    balance_credits: payload.balance,
+    idempotency_key: idempotencyKey
+  };
+  const fullEnvelope = {
+    ...payload,
+    balance_credits: payload.balance,
+    idempotency_key: idempotencyKey,
+    render: {
+      sections: [
+        {
+          title: "billing top-up",
+          lines: [
+            `Added: ${payload.credits} Deepline Credits`,
+            `Charged: ${amountText}`,
+            `Balance: ${payload.balance} Deepline Credits`,
+            ...paymentLabel ? [`Payment method: ${paymentLabel}`] : []
+          ]
+        }
+      ]
+    }
+  };
+  printCommandEnvelope(options.compact ? compactEnvelope : fullEnvelope, {
+    json: options.json
+  });
+}
 async function handleRedeemCode(code, options) {
   const { http } = getAuthedHttpClient();
   const payload = await http.post(
@@ -6409,6 +6645,7 @@ Examples:
   deepline billing subscription status --json
 
   # Buy credits or a plan
+  deepline billing top-up 1000 --json
   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
@@ -6548,6 +6785,25 @@ 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("top-up").description("Charge the saved payment method and add Deepline credits.").addHelpText(
+    "after",
+    `
+Notes:
+  Mutates workspace billing by charging the saved payment method for the active
+  workspace, then adding purchased Deepline credits. If no saved payment method
+  is available, use the checkout command printed in the error response.
+  --dry-run prints the planned request and idempotency key without charging.
+
+Examples:
+  deepline billing top-up 1000
+  deepline billing top-up 1000 --json
+  deepline billing top-up 1000 --dry-run --json
+  deepline billing top-up 1000 --idempotency-key refill-2026-07-08 --json
+`
+  ).argument("<credits>", "Positive integer Deepline credit amount").option(
+    "--idempotency-key <key>",
+    "Stable retry key for the same intended top-up"
+  ).option("--dry-run", "Print the planned top-up without charging").option("--compact", "Keep only high-signal fields in JSON output").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleTopUp);
   billing.command("plans").description("Show published plans and the plan you are on.").addHelpText(
     "after",
     `
@@ -6668,7 +6924,7 @@ Examples:
 
 // src/cli/commands/csv.ts
 import { spawn } from "child_process";
-import { randomUUID } from "crypto";
+import { randomUUID as randomUUID2 } from "crypto";
 import {
   closeSync,
   existsSync as existsSync6,
@@ -7573,7 +7829,7 @@ async function handleCsvRenderStart(options) {
   ensureCsvRenderStateDir();
   const logPath = csvRenderLogPath();
   const logFd = openSync(logPath, "w");
-  const token = randomUUID();
+  const token = randomUUID2();
   const child = spawn(
     process.execPath,
     ["-e", CSV_RENDER_SERVER_SOURCE],
@@ -12335,6 +12591,19 @@ function formatCreditAmount(value) {
   }
   return Number(value.toFixed(8)).toString();
 }
+function recommendedTopUpCredits(value) {
+  const parsed = typeof value === "number" && Number.isFinite(value) ? value : typeof value === "string" && value.trim() ? Number(value) : NaN;
+  return Math.max(100, Number.isFinite(parsed) ? Math.ceil(parsed) : 100);
+}
+function insufficientCreditsRecoveryCommands(billing) {
+  const topUpCredits = recommendedTopUpCredits(
+    billing.recommended_add_credits ?? billing.needed_credits
+  );
+  return {
+    topUp: `deepline billing top-up ${topUpCredits} --json`,
+    checkout: `deepline billing checkout --credits ${topUpCredits} --no-open --json`
+  };
+}
 function extractJsonObjectFromText(text) {
   const start = text.indexOf("{");
   if (start < 0) {
@@ -12427,8 +12696,9 @@ function formatInsufficientCreditsMessage(input2) {
   const billingUrl = getStringField(input2.billing, "billing_url");
   const workspace = getStringField(input2.billing, "workspace_id") ?? getStringField(input2.billing, "workspaceId");
   const workspaceSuffix = workspace ? ` (workspace=${workspace})` : "";
+  const recovery = insufficientCreditsRecoveryCommands(input2.billing);
   const addSuffix = billingUrl && recommended !== "-" ? ` Add >=${recommended} at ${billingUrl}.` : billingUrl ? ` Add credits at ${billingUrl}.` : "";
-  return `Workspace balance ${balance} < required ${required} for ${operation}${workspaceSuffix}.${addSuffix}`;
+  return `Workspace balance ${balance} < required ${required} for ${operation}${workspaceSuffix}.${addSuffix} Ask the user if they want to add Deepline credits. If they approve, run: ${recovery.topUp}. If checkout is required, run: ${recovery.checkout}.`;
 }
 function buildInsufficientCreditsSummaryLines(input2) {
   const progress = input2.status.progress;
@@ -12444,11 +12714,15 @@ function buildInsufficientCreditsSummaryLines(input2) {
   const recommended = formatCreditAmount(
     input2.billing.recommended_add_credits ?? input2.billing.needed_credits
   );
+  const recovery = insufficientCreditsRecoveryCommands(input2.billing);
   if (billingUrl) {
     lines.push(
       recommended !== "-" ? `  add credits: add >=${recommended} at ${billingUrl}` : `  add credits: ${billingUrl}`
     );
   }
+  lines.push("  ask user: ask whether they want to add Deepline credits");
+  lines.push(`  top up after approval: ${recovery.topUp}`);
+  lines.push(`  checkout fallback: ${recovery.checkout}`);
   const runId = input2.status.runId?.trim();
   if (runId) {
     lines.push(`  inspect: deepline runs get ${runId} --json`);
@@ -21587,7 +21861,7 @@ import {
 import { homedir as homedir8, platform } from "os";
 import { basename as basename3, dirname as dirname8, join as join8, resolve as resolve10 } from "path";
 import { gzipSync } from "zlib";
-import { randomUUID as randomUUID2 } from "crypto";
+import { randomUUID as randomUUID3 } from "crypto";
 var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 var UUID_IN_TEXT_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
 var MAX_SESSION_UPLOAD_BYTES = 35e5;
@@ -21949,7 +22223,7 @@ async function uploadPayload(path, payload) {
   return await http.post(path, payload);
 }
 async function uploadChunkedSessions(sessions, options) {
-  const uploadId = randomUUID2();
+  const uploadId = randomUUID3();
   for (const session of sessions) {
     const bytes = Buffer.from(session.encodedContent, "base64");
     const chunks = [];
@@ -23782,7 +24056,7 @@ var EXIT_AUTH2 = 1;
 var EXIT_SERVER3 = 2;
 var MAX_PROMPT_LENGTH = 8e3;
 var MAX_BODY_BYTES = 64 * 1024;
-function shellQuote(arg) {
+function shellQuote2(arg) {
   return `'${arg.replace(/'/g, `'\\''`)}'`;
 }
 function hasClaudeBinary() {
@@ -23955,7 +24229,7 @@ async function handleQuickstart(options) {
   }
   progress.complete();
   const { prompt, workflowId } = outcome;
-  const claudeCommand = `claude ${shellQuote(prompt)}`;
+  const claudeCommand = `claude ${shellQuote2(prompt)}`;
   const claudeAvailable = hasClaudeBinary();
   const willLaunch = options.launch !== false && !jsonOutput && interactive && claudeAvailable;
   printCommandEnvelope(
@@ -25889,7 +26163,7 @@ function parseExecuteOptions(args) {
 function safeFileStem(value) {
   return value.trim().replace(/[^a-zA-Z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64) || "tool";
 }
-function shellQuote2(value) {
+function shellQuote3(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 function powerShellQuote(value) {
@@ -25959,7 +26233,7 @@ export default definePlay(${JSON.stringify(playName)}, async (ctx) => {
     path: scriptPath,
     sourceCode: script,
     projectDir,
-    macCopyCommand: `mkdir -p ${shellQuote2(projectDir)} && cp ${shellQuote2(scriptPath)} ${shellQuote2(`${projectDir}/${fileName}`)}`,
+    macCopyCommand: `mkdir -p ${shellQuote3(projectDir)} && cp ${shellQuote3(scriptPath)} ${shellQuote3(`${projectDir}/${fileName}`)}`,
     windowsCopyCommand: `New-Item -ItemType Directory -Force -Path ${powerShellQuote(projectDir.replace(/\//g, "\\"))} | Out-Null; Copy-Item -LiteralPath ${powerShellQuote(scriptPath)} -Destination ${powerShellQuote(`${projectDir.replace(/\//g, "\\")}\\${fileName}`)}`
   };
 }
@@ -25982,7 +26256,7 @@ function buildToolExecuteBaseEnvelope(input2) {
     envelope,
     "output"
   );
-  const inspectCommand = `deepline tools execute ${input2.toolId} --input ${shellQuote2(JSON.stringify(input2.params))} --json`;
+  const inspectCommand = `deepline tools execute ${input2.toolId} --input ${shellQuote3(JSON.stringify(input2.params))} --json`;
   const actions = input2.listConversion ? [
     {
       label: "next",
@@ -27060,7 +27334,7 @@ function hasCommand(command) {
   });
   return result.status === 0;
 }
-function shellQuote3(arg) {
+function shellQuote4(arg) {
   return `'${arg.replace(/'/g, `'\\''`)}'`;
 }
 function resolveSkillsInstallCommands(baseUrl, skillNames = DEFAULT_SDK_SKILL_NAMES) {
@@ -27068,7 +27342,7 @@ function resolveSkillsInstallCommands(baseUrl, skillNames = DEFAULT_SDK_SKILL_NA
   const npxInstall = {
     command: "npx",
     args: npxArgs,
-    manualCommand: `npx ${npxArgs.map(shellQuote3).join(" ")}`
+    manualCommand: `npx ${npxArgs.map(shellQuote4).join(" ")}`
   };
   if (hasCommand("bunx")) {
     const bunxArgs = buildBunxSkillsInstallArgs(baseUrl, skillNames);
@@ -27076,7 +27350,7 @@ function resolveSkillsInstallCommands(baseUrl, skillNames = DEFAULT_SDK_SKILL_NA
       {
         command: "bunx",
         args: bunxArgs,
-        manualCommand: `bunx ${bunxArgs.map(shellQuote3).join(" ")}`
+        manualCommand: `bunx ${bunxArgs.map(shellQuote4).join(" ")}`
       },
       npxInstall
     ];
@@ -27243,14 +27517,14 @@ function posixShellQuote(value) {
 function windowsCmdQuote(value) {
   return `"${value.replace(/"/g, '""')}"`;
 }
-function shellQuote4(value) {
+function shellQuote5(value) {
   if (process.platform === "win32") {
     return /^[A-Za-z0-9_./:@%+=,-]+$/.test(value) ? value : windowsCmdQuote(value);
   }
   return posixShellQuote(value);
 }
 function buildSourceUpdateCommand(sourceRoot) {
-  const quotedRoot = shellQuote4(sourceRoot);
+  const quotedRoot = shellQuote5(sourceRoot);
   const cdCommand = process.platform === "win32" ? `cd /d ${quotedRoot}` : `cd ${quotedRoot}`;
   return `${cdCommand} && git fetch origin main --tags && git merge --ff-only origin/main`;
 }
@@ -27262,7 +27536,7 @@ function buildSidecarProjectConfigCommand(versionDir, nodeBin) {
     "fs.mkdirSync(dir,{recursive:true});",
     `fs.writeFileSync(path.join(dir,'package.json'),${JSON.stringify(NPM_SDK_SIDECAR_PACKAGE_JSON)});`
   ].join("");
-  return `${shellQuote4(nodeBin)} -e ${shellQuote4(script)} ${shellQuote4(versionDir)}`;
+  return `${shellQuote5(nodeBin)} -e ${shellQuote5(script)} ${shellQuote5(versionDir)}`;
 }
 function sidecarStateDir(input2) {
   const scope = input2.env.DEEPLINE_CONFIG_SCOPE?.trim();
@@ -27301,7 +27575,7 @@ function resolvePythonSidecarUpdatePlan(options) {
   const packageSpec = options.packageSpec || "deepline@latest";
   const npmCommand = "npm";
   const versionDir = join14(stateDir, "versions", "<version>");
-  const manualCommand = `${buildSidecarProjectConfigCommand(versionDir, nodeBin)} && ${npmCommand} install --prefix ${shellQuote4(versionDir)} ${NPM_SDK_INSTALL_COMMON_FLAGS.map(shellQuote4).join(" ")} ${shellQuote4(packageSpec)}`;
+  const manualCommand = `${buildSidecarProjectConfigCommand(versionDir, nodeBin)} && ${npmCommand} install --prefix ${shellQuote5(versionDir)} ${NPM_SDK_INSTALL_COMMON_FLAGS.map(shellQuote5).join(" ")} ${shellQuote5(packageSpec)}`;
   return {
     kind: "python-sidecar",
     stateDir,
@@ -27381,7 +27655,7 @@ function resolveUpdatePlan(options = {}) {
     command,
     args,
     ...installPrefix ? { installPrefix } : {},
-    manualCommand: `${command} ${args.map(shellQuote4).join(" ")}`
+    manualCommand: `${command} ${args.map(shellQuote5).join(" ")}`
   };
 }
 var AUTO_UPDATE_FAILURE_FILE = ".auto-update-failure.json";
@@ -27542,9 +27816,9 @@ function writeSidecarLauncher(input2) {
     input2.path,
     [
       "#!/usr/bin/env sh",
-      `export DEEPLINE_HOST_URL=${shellQuote4(input2.hostUrl)}`,
-      `export DEEPLINE_CONFIG_SCOPE=${shellQuote4(input2.scope)}`,
-      `exec ${shellQuote4(input2.nodeBin)} ${shellQuote4(input2.entryPath)} "$@"`,
+      `export DEEPLINE_HOST_URL=${shellQuote5(input2.hostUrl)}`,
+      `export DEEPLINE_CONFIG_SCOPE=${shellQuote5(input2.scope)}`,
+      `exec ${shellQuote5(input2.nodeBin)} ${shellQuote5(input2.entryPath)} "$@"`,
       ""
     ].join("\n"),
     { encoding: "utf8", mode: 493 }

package/dist/index.d.mts

@@ -1396,6 +1396,27 @@ type BillingInvoicesResult = {
     org_id: string;
     entries: BillingInvoiceEntry[];
 };
+/** Saved payment method details returned by one-click billing top-up. */
+type BillingPaymentMethodSummary = {
+    brand?: string | null;
+    last4?: string | null;
+    exp_month?: number | null;
+    exp_year?: number | null;
+    label?: string | null;
+};
+/**
+ * Result of `POST /api/v2/billing/top-up`: a saved-card charge and purchased
+ * Deepline credit grant for the active workspace.
+ */
+type BillingTopUpResult = {
+    ok: true;
+    credits: number;
+    amount_cents: number;
+    currency: string;
+    balance: number;
+    stripe_payment_intent_id: string;
+    payment_method?: BillingPaymentMethodSummary | null;
+};
 /** One published plan from `GET /api/v2/billing/catalog/current`. */
 type BillingPlanEntry = {
     plan_family_id: string;
@@ -1453,6 +1474,11 @@ type BillingPlansResult = {
  * @sdkReference client 030 client.billing
  */
 type BillingNamespace = {
+    /** Charge the saved payment method and add Deepline credits to the active workspace. */
+    topUp: (options: {
+        credits: number;
+        idempotencyKey?: string;
+    }) => Promise<BillingTopUpResult>;
     /** Published plans plus the plan you are on ("what plans exist and what am I on"). */
     plans: () => Promise<BillingPlansResult>;
     subscription: {
@@ -2329,6 +2355,18 @@ declare class DeeplineClient {
      * @returns Snake_case catalog from `GET /api/v2/billing/catalog/current`
      */
     getBillingPlans(): Promise<BillingPlansResult>;
+    /**
+     * Charge the saved payment method and add Deepline credits to the active
+     * workspace. Prefer `client.billing.topUp(...)`.
+     *
+     * @throws {@link DeeplineError} with `statusCode: 409` when checkout is
+     *   required because the workspace has no saved payment method or the card
+     *   requires confirmation.
+     */
+    topUpBillingBalance(options: {
+        credits: number;
+        idempotencyKey?: string;
+    }): Promise<BillingTopUpResult>;
     /**
      * Subscription state for the active workspace: active plan, whether a
      * Stripe subscription backs it, renewal/cancellation facts, and remaining
@@ -4251,4 +4289,4 @@ declare function writeCsvOutputFile(rows: Array<Record<string, unknown>>, stem:
  */
 declare function extractSummaryFields(payload: unknown): Record<string, Scalar>;
 
-export { AuthError, type BillingCreditPool, type BillingInvoiceEntry, type BillingInvoicesResult, type BillingNamespace, type BillingSubscriptionCancelResult, type BillingSubscriptionStatus, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CsvInput, type CsvOptions, type CustomerDbQueryResult, DEEPLINE_EXTRACTOR_TARGETS, DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, type DatasetColumnDefinition, type DatasetColumnRunInput, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, type DeeplineEmailStatusGetterValue, DeeplineError, type DeeplineExtractorTarget, type DeeplineGetterValue, type DeeplineGetterValueMap, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplinePlaysNamespace, type DeeplineToolCategory, type DeeplineToolsNamespace, type DefinePlayConfig, type DefinedPlay, type FileInput, JOB_CHANGE_STATUS_VALUES, type JobChangeStatus, type LiveEventEnvelope, PHONE_STATUS_VALUES, PLAY_BOOTSTRAP_COMPANY_FIELDS, PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_CONTACT_FIELDS, PLAY_BOOTSTRAP_FINDER_KINDS, PLAY_BOOTSTRAP_OUTPUT_FIELD_BY_FINDER, PLAY_BOOTSTRAP_PEOPLE_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_PROVIDER_CATEGORY_BY_FINDER, PLAY_BOOTSTRAP_SOURCE_KINDS, PLAY_BOOTSTRAP_STAGE_KINDS, PLAY_BOOTSTRAP_TEMPLATES, PROD_URL, type PhoneStatus, type PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayDataset, type PlayDatasetInput, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayRevisionSummary, type PlayRunResult, type PlayRunStart, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PrebuiltPlayRef, type PreviousCell, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type ResolvedConfig, RunObserveTransportUnavailableError, type RunsListOptions, type RunsLogsOptions, type RunsLogsResult, type RunsNamespace, type RunsTailOptions, SDK_API_CONTRACT, SDK_VERSION, type SqlListenerDeclaration, type SqlListenerEvent, type SqlListenerOperation, type SqlQuery, type StartPlayRunRequest, type StepOptions, type StepProgram, type StepProgramResolver, type StepResolver, type StopPlayRunResult, type ToolDefinition, type ToolExecuteResult, type ToolExecution, type ToolExecutionRequest, type ToolMetadata, type ToolSearchOptions, type ToolSearchResult, defineInput, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isDeeplineExtractorTarget, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, resolveConfig, runIf, steps, tryConvertToList, writeCsvOutputFile, writeJsonOutputFile };
+export { AuthError, type BillingCreditPool, type BillingInvoiceEntry, type BillingInvoicesResult, type BillingNamespace, type BillingPaymentMethodSummary, type BillingSubscriptionCancelResult, type BillingSubscriptionStatus, type BillingTopUpResult, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CsvInput, type CsvOptions, type CustomerDbQueryResult, DEEPLINE_EXTRACTOR_TARGETS, DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, type DatasetColumnDefinition, type DatasetColumnRunInput, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, type DeeplineEmailStatusGetterValue, DeeplineError, type DeeplineExtractorTarget, type DeeplineGetterValue, type DeeplineGetterValueMap, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplinePlaysNamespace, type DeeplineToolCategory, type DeeplineToolsNamespace, type DefinePlayConfig, type DefinedPlay, type FileInput, JOB_CHANGE_STATUS_VALUES, type JobChangeStatus, type LiveEventEnvelope, PHONE_STATUS_VALUES, PLAY_BOOTSTRAP_COMPANY_FIELDS, PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_CONTACT_FIELDS, PLAY_BOOTSTRAP_FINDER_KINDS, PLAY_BOOTSTRAP_OUTPUT_FIELD_BY_FINDER, PLAY_BOOTSTRAP_PEOPLE_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_PROVIDER_CATEGORY_BY_FINDER, PLAY_BOOTSTRAP_SOURCE_KINDS, PLAY_BOOTSTRAP_STAGE_KINDS, PLAY_BOOTSTRAP_TEMPLATES, PROD_URL, type PhoneStatus, type PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayDataset, type PlayDatasetInput, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayRevisionSummary, type PlayRunResult, type PlayRunStart, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PrebuiltPlayRef, type PreviousCell, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type ResolvedConfig, RunObserveTransportUnavailableError, type RunsListOptions, type RunsLogsOptions, type RunsLogsResult, type RunsNamespace, type RunsTailOptions, SDK_API_CONTRACT, SDK_VERSION, type SqlListenerDeclaration, type SqlListenerEvent, type SqlListenerOperation, type SqlQuery, type StartPlayRunRequest, type StepOptions, type StepProgram, type StepProgramResolver, type StepResolver, type StopPlayRunResult, type ToolDefinition, type ToolExecuteResult, type ToolExecution, type ToolExecutionRequest, type ToolMetadata, type ToolSearchOptions, type ToolSearchResult, defineInput, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isDeeplineExtractorTarget, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, resolveConfig, runIf, steps, tryConvertToList, writeCsvOutputFile, writeJsonOutputFile };