deepline 0.1.194 → 0.1.195

package/dist/bundling-sources/apps/play-runner-workers/src/coordinator-entry.ts

@@ -31,21 +31,13 @@ import type { RuntimeTestPolicyOverrides } from '../../../shared_libs/play-runti
 import { DYNAMIC_PLAY_WORKER_ARTIFACT_VERSION } from '../../../shared_libs/play-runtime/dynamic-worker-version';
 import {
   DB_SESSION_DEFAULT_TTL_SECONDS,
-  createDbSessionResponseSchema,
-  type CreateDbSessionResponse,
   type PreloadedRuntimeDbSession,
 } from '../../../shared_libs/play-runtime/db-session';
 import {
   dbSessionPostgresUrlAad,
-  decryptDbSessionPostgresUrlWithPrivateKey,
   encryptDbSessionPostgresUrl,
-  generateDbSessionPostgresUrlDecryptionKey,
-  type PostgresUrlDecryptionKey,
 } from '../../../shared_libs/play-runtime/db-session-crypto';
-import {
-  planRuntimeDbSessionRequirements,
-  type RuntimeDbSessionRequirement,
-} from '../../../shared_libs/play-runtime/db-session-plan';
+import { planRuntimeDbSessionRequirements } from '../../../shared_libs/play-runtime/db-session-plan';
 import type {
   PlayRuntimeManifest,
   PlayRuntimeManifestMap,
@@ -66,7 +58,6 @@ import {
 } from '../../../shared_libs/play-runtime/runtime-contract';
 import {
   PLAY_RUNTIME_API_COMPAT_PATH,
-  PLAY_RUNTIME_CHILD_EXECUTOR_TOKEN_COMPAT_PATH,
   PLAY_RUNTIME_TAIL_LOG_COMPAT_PATH,
 } from '../../../shared_libs/play-runtime/runtime-api-paths';
 import {
@@ -1836,286 +1827,6 @@ async function restartWorkflowAfterPlatformReset(input: {
   }
 }
 
-async function mintChildWorkflowExecutorToken(input: {
-  env: CoordinatorEnv;
-  baseUrl: string;
-  parentExecutorToken: string;
-  parentRunId: string;
-  parentPlayName: string;
-  childRunId: string;
-  childPlayName: string;
-  maxCreditsPerRun?: number | null;
-}): Promise<string> {
-  const response = await input.env.HARNESS.runtimeApiCall({
-    contract: PLAY_RUNTIME_CONTRACT,
-    executorToken: input.parentExecutorToken,
-    baseUrl: input.baseUrl,
-    path: PLAY_RUNTIME_CHILD_EXECUTOR_TOKEN_COMPAT_PATH,
-    headers: {
-      'x-deepline-request-id': crypto.randomUUID(),
-      [PLAY_RUNTIME_CONTRACT_HEADER]: String(PLAY_RUNTIME_CONTRACT),
-    },
-    timeoutMs: 15_000,
-    body: {
-      parentRunId: input.parentRunId,
-      parentPlayName: input.parentPlayName,
-      childRunId: input.childRunId,
-      childPlayName: input.childPlayName,
-      maxCreditsPerRun: input.maxCreditsPerRun ?? null,
-    },
-  });
-  const text = response.body;
-  let parsed: Record<string, unknown> = {};
-  try {
-    parsed = text ? (JSON.parse(text) as Record<string, unknown>) : {};
-  } catch {
-    parsed = {};
-  }
-  if (response.status < 200 || response.status >= 300) {
-    const error = isRecord(parsed.error) ? parsed.error : null;
-    const message =
-      (typeof error?.message === 'string' && error.message.trim()) ||
-      (typeof parsed.error === 'string' && parsed.error.trim()) ||
-      text.slice(0, 800) ||
-      `Origin child executor token mint failed with ${response.status}.`;
-    throw new Error(message);
-  }
-  const executorToken = parsed.executorToken;
-  if (typeof executorToken !== 'string' || !executorToken.trim()) {
-    throw new Error(
-      'Origin child executor token response was missing executorToken.',
-    );
-  }
-  return executorToken;
-}
-
-function stripDbSessionUrl(
-  session: CreateDbSessionResponse,
-): Omit<CreateDbSessionResponse, 'postgresUrl' | 'encryptedPostgresUrl'> {
-  const {
-    postgresUrl: _postgresUrl,
-    encryptedPostgresUrl: _encryptedPostgresUrl,
-    ...sessionWithoutUrl
-  } = session;
-  void _postgresUrl;
-  void _encryptedPostgresUrl;
-  return sessionWithoutUrl;
-}
-
-function assertChildDbSessionScope(input: {
-  session: CreateDbSessionResponse;
-  requirement: RuntimeDbSessionRequirement;
-  orgId: string;
-  childPlayName: string;
-}): void {
-  const { session, requirement, orgId, childPlayName } = input;
-  if (
-    session.playName !== childPlayName ||
-    session.target.orgId !== orgId ||
-    session.target.tableNamespace !== requirement.tableNamespace ||
-    session.target.logicalTable !== requirement.logicalTable
-  ) {
-    throw new Error(
-      'Runtime API returned a DB session outside the child play scope.',
-    );
-  }
-  const expectedOperations = [...requirement.operations].sort().join(',');
-  const actualOperations = [...session.operations].sort().join(',');
-  if (actualOperations !== expectedOperations) {
-    throw new Error(
-      'Runtime API returned a DB session with unexpected operations.',
-    );
-  }
-}
-
-async function reencryptChildDbSessionForExecutor(input: {
-  session: CreateDbSessionResponse;
-  decryptionKey: PostgresUrlDecryptionKey;
-  childExecutorToken: string;
-}): Promise<CreateDbSessionResponse> {
-  const sessionWithoutUrl = stripDbSessionUrl(input.session);
-  if (!input.session.encryptedPostgresUrl) {
-    throw new Error('Runtime API returned an unencrypted DB session URL.');
-  }
-  const postgresUrl = await decryptDbSessionPostgresUrlWithPrivateKey({
-    encrypted: input.session.encryptedPostgresUrl,
-    privateKey: input.decryptionKey.privateKey,
-    aad: dbSessionPostgresUrlAad(sessionWithoutUrl),
-  });
-  return {
-    ...sessionWithoutUrl,
-    encryptedPostgresUrl: await encryptDbSessionPostgresUrl({
-      postgresUrl,
-      secret: input.childExecutorToken,
-      aad: dbSessionPostgresUrlAad(sessionWithoutUrl),
-    }),
-  };
-}
-
-async function createChildRuntimeDbSession(input: {
-  env: CoordinatorEnv;
-  baseUrl: string;
-  childExecutorToken: string;
-  childPlayName: string;
-  requirement: RuntimeDbSessionRequirement;
-  userEmail: string;
-  orgId: string;
-}): Promise<CreateDbSessionResponse> {
-  const decryptionKey = await generateDbSessionPostgresUrlDecryptionKey();
-  const response = await input.env.HARNESS.runtimeApiCall({
-    contract: PLAY_RUNTIME_CONTRACT,
-    executorToken: input.childExecutorToken,
-    baseUrl: input.baseUrl,
-    path: PLAY_RUNTIME_API_COMPAT_PATH,
-    headers: {
-      'x-deepline-request-id': crypto.randomUUID(),
-      [PLAY_RUNTIME_CONTRACT_HEADER]: String(PLAY_RUNTIME_CONTRACT),
-    },
-    timeoutMs: 15_000,
-    body: {
-      action: 'create_db_session',
-      playName: input.childPlayName,
-      target: {
-        tableNamespace: input.requirement.tableNamespace,
-        logicalTable: input.requirement.logicalTable,
-      },
-      operations: input.requirement.operations,
-      limits: input.requirement.limits,
-      sheetContract: input.requirement.sheetContract ?? null,
-      ttlSeconds: DB_SESSION_DEFAULT_TTL_SECONDS,
-      userEmail: input.userEmail,
-      postgresUrlEncryption: decryptionKey.request,
-    },
-  });
-  const text = response.body;
-  let parsed: unknown = {};
-  try {
-    parsed = text ? JSON.parse(text) : {};
-  } catch {
-    parsed = {};
-  }
-  if (response.status < 200 || response.status >= 300) {
-    const error =
-      isRecord(parsed) && isRecord(parsed.error) ? parsed.error : {};
-    const message =
-      (typeof error.message === 'string' && error.message.trim()) ||
-      (isRecord(parsed) &&
-      typeof parsed.error === 'string' &&
-      parsed.error.trim()
-        ? parsed.error.trim()
-        : '') ||
-      text.slice(0, 800) ||
-      `Origin DB session mint failed with ${response.status}.`;
-    throw new Error(message);
-  }
-  const session = createDbSessionResponseSchema.parse(parsed);
-  assertChildDbSessionScope({
-    session,
-    requirement: input.requirement,
-    orgId: input.orgId,
-    childPlayName: input.childPlayName,
-  });
-  return await reencryptChildDbSessionForExecutor({
-    session,
-    decryptionKey,
-    childExecutorToken: input.childExecutorToken,
-  });
-}
-
-async function preloadChildRuntimeDbSessions(input: {
-  env: CoordinatorEnv;
-  baseUrl: string;
-  childExecutorToken: string;
-  childRunId: string;
-  childPlayName: string;
-  manifest: PlayRuntimeManifest;
-  orgId: string;
-  userEmail: string;
-}): Promise<PreloadedRuntimeDbSession[]> {
-  const startedAt = Date.now();
-  const requirements = planRuntimeDbSessionRequirements(
-    input.manifest.staticPipeline ?? null,
-  );
-  const sessions = await Promise.all(
-    requirements.map(async (requirement) => ({
-      tableNamespace: requirement.tableNamespace,
-      logicalTable: requirement.logicalTable,
-      operations: requirement.operations,
-      ...(requirement.limits ? { limits: requirement.limits } : {}),
-      session: await createChildRuntimeDbSession({
-        env: input.env,
-        baseUrl: input.baseUrl,
-        childExecutorToken: input.childExecutorToken,
-        childPlayName: input.childPlayName,
-        requirement,
-        userEmail: input.userEmail,
-        orgId: input.orgId,
-      }),
-    })),
-  );
-  recordCoordinatorPerfTrace({
-    runId: input.childRunId,
-    phase: 'coordinator.child_db_session_preload',
-    ms: Date.now() - startedAt,
-    graphHash: input.manifest.graphHash,
-    extra: { sessions: sessions.length },
-  });
-  return sessions;
-}
-
-async function registerChildRunWithRuntime(input: {
-  env: CoordinatorEnv;
-  baseUrl: string;
-  childExecutorToken: string;
-  childRunId: string;
-  childPlayName: string;
-  manifest: PlayRuntimeManifest;
-  governance: PlayCallGovernanceSnapshot;
-  runtimeBackend: string;
-  schedulerBackend: string;
-  executionProfile: string;
-}): Promise<void> {
-  const response = await input.env.HARNESS.runtimeApiCall({
-    contract: PLAY_RUNTIME_CONTRACT,
-    executorToken: input.childExecutorToken,
-    baseUrl: input.baseUrl,
-    path: PLAY_RUNTIME_API_COMPAT_PATH,
-    headers: {
-      'x-deepline-request-id': crypto.randomUUID(),
-      [PLAY_RUNTIME_CONTRACT_HEADER]: String(PLAY_RUNTIME_CONTRACT),
-    },
-    timeoutMs: 15_000,
-    body: {
-      action: 'start_inline_child_run',
-      playName: input.childPlayName,
-      runId: input.childRunId,
-      parentRunId: input.governance.parentRunId,
-      rootRunId: input.governance.rootRunId,
-      workflowFamilyKey:
-        input.governance.rootRunId ??
-        input.governance.parentRunId ??
-        input.childRunId,
-      artifactStorageKey: input.manifest.artifactStorageKey,
-      artifactHash: input.manifest.artifactHash,
-      graphHash: input.manifest.graphHash,
-      runtimeBackend: input.runtimeBackend,
-      schedulerBackend: input.schedulerBackend,
-      executionProfile: input.executionProfile,
-      ...(typeof input.manifest.maxCreditsPerRun === 'number'
-        ? { maxCreditsPerRun: input.manifest.maxCreditsPerRun }
-        : {}),
-      staticPipeline: input.manifest.staticPipeline ?? null,
-      source: 'published',
-    },
-  });
-  if (response.status < 200 || response.status >= 300) {
-    const text = response.body ?? '';
-    throw new Error(
-      `Inline child run registration failed ${response.status}: ${text.slice(0, 800)}`,
-    );
-  }
-}
-
 async function markRegisteredChildRunFailed(input: {
   env: CoordinatorEnv;
   baseUrl: string;
@@ -2310,6 +2021,9 @@ async function prepareInlineChildRunWithRuntime(input: {
   manifest: PlayRuntimeManifest;
   governance: PlayCallGovernanceSnapshot;
   userEmail: string;
+  runtimeBackend?: string;
+  schedulerBackend?: string;
+  executionProfile?: string;
 }): Promise<{
   childToken: string;
   preloadedDbSessions: PreloadedRuntimeDbSession[];
@@ -2334,9 +2048,9 @@ async function prepareInlineChildRunWithRuntime(input: {
       artifactStorageKey: input.manifest.artifactStorageKey,
       artifactHash: input.manifest.artifactHash,
       graphHash: input.manifest.graphHash,
-      runtimeBackend: 'workers_edge',
-      schedulerBackend: 'inline_child',
-      executionProfile: 'workers_edge',
+      runtimeBackend: input.runtimeBackend ?? 'workers_edge',
+      schedulerBackend: input.schedulerBackend ?? 'inline_child',
+      executionProfile: input.executionProfile ?? 'workers_edge',
       ...(typeof input.manifest.maxCreditsPerRun === 'number'
         ? { maxCreditsPerRun: input.manifest.maxCreditsPerRun }
         : {}),
@@ -3218,43 +2932,39 @@ async function submitChildWorkflowThroughCoordinator(input: {
   });
   const baseUrl = resolveRuntimeApiBaseUrl(input.env, input.body);
 
-  const tokenStartedAt = Date.now();
-  const childToken = await mintChildWorkflowExecutorToken({
-    env: input.env,
-    baseUrl,
-    parentExecutorToken,
-    parentRunId: input.parentRunId,
-    parentPlayName:
-      typeof input.body.parentPlayName === 'string' &&
-      input.body.parentPlayName.trim()
-        ? input.body.parentPlayName.trim()
-        : governance.parentPlayName,
-    childRunId,
-    childPlayName,
-    maxCreditsPerRun: manifest.maxCreditsPerRun ?? null,
-  });
-  trace('coordinator.child_submit_token', tokenStartedAt, manifest.graphHash, {
-    childRunId,
-    childPlayName,
-  });
-
-  const dbSessionStartedAt = Date.now();
-  const preloadedDbSessions = await preloadChildRuntimeDbSessions({
-    env: input.env,
-    baseUrl,
-    childExecutorToken: childToken,
-    childRunId,
-    childPlayName,
-    manifest,
-    orgId,
-    userEmail:
-      typeof input.body.userEmail === 'string' ? input.body.userEmail : '',
-  });
+  const prepareStartedAt = Date.now();
+  const { childToken, preloadedDbSessions, prepareTimings, transportTimings } =
+    await prepareInlineChildRunWithRuntime({
+      env: input.env,
+      baseUrl,
+      parentExecutorToken,
+      parentRunId: input.parentRunId,
+      parentPlayName:
+        typeof input.body.parentPlayName === 'string' &&
+        input.body.parentPlayName.trim()
+          ? input.body.parentPlayName.trim()
+          : governance.parentPlayName,
+      childRunId,
+      childPlayName,
+      manifest,
+      governance,
+      userEmail:
+        typeof input.body.userEmail === 'string' ? input.body.userEmail : '',
+      runtimeBackend: 'cf_workflows_dynamic_worker',
+      schedulerBackend: 'cf_workflows',
+      executionProfile: 'workers_edge',
+    });
   trace(
-    'coordinator.child_submit_db_session_preload',
-    dbSessionStartedAt,
+    'coordinator.child_submit_prepare',
+    prepareStartedAt,
     manifest.graphHash,
-    { childRunId, sessions: preloadedDbSessions.length },
+    {
+      childRunId,
+      childPlayName,
+      sessions: preloadedDbSessions.length,
+      prepareTimings,
+      transportTimings,
+    },
   );
 
   const params = buildChildWorkflowParams({
@@ -3274,29 +2984,6 @@ async function submitChildWorkflowThroughCoordinator(input: {
       preloadedDbSessions.length > 0 ? preloadedDbSessions : null,
   });
 
-  const registerStartedAt = Date.now();
-  await registerChildRunWithRuntime({
-    env: input.env,
-    baseUrl,
-    childExecutorToken: childToken,
-    childRunId,
-    childPlayName,
-    manifest,
-    governance,
-    runtimeBackend: 'cf_workflows_dynamic_worker',
-    schedulerBackend: 'cf_workflows',
-    executionProfile: 'workers_edge',
-  });
-  trace(
-    'coordinator.child_submit_register_run',
-    registerStartedAt,
-    manifest.graphHash,
-    {
-      childRunId,
-      childPlayName,
-    },
-  );
-
   const workflowSubmitStartedAt = Date.now();
   let response: Response | null = null;
   let responseText = '';

package/dist/bundling-sources/apps/play-runner-workers/src/entry.ts

@@ -1323,6 +1323,14 @@ function redactSecretsFromLogString(value: string): string {
     );
 }
 
+function safeRuntimeApiOrigin(value: string): string {
+  try {
+    return new URL(value).origin;
+  } catch {
+    return '<invalid>';
+  }
+}
+
 async function postRuntimeApi<T>(
   baseUrl: string,
   executorToken: string,
@@ -1336,6 +1344,9 @@ async function postRuntimeApi<T>(
   // Routes through the in-process RUNTIME_API service binding. Missing binding
   // is an infra error in workers_edge, not a reason to fall back to public HTTP.
   const serializedBody = JSON.stringify(body);
+  const requestDescription = describeRuntimeApiBody(body);
+  const maxAttempts = RUNTIME_API_RETRY_DELAYS_MS.length + 1;
+  const baseOrigin = safeRuntimeApiOrigin(baseUrl);
   let lastError: unknown = null;
   for (
     let attempt = 0;
@@ -1343,6 +1354,7 @@ async function postRuntimeApi<T>(
     attempt += 1
   ) {
     let res: Response;
+    const requestId = makeRequestId();
     try {
       res = await fetchRuntimeApi(
         baseUrl,
@@ -1352,7 +1364,7 @@ async function postRuntimeApi<T>(
           headers: {
             'content-type': 'application/json',
             authorization: `Bearer ${executorToken}`,
-            'x-deepline-request-id': makeRequestId(),
+            'x-deepline-request-id': requestId,
             ...(options.runtimeTestFaultHeader?.trim()
               ? {
                   [PLAY_RUNTIME_TEST_FAULT_HEADER]:
@@ -1373,8 +1385,25 @@ async function postRuntimeApi<T>(
         attempt >= RUNTIME_API_RETRY_DELAYS_MS.length ||
         !isRetryableWorkerRuntimeApiError(error)
       ) {
+        console.warn('[play-harness.runtime_api.exhausted]', {
+          request: requestDescription,
+          attempt: attempt + 1,
+          maxAttempts,
+          requestId,
+          baseOrigin,
+          error: error instanceof Error ? error.message : String(error),
+        });
         throw error;
       }
+      console.warn('[play-harness.runtime_api.retry]', {
+        request: requestDescription,
+        attempt: attempt + 1,
+        maxAttempts,
+        requestId,
+        baseOrigin,
+        retryInMs: RUNTIME_API_RETRY_DELAYS_MS[attempt] ?? 0,
+        error: error instanceof Error ? error.message : String(error),
+      });
       await sleepRuntimeApiRetry(attempt);
       continue;
     }
@@ -1390,8 +1419,27 @@ async function postRuntimeApi<T>(
       attempt >= RUNTIME_API_RETRY_DELAYS_MS.length ||
       !isRetryableRuntimeApiResponse(res.status, text)
     ) {
+      console.warn('[play-harness.runtime_api.exhausted]', {
+        request: requestDescription,
+        attempt: attempt + 1,
+        maxAttempts,
+        requestId,
+        baseOrigin,
+        status: res.status,
+        body: redacted,
+      });
       throw lastError;
     }
+    console.warn('[play-harness.runtime_api.retry]', {
+      request: requestDescription,
+      attempt: attempt + 1,
+      maxAttempts,
+      requestId,
+      baseOrigin,
+      status: res.status,
+      retryInMs: RUNTIME_API_RETRY_DELAYS_MS[attempt] ?? 0,
+      body: redacted,
+    });
     await sleepRuntimeApiRetry(attempt);
   }
   throw lastError instanceof Error ? lastError : new Error(String(lastError));

package/dist/bundling-sources/apps/play-runner-workers/src/workflow-retry.ts

@@ -15,6 +15,31 @@ export type WorkflowRetryDecision =
       message: string | null;
     };
 
+function workflowRetryReasonForFailure(failure: {
+  code: string;
+  cause?: string;
+}): string {
+  if (failure.code === 'PLATFORM_WORKER_SUBREQUEST_INTERRUPTED') {
+    return 'cloudflare_worker_subrequest_limit';
+  }
+  if (
+    failure.cause &&
+    /runtime API 404:[\s\S]*(?:DeploymentNotFound|DEPLOYMENT_NOT_FOUND|requested deployment .*exist|deployment could not be found on Vercel)/i.test(
+      failure.cause,
+    )
+  ) {
+    return 'vercel_runtime_api_deployment_missing';
+  }
+  return 'cloudflare_durable_object_reset';
+}
+
+function workflowRetryExhaustedReasonForFailure(failure: {
+  code: string;
+  cause?: string;
+}): string {
+  return `${workflowRetryReasonForFailure(failure)}_retry_exhausted`;
+}
+
 export function decideWorkflowPlatformRetry(input: {
   workflowStatus: string;
   error: string | null;
@@ -33,10 +58,7 @@ export function decideWorkflowPlatformRetry(input: {
   ) {
     return {
       action: 'retry',
-      reason:
-        failure.code === 'PLATFORM_WORKER_SUBREQUEST_INTERRUPTED'
-          ? 'cloudflare_worker_subrequest_limit'
-          : 'cloudflare_durable_object_reset',
+      reason: workflowRetryReasonForFailure(failure),
       nextAttempt: input.retryAttempts + 1,
       message: failure.message,
     };
@@ -44,9 +66,7 @@ export function decideWorkflowPlatformRetry(input: {
   return {
     action: 'fail',
     reason: retryablePlatformReset
-      ? failure.code === 'PLATFORM_WORKER_SUBREQUEST_INTERRUPTED'
-        ? 'cloudflare_worker_subrequest_limit_retry_exhausted'
-        : 'cloudflare_durable_object_reset_retry_exhausted'
+      ? workflowRetryExhaustedReasonForFailure(failure)
       : null,
     message: failure.message,
   };

package/dist/bundling-sources/sdk/src/client.ts

@@ -494,6 +494,29 @@ export type BillingInvoicesResult = {
   entries: BillingInvoiceEntry[];
 };
 
+/** Saved payment method details returned by one-click billing top-up. */
+export 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.
+ */
+export 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`. */
 export type BillingPlanEntry = {
   plan_family_id: string;
@@ -553,6 +576,11 @@ export type BillingPlansResult = {
  * @sdkReference client 030 client.billing
  */
 export 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: {
@@ -701,7 +729,10 @@ const STAGE_LEGACY_MULTIPART_MAX_BYTES = 4_000_000;
 
 const STAGE_DIRECT_UPLOAD_MAX_ATTEMPTS = 3;
 
-function stagedUploadIdentity(logicalPath: string, contentHash: string): string {
+function stagedUploadIdentity(
+  logicalPath: string,
+  contentHash: string,
+): string {
   return `${contentHash}:${logicalPath}`;
 }
 
@@ -1021,6 +1052,7 @@ export class DeeplineClient {
       stopAll: (options) => this.stopAllRuns(options),
     };
     this.billing = {
+      topUp: (options) => this.topUpBillingBalance(options),
       plans: () => this.getBillingPlans(),
       subscription: {
         status: () => this.getBillingSubscriptionStatus(),
@@ -3251,6 +3283,34 @@ export class DeeplineClient {
     return this.http.get<BillingPlansResult>('/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: {
+    credits: number;
+    idempotencyKey?: string;
+  }): Promise<BillingTopUpResult> {
+    return this.http.post<BillingTopUpResult>(
+      '/api/v2/billing/top-up',
+      {
+        credits: options.credits,
+        ...(options.idempotencyKey
+          ? { idempotency_key: options.idempotencyKey }
+          : {}),
+      },
+      undefined,
+      // 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

package/dist/bundling-sources/sdk/src/index.ts

@@ -62,8 +62,10 @@ export type {
   BillingInvoiceEntry,
   BillingInvoicesResult,
   BillingNamespace,
+  BillingPaymentMethodSummary,
   BillingSubscriptionCancelResult,
   BillingSubscriptionStatus,
+  BillingTopUpResult,
   PlayStatus,
   PlaySheetRow,
   PlaySheetRowsResult,