deepline 0.1.0 → 0.1.1

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

@@ -0,0 +1,1188 @@
+/**
+ * The main API client for interacting with the Deepline platform.
+ *
+ * `DeeplineClient` is the low-level workhorse — it maps 1:1 to the REST API
+ * and handles authentication, retries, and response parsing. For a higher-level
+ * interface with named play handles and tool shortcuts, use {@link Deepline.connect}
+ * or {@link DeeplineContext} instead.
+ *
+ * ## Quick start
+ *
+ * ```typescript
+ * import { DeeplineClient } from 'deepline';
+ *
+ * const client = new DeeplineClient();
+ *
+ * // List available tools
+ * const tools = await client.listTools();
+ *
+ * // Execute a tool
+ * const result = await client.executeTool('test_company_search', { domain: 'stripe.com' });
+ *
+ * // Run a play end-to-end
+ * const playResult = await client.runPlay(bundledCode, null, 'my-play', {
+ *   onProgress: (status) => console.log(status.progress?.logs),
+ * });
+ * ```
+ *
+ * ## Configuration
+ *
+ * All options are optional — the client resolves API keys and URLs automatically
+ * from environment variables and CLI config files. See {@link resolveConfig} for
+ * the full resolution order.
+ *
+ * @module
+ */
+import { resolveConfig } from './config.js';
+import { HttpClient } from './http.js';
+import type {
+  DeeplineClientOptions,
+  ResolvedConfig,
+  PlayRevisionSummary,
+  PlayRunListItem,
+  PlayDetail,
+  PlayCheckResult,
+  PlayRunResult,
+  PlayRunStart,
+  PlayStatus,
+  PlayLiveEvent,
+  PlayListItem,
+  PlayDescription,
+  StopPlayRunResult,
+  ClearPlayHistoryRequest,
+  ClearPlayHistoryResult,
+  PublishPlayVersionRequest,
+  PublishPlayVersionResult,
+  StartPlayRunRequest,
+  DeletePlayResult,
+  ToolDefinition,
+  ToolMetadata,
+  CustomerDbQueryResult,
+} from './types.js';
+import type { PlayStagedFileRef } from './plays/local-file-discovery.js';
+import type { PlayCompilerManifest } from '../../shared_libs/plays/compiler-manifest.js';
+
+const TERMINAL_PLAY_STATUSES = new Set(['completed', 'failed', 'cancelled']);
+
+function normalizePlayStatus(raw: Record<string, unknown>): PlayStatus {
+  const status =
+    typeof raw.status === 'string'
+      ? raw.status
+      : typeof raw.temporalStatus === 'string'
+        ? mapLegacyTemporalStatus(raw.temporalStatus)
+        : 'running';
+  const runId =
+    typeof raw.runId === 'string'
+      ? raw.runId
+      : typeof raw.workflowId === 'string'
+        ? raw.workflowId
+        : '';
+  return {
+    ...(raw as unknown as Omit<PlayStatus, 'runId' | 'status'>),
+    runId,
+    status: status as PlayStatus['status'],
+  };
+}
+
+function mapLegacyTemporalStatus(status: string): PlayStatus['status'] {
+  switch (status.trim().toUpperCase()) {
+    case 'PENDING':
+      return 'queued';
+    case 'COMPLETED':
+      return 'completed';
+    case 'FAILED':
+      return 'failed';
+    case 'CANCELLED':
+    case 'TERMINATED':
+    case 'TIMED_OUT':
+      return 'cancelled';
+    case 'RUNNING':
+    default:
+      return 'running';
+  }
+}
+
+/**
+ * Low-level client for the Deepline REST API.
+ *
+ * Provides typed methods for every API endpoint: tools, plays, auth, and health.
+ * Handles authentication, retries, and localhost failover automatically.
+ *
+ * @example
+ * ```typescript
+ * import { DeeplineClient } from 'deepline';
+ *
+ * // Zero-config (uses env vars / CLI auth):
+ * const client = new DeeplineClient();
+ *
+ * // Explicit config:
+ * const client2 = new DeeplineClient({
+ *   apiKey: 'dl_test_...',
+ *   baseUrl: 'http://localhost:3000',
+ * });
+ * ```
+ */
+export class DeeplineClient {
+  private readonly http: HttpClient;
+  private readonly config: ResolvedConfig;
+
+  /**
+   * @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.
+   */
+  constructor(options?: DeeplineClientOptions) {
+    this.config = resolveConfig(options);
+    this.http = new HttpClient(this.config);
+  }
+
+  /** The resolved base URL this client is targeting (e.g. `"http://localhost:3000"`). */
+  get baseUrl(): string {
+    return this.config.baseUrl;
+  }
+
+  private compactSchema(schema: Record<string, unknown> | null | undefined) {
+    if (!schema) return null;
+    const fields = Array.isArray(schema.fields)
+      ? schema.fields
+          .map((field) =>
+            field && typeof field === 'object'
+              ? {
+                  name: String((field as Record<string, unknown>).name ?? ''),
+                  type: (field as Record<string, unknown>).type ?? undefined,
+                  required:
+                    (field as Record<string, unknown>).required ?? undefined,
+                }
+              : null,
+          )
+          .filter((field) => Boolean(field?.name))
+      : [];
+    return fields.length > 0 ? { fields } : schema;
+  }
+
+  private playRunCommand(name: string): string {
+    return `deepline plays run ${name} --input '{...}' --watch`;
+  }
+
+  private summarizePlayListItem(
+    play: PlayListItem,
+    options?: { compact?: boolean },
+  ): PlayDescription {
+    const aliases = play.aliases?.length ? play.aliases : [play.name];
+    const runCommand = this.playRunCommand(play.name);
+    return {
+      name: play.name,
+      ...(play.reference ? { reference: play.reference } : {}),
+      ...(play.displayName ? { displayName: play.displayName } : {}),
+      origin: play.origin,
+      ownerType: play.ownerType,
+      canEdit: play.canEdit,
+      canClone: play.canClone,
+      aliases,
+      inputSchema: options?.compact
+        ? this.compactSchema(play.inputSchema)
+        : (play.inputSchema ?? null),
+      outputSchema: options?.compact
+        ? this.compactSchema(play.outputSchema)
+        : (play.outputSchema ?? null),
+      runCommand,
+      examples: [runCommand],
+      currentPublishedVersion: play.currentPublishedVersion ?? null,
+      isDraftDirty: play.isDraftDirty,
+    };
+  }
+
+  private summarizePlayDetail(
+    detail: PlayDetail,
+    options?: { compact?: boolean },
+  ): PlayDescription {
+    const play = detail.play;
+    return {
+      ...this.summarizePlayListItem(play, options),
+      currentPublishedVersion:
+        play.currentPublishedVersion ?? play.liveRevision?.version ?? null,
+      latestRunId: play.latestRunId ?? detail.latestRuns[0]?.workflowId ?? null,
+    };
+  }
+
+  // ——————————————————————————————————————————————————————————
+  // Tools
+  // ——————————————————————————————————————————————————————————
+
+  /**
+   * List all available tools.
+   *
+   * Returns tool definitions including ID, provider, description, input/output schemas,
+   * and list extractor paths for automatic CSV conversion.
+   *
+   * @returns Array of tool definitions
+   *
+   * @example
+   * ```typescript
+   * const tools = await client.listTools();
+   * const searchTools = tools.filter(t => t.categories.includes('search'));
+   * console.log(`Found ${searchTools.length} search tools`);
+   * ```
+   */
+  async listTools(): Promise<ToolDefinition[]> {
+    const res = await this.http.get<{ tools: ToolDefinition[] }>(
+      '/api/v2/tools',
+    );
+    return res.tools;
+  }
+
+  /**
+   * Get detailed metadata for a single tool.
+   *
+   * Returns everything from {@link ToolDefinition} plus pricing info, sample
+   * inputs/outputs, failure modes, and cost estimates.
+   *
+   * @param toolId - Tool identifier (e.g. `"apollo_people_search"`)
+   * @returns Full tool metadata
+   *
+   * @example
+   * ```typescript
+   * const meta = await client.getTool('apollo_people_search');
+   * console.log(`Cost: ${meta.estimatedCreditsRange} credits`);
+   * console.log(`Input schema:`, meta.inputSchema);
+   * ```
+   */
+  async getTool(toolId: string): Promise<ToolMetadata> {
+    return this.http.request<ToolMetadata>(
+      `/api/v2/integrations/${encodeURIComponent(toolId)}/get`,
+      {
+        method: 'GET',
+        headers: {
+          'x-deepline-tool-meta-only': '1',
+        },
+      },
+    );
+  }
+
+  /**
+   * Execute a tool and return the extracted result.
+   *
+   * Sends the input payload to the tool and returns the `.result` field from the
+   * response. For the full response envelope (including job_id, credits, etc.),
+   * use {@link executeToolRaw}.
+   *
+   * @param toolId - Tool identifier (e.g. `"test_company_search"`)
+   * @param input - Tool-specific input parameters
+   * @returns The tool's output (shape varies by tool)
+   * @throws {@link DeeplineError} if the tool execution fails
+   *
+   * @example
+   * ```typescript
+   * const company = await client.executeTool('test_company_search', {
+   *   domain: 'stripe.com',
+   * });
+   * console.log(company); // { name: "Stripe", industry: "Financial Services", ... }
+   * ```
+   */
+  async executeTool(
+    toolId: string,
+    input: Record<string, unknown>,
+  ): Promise<unknown> {
+    const res = await this.http.post<{ result: unknown }>(
+      `/api/v2/integrations/${encodeURIComponent(toolId)}/execute`,
+      { payload: input },
+    );
+    return res.result ?? res;
+  }
+
+  /**
+   * Execute a tool and return the full response envelope.
+   *
+   * Unlike {@link executeTool}, this returns the complete API response including
+   * `job_id`, `status`, `credits`, and the raw `result` object.
+   *
+   * @param toolId - Tool identifier
+   * @param input - Tool-specific input parameters
+   * @returns Full response with job metadata and result
+   *
+   * @example
+   * ```typescript
+   * const raw = await client.executeToolRaw('test_company_search', { domain: 'stripe.com' });
+   * console.log(`Job: ${raw.job_id}, Credits: ${raw.credits}`);
+   * console.log(`Result:`, raw.result);
+   * ```
+   */
+  async executeToolRaw(
+    toolId: string,
+    input: Record<string, unknown>,
+  ): Promise<Record<string, unknown>> {
+    return this.http.post<Record<string, unknown>>(
+      `/api/v2/integrations/${encodeURIComponent(toolId)}/execute`,
+      { payload: input },
+    );
+  }
+
+  async queryCustomerDb(input: {
+    sql: string;
+    maxRows?: number;
+  }): Promise<CustomerDbQueryResult> {
+    return this.http.post<CustomerDbQueryResult>('/api/v2/db/query', {
+      sql: input.sql,
+      ...(input.maxRows ? { max_rows: input.maxRows } : {}),
+    });
+  }
+
+  // ——————————————————————————————————————————————————————————
+  // Plays — submission and lifecycle
+  // ——————————————————————————————————————————————————————————
+
+  /**
+   * Start a play run.
+   *
+   * Internal/advanced primitive. For normal callers, prefer the public
+   * entrypoints: the CLI, {@link Deepline.connect}, {@link submitPlay},
+   * or {@link runPlay}.
+   *
+   * Supported invocation surfaces intentionally share this same run contract:
+   * `deepline play run`, repo scripts such as `bun run deepline -- play run`,
+   * SDK context calls like `Deepline.connect().play(name).run()`, and direct
+   * `POST /api/v2/plays/run` calls all return a workflow/run id. The completed
+   * output is always retrievable from `getPlayStatus(runId).result` (or from
+   * `PlayJob.get()` for SDK context calls). Execution logs live under
+   * `progress.logs`; they are not part of the user output object.
+   *
+   * @param request - Play run configuration (name, code, input, etc.)
+   * @returns Workflow metadata including the `workflowId` for status polling
+   *
+   * @example
+   * ```typescript
+   * // Run a live play by name:
+   * const started = await client.startPlayRun({
+   *   name: 'email-waterfall',
+   *   input: { linkedin_url: 'https://linkedin.com/in/jdoe', domain: 'acme.com' },
+   * });
+   * console.log(`Workflow: ${started.workflowId}`);
+   *
+   * // Run an ad hoc artifact-backed play:
+   * const started2 = await client.startPlayRun({
+   *   artifactStorageKey: 'plays/v1/orgs/acme/plays/my-play/artifacts/playgraph_abc123.json',
+   * });
+   * ```
+   */
+  async startPlayRun(request: StartPlayRunRequest): Promise<PlayRunStart> {
+    return this.http.post<PlayRunStart>('/api/v2/plays/run', {
+      ...(request.name ? { name: request.name } : {}),
+      ...(request.revisionId ? { revisionId: request.revisionId } : {}),
+      ...(request.artifactStorageKey
+        ? { artifactStorageKey: request.artifactStorageKey }
+        : {}),
+      ...(request.sourceCode ? { sourceCode: request.sourceCode } : {}),
+      ...('staticPipeline' in request
+        ? { staticPipeline: request.staticPipeline }
+        : {}),
+      ...(request.artifactHash ? { artifactHash: request.artifactHash } : {}),
+      ...(request.graphHash ? { graphHash: request.graphHash } : {}),
+      ...(request.runtimeArtifact
+        ? { runtimeArtifact: request.runtimeArtifact }
+        : {}),
+      ...(request.compilerManifest
+        ? { compilerManifest: request.compilerManifest }
+        : {}),
+      ...(request.inputFileUpload
+        ? { inputFileUpload: request.inputFileUpload }
+        : {}),
+      ...(request.packagedFileUploads?.length
+        ? { packagedFileUploads: request.packagedFileUploads }
+        : {}),
+      ...(request.input ? { input: request.input } : {}),
+      ...(request.inputFile ? { inputFile: request.inputFile } : {}),
+      ...(request.packagedFiles?.length
+        ? { packagedFiles: request.packagedFiles }
+        : {}),
+      ...(request.force ? { force: true } : {}),
+      ...(typeof request.waitForCompletionMs === 'number'
+        ? { waitForCompletionMs: request.waitForCompletionMs }
+        : {}),
+      // Profile selection is the API's job, not the CLI's. The server
+      // hardcodes workers_edge as the default; tests that want a
+      // different profile pass `request.profile` explicitly.
+      ...(request.profile ? { profile: request.profile } : {}),
+    });
+  }
+
+  async *startPlayRunStream(
+    request: StartPlayRunRequest,
+    options?: { signal?: AbortSignal },
+  ): AsyncGenerator<PlayLiveEvent> {
+    const body = {
+      ...(request.name ? { name: request.name } : {}),
+      ...(request.revisionId ? { revisionId: request.revisionId } : {}),
+      ...(request.artifactStorageKey
+        ? { artifactStorageKey: request.artifactStorageKey }
+        : {}),
+      ...(request.sourceCode ? { sourceCode: request.sourceCode } : {}),
+      ...('staticPipeline' in request
+        ? { staticPipeline: request.staticPipeline }
+        : {}),
+      ...(request.artifactHash ? { artifactHash: request.artifactHash } : {}),
+      ...(request.graphHash ? { graphHash: request.graphHash } : {}),
+      ...(request.runtimeArtifact
+        ? { runtimeArtifact: request.runtimeArtifact }
+        : {}),
+      ...(request.compilerManifest
+        ? { compilerManifest: request.compilerManifest }
+        : {}),
+      ...(request.inputFileUpload
+        ? { inputFileUpload: request.inputFileUpload }
+        : {}),
+      ...(request.packagedFileUploads?.length
+        ? { packagedFileUploads: request.packagedFileUploads }
+        : {}),
+      ...(request.input ? { input: request.input } : {}),
+      ...(request.inputFile ? { inputFile: request.inputFile } : {}),
+      ...(request.packagedFiles?.length
+        ? { packagedFiles: request.packagedFiles }
+        : {}),
+      ...(request.force ? { force: true } : {}),
+      ...(request.profile ? { profile: request.profile } : {}),
+    };
+    for await (const event of this.http.streamSse<PlayLiveEvent>(
+      '/api/v2/plays/run?stream=true',
+      {
+        method: 'POST',
+        body,
+        signal: options?.signal,
+      },
+    )) {
+      if (event.scope === 'play') {
+        yield event;
+      }
+    }
+  }
+
+  /**
+   * Register a bundled play artifact.
+   *
+   * Internal/advanced primitive used by packaging flows. Public callers should
+   * prefer the CLI, {@link submitPlay}, or {@link runPlay}.
+   */
+  async registerPlayArtifact(input: {
+    name: string;
+    sourceCode: string;
+    artifact: Record<string, unknown>;
+    compilerManifest?: PlayCompilerManifest;
+    publish?: boolean;
+    ownerType?: 'org' | 'deepline';
+    scope?: 'org' | 'system';
+    userId?: string;
+  }): Promise<{
+    success?: boolean;
+    name?: string;
+    artifactStorageKey: string;
+    artifactMetadata?: Record<string, unknown> | null;
+    staticPipeline?: unknown;
+    definitionId?: string | null;
+    revisionId?: string | null;
+    version?: number | null;
+    liveVersion?: number | null;
+    triggerMetadata?: unknown;
+    triggerBindings?: unknown;
+  }> {
+    const compilerManifest =
+      input.compilerManifest ??
+      (await this.compilePlayManifest({
+        name: input.name,
+        sourceCode: input.sourceCode,
+        artifact: input.artifact,
+      }));
+    return this.http.post('/api/v2/plays/artifacts', {
+      ...input,
+      compilerManifest,
+    });
+  }
+
+  async registerPlayArtifacts(
+    artifacts: Array<{
+      name: string;
+      sourceCode: string;
+      artifact: Record<string, unknown>;
+      compilerManifest?: PlayCompilerManifest;
+      publish?: boolean;
+      ownerType?: 'org' | 'deepline';
+      scope?: 'org' | 'system';
+      userId?: string;
+    }>,
+  ): Promise<{
+    success: boolean;
+    artifacts: Array<{
+      success?: boolean;
+      name?: string;
+      artifactStorageKey: string;
+      artifactMetadata?: Record<string, unknown> | null;
+      staticPipeline?: unknown;
+      definitionId?: string | null;
+      revisionId?: string | null;
+      version?: number | null;
+      liveVersion?: number | null;
+      triggerMetadata?: unknown;
+      triggerBindings?: unknown;
+    }>;
+  }> {
+    const compiledArtifacts = await Promise.all(
+      artifacts.map(async (artifact) => ({
+        ...artifact,
+        compilerManifest:
+          artifact.compilerManifest ??
+          (await this.compilePlayManifest({
+            name: artifact.name,
+            sourceCode: artifact.sourceCode,
+            artifact: artifact.artifact,
+          })),
+      })),
+    );
+    return this.http.post('/api/v2/plays/artifacts', {
+      artifacts: compiledArtifacts,
+    });
+  }
+
+  async compilePlayManifest(input: {
+    name: string;
+    sourceCode: string;
+    artifact: Record<string, unknown>;
+    importedPlayDependencies?: PlayCompilerManifest[];
+  }): Promise<PlayCompilerManifest> {
+    const response = await this.http.post<{
+      compilerManifest: PlayCompilerManifest;
+    }>('/api/v2/plays/compile-manifest', input);
+    return response.compilerManifest;
+  }
+
+  /**
+   * Check a bundled play artifact against the server's current play compiler.
+   *
+   * Unlike {@link registerPlayArtifact}, this does not store the artifact,
+   * publish a revision, or start a run. It is the authoritative cloud validation
+   * path used by `deepline play check`.
+   */
+  async checkPlayArtifact(input: {
+    name?: string;
+    sourceCode: string;
+    artifact: Record<string, unknown>;
+  }): Promise<PlayCheckResult> {
+    return this.http.post('/api/v2/plays/check', input);
+  }
+
+  async startPlayRunFromBundle(input: {
+    name: string;
+    sourceCode: string;
+    artifact: Record<string, unknown>;
+    compilerManifest?: PlayCompilerManifest;
+    input?: Record<string, unknown>;
+    inputFile?: PlayStagedFileRef | null;
+    packagedFiles?: PlayStagedFileRef[];
+    force?: boolean;
+  }): Promise<PlayRunStart> {
+    const compilerManifest =
+      input.compilerManifest ??
+      (await this.compilePlayManifest({
+        name: input.name,
+        sourceCode: input.sourceCode,
+        artifact: input.artifact,
+      }));
+    const registeredArtifact = await this.registerPlayArtifact({
+      name: input.name,
+      sourceCode: input.sourceCode,
+      artifact: input.artifact,
+      compilerManifest,
+      publish: false,
+    });
+    if (!registeredArtifact.artifactStorageKey) {
+      throw new Error(
+        'registerPlayArtifact did not return an artifactStorageKey.',
+      );
+    }
+
+    return this.startPlayRun({
+      name: input.name,
+      artifactStorageKey: registeredArtifact.artifactStorageKey,
+      compilerManifest,
+      ...(input.input ? { input: input.input } : {}),
+      ...(input.inputFile ? { inputFile: input.inputFile } : {}),
+      ...(input.packagedFiles?.length
+        ? { packagedFiles: input.packagedFiles }
+        : {}),
+      ...(input.force ? { force: true } : {}),
+    });
+  }
+
+  /**
+   * Register a bundled play artifact and start a run from the live revision.
+   *
+   * Convenience wrapper around {@link registerPlayArtifact} plus
+   * {@link startPlayRun}. This is the canonical file-backed path used by wrappers.
+   * The returned id can be passed to {@link getPlayStatus} to retrieve the same
+   * durable `{ result }` object that the CLI prints after `--watch` completes.
+   *
+   * @param code - Source string fallback; the bundled artifact should be passed in `options.artifact`
+   * @param csvPath - Path to input CSV file, or `null`
+   * @param name - Play name (extracted from source if omitted)
+   * @param options - Additional submission options
+   * @returns Workflow metadata with `workflowId`
+   *
+   * @example
+   * ```typescript
+   * const started = await client.submitPlay(
+   *   originalSource,
+   *   './leads.csv',
+   *   'bulk-enrich',
+   *   { artifact: bundledArtifact, input: { limit: 100 } },
+   * );
+   * ```
+   */
+  async submitPlay(
+    code: string,
+    csvPath: string | null,
+    name?: string,
+    options?: {
+      sourceCode?: string;
+      artifact?: Record<string, unknown>;
+      compilerManifest?: PlayCompilerManifest;
+      input?: Record<string, unknown>;
+      inputFile?: PlayStagedFileRef | null;
+      packagedFiles?: PlayStagedFileRef[];
+      force?: boolean;
+    },
+  ): Promise<PlayRunStart> {
+    const runtimeInput = options?.input ? { ...options.input } : {};
+
+    if (csvPath) {
+      runtimeInput.file = csvPath;
+    }
+
+    const sourceCode = options?.sourceCode ?? code;
+    const artifact = options?.artifact;
+    if (!name?.trim()) {
+      throw new Error('submitPlay requires a play name.');
+    }
+    if (!artifact) {
+      throw new Error('submitPlay requires a bundled play artifact.');
+    }
+    const compilerManifest =
+      options?.compilerManifest ??
+      (await this.compilePlayManifest({
+        name,
+        sourceCode,
+        artifact,
+      }));
+
+    const registeredArtifact = await this.registerPlayArtifact({
+      name,
+      sourceCode,
+      artifact,
+      compilerManifest,
+      publish: false,
+    });
+    if (!registeredArtifact.artifactStorageKey) {
+      throw new Error(
+        'registerPlayArtifact did not return an artifactStorageKey.',
+      );
+    }
+
+    return this.startPlayRun({
+      name,
+      artifactStorageKey: registeredArtifact.artifactStorageKey,
+      sourceCode,
+      staticPipeline: registeredArtifact.staticPipeline ?? null,
+      artifactHash:
+        typeof artifact.artifactHash === 'string'
+          ? artifact.artifactHash
+          : undefined,
+      graphHash:
+        typeof artifact.graphHash === 'string' ? artifact.graphHash : undefined,
+      runtimeArtifact: artifact,
+      compilerManifest,
+      ...(Object.keys(runtimeInput).length > 0 ? { input: runtimeInput } : {}),
+      ...(options?.inputFile ? { inputFile: options.inputFile } : {}),
+      ...(options?.packagedFiles?.length
+        ? { packagedFiles: options.packagedFiles }
+        : {}),
+      ...(options?.force ? { force: true } : {}),
+    });
+  }
+
+  /**
+   * Upload files to the staging area for use in play runs.
+   *
+   * Internal/advanced primitive used by packaging flows. Public callers should
+   * prefer the CLI, {@link submitPlay}, or {@link runPlay}.
+   *
+   * Staged files are referenced by their returned {@link PlayStagedFileRef}
+   * in subsequent {@link startPlayRun} calls via `inputFile` or `packagedFiles`.
+   *
+   * @param files - Array of files to stage (base64-encoded content)
+   * @returns Array of staged file references
+   *
+   * @example
+   * ```typescript
+   * const staged = await client.stagePlayFiles([{
+   *   logicalPath: 'data/leads.csv',
+   *   contentBase64: Buffer.from(csvContent).toString('base64'),
+   *   contentHash: sha256(csvContent),
+   *   contentType: 'text/csv',
+   *   bytes: csvContent.length,
+   * }]);
+   * // Use staged[0] as inputFile in startPlayRun
+   * ```
+   */
+  async stagePlayFiles(
+    files: Array<{
+      logicalPath: string;
+      contentBase64: string;
+      contentHash: string;
+      contentType: string;
+      bytes: number;
+    }>,
+  ): Promise<PlayStagedFileRef[]> {
+    const response = await this.http.post<{ files: PlayStagedFileRef[] }>(
+      '/api/v2/plays/files/stage',
+      { files },
+    );
+    return response.files;
+  }
+
+  async resolveStagedPlayFiles(
+    files: Array<{
+      logicalPath: string;
+      contentHash: string;
+      contentType: string;
+      bytes: number;
+    }>,
+  ): Promise<{
+    files: PlayStagedFileRef[];
+    missing: Array<{ logicalPath: string; contentHash: string }>;
+  }> {
+    return this.http.post<{
+      files: PlayStagedFileRef[];
+      missing: Array<{ logicalPath: string; contentHash: string }>;
+    }>('/api/v2/plays/files/stage', { files });
+  }
+
+  // ——————————————————————————————————————————————————————————
+  // Plays — status and monitoring
+  // ——————————————————————————————————————————————————————————
+
+  /**
+   * Get the current status of a play execution.
+   *
+   * Internal/advanced primitive. Public callers should usually prefer
+   * {@link runPlay}, {@link PlayJob.get}, or `deepline play run --watch`.
+   *
+   * Poll this method until `status` reaches a terminal state:
+   * `'completed'`, `'failed'`, or `'cancelled'`.
+   *
+   * @param workflowId - Play-run id from {@link startPlayRun}
+   * @returns Current status with progress logs and partial results
+   *
+   * @example
+   * ```typescript
+   * const status = await client.getPlayStatus('play-abc123');
+   * console.log(`Status: ${status.status}`);
+   * console.log(`Logs: ${status.progress?.logs.length ?? 0} lines`);
+   * ```
+   */
+  async getPlayStatus(workflowId: string): Promise<PlayStatus> {
+    const response = await this.http.get<Record<string, unknown>>(
+      `/api/v2/plays/run/${encodeURIComponent(workflowId)}`,
+    );
+    return normalizePlayStatus(response);
+  }
+
+  /**
+   * Get the lightweight tail-polling status for a play execution.
+   *
+   * This is intentionally smaller than {@link getPlayStatus}: it returns the
+   * fields needed for CLI log tailing while the run is in flight, without
+   * forcing the API to rebuild final result views on every poll. Call
+   * {@link getPlayStatus} once after a terminal state for the full result.
+   */
+  async getPlayTailStatus(
+    workflowId: string,
+    options?: {
+      afterLogIndex?: number;
+      waitMs?: number;
+      terminalOnly?: boolean;
+    },
+  ): Promise<PlayStatus> {
+    const params = new URLSearchParams({ mode: 'tail' });
+    if (typeof options?.afterLogIndex === 'number') {
+      params.set('afterLogIndex', String(options.afterLogIndex));
+    }
+    if (typeof options?.waitMs === 'number') {
+      params.set('waitMs', String(options.waitMs));
+    }
+    if (options?.terminalOnly) {
+      params.set('terminalOnly', 'true');
+    }
+    const response = await this.http.get<Record<string, unknown>>(
+      `/api/v2/plays/run/${encodeURIComponent(workflowId)}?${params.toString()}`,
+    );
+    return normalizePlayStatus(response);
+  }
+
+  /**
+   * Stream semantic play-run events using the same SSE feed as the dashboard.
+   *
+   * Consumers should still keep a polling fallback: SSE is the fast live-update
+   * transport, while the status endpoints remain the authoritative recovery path.
+   */
+  async *streamPlayRunEvents(
+    workflowId: string,
+    options?: {
+      signal?: AbortSignal;
+      lastEventId?: string;
+      mode?: 'cli' | 'ui';
+    },
+  ): AsyncGenerator<PlayLiveEvent> {
+    const headers =
+      options?.lastEventId && options.lastEventId.trim()
+        ? { 'Last-Event-ID': options.lastEventId.trim() }
+        : undefined;
+    const params = new URLSearchParams({ stream: 'true' });
+    params.set('mode', options?.mode ?? 'cli');
+    for await (const event of this.http.streamSse<PlayLiveEvent>(
+      `/api/v2/plays/run/${encodeURIComponent(workflowId)}?${params.toString()}`,
+      { signal: options?.signal, headers },
+    )) {
+      if (event.scope === 'play') {
+        yield event;
+      }
+    }
+  }
+
+  /**
+   * Cancel a running play execution.
+   *
+   * Sends a stop request for the run.
+   *
+   * @param workflowId - Temporal workflow ID to cancel
+   *
+   * @example
+   * ```typescript
+   * await client.cancelPlay('play-abc123');
+   * ```
+   */
+  async cancelPlay(workflowId: string): Promise<void> {
+    await this.http.request(
+      `/api/v2/plays/run/${encodeURIComponent(workflowId)}/stop`,
+      { method: 'POST' },
+    );
+  }
+
+  /**
+   * Stop a running play execution, including open HITL waits.
+   *
+   * @param workflowId - Temporal workflow ID to stop
+   * @param options.reason - Optional audit/debug reason
+   */
+  async stopPlay(
+    workflowId: string,
+    options?: { reason?: string },
+  ): Promise<StopPlayRunResult> {
+    return this.http.post<StopPlayRunResult>(
+      `/api/v2/plays/run/${encodeURIComponent(workflowId)}/stop`,
+      options?.reason ? { reason: options.reason } : {},
+    );
+  }
+
+  /**
+   * List recent runs for a named play.
+   *
+   * Returns runs sorted by start time (newest first), including workflow IDs,
+   * status, timestamps, and metadata.
+   *
+   * @param playName - The play name to query
+   * @returns Array of run summaries (empty array if no runs exist)
+   *
+   * @example
+   * ```typescript
+   * const runs = await client.listPlayRuns('email-waterfall');
+   * for (const run of runs) {
+   *   console.log(`${run.workflowId}: ${run.status} (${run.executionTime})`);
+   * }
+   * ```
+   */
+  async listPlayRuns(playName: string): Promise<PlayRunListItem[]> {
+    const encodedName = encodeURIComponent(playName);
+    const response = await this.http.get<{ runs: PlayRunListItem[] }>(
+      `/api/v2/plays/${encodedName}/runs`,
+    );
+    return response.runs ?? [];
+  }
+
+  async listPlays(): Promise<PlayListItem[]> {
+    const response = await this.http.get<{ plays: PlayListItem[] }>(
+      '/api/v2/plays',
+    );
+    return response.plays ?? [];
+  }
+
+  async searchPlays(options: {
+    query: string;
+    origin?: 'prebuilt' | 'owned';
+    compact?: boolean;
+  }): Promise<PlayDescription[]> {
+    const query = options.query.trim().toLowerCase();
+    const terms = query.split(/\s+/).filter(Boolean);
+    const plays = await this.listPlays();
+    return plays
+      .filter((play) => {
+        if (options.origin && (play.origin ?? 'owned') !== options.origin) {
+          return false;
+        }
+        const haystack = [
+          play.name,
+          play.reference,
+          play.displayName,
+          play.origin,
+          ...(play.aliases ?? []),
+          play.inputSchema ? JSON.stringify(play.inputSchema) : '',
+        ]
+          .filter(Boolean)
+          .join(' ')
+          .toLowerCase();
+        return terms.every((term) => haystack.includes(term));
+      })
+      .map((play) => this.summarizePlayListItem(play, options));
+  }
+
+  /**
+   * Get the full definition and state of a named play.
+   *
+   * Returns the play's revision state (draft, live), recent runs,
+   * sheet processing summary, and database URL.
+   *
+   * @param name - Play name
+   * @returns Complete play detail
+   *
+   * @example
+   * ```typescript
+   * const detail = await client.getPlay('email-waterfall');
+   * console.log(`Live: v${detail.play.currentPublishedVersion}`);
+   * console.log(`Draft dirty: ${detail.play.isDraftDirty}`);
+   * console.log(`Total runs: ${detail.play.runCount}`);
+   * ```
+   */
+  async getPlay(name: string): Promise<PlayDetail> {
+    const encodedName = encodeURIComponent(name);
+    return this.http.get<PlayDetail>(`/api/v2/plays/${encodedName}`);
+  }
+
+  async describePlay(
+    name: string,
+    options?: { compact?: boolean },
+  ): Promise<PlayDescription> {
+    const detail = await this.getPlay(name);
+    return this.summarizePlayDetail(detail, options);
+  }
+
+  /**
+   * Clear run history and durable sheet/result data for a play without deleting
+   * the play definition or revisions.
+   */
+  async clearPlayHistory(
+    name: string,
+    request: ClearPlayHistoryRequest = {},
+  ): Promise<ClearPlayHistoryResult> {
+    const encodedName = encodeURIComponent(name);
+    return this.http.post<ClearPlayHistoryResult>(
+      `/api/v2/plays/${encodedName}/history/clear`,
+      request,
+    );
+  }
+
+  /**
+   * List saved versions for a named play.
+   *
+   * Returns immutable revision snapshots newest-first, including the revision
+   * id needed for exact-version runs and live-version switching.
+   *
+   * @param name - Play name
+   * @returns Version list (newest first)
+   */
+  async listPlayVersions(name: string): Promise<PlayRevisionSummary[]> {
+    const encodedName = encodeURIComponent(name);
+    const response = await this.http.get<{ versions: PlayRevisionSummary[] }>(
+      `/api/v2/plays/${encodedName}/versions`,
+    );
+    return response.versions ?? [];
+  }
+
+  /**
+   * Make a play revision live.
+   *
+   * When `revisionId` is omitted, the current working revision becomes live.
+   * The live version is what executes when the play is run by name without
+   * specifying an explicit revision.
+   *
+   * @param name - Play name
+   * @param request - Optional explicit revision to make live
+   * @returns Result with the new live version number
+   *
+   * @example
+   * ```typescript
+   * const result = await client.publishPlayVersion('email-waterfall');
+   * if (result.success) {
+   *   console.log(`Live v${result.liveVersion}`);
+   * }
+   * ```
+   */
+  async publishPlayVersion(
+    name: string,
+    request: PublishPlayVersionRequest = {},
+  ): Promise<PublishPlayVersionResult> {
+    const encodedName = encodeURIComponent(name);
+    return this.http.post<PublishPlayVersionResult>(
+      `/api/v2/plays/${encodedName}/live`,
+      request,
+    );
+  }
+
+  /**
+   * Delete an org-owned play definition, including its revisions, trigger
+   * bindings, and local run records. Deepline prebuilt plays are read-only.
+   */
+  async deletePlay(name: string): Promise<DeletePlayResult> {
+    const encodedName = encodeURIComponent(name);
+    return this.http.delete<DeletePlayResult>(`/api/v2/plays/${encodedName}`);
+  }
+
+  // ——————————————————————————————————————————————————————————
+  // Plays — high-level orchestration
+  // ——————————————————————————————————————————————————————————
+
+  /**
+   * Run a play end-to-end: submit, poll until terminal, return result.
+   *
+   * This is the highest-level play execution method. It submits the play,
+   * polls for status updates, and returns a structured result with logs
+   * and timing. Supports cancellation via `AbortSignal`.
+   *
+   * @param code - Source string fallback; pass the bundled artifact in `options.artifact`
+   * @param csvPath - Input CSV path, or `null`
+   * @param name - Play name
+   * @param options - Execution options
+   * @returns Final execution result with success/failure, output, logs, and duration
+   *
+   * @example
+   * ```typescript
+   * const result = await client.runPlay(bundledCode, null, 'my-play', {
+   *   input: { domain: 'stripe.com' },
+   *   onProgress: (status) => {
+   *     const logs = status.progress?.logs ?? [];
+   *     console.log(`[${status.status}] ${logs.length} log lines`);
+   *   },
+   *   pollIntervalMs: 1000,
+   * });
+   *
+   * if (result.success) {
+   *   console.log('Output:', result.result);
+   * } else {
+   *   console.error(`Failed after ${result.durationMs}ms:`, result.error);
+   * }
+   * ```
+   *
+   * @example Cancellation
+   * ```typescript
+   * const controller = new AbortController();
+   * setTimeout(() => controller.abort(), 30_000); // 30s timeout
+   *
+   * const result = await client.runPlay(code, null, 'slow-play', {
+   *   signal: controller.signal,
+   * });
+   * // result.success === false, result.error === 'Cancelled by user'
+   * ```
+   */
+  async runPlay(
+    code: string,
+    csvPath: string | null,
+    name?: string,
+    options?: {
+      /** Called on each poll iteration with the current status. */
+      onProgress?: (status: PlayStatus) => void;
+      /** Milliseconds between status polls. Default: `500`. */
+      pollIntervalMs?: number;
+      /** Abort signal — triggers cancellation and immediate return. */
+      signal?: AbortSignal;
+      /** Runtime input for the play function. */
+      input?: Record<string, unknown>;
+      sourceCode?: string;
+      artifact?: Record<string, unknown>;
+      compilerManifest?: PlayCompilerManifest;
+      inputFile?: PlayStagedFileRef | null;
+      packagedFiles?: PlayStagedFileRef[];
+      /** Force-supersede any active runs for this play before starting. */
+      force?: boolean;
+    },
+  ): Promise<PlayRunResult> {
+    const { workflowId } = await this.submitPlay(code, csvPath, name, {
+      input: options?.input,
+      sourceCode: options?.sourceCode,
+      artifact: options?.artifact,
+      compilerManifest: options?.compilerManifest,
+      inputFile: options?.inputFile,
+      packagedFiles: options?.packagedFiles,
+      force: options?.force,
+    });
+    const pollInterval = options?.pollIntervalMs ?? 500;
+    const start = Date.now();
+
+    while (true) {
+      if (options?.signal?.aborted) {
+        await this.cancelPlay(workflowId);
+        return {
+          success: false,
+          runId: workflowId,
+          logs: [],
+          durationMs: Date.now() - start,
+          error: 'Cancelled by user',
+        };
+      }
+
+      const status = await this.getPlayStatus(workflowId);
+      options?.onProgress?.(status);
+
+      if (TERMINAL_PLAY_STATUSES.has(status.status)) {
+        return {
+          success: status.status === 'completed',
+          runId: status.runId || workflowId,
+          result: status.result,
+          logs: status.progress?.logs ?? [],
+          durationMs: Date.now() - start,
+          error:
+            status.progress?.error ??
+            (status.status !== 'completed' ? status.status : undefined),
+        };
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, pollInterval));
+    }
+  }
+
+  // ——————————————————————————————————————————————————————————
+  // Health
+  // ——————————————————————————————————————————————————————————
+
+  /**
+   * Check API connectivity and server health.
+   *
+   * @returns Health status with API version
+   *
+   * @example
+   * ```typescript
+   * const health = await client.health();
+   * console.log(`API: ${health.status} (${health.version})`);
+   * // { status: "ok", version: "v2" }
+   * ```
+   */
+  async health(): Promise<{ status: string; version?: string }> {
+    return this.http.get<{ status: string; version?: string }>(
+      '/api/v2/health',
+    );
+  }
+}
+
+export type { PlayRunListItem, PlayStatus } from './types.js';