deepline 0.3.89 → 0.3.91

package/contracts/install-commands.json

@@ -0,0 +1,29 @@
+{
+  "skills": {
+    "index_path": "/.well-known/skills/index.json",
+    "default_agents": [
+      "codex",
+      "claude-code",
+      "cursor",
+      "gemini-cli",
+      "antigravity"
+    ],
+    "npx_binary": "npx",
+    "npx_add_args_template": [
+      "--yes",
+      "skills@1.5.15",
+      "add",
+      "{skills_source_url}",
+      "--agent",
+      "{agents}",
+      "--global",
+      "--yes",
+      "--skill",
+      "{skill_name}",
+      "--full-depth"
+    ]
+  },
+  "cli": {
+    "sdk_npm_global": "npm install -g deepline@latest"
+  }
+}

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

@@ -1,3 +1,4 @@
+import { iterateCursorPages } from './pagination.js';
 /**
  * The main API client for interacting with the Deepline platform.
  *
@@ -37,7 +38,10 @@ import { resolveConfig } from './config.js';
 import { DeeplineError } from './errors.js';
 import { HttpClient } from './http.js';
 import { PRODUCT_NOTIFICATION_SLACK_OAUTH_SCOPES } from '../../shared_libs/product-notifications/contract.js';
-import { normalizeProductNotificationEmail } from '../../shared_libs/product-notifications/configuration.js';
+import {
+  DEFAULT_PRODUCT_NOTIFICATION_DELIVERY_TIMING,
+  normalizeProductNotificationEmail,
+} from '../../shared_libs/product-notifications/configuration.js';
 import {
   type ProductNotificationConfigurationChange,
   type EffectiveProductNotificationDestination,
@@ -592,6 +596,35 @@ export type RunsListOptions = {
   offset?: number;
 };
 
+/** One server page; legacy runs.list continues to return an array. */
+export type RunsListPage = {
+  runs: PlayRunListItem[];
+  total?: number;
+  offset?: number;
+  limit?: number;
+  hasMore?: boolean;
+};
+
+export type PlaysListOptions = {
+  origin?: 'prebuilt' | 'owned';
+  grep?: string;
+  /**
+   * @deprecated Grep is always evaluated by the Convex full-text index.
+   * This retained option is ignored for source compatibility.
+   */
+  grepMode?: 'all' | 'any' | 'phrase';
+  categories?: string | string[];
+  includeToolCategories?: boolean;
+  includeArchived?: boolean;
+  includeCostEstimates?: boolean;
+};
+
+export type PlaysListPage = {
+  plays: PlayListItem[];
+  cursor: string | null;
+  hasMore: boolean;
+};
+
 /** Options for `client.runs.get(...)`. */
 export type RunsGetOptions = {
   /** Return the raw status payload instead of the compact package. */
@@ -716,6 +749,7 @@ export type PlaySecretMetadata = {
   scope: 'org' | 'play';
   playName?: string;
   name: string;
+  note?: string;
   status: string;
   hasValue: boolean;
   createdAt: number;
@@ -732,11 +766,8 @@ export type PlaySecretCheck = {
 };
 
 /**
- * Public runs namespace exposed as `client.runs`.
- *
- * This namespace mirrors the canonical `/api/v2/runs` resource family and is
- * the preferred low-level surface for polling, streaming, stopping, reading
- * logs, and exporting durable dataset rows.
+ * `client.runs` mirrors `/api/v2/runs`: the preferred low-level surface for
+ * polling, streaming, stopping, reading logs, and exporting durable dataset rows.
  *
  * @sdkReference client 020 client.runs
  */
@@ -761,6 +792,8 @@ export type RunsNamespace = {
   }>;
   /** List runs for one play, optionally filtered by status. */
   list: (options: RunsListOptions) => Promise<PlayRunListItem[]>;
+  /** Read one run page with total, offset, limit and completeness metadata. */
+  listPage: (options: RunsListOptions) => Promise<RunsListPage>;
   /** Stream run events and return the latest/terminal run status. */
   tail: (runId: string, options?: RunsTailOptions) => Promise<PlayStatus>;
   /** Fetch persisted log lines for a run. */
@@ -1053,7 +1086,13 @@ export type MonitorBatchOperationResult = {
   rejoined?: boolean;
   operation: {
     runId: string;
-    kind: 'audit' | 'deactivate' | 'reactivate' | 'deploy' | 'repair';
+    kind:
+      | 'audit'
+      | 'converge'
+      | 'deactivate'
+      | 'reactivate'
+      | 'deploy'
+      | 'repair';
     state: 'running' | 'retry_scheduled' | 'completed' | 'failed';
     dryRun: boolean;
     scope: unknown;
@@ -1149,6 +1188,11 @@ export type MonitorsHealth = {
   };
   converged: number;
   needs_repair: number;
+  /**
+   * Unknown records without an upstream resource id. Use the exact inventory
+   * reconciler to align them; ordinary repair never guesses an identity.
+   */
+  alignment_required: number;
   /** Observed active, but nothing delivered inside `silent_window_days`. */
   silent: number;
   silent_window_days: number;
@@ -1168,12 +1212,30 @@ export type MonitorsHealth = {
   /** Bounded current durable monitor work, if the server supports it. */
   batch_operations?: Array<{
     run_id: string;
-    kind: 'audit' | 'deactivate' | 'reactivate' | 'repair' | 'deploy';
+    kind:
+      | 'audit'
+      | 'converge'
+      | 'deactivate'
+      | 'reactivate'
+      | 'repair'
+      | 'deploy';
     state: 'running' | 'retry_scheduled';
     updated_at: number;
     next_attempt_at?: number;
     summary?: Record<string, unknown>;
   }>;
+  /** Bounded sample explaining why normal audit did not settle the row. */
+  unaudited_monitors: Array<{
+    monitor_key: string;
+    tool: string;
+    observed: 'unknown' | null;
+    observed_at: number | null;
+    provider_resource_id: string | null;
+    reason:
+      | 'not_yet_audited'
+      | 'missing_provider_resource_id'
+      | 'provider_observation_unknown';
+  }>;
 };
 
 /** One bounded audit pass, from `POST /api/v2/monitors/audit`. */
@@ -1316,6 +1378,8 @@ export type MonitorsNamespace = {
 
 /** One credit grant pool reported by the billing subscription status endpoint. */
 export type BillingCreditPool = {
+  /** Stable grant identity; optional when talking to an older server. */
+  grant_id?: string;
   pool: string;
   credits_remaining: number;
   credits_granted: number;
@@ -1400,12 +1464,13 @@ export type TargetBillingOperation = {
 };
 
 export type TargetBillingPlan = {
-  sku: 'payg-v1' | 'builder-v1' | 'team-v1';
+  sku: 'payg-v1' | 'builder-v1' | 'growth-v1' | 'growth-canary-v1' | 'team-v1';
   name: string;
   recurring_price_usd: number;
-  interval: 'month';
+  interval: 'month' | 'year';
   included_credits: number;
   purchased_credit_price_usd: number;
+  acquisition_enabled: boolean;
 };
 
 export type TargetBillingPlansResult = {
@@ -1414,6 +1479,7 @@ export type TargetBillingPlansResult = {
   current_plan_sku: string;
   pending_plan_sku: string | null;
   acquisition_enabled: boolean;
+  enabled_offer_keys: TargetBillingPlan['sku'][];
 };
 
 export type TargetBillingStatusResult = {
@@ -1443,6 +1509,8 @@ export type TargetAutoRechargeResult = {
   threshold_credits: number | null;
   refill_to_credits: number | null;
   rolling_limit_cents: null;
+  purchase_limit_cents?: number | null;
+  rolling_committed_cents?: number;
 };
 
 export type TargetAutoRechargeUpdateOptions =
@@ -1454,6 +1522,8 @@ export type TargetAutoRechargeUpdateOptions =
       enabled: true;
       thresholdCredits: number;
       refillToCredits: number;
+      /** Maximum automatic purchases in a rolling 30-day window, in USD cents. */
+      purchaseLimitCents?: number | null;
       idempotencyKey: string;
     };
 
@@ -1581,10 +1651,8 @@ export type WorkspacesNamespace = {
 };
 
 /**
- * Public billing namespace exposed as `client.billing`.
- *
- * Carries plans, subscription state, cancellation, and invoice/receipt history
- * so CLI commands and programmatic callers share one surface.
+ * Public `client.billing` namespace for CLI commands and programmatic callers.
+ * Covers plans, subscription state, cancellation, and invoice/receipt history.
  *
  * @sdkReference client 030 client.billing
  */
@@ -1618,6 +1686,9 @@ export type BillingNamespace = {
   /** Read and manage the Metronome-backed automatic recharge configuration. */
   autoRecharge: {
     get: () => Promise<TargetAutoRechargeResult>;
+    trigger: (options?: {
+      idempotencyKey: string;
+    }) => Promise<{ data: { status: string; operation_id?: string } }>;
     update: (
       options: TargetAutoRechargeUpdateOptions,
     ) => Promise<TargetAutoRechargeResult>;
@@ -1627,6 +1698,12 @@ export type BillingNamespace = {
     credits: number;
     idempotencyKey: string;
   }) => Promise<TargetBillingMutationResult>;
+  /** Inspect or retire the original purchase intent without starting a payment. */
+  recoverCreditPurchase: (options: {
+    credits: number;
+    orgId: string;
+    idempotencyKey: string;
+  }) => Promise<TargetBillingMutationResult>;
   /** Start, change, cancel, or undo a target plan transition. */
   transitionPlan: (
     options: TargetBillingPlanTransitionOptions,
@@ -2190,6 +2267,7 @@ export class DeeplineClient {
     this.runs = {
       get: (runId, options) => this.getRunStatus(runId, options),
       list: (options) => this.listRuns(options),
+      listPage: (options) => this.listRunsPage(options),
       tail: (runId, options) => this.tailRun(runId, options),
       logs: (runId, options) => this.getRunLogs(runId, options),
       input: (runId) => this.getRunInput(runId),
@@ -2215,9 +2293,21 @@ export class DeeplineClient {
       targetStatus: () => this.getTargetBillingStatus(),
       autoRecharge: {
         get: () => this.getTargetAutoRecharge(),
+        trigger: (options) =>
+          this.http.post(
+            '/api/v2/billing/auto-recharge/trigger',
+            {},
+            {
+              'Idempotency-Key': requireTargetBillingIdempotencyKey(
+                options?.idempotencyKey ?? globalThis.crypto.randomUUID(),
+              ),
+            },
+          ),
         update: (options) => this.updateTargetAutoRecharge(options),
       },
       purchaseCredits: (options) => this.purchaseTargetBillingCredits(options),
+      recoverCreditPurchase: (options) =>
+        this.recoverTargetBillingCreditPurchase(options),
       transitionPlan: (options) => this.transitionTargetBillingPlan(options),
       portalSession: () => this.createTargetBillingPortalSession(),
     };
@@ -2473,6 +2563,18 @@ export class DeeplineClient {
     return this.http.get(`/api/v2/secrets?${params.toString()}`);
   }
 
+  /** Add, replace, or clear the non-sensitive note attached to one secret. */
+  async updateSecretNote(
+    secretId: string,
+    note: string,
+  ): Promise<PlaySecretMetadata> {
+    const response = await this.http.patch<{ secret: PlaySecretMetadata }>(
+      `/api/v2/secrets/${encodeURIComponent(secretId)}`,
+      { note },
+    );
+    return response.secret;
+  }
+
   // ——————————————————————————————————————————————————————————
   // Tools
   // ——————————————————————————————————————————————————————————
@@ -3870,6 +3972,11 @@ export class DeeplineClient {
    * ```
    */
   async listRuns(options: RunsListOptions): Promise<PlayRunListItem[]> {
+    return (await this.listRunsPage(options)).runs;
+  }
+
+  /** Read one run page without discarding server pagination metadata. */
+  async listRunsPage(options: RunsListOptions): Promise<RunsListPage> {
     const playName = options.play?.trim();
     const params = new URLSearchParams();
     if (playName) {
@@ -3901,10 +4008,10 @@ export class DeeplineClient {
       throw new Error('runs.list requires options.play or options.status.');
     }
     params.set('compact', 'true');
-    const response = await this.http.get<{ runs: PlayRunListItem[] }>(
+    const response = await this.http.get<RunsListPage>(
       `/api/v2/runs?${params.toString()}`,
     );
-    return response.runs ?? [];
+    return { ...response, runs: response.runs ?? [] };
   }
 
   /**
@@ -4395,20 +4502,46 @@ export class DeeplineClient {
   }
 
   /**
-   * List callable plays visible to the workspace.
+   * List one page of callable plays; grep retains exhaustive matching results.
+   * Use listPlaysPage to retain pagination metadata.
    *
    * Pass `origin: "prebuilt"` for Deepline-managed prebuilts or
    * `origin: "owned"` for org-owned plays.
    */
-  async listPlays(options?: {
-    origin?: 'prebuilt' | 'owned';
-    grep?: string;
-    grepMode?: 'all' | 'any' | 'phrase';
-    categories?: string | string[];
-    includeToolCategories?: boolean;
-    includeArchived?: boolean;
-  }): Promise<PlayListItem[]> {
+  async listPlays(options?: PlaysListOptions): Promise<PlayListItem[]> {
+    if (!options?.grep?.trim()) {
+      return (await this.requestPlaysPage(options, false)).plays;
+    }
+    const plays: PlayListItem[] = [];
+    for await (const items of iterateCursorPages(async (cursor) => {
+      const page = await this.listPlaysPage({ ...options, cursor });
+      return { items: page.plays, cursor: page.cursor, hasMore: page.hasMore };
+    })) {
+      plays.push(...items);
+    }
+    return plays;
+  }
+
+  /** Read one bounded inventory page; cursor continues the same filters. */
+  async listPlaysPage(
+    options?: PlaysListOptions & {
+      limit?: number;
+      cursor?: string | null;
+    },
+  ): Promise<PlaysListPage> {
+    return this.requestPlaysPage(options);
+  }
+
+  private async requestPlaysPage(
+    options?: PlaysListOptions & {
+      limit?: number;
+      cursor?: string | null;
+    },
+    paginateInventory = true,
+  ): Promise<PlaysListPage> {
     const params = new URLSearchParams();
+    if (paginateInventory && !options?.grep?.trim())
+      params.set('inventory_paginated', '1');
     if (options?.origin) params.set('origin', options.origin);
     if (options?.categories) {
       params.set(
@@ -4422,32 +4555,32 @@ export class DeeplineClient {
       params.set('include_tool_categories', '1');
     }
     if (options?.includeArchived) params.set('include_archived', '1');
+    if (options?.includeCostEstimates) {
+      params.set('include_cost_estimates', '1');
+    }
     if (options?.grep?.trim()) {
       params.set('grep', options.grep.trim());
-      params.set('grep_mode', options.grepMode ?? 'all');
-      params.set('grep_paginated', '1');
       params.set('limit', '60');
     }
-    type PlayListResponse = {
+    if (options?.limit !== undefined) {
+      if (!Number.isSafeInteger(options.limit) || options.limit < 1) {
+        throw new Error('Play page limit must be a positive integer');
+      }
+      params.set('limit', String(options.limit));
+    }
+    if (options?.cursor) params.set('cursor', options.cursor);
+    const suffix = params.size ? `?${params.toString()}` : '';
+    const response = await this.http.get<{
       plays?: PlayListItem[];
       cursor?: string | null;
       hasMore?: boolean;
       pagination?: { cursor?: string | null; hasMore?: boolean };
+    }>(`/api/v2/plays${suffix}`);
+    return {
+      plays: response.plays ?? [],
+      cursor: response.pagination?.cursor ?? response.cursor ?? null,
+      hasMore: Boolean(response.pagination?.hasMore ?? response.hasMore),
     };
-    const plays: PlayListItem[] = [];
-    let cursor: string | null = null;
-    let hasMore = true;
-    do {
-      if (cursor) params.set('cursor', cursor);
-      const suffix = params.toString() ? `?${params.toString()}` : '';
-      const response = await this.http.get<PlayListResponse>(
-        `/api/v2/plays${suffix}`,
-      );
-      plays.push(...(response.plays ?? []));
-      cursor = response.pagination?.cursor ?? response.cursor ?? null;
-      hasMore = Boolean(response.pagination?.hasMore ?? response.hasMore);
-    } while (Boolean(options?.grep?.trim()) && hasMore && cursor);
-    return plays;
   }
 
   /** Set whether an org-owned Play sorts before unpinned Plays. */
@@ -4637,7 +4770,7 @@ export class DeeplineClient {
       groupKey,
       name,
       enabled: true,
-      deliveryTiming: { mode: 'immediate' },
+      deliveryTiming: DEFAULT_PRODUCT_NOTIFICATION_DELIVERY_TIMING,
       source: 'workspace',
       configMode: 'custom',
       version: 0,
@@ -5338,6 +5471,9 @@ export class DeeplineClient {
             enabled: true,
             threshold_credits: options.thresholdCredits,
             refill_to_credits: options.refillToCredits,
+            ...(options.purchaseLimitCents !== undefined
+              ? { purchase_limit_cents: options.purchaseLimitCents }
+              : {}),
           }
         : { enabled: false },
       { 'Idempotency-Key': idempotencyKey },
@@ -5364,6 +5500,48 @@ export class DeeplineClient {
     );
   }
 
+  /** Recover only the original workspace, credit amount, and purchase key; never charge. */
+  async recoverTargetBillingCreditPurchase(options: {
+    credits: number;
+    orgId: string;
+    idempotencyKey: string;
+  }): Promise<TargetBillingMutationResult> {
+    if (typeof options.idempotencyKey !== 'string') {
+      throw new DeeplineError(
+        'The original billing idempotencyKey is required.',
+        undefined,
+        'INVALID_BILLING_IDEMPOTENCY_KEY',
+      );
+    }
+    const idempotencyKey = requireTargetBillingIdempotencyKey(
+      options.idempotencyKey,
+    );
+    if (!Number.isSafeInteger(options.credits) || options.credits <= 0) {
+      throw new DeeplineError(
+        'credits must be a positive safe integer.',
+        undefined,
+        'INVALID_CREDITS',
+      );
+    }
+    if (
+      typeof options.orgId !== 'string' ||
+      !options.orgId.trim() ||
+      options.orgId !== options.orgId.trim()
+    ) {
+      throw new DeeplineError(
+        'The original orgId is required without surrounding whitespace.',
+        undefined,
+        'INVALID_ORG_ID',
+      );
+    }
+    return this.http.post<TargetBillingMutationResult>(
+      '/api/v2/billing/credit-purchases/recover',
+      { credits: options.credits, org_id: options.orgId },
+      { 'Idempotency-Key': idempotencyKey },
+      { maxRetries: 0, exactUrlOnly: true },
+    );
+  }
+
   /**
    * Start, change, cancel, or restore a target plan through one idempotent
    * commercial operation.

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

@@ -101,6 +101,9 @@ export type {
   PlaySheetRow,
   PlaySheetRowsResult,
   RunsListOptions,
+  RunsListPage,
+  PlaysListOptions,
+  PlaysListPage,
   RunsLogsOptions,
   RunsLogsResult,
   RunsNamespace,
@@ -234,6 +237,7 @@ export type {
   PublishPlayVersionRequest,
   PublishPlayVersionResult,
   StartPlayRunRequest,
+  PlayCostEstimate,
   PlayListItem,
   CustomerDbQueryResult,
   DeeplineToolCategory,