deepline 0.1.85 → 0.1.89

package/dist/repo/sdk/src/client.ts

@@ -99,6 +99,13 @@ type ExecuteToolRawOptions = {
   includeToolMetadata?: boolean;
 };
 
+/**
+ * Standard provider/tool execution envelope returned by low-level SDK calls.
+ *
+ * `toolResponse.raw` contains the provider result. `extractedValues` and
+ * `extractedLists` contain Deepline-normalized getters when the tool exposes
+ * them. Billing fields are Deepline-facing and must not expose provider spend.
+ */
 export type ToolExecution<TData = unknown, TMeta = Record<string, unknown>> = {
   status: string;
   job_id?: string;
@@ -113,19 +120,23 @@ export type ToolExecution<TData = unknown, TMeta = Record<string, unknown>> = {
   [key: string]: unknown;
 };
 
+/** Filters for `client.runs.list(...)`. */
 export type RunsListOptions = {
   play: string;
   status?: string;
 };
 
+/** Streaming options for `client.runs.tail(...)`. */
 export type RunsTailOptions = {
   signal?: AbortSignal;
 };
 
+/** Log fetch options for `client.runs.logs(...)`. */
 export type RunsLogsOptions = {
   limit?: number;
 };
 
+/** Persisted log response for one play run. */
 export type RunsLogsResult = {
   runId: string;
   totalCount: number;
@@ -137,6 +148,7 @@ export type RunsLogsResult = {
   entries: string[];
 };
 
+/** One persisted runtime-sheet row returned by `client.runs.exportDatasetRows(...)`. */
 export type PlaySheetRow = {
   key?: string;
   status?: string;
@@ -144,6 +156,7 @@ export type PlaySheetRow = {
   [key: string]: unknown;
 };
 
+/** Runtime-sheet rows and aggregate progress for one dataset/table namespace. */
 export type PlaySheetRowsResult = {
   rows: PlaySheetRow[];
   summary?: {
@@ -175,11 +188,25 @@ export type PlaySecretMetadata = {
   lastUsedAt?: number;
 };
 
+/**
+ * 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.
+ *
+ * @sdkReference client 020 client.runs
+ */
 export type RunsNamespace = {
+  /** Get current run status by public run id. */
   get: (runId: string, options?: { full?: boolean }) => Promise<PlayStatus>;
+  /** List runs for one play, optionally filtered by status. */
   list: (options: RunsListOptions) => Promise<PlayRunListItem[]>;
+  /** Stream run events and return the latest/terminal run status. */
   tail: (runId: string, options?: RunsTailOptions) => Promise<PlayStatus>;
+  /** Fetch persisted log lines for a run. */
   logs: (runId: string, options?: RunsLogsOptions) => Promise<RunsLogsResult>;
+  /** Export persisted rows for a runtime-sheet dataset/table namespace. */
   exportDatasetRows: (input: {
     playName: string;
     tableNamespace: string;
@@ -187,6 +214,7 @@ export type RunsNamespace = {
     limit?: number;
     offset?: number;
   }) => Promise<PlaySheetRowsResult>;
+  /** Stop a running/waiting run. */
   stop: (
     runId: string,
     options?: { reason?: string },
@@ -197,6 +225,27 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value && typeof value === 'object' && !Array.isArray(value));
 }
 
+function isPrebuiltPlayDescription(
+  play: Pick<PlayDescription, 'origin' | 'ownerType'>,
+): boolean {
+  return play.origin === 'prebuilt' || play.ownerType === 'deepline';
+}
+
+function preferPrebuiltPlayDescriptions<T extends PlayDescription>(
+  plays: T[],
+): T[] {
+  const prebuilt: T[] = [];
+  const owned: T[] = [];
+  for (const play of plays) {
+    if (isPrebuiltPlayDescription(play)) {
+      prebuilt.push(play);
+    } else {
+      owned.push(play);
+    }
+  }
+  return [...prebuilt, ...owned];
+}
+
 function isPlayRunPackage(value: unknown): value is PlayRunPackage {
   return Boolean(
     value &&
@@ -433,13 +482,21 @@ function playRunStatusFromState(state: PlayLiveStatusState): PlayStatus {
  *   baseUrl: 'http://localhost:3000',
  * });
  * ```
+ *
+ * @sdkReference client 010
  */
 export class DeeplineClient {
   private readonly http: HttpClient;
   private readonly config: ResolvedConfig;
+  /** Canonical run lifecycle namespace backed by `/api/v2/runs`. */
   readonly runs: RunsNamespace;
 
   /**
+   * Create a low-level SDK client.
+   *
+   * Most callers can omit options and let the SDK resolve auth/config from
+   * environment variables and CLI-managed credentials.
+   *
    * @param options - Optional overrides for API key, base URL, timeout, and retries.
    * @throws {@link ConfigError} if no API key can be resolved from any source.
    */
@@ -599,6 +656,7 @@ export class DeeplineClient {
   // Secrets
   // ——————————————————————————————————————————————————————————
 
+  /** List secret metadata visible to the current workspace. */
   async listSecrets(): Promise<PlaySecretMetadata[]> {
     const response = await this.http.get<{ secrets?: PlaySecretMetadata[] }>(
       '/api/v2/secrets',
@@ -606,6 +664,12 @@ export class DeeplineClient {
     return Array.isArray(response.secrets) ? response.secrets : [];
   }
 
+  /**
+   * Check whether a named secret exists, is active, and has a stored value.
+   *
+   * @param name - Secret name. It is normalized to uppercase before lookup.
+   * @returns Matching active secret metadata, or `null`.
+   */
   async checkSecret(name: string): Promise<PlaySecretMetadata | null> {
     const normalized = name.trim().toUpperCase();
     const secrets = await this.listSecrets();
@@ -742,6 +806,12 @@ export class DeeplineClient {
     );
   }
 
+  /**
+   * Back-compatible alias for {@link executeTool}.
+   *
+   * Retained for callers that still use the older raw naming while the response
+   * envelope remains the same.
+   */
   async executeToolRaw<TData = unknown, TMeta = Record<string, unknown>>(
     toolId: string,
     input: Record<string, unknown>,
@@ -750,6 +820,12 @@ export class DeeplineClient {
     return this.executeTool<TData, TMeta>(toolId, input, options);
   }
 
+  /**
+   * Run a bounded SQL query against the customer data plane.
+   *
+   * Use this from trusted backend or agent contexts only. The API enforces
+   * workspace scoping and row limits.
+   */
   async queryCustomerDb(input: {
     sql: string;
     maxRows?: number;
@@ -843,6 +919,17 @@ export class DeeplineClient {
     return normalizePlayRunStart(response);
   }
 
+  /**
+   * Start a play run and stream live runtime events from the same request.
+   *
+   * Use this when a caller wants low-level event handling instead of submitting
+   * first and then connecting to `streamPlayRunEvents(runId)`.
+   *
+   * @param request - Play run configuration.
+   * @param options - Optional streaming options.
+   * @param options.signal - Optional abort signal for the streaming request.
+   * @returns Async stream of play-scoped live events.
+   */
   async *startPlayRunStream(
     request: StartPlayRunRequest,
     options?: { signal?: AbortSignal },
@@ -940,6 +1027,12 @@ export class DeeplineClient {
     });
   }
 
+  /**
+   * Register multiple bundled play artifacts in one request.
+   *
+   * Used by packaging and prebuilt publication flows. Each artifact is compiled
+   * first when a compiler manifest is not already supplied.
+   */
   async registerPlayArtifacts(
     artifacts: Array<{
       name: string;
@@ -986,6 +1079,13 @@ export class DeeplineClient {
     });
   }
 
+  /**
+   * Compile a bundled play artifact into the server-side compiler manifest.
+   *
+   * The manifest records imports, trigger bindings, static pipeline shape, and
+   * runtime metadata needed before a play artifact can be checked, registered,
+   * or run.
+   */
   async compilePlayManifest(input: {
     name: string;
     sourceCode: string;
@@ -1029,6 +1129,12 @@ export class DeeplineClient {
     return this.http.post('/api/v2/plays/check', input);
   }
 
+  /**
+   * Compile legacy enrich command arguments into a runtime plan.
+   *
+   * This is primarily used by CLI compatibility paths that translate older
+   * enrichment commands onto the play runtime.
+   */
   async compileEnrichPlan(input: {
     plan_args?: string[];
     config?: unknown;
@@ -1036,6 +1142,12 @@ export class DeeplineClient {
     return this.http.post('/api/v2/enrich/compile', input);
   }
 
+  /**
+   * Register an already-bundled play artifact and start a run from it.
+   *
+   * This is the low-level file-backed run path used by SDK/CLI packaging
+   * wrappers after local bundling has produced the runtime artifact.
+   */
   async startPlayRunFromBundle(input: {
     name: string;
     sourceCode: string;
@@ -1247,6 +1359,12 @@ export class DeeplineClient {
     return response.files;
   }
 
+  /**
+   * Resolve staged play files by content hash without uploading bytes.
+   *
+   * Missing files are returned so callers can upload only the files the server
+   * does not already have.
+   */
   async resolveStagedPlayFiles(
     files: Array<{
       logicalPath: string;
@@ -1513,6 +1631,12 @@ export class DeeplineClient {
     };
   }
 
+  /**
+   * Export persisted runtime-sheet rows for a play dataset/table namespace.
+   *
+   * This is the SDK form of exporting `ctx.dataset(...).run()` output for a
+   * specific play and optional run id.
+   */
   async getPlaySheetRows(input: {
     playName: string;
     tableNamespace: string;
@@ -1552,6 +1676,12 @@ export class DeeplineClient {
     );
   }
 
+  /**
+   * List callable plays visible to the workspace.
+   *
+   * Pass `origin: "prebuilt"` for Deepline-managed prebuilts or
+   * `origin: "owned"` for org-owned plays.
+   */
   async listPlays(options?: {
     origin?: 'prebuilt' | 'owned';
     grep?: string;
@@ -1571,18 +1701,36 @@ export class DeeplineClient {
     return response.plays ?? [];
   }
 
+  /**
+   * Search callable plays and return compact play descriptions.
+   *
+   * Prebuilt plays are preferred by default because they have maintained
+   * contracts and stable run behavior.
+   */
   async searchPlays(options: {
     query: string;
     compact?: boolean;
+    scope?: 'prebuilt' | 'owned' | 'all';
   }): Promise<PlayDescription[]> {
     const params = new URLSearchParams();
     params.set('search', options.query.trim());
+    const scope = options.scope ?? 'prebuilt';
+    if (scope !== 'all') {
+      params.set('origin', scope);
+    }
     const response = await this.http.get<{ plays: PlayListItem[] }>(
       `/api/v2/plays?${params.toString()}`,
     );
-    return (response.plays ?? []).map((play) =>
+    const plays = (response.plays ?? []).map((play) =>
       this.summarizePlayListItem(play, options),
     );
+    if (scope === 'prebuilt') {
+      return plays.filter(isPrebuiltPlayDescription);
+    }
+    if (scope === 'owned') {
+      return plays.filter((play) => !isPrebuiltPlayDescription(play));
+    }
+    return preferPrebuiltPlayDescriptions(plays);
   }
 
   /**
@@ -1607,6 +1755,12 @@ export class DeeplineClient {
     return this.http.get<PlayDetail>(`/api/v2/plays/${encodedName}`);
   }
 
+  /**
+   * Get a normalized play description suitable for agents and CLIs.
+   *
+   * The description includes runnable examples, input/output summaries, clone
+   * guidance, revision state, and latest run metadata when available.
+   */
   async describePlay(
     name: string,
     options?: { compact?: boolean },

package/dist/repo/sdk/src/http.ts

@@ -29,6 +29,7 @@ import { baseUrlSlug } from './config.js';
 import {
   COORDINATOR_INTERNAL_TOKEN_HEADER,
   COORDINATOR_URL_OVERRIDE_HEADER,
+  SYNTHETIC_RUN_HEADER,
   WORKER_CALLBACK_URL_OVERRIDE_HEADER,
 } from '../../shared_libs/play-runtime/coordinator-headers.js';
 
@@ -149,6 +150,16 @@ export class HttpClient {
     if (workerCallbackUrl?.trim()) {
       headers[WORKER_CALLBACK_URL_OVERRIDE_HEADER] = workerCallbackUrl.trim();
     }
+    // Automated test harnesses (e.g. tests/v2-plays) set DEEPLINE_SYNTHETIC_RUN
+    // so their intentionally failing plays do not page the SDK CLI error
+    // channel. Honored server-side only in non-prod (see plays/run route).
+    const syntheticRun =
+      typeof process !== 'undefined'
+        ? process.env?.DEEPLINE_SYNTHETIC_RUN
+        : undefined;
+    if (syntheticRun && syntheticRun.trim() && syntheticRun.trim() !== '0') {
+      headers[SYNTHETIC_RUN_HEADER] = '1';
+    }
     return headers;
   }
 

package/dist/repo/sdk/src/index.ts

@@ -55,7 +55,17 @@
 
 // ——— Client ———
 export { DeeplineClient } from './client.js';
-export type { PlayStatus, ToolExecution } from './client.js';
+export type {
+  PlayStatus,
+  PlaySheetRow,
+  PlaySheetRowsResult,
+  RunsListOptions,
+  RunsLogsOptions,
+  RunsLogsResult,
+  RunsNamespace,
+  RunsTailOptions,
+  ToolExecution,
+} from './client.js';
 export { SDK_API_CONTRACT, SDK_VERSION } from './version.js';
 export {
   DEEPLINE_TOOL_CATEGORIES,
@@ -129,33 +139,46 @@ export type {
   PublishPlayVersionResult,
   StartPlayRunRequest,
   PlayListItem,
+  CustomerDbQueryResult,
   DeeplineToolCategory,
   PlayBootstrapFinderKind,
   PlayBootstrapEntityKind,
+  StopPlayRunResult,
+  ToolSearchOptions,
+  ToolSearchResult,
 } from './types.js';
 
 export type {
   DefinePlayConfig,
+  CsvOptions,
   DeeplineNamedPlay,
+  DeeplinePlaysNamespace,
   DeeplinePlayRuntimeContext,
+  DeeplineToolsNamespace,
   DefinedPlay,
   ColumnMap,
   ColumnResolver,
   CsvInput,
   DatasetBuilder,
+  DatasetColumnDefinition,
+  DatasetColumnRunInput,
   PlayBindings,
   FileInput,
   PlayInputContract,
   PlayJob,
   ConditionalStepResolver,
+  PreviousCell,
   PlayDataset,
   PlayDatasetInput,
   PlayStepProgramStep,
   PrebuiltPlayRef,
+  StaleAfterSeconds,
+  StepOptions,
   StepProgram,
   StepProgramResolver,
   StepResolver,
   ToolExecuteResult,
+  ToolExecutionRequest,
   DeeplineEmailStatusGetterValue,
   DeeplineExtractorTarget,
   DeeplineGetterValue,