deepline 0.0.1 → 0.1.1

package/dist/index.d.mts

@@ -1,105 +1,2422 @@
+/**
+ * The runtime shape of a built play artifact. Different runner backends need
+ * different bundle outputs:
+ *   - cjs_node20: Daytona + local-process (full Node.js sandbox).
+ *   - esm_workers: Cloudflare Workers (V8 isolate, no `fs`/`child_process`).
+ *
+ * The CLI selects which kind to build based on the target backend; the worker
+ * validates the kind matches the backend it's about to dispatch to.
+ */
+declare const PLAY_ARTIFACT_KINDS: {
+    readonly cjsNode20: "cjs_node20";
+    readonly esmWorkers: "esm_workers";
+};
+type PlayArtifactKind = (typeof PLAY_ARTIFACT_KINDS)[keyof typeof PLAY_ARTIFACT_KINDS];
+
+interface PlayStaticPipelineSnapshot {
+    tableNamespace?: string;
+    inputFields?: string[];
+    csvArg?: string;
+    hasInlineData?: boolean;
+    csvDescription?: string;
+    mapDescription?: string;
+    fields: string[];
+    stages?: PlayStaticSubstepSnapshot[];
+    substeps: PlayStaticSubstepSnapshot[];
+    sheetContract?: PlaySheetContractSnapshot | null;
+    sheetContractErrors?: string[];
+}
+type PlaySheetColumnSourceSnapshot = 'input' | 'mapField' | 'waterfallStep' | 'childPlayColumn';
+interface PlaySheetColumnContractSnapshot {
+    id: string;
+    sqlName: string;
+    source: PlaySheetColumnSourceSnapshot;
+    field?: string;
+    parentField?: string;
+    playId?: string;
+    waterfallId?: string;
+    outputField?: string;
+    outputSqlName?: string;
+    stepId?: string;
+    toolId?: string;
+}
+interface PlaySheetContractSnapshot {
+    tableNamespace: string;
+    columns: PlaySheetColumnContractSnapshot[];
+}
+interface PlayStaticSourceRangeSnapshot {
+    sourcePath?: string;
+    startLine: number;
+    endLine: number;
+    startColumn: number;
+    endColumn: number;
+}
+type PlayStaticSubstepMetadataSnapshot = {
+    conditional?: boolean;
+};
+type PlayStaticSubstepSnapshot = PlayStaticSubstepMetadataSnapshot & ({
+    type: 'csv';
+    field: string;
+    path?: string;
+    description?: string;
+    sourceRange?: PlayStaticSourceRangeSnapshot;
+    callDepth?: number;
+    callPath?: string[];
+} | {
+    type: 'map';
+    field: string;
+    name?: string;
+    tableNamespace?: string;
+    inputFields?: string[];
+    outputFields?: string[];
+    waterfallIds?: string[];
+    sheetContract?: PlaySheetContractSnapshot | null;
+    description?: string;
+    sourceRange?: PlayStaticSourceRangeSnapshot;
+    callDepth?: number;
+    callPath?: string[];
+} | {
+    type: 'tool';
+    toolId: string;
+    field: string;
+    description?: string;
+    inLoop?: boolean;
+    isEventWait?: boolean;
+    sourceRange?: PlayStaticSourceRangeSnapshot;
+    callDepth?: number;
+    callPath?: string[];
+} | {
+    type: 'waterfall';
+    tool?: string;
+    field: string;
+    inLoop?: boolean;
+    id?: string;
+    output?: string;
+    minResults?: number;
+    sourceText?: string;
+    steps?: Array<{
+        id: string;
+        kind?: 'tool' | 'code';
+        toolId?: string;
+        paramsSource?: string;
+    }>;
+    description?: string;
+    sourceRange?: PlayStaticSourceRangeSnapshot;
+    callDepth?: number;
+    callPath?: string[];
+} | {
+    type: 'step_suite';
+    field: string;
+    steps: PlayStaticSubstepSnapshot[];
+    returnSource?: string;
+    description?: string;
+    sourceRange?: PlayStaticSourceRangeSnapshot;
+    callDepth?: number;
+    callPath?: string[];
+} | {
+    type: 'play_call';
+    playId: string;
+    field: string;
+    inLoop?: boolean;
+    pipeline?: PlayStaticPipelineSnapshot | null;
+    cycleDetected?: boolean;
+    resolutionError?: string;
+    description?: string;
+    sourceRange?: PlayStaticSourceRangeSnapshot;
+    callDepth?: number;
+    callPath?: string[];
+} | {
+    type: 'run_javascript';
+    alias: string;
+    description?: string;
+    sourceRange?: PlayStaticSourceRangeSnapshot;
+    callDepth?: number;
+    callPath?: string[];
+} | {
+    type: 'code';
+    field: string;
+    description?: string;
+    sourceRange?: PlayStaticSourceRangeSnapshot;
+    callDepth?: number;
+    callPath?: string[];
+});
+type PlayCompilerDependencyManifest = {
+    playName: string;
+    sourceHash: string;
+    graphHash: string;
+    artifactHash: string;
+    staticPipeline: PlayStaticPipelineSnapshot;
+};
+type PlayCompilerManifest = {
+    compilerVersion: number;
+    playName: string;
+    sourceHash: string;
+    graphHash: string;
+    artifactHash: string;
+    artifactKind?: PlayArtifactKind;
+    staticPipeline: PlayStaticPipelineSnapshot;
+    importedPlayDependencies: PlayCompilerDependencyManifest[];
+};
+
+/**
+ * Options for constructing a {@link DeeplineClient} or connecting via {@link Deepline.connect}.
+ *
+ * All fields are optional — the SDK resolves missing values from environment
+ * variables and CLI-managed config files. See {@link resolveConfig} for the
+ * full resolution order.
+ *
+ * @example
+ * ```typescript
+ * import { DeeplineClient } from 'deepline';
+ *
+ * // Minimal — uses env vars / CLI config automatically:
+ * const client = new DeeplineClient();
+ *
+ * // Explicit overrides:
+ * const client2 = new DeeplineClient({
+ *   apiKey: 'dl_test_...',
+ *   baseUrl: 'http://localhost:3000',
+ *   timeout: 30_000,
+ *   maxRetries: 5,
+ * });
+ * ```
+ */
 interface DeeplineClientOptions {
+    /** API key. Overrides `DEEPLINE_API_KEY` env var and CLI-stored keys. */
     apiKey?: string;
+    /** Base URL of the Deepline API. Overrides `DEEPLINE_ORIGIN_URL` / `DEEPLINE_API_BASE_URL`. */
     baseUrl?: string;
+    /** Per-request timeout in milliseconds. Default: `60_000` (60 seconds). */
     timeout?: number;
+    /** Maximum retry attempts for transient failures (network errors, 429s). Default: `3`. */
     maxRetries?: number;
 }
+/**
+ * Fully resolved configuration used internally by the SDK.
+ *
+ * Produced by {@link resolveConfig} — all fields are guaranteed non-empty.
+ */
 interface ResolvedConfig {
+    /** Validated API key (non-empty string). */
     apiKey: string;
+    /** Normalized base URL (trailing slash stripped). */
     baseUrl: string;
+    /** Request timeout in milliseconds. */
     timeout: number;
+    /** Max retry count for transient failures. */
     maxRetries: number;
 }
-interface ToolExecuteResult {
-    job_id: string;
-    status: string;
-    result: Record<string, unknown>;
-    error?: string;
-    credits?: number | null;
+interface CustomerDbColumn {
+    name: string;
+    table_id: number | null;
+    data_type_id: number | null;
 }
+interface CustomerDbQueryResult {
+    command: string;
+    row_count: number | null;
+    row_count_returned: number;
+    truncated: boolean;
+    columns: CustomerDbColumn[];
+    rows: unknown[];
+}
+/**
+ * Summary definition of a tool, returned by {@link DeeplineClient.listTools}.
+ *
+ * Contains everything needed to discover, describe, and call a tool.
+ *
+ * @example
+ * ```typescript
+ * const tools = await client.listTools();
+ * for (const tool of tools) {
+ *   console.log(`${tool.toolId} (${tool.provider}): ${tool.description}`);
+ * }
+ * ```
+ */
 interface ToolDefinition {
+    /** Unique tool identifier used in API calls (e.g. `"apollo_people_search"`). */
     toolId: string;
+    /** Provider that backs this tool (e.g. `"apollo"`, `"hunter"`, `"test"`). */
     provider: string;
+    /** Human-readable name for display. */
     displayName: string;
+    /** What this tool does — suitable for LLM tool descriptions. */
     description: string;
+    /** Categorization tags (e.g. `["people", "enrichment"]`). */
     categories: string[];
+    /** Operation slug within the provider. */
+    operation?: string;
+    /** Normalized operation identifier. */
+    operationId?: string;
+    /** Alternative names that resolve to this tool. */
+    operationAliases?: string[];
+    /** JSON Schema describing the tool's input parameters. */
     inputSchema?: Record<string, unknown>;
+    /** JSON Schema describing the tool's output shape. */
     outputSchema?: Record<string, unknown>;
+    /**
+     * Dotted paths for extracting list data from the tool's response.
+     *
+     * Used by {@link tryConvertToList} to automatically find the array of results
+     * in a nested response. Example: `["people", "result.data"]`.
+     */
+    listExtractorPaths?: string[];
+    /** Field mappings for extracting identity fields (email, phone, etc.) from results. */
+    resultIdentityGetters?: Record<string, string[]>;
+    /** Whether the output is a direct object or wrapped in a `result` envelope. */
+    rowContextShape?: 'direct' | 'result_envelope';
 }
+/**
+ * Extended tool metadata including pricing, samples, and failure modes.
+ *
+ * Returned by {@link DeeplineClient.getTool}. Extends {@link ToolDefinition}
+ * with operational details needed for cost estimation and debugging.
+ *
+ * @example
+ * ```typescript
+ * const meta = await client.getTool('apollo_people_search');
+ * console.log(meta.displayName);              // "Apollo People Search"
+ * console.log(meta.estimatedCreditsRange);     // "1-5"
+ * console.log(meta.samples);                   // { input: {...}, output: {...} }
+ * ```
+ */
+interface ToolMetadata extends ToolDefinition {
+    /** Related async polling action, if this tool supports async execution. */
+    asyncGetAction?: string | null;
+    /** Known failure scenarios and their expected handling. */
+    failureMode?: Record<string, unknown> | null;
+    /** Provider-side pricing structure. */
+    cost?: Record<string, unknown> | null;
+    /** How many Deepline credits map to one provider pricing unit. */
+    deeplineCreditsPerPricingUnit?: number | null;
+    /** Whether cost is billed by the provider or by Deepline. */
+    billingSource?: string;
+    /** Display label for the billing source. */
+    billingSourceLabel?: string;
+    /** Play expansion config if this tool auto-expands in plays. */
+    playExpansion?: Record<string, unknown>;
+    /** Estimated credit range for a single call (e.g. `"1-5"`). */
+    estimatedCreditsRange?: string;
+    /** Version of the cost estimation model used. */
+    estimateModelVersion?: string;
+    /** Tools whose costs were used to build this estimate. */
+    estimateBasedOnTools?: string[];
+    /** Individual step cost contributions (for composite tools). */
+    stepContributions?: unknown[];
+    /** Example input/output pairs for documentation and testing. */
+    samples?: Record<string, unknown>;
+}
+/**
+ * Final result of a play execution, returned by {@link DeeplineClient.runPlay}.
+ *
+ * @example
+ * ```typescript
+ * const result = await client.runPlay(code, null, 'my-play');
+ * if (result.success) {
+ *   console.log('Output:', result.result);
+ *   console.log(`Completed in ${result.durationMs}ms`);
+ * } else {
+ *   console.error('Failed:', result.error);
+ *   console.log('Logs:', result.logs.join('\n'));
+ * }
+ * ```
+ */
 interface PlayRunResult {
+    /** `true` if the play completed successfully (`status === 'completed'`). */
     success: boolean;
-    workflowId: string;
+    /** Public play-run identifier — use for `play tail` or status polling. */
+    runId: string;
+    /** The play's return value. Only present on success. */
     result?: unknown;
+    /** All log lines emitted via `ctx.log()` during execution. */
     logs: string[];
+    /** Wall-clock duration from submission to completion, in milliseconds. */
     durationMs: number;
+    /** Error message if the play failed, was cancelled, or timed out. */
     error?: string;
 }
+/**
+ * Progress snapshot from a running play, nested inside {@link PlayStatus}.
+ */
+interface PlayProgressStatus {
+    /** Human-readable description of the current step. */
+    status: string;
+    /** Total row count for row-based processing (e.g. CSV enrichment). */
+    totalRows?: number;
+    /** Accumulated log lines from `ctx.log()`. Grows monotonically. */
+    logs: string[];
+    /** Error message if the play has failed. */
+    error?: string;
+}
+/**
+ * Current status of a play execution, returned by {@link DeeplineClient.getPlayStatus}.
+ *
+ * Poll this until `status` reaches a terminal state:
+ * `'completed'` | `'failed'` | `'cancelled'`.
+ *
+ * @example
+ * ```typescript
+ * const status = await client.getPlayStatus(runId);
+ * if (status.status === 'completed') {
+ *   console.log('Done:', status.result);
+ * } else if (status.status === 'running' || status.status === 'waiting') {
+ *   console.log('Logs so far:', status.progress?.logs);
+ * }
+ * ```
+ */
+interface PlayStatus {
+    /** Public play-run identifier. */
+    runId: string;
+    /** Public Deepline play-run API version. */
+    apiVersion?: number;
+    /** Saved play name for this run, when available. */
+    name?: string;
+    /** Alias for `name` used by run/result APIs. */
+    playName?: string;
+    /** Product-level play-run state. */
+    status: 'queued' | 'running' | 'waiting' | 'completed' | 'failed' | 'cancelled';
+    /** Execution progress with logs and error details. */
+    progress?: PlayProgressStatus;
+    /** Partial or final result. Available once the play returns. */
+    result?: unknown;
+    /** Temporal-backed run metadata when returned by the status endpoint. */
+    run?: {
+        startTime?: string | null;
+        closeTime?: string | null;
+        [key: string]: unknown;
+    } | null;
+    /** Server-rendered result view metadata for CLI/UI summaries. */
+    resultView?: unknown;
+    /** Canonical run contract snapshot metadata, when available. */
+    contract?: Record<string, unknown> | null;
+    /** If the run is blocked on a durable boundary, expose the public wait state. */
+    wait?: {
+        kind: 'integration_event' | 'sleep';
+        boundaryId?: string;
+        eventKey?: string;
+        until?: number;
+    } | null;
+}
+type LiveEventScope = 'play' | 'agent';
+interface LiveEventEnvelope<TPayload = unknown> {
+    cursor: string;
+    streamId: string;
+    scope: LiveEventScope;
+    type: string;
+    at: string;
+    payload: TPayload;
+}
+type PlayLiveEvent = LiveEventEnvelope<unknown> & {
+    scope: 'play';
+};
+/**
+ * Result returned by {@link DeeplineClient.stopPlay}.
+ */
+interface StopPlayRunResult {
+    /** Public play-run identifier that was stopped. */
+    runId: string;
+    /** Stop request acknowledgement. */
+    stopped: true;
+    /** Number of open HITL interactions marked cancelled. */
+    hitlCancelledCount: number;
+}
+/**
+ * Summary of a single play run, returned by {@link DeeplineClient.listPlayRuns}.
+ */
+interface PlayRunListItem {
+    /** Temporal workflow ID. */
+    workflowId: string;
+    /** Temporal run ID (unique per retry of the same workflow). */
+    runId: string;
+    /** Workflow type (typically `'Workflow'`). */
+    type: string;
+    /** Human-readable status (e.g. `'Completed'`, `'Failed'`). */
+    status: string;
+    /** ISO 8601 timestamp when the run started. */
+    startTime: string | null;
+    /** ISO 8601 timestamp when the run finished. */
+    closeTime: string | null;
+    /** Duration string (e.g. `'2.5s'`). */
+    executionTime: string | null;
+    /** Metadata attached to the workflow. */
+    memo: {
+        /** Organization that owns this run. */
+        orgId: string;
+        /** Play name. */
+        playName: string;
+        /** User who triggered the run, if known. */
+        userId: string | null;
+    };
+}
+/**
+ * A single revision (version) of a play's code and configuration.
+ */
+interface PlayRevisionSummary {
+    /** Convex revision document ID used for exact-version runs and live promotion. */
+    _id?: string;
+    /** Monotonically increasing version number. */
+    version: number;
+    /** R2 storage reference for the bundled code artifact. */
+    artifactStorageKey?: string | null;
+    /** Immutable artifact hash for the revision. */
+    artifactHash?: string | null;
+    /** Static dependency graph hash for the revision. */
+    graphHash?: string | null;
+    /** Hash of the original source file. */
+    sourceHash?: string | null;
+    /** Original TypeScript source code. */
+    sourceCode?: string | null;
+    /** Primary key column for CSV-based plays. */
+    tableNamespace?: string | null;
+    /** Static pipeline definition (for declarative plays). */
+    staticPipeline?: unknown;
+    /** Extracted binding metadata. */
+    bindings?: unknown;
+    /** Human-readable description of this revision. */
+    description?: string | null;
+    /** Unix timestamp (ms) when this revision was created. */
+    createdAt?: number;
+    /** Unix timestamp (ms) of last update. */
+    updatedAt?: number;
+}
+/**
+ * Aggregate row-processing stats for a play's sheet.
+ */
+interface PlaySheetStats {
+    total: number;
+    queued: number;
+    running: number;
+    completed: number;
+    failed: number;
+}
+/**
+ * Per-column processing stats within a play's sheet.
+ */
+interface PlaySheetColumnStats {
+    queued: number;
+    running: number;
+    completed: number;
+    failed: number;
+    cached: number;
+}
+/**
+ * Summary of a play's data sheet state.
+ */
+interface PlaySheetSummary {
+    /** Aggregate stats across all rows. */
+    stats: PlaySheetStats;
+    /** Per-column breakdown of processing state. */
+    columns: Record<string, PlaySheetColumnStats>;
+}
+/**
+ * Full play definition with revision history and run stats.
+ *
+ * Returned by {@link DeeplineClient.getPlay}.
+ */
+interface PlayDefinitionDetail {
+    /** Convex document ID. */
+    _id: string;
+    /** Stable registry key. */
+    playKey?: string;
+    /** Canonical owner-qualified play reference. */
+    reference?: string;
+    /** Play name (unique within an org). */
+    name: string;
+    /** Human-friendly display name for UI surfaces. */
+    displayName?: string;
+    /** Whether this entry comes from the Deepline prebuilt registry or the org-owned catalog. */
+    origin?: 'prebuilt' | 'owned';
+    /** Ownership class used for permissions and badges. */
+    ownerType?: 'deepline' | 'org';
+    /** Slug of the owning workspace, or `deepline` for system plays. */
+    ownerSlug?: string;
+    /** Scope in the control plane. */
+    scope?: 'org' | 'system';
+    /** Whether the current actor can edit this play in place. */
+    canEdit?: boolean;
+    /** Whether the current actor can clone this play into their org. */
+    canClone?: boolean;
+    /** Organization ID that owns this play. */
+    orgId: string;
+    /** User ID that created the play. */
+    userId: string;
+    /** Total number of times this play has been executed. */
+    runCount: number;
+    /** Primary key column for CSV-based plays. */
+    tableNamespace?: string | null;
+    /** Temporal workflow ID of the latest run. */
+    latestRunId?: string | null;
+    /** Unix timestamp (ms). */
+    createdAt: number;
+    /** Unix timestamp (ms). */
+    updatedAt: number;
+    /** Source code of the current revision. */
+    sourceCode?: string | null;
+    /** Static pipeline, if applicable. */
+    staticPipeline?: unknown;
+    /** Serialized input schema contract for rendering / validation help. */
+    inputSchema?: Record<string, unknown> | null;
+    /** Serialized output schema contract for rendering / validation help. */
+    outputSchema?: Record<string, unknown> | null;
+    /** Alternate names that resolve to this play. */
+    aliases?: string[];
+    /** The revision that run-by-name resolves to. */
+    currentRevision?: PlayRevisionSummary | null;
+    /** The current working revision (may differ from live). */
+    workingRevision?: PlayRevisionSummary | null;
+    /** The live revision that executes for named runs. */
+    liveRevision?: PlayRevisionSummary | null;
+    /** `true` if the working revision differs from the live revision. */
+    isDraftDirty?: boolean;
+    /** Compatibility field for older readers. */
+    currentPublishedVersion?: number | null;
+}
+interface PlayListItem {
+    playKey?: string;
+    reference?: string;
+    name: string;
+    displayName?: string;
+    origin?: 'prebuilt' | 'owned';
+    ownerType?: 'deepline' | 'org';
+    ownerSlug?: string;
+    canEdit?: boolean;
+    canClone?: boolean;
+    orgId: string;
+    userId: string;
+    runCount: number;
+    updatedAt: number;
+    createdAt: number;
+    currentPublishedVersion?: number | null;
+    tableNamespace?: string | null;
+    isDraftDirty?: boolean;
+    inputSchema?: Record<string, unknown> | null;
+    outputSchema?: Record<string, unknown> | null;
+    aliases?: string[];
+}
+interface PlayDescription {
+    name: string;
+    reference?: string;
+    displayName?: string;
+    origin?: 'prebuilt' | 'owned';
+    ownerType?: 'deepline' | 'org';
+    canEdit?: boolean;
+    canClone?: boolean;
+    aliases: string[];
+    inputSchema?: Record<string, unknown> | null;
+    outputSchema?: Record<string, unknown> | null;
+    runCommand: string;
+    examples: string[];
+    currentPublishedVersion?: number | null;
+    isDraftDirty?: boolean;
+    latestRunId?: string | null;
+}
+/**
+ * Complete play detail including definition, recent runs, and sheet state.
+ *
+ * Returned by {@link DeeplineClient.getPlay}.
+ *
+ * @example
+ * ```typescript
+ * const detail = await client.getPlay('email-waterfall');
+ * console.log(`${detail.play.name} — ${detail.play.runCount} runs`);
+ * console.log(`Live: v${detail.play.liveRevision?.version}`);
+ * console.log(`Latest runs:`, detail.latestRuns.map(r => r.status));
+ * ```
+ */
+interface PlayDetail {
+    /** Full play definition with revisions. */
+    play: PlayDefinitionDetail;
+    /** Most recent runs (newest first). */
+    latestRuns: PlayRunListItem[];
+    /** Sheet processing summary. */
+    sheetSummary: PlaySheetSummary;
+    /** Neon database URL for this play's customer data. */
+    customerDbUrl: string;
+    /** Change cursor for incremental sync. */
+    deltaCursor: number;
+}
+interface ClearPlayHistoryRequest {
+    /** Optional explicit ctx.map keys to clear. Omit to clear all discovered sheets for the play. */
+    tableNamespaces?: string[];
+}
+interface ClearPlayHistoryResult {
+    playName: string;
+    deletedRuns: number;
+    droppedTables: string[];
+}
+/**
+ * Response from starting a play run.
+ *
+ * Internal/advanced payload returned by low-level play submission primitives.
+ * Most callers should prefer `deepline play run`, {@link DeeplineClient.runPlay},
+ * or {@link PlayJob.get}.
+ *
+ * @example
+ * ```typescript
+ * const started = await client.startPlayRun({ name: 'my-play', input: { domain: 'stripe.com' } });
+ * console.log(`Started: ${started.workflowId}`);
+ * console.log(`Status URL: ${started.statusUrl}`);
+ * console.log(`Dashboard: ${started.dashboardUrl}`);
+ * ```
+ */
+interface PlayRunStart {
+    /** Temporal workflow ID for tracking this execution. */
+    workflowId: string;
+    /** Public Deepline play-run API version. */
+    apiVersion?: number;
+    /** Play name (echoed back from the request). */
+    name?: string;
+    /** Initial status (typically `'RUNNING'`). */
+    status?: string;
+    /** Resolved runtime backend used for this run. */
+    runtimeBackend?: string;
+    /** Canonical run contract compatibility metadata. */
+    contract?: Record<string, unknown> | null;
+    /** URL to poll for status updates. */
+    statusUrl?: string;
+    /** Dashboard URL for the named play. */
+    dashboardUrl?: string;
+    /** Terminal status returned when the start request used a short completion wait. */
+    finalStatus?: unknown;
+}
+/**
+ * Result returned by {@link DeeplineClient.checkPlayArtifact}.
+ *
+ * This is the check-only version of play artifact registration: the server runs
+ * the same preflight compiler and static-analysis pass without storing,
+ * publishing, or starting a Temporal run.
+ */
+interface PlayCheckResult {
+    valid: boolean;
+    errors: string[];
+    staticPipeline?: Record<string, unknown> | null;
+    artifactHash?: string | null;
+    graphHash?: string | null;
+}
+/**
+ * Request body for starting a play run via {@link DeeplineClient.startPlayRun}.
+ *
+ * Internal/advanced request shape for low-level submission primitives.
+ * Most callers should prefer `deepline play run`, {@link DeeplineClient.runPlay},
+ * or {@link Deepline.connect}.
+ *
+ * Either `name` (for live plays) or `artifactStorageKey` (for packaged ad hoc runs) is required.
+ *
+ * @example
+ * ```typescript
+ * // Run a live play by name:
+ * await client.startPlayRun({ name: 'email-waterfall', input: { domain: 'stripe.com' } });
+ *
+ * // Run a packaged ad hoc play by registered artifact:
+ * await client.startPlayRun({
+ *   artifactStorageKey: 'plays/artifacts/org/acme/my-play/playgraph_abc123.json',
+ *   input: { domain: 'stripe.com' },
+ * });
+ * ```
+ */
+interface StartPlayRunRequest {
+    /** Play name for registered revisions. */
+    name?: string;
+    /** Explicit revision ID when the caller wants a specific saved version. */
+    revisionId?: string;
+    /** R2 artifact key for ad hoc artifact-backed runs. */
+    artifactStorageKey?: string;
+    /** Source snapshot already validated while registering this artifact. */
+    sourceCode?: string;
+    /** Static pipeline already produced while registering this artifact. */
+    staticPipeline?: unknown;
+    /** Artifact content hash already validated while registering this artifact. */
+    artifactHash?: string;
+    /** Static graph hash already validated while registering this artifact. */
+    graphHash?: string;
+    /** Optional preloaded artifact snapshot for immediate ad hoc execution. */
+    runtimeArtifact?: Record<string, unknown>;
+    /** Compiler manifest for ad hoc graph runs, including imported play dependencies. */
+    compilerManifest?: PlayCompilerManifest;
+    /** Primary input file bytes for one-shot server-side staging. */
+    inputFileUpload?: unknown;
+    /** Packaged file bytes for one-shot server-side staging. */
+    packagedFileUploads?: unknown[];
+    /** Runtime input passed to the play function as its second argument. */
+    input?: Record<string, unknown>;
+    /** Staged file reference for the primary input file (e.g. CSV). */
+    inputFile?: unknown;
+    /** Additional staged file references (dependencies, data files). */
+    packagedFiles?: unknown[];
+    /** Force-supersede any active runs for this play before starting. */
+    force?: boolean;
+    /** Optionally let the start request wait briefly and return a terminal result. */
+    waitForCompletionMs?: number;
+    /**
+     * Per-run execution profile override. The server defaults to `workers_edge`;
+     * tests/benchmarks pass `legacy` or `local` here. Most callers should leave
+     * this unset.
+     */
+    profile?: string;
+}
+/**
+ * Request body for making a play revision live.
+ *
+ * If omitted, the server promotes the current working revision.
+ */
+interface PublishPlayVersionRequest {
+    /** Explicit revision ID to make live. */
+    revisionId?: string;
+}
+/**
+ * Result returned after making a play revision live.
+ */
+interface PublishPlayVersionResult {
+    success: boolean;
+    name: string;
+    liveVersion?: number;
+    triggerMetadata?: unknown;
+    triggerBindings?: unknown;
+}
+/**
+ * Result returned after deleting an org-owned play.
+ */
+interface DeletePlayResult {
+    deleted: boolean;
+    name: string;
+    deletedRevisionCount: number;
+    deletedBindingCount: number;
+    deletedRunCount: number;
+}
+
+interface PlayStagedFileRef {
+    storageKind: 'r2';
+    storageKey: string;
+    logicalPath: string;
+    fileName: string;
+    contentHash: string;
+    contentType: string;
+    bytes: number;
+}
 
+/**
+ * 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',
+ * });
+ * ```
+ */
 declare class DeeplineClient {
     private readonly http;
     private readonly config;
+    /**
+     * @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);
+    /** The resolved base URL this client is targeting (e.g. `"http://localhost:3000"`). */
     get baseUrl(): string;
-    /** List available tools. */
+    private compactSchema;
+    private playRunCommand;
+    private summarizePlayListItem;
+    private summarizePlayDetail;
+    /**
+     * 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`);
+     * ```
+     */
     listTools(): Promise<ToolDefinition[]>;
-    /** Execute a single tool. */
+    /**
+     * 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);
+     * ```
+     */
+    getTool(toolId: string): Promise<ToolMetadata>;
+    /**
+     * 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", ... }
+     * ```
+     */
     executeTool(toolId: string, input: Record<string, unknown>): Promise<unknown>;
     /**
-     * Submit a play for cloud execution.
-     * Returns a workflowId. Use pollPlay() to get status.
+     * 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);
+     * ```
+     */
+    executeToolRaw(toolId: string, input: Record<string, unknown>): Promise<Record<string, unknown>>;
+    queryCustomerDb(input: {
+        sql: string;
+        maxRows?: number;
+    }): Promise<CustomerDbQueryResult>;
+    /**
+     * 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',
+     * });
+     * ```
      */
-    submitPlay(code: string, csvPath: string, name?: string): Promise<{
-        workflowId: string;
+    startPlayRun(request: StartPlayRunRequest): Promise<PlayRunStart>;
+    startPlayRunStream(request: StartPlayRunRequest, options?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<PlayLiveEvent>;
+    /**
+     * Register a bundled play artifact.
+     *
+     * Internal/advanced primitive used by packaging flows. Public callers should
+     * prefer the CLI, {@link submitPlay}, or {@link runPlay}.
+     */
+    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;
     }>;
-    /** Poll workflow status. */
+    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;
+        }>;
+    }>;
+    compilePlayManifest(input: {
+        name: string;
+        sourceCode: string;
+        artifact: Record<string, unknown>;
+        importedPlayDependencies?: PlayCompilerManifest[];
+    }): Promise<PlayCompilerManifest>;
+    /**
+     * 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`.
+     */
+    checkPlayArtifact(input: {
+        name?: string;
+        sourceCode: string;
+        artifact: Record<string, unknown>;
+    }): Promise<PlayCheckResult>;
+    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>;
+    /**
+     * 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 } },
+     * );
+     * ```
+     */
+    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>;
+    /**
+     * 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
+     * ```
+     */
+    stagePlayFiles(files: Array<{
+        logicalPath: string;
+        contentBase64: string;
+        contentHash: string;
+        contentType: string;
+        bytes: number;
+    }>): Promise<PlayStagedFileRef[]>;
+    resolveStagedPlayFiles(files: Array<{
+        logicalPath: string;
+        contentHash: string;
+        contentType: string;
+        bytes: number;
+    }>): Promise<{
+        files: PlayStagedFileRef[];
+        missing: Array<{
+            logicalPath: string;
+            contentHash: string;
+        }>;
+    }>;
+    /**
+     * 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`);
+     * ```
+     */
     getPlayStatus(workflowId: string): Promise<PlayStatus>;
-    /** Cancel a running play. */
+    /**
+     * 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.
+     */
+    getPlayTailStatus(workflowId: string, options?: {
+        afterLogIndex?: number;
+        waitMs?: number;
+        terminalOnly?: boolean;
+    }): Promise<PlayStatus>;
+    /**
+     * 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.
+     */
+    streamPlayRunEvents(workflowId: string, options?: {
+        signal?: AbortSignal;
+        lastEventId?: string;
+        mode?: 'cli' | 'ui';
+    }): AsyncGenerator<PlayLiveEvent>;
+    /**
+     * 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');
+     * ```
+     */
     cancelPlay(workflowId: string): Promise<void>;
     /**
-     * Run a play end-to-end: submit, poll until done, return result.
-     * onProgress is called on each poll with current status.
+     * Stop a running play execution, including open HITL waits.
+     *
+     * @param workflowId - Temporal workflow ID to stop
+     * @param options.reason - Optional audit/debug reason
+     */
+    stopPlay(workflowId: string, options?: {
+        reason?: string;
+    }): Promise<StopPlayRunResult>;
+    /**
+     * 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})`);
+     * }
+     * ```
+     */
+    listPlayRuns(playName: string): Promise<PlayRunListItem[]>;
+    listPlays(): Promise<PlayListItem[]>;
+    searchPlays(options: {
+        query: string;
+        origin?: 'prebuilt' | 'owned';
+        compact?: boolean;
+    }): Promise<PlayDescription[]>;
+    /**
+     * 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}`);
+     * ```
+     */
+    getPlay(name: string): Promise<PlayDetail>;
+    describePlay(name: string, options?: {
+        compact?: boolean;
+    }): Promise<PlayDescription>;
+    /**
+     * Clear run history and durable sheet/result data for a play without deleting
+     * the play definition or revisions.
+     */
+    clearPlayHistory(name: string, request?: ClearPlayHistoryRequest): Promise<ClearPlayHistoryResult>;
+    /**
+     * 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)
+     */
+    listPlayVersions(name: string): Promise<PlayRevisionSummary[]>;
+    /**
+     * 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}`);
+     * }
+     * ```
+     */
+    publishPlayVersion(name: string, request?: PublishPlayVersionRequest): Promise<PublishPlayVersionResult>;
+    /**
+     * Delete an org-owned play definition, including its revisions, trigger
+     * bindings, and local run records. Deepline prebuilt plays are read-only.
+     */
+    deletePlay(name: string): Promise<DeletePlayResult>;
+    /**
+     * 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'
+     * ```
      */
-    runPlay(code: string, csvPath: string, name?: string, options?: {
+    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>;
-    /** Health check. */
+    /**
+     * 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" }
+     * ```
+     */
     health(): Promise<{
         status: string;
         version?: string;
     }>;
 }
-interface PlayStatus {
-    workflowId: string;
-    temporalStatus: string;
-    progress?: {
-        status: string;
-        totalRows?: number;
-        logs: string[];
-        error?: string;
-    };
-    result?: unknown;
-}
 
+declare const SDK_VERSION = "0.1.1";
+declare const SDK_API_CONTRACT = "2026-04-plays-v1";
+
+/**
+ * Base error class for all Deepline SDK errors.
+ *
+ * Every error thrown by the SDK extends this class, so you can catch all
+ * Deepline-specific errors with a single `catch (e) { if (e instanceof DeeplineError) }`.
+ *
+ * @example
+ * ```typescript
+ * import { DeeplineClient, DeeplineError, AuthError } from 'deepline';
+ *
+ * const client = new DeeplineClient();
+ * try {
+ *   await client.executeTool('apollo_people_search', { query: 'cto' });
+ * } catch (err) {
+ *   if (err instanceof AuthError) {
+ *     console.error('Bad API key — run: deepline auth register');
+ *   } else if (err instanceof DeeplineError) {
+ *     console.error(`API error ${err.statusCode}: ${err.message}`);
+ *   }
+ * }
+ * ```
+ */
 declare class DeeplineError extends Error {
+    /** HTTP status code from the API response, if applicable. */
     statusCode?: number | undefined;
+    /** Machine-readable error code (e.g. `'AUTH_ERROR'`, `'RATE_LIMIT'`, `'CONFIG_ERROR'`). */
     code?: string | undefined;
+    /** Additional context from the API response body. */
     details?: Record<string, unknown> | undefined;
-    constructor(message: string, statusCode?: number | undefined, code?: string | undefined, details?: Record<string, unknown> | undefined);
+    constructor(message: string, 
+    /** HTTP status code from the API response, if applicable. */
+    statusCode?: number | undefined, 
+    /** Machine-readable error code (e.g. `'AUTH_ERROR'`, `'RATE_LIMIT'`, `'CONFIG_ERROR'`). */
+    code?: string | undefined, 
+    /** Additional context from the API response body. */
+    details?: Record<string, unknown> | undefined);
 }
+/**
+ * Thrown when the API rejects the request due to an invalid or missing API key.
+ *
+ * This maps to HTTP 401/403 responses. The SDK never retries auth errors —
+ * they fail immediately.
+ *
+ * Fix: run `deepline auth register` to obtain a valid key, or pass one via
+ * the `apiKey` option or `DEEPLINE_API_KEY` environment variable.
+ *
+ * @example
+ * ```typescript
+ * import { AuthError } from 'deepline';
+ *
+ * try {
+ *   await client.listTools();
+ * } catch (err) {
+ *   if (err instanceof AuthError) {
+ *     // Redirect user to auth flow
+ *   }
+ * }
+ * ```
+ */
 declare class AuthError extends DeeplineError {
     constructor(message?: string);
 }
+/**
+ * Thrown when the API returns HTTP 429 (Too Many Requests).
+ *
+ * The SDK retries rate-limited requests automatically up to `maxRetries` times
+ * with exponential backoff. This error is only thrown when all retries are exhausted.
+ *
+ * Use {@link RateLimitError.retryAfterMs} to implement your own backoff if needed.
+ *
+ * @example
+ * ```typescript
+ * import { RateLimitError } from 'deepline';
+ *
+ * try {
+ *   await client.executeTool('apollo_people_search', { query: 'cto' });
+ * } catch (err) {
+ *   if (err instanceof RateLimitError) {
+ *     console.log(`Retry after ${err.retryAfterMs}ms`);
+ *     await sleep(err.retryAfterMs);
+ *     // retry...
+ *   }
+ * }
+ * ```
+ */
 declare class RateLimitError extends DeeplineError {
+    /** Milliseconds to wait before retrying, from the `Retry-After` response header. Defaults to 5000. */
     retryAfterMs: number;
     constructor(retryAfterMs?: number, message?: string);
 }
+/**
+ * Thrown when the SDK cannot resolve a valid configuration.
+ *
+ * Most commonly: no API key found in any of the resolution sources
+ * (explicit option, environment variable, CLI env files).
+ *
+ * @example
+ * ```typescript
+ * import { ConfigError } from 'deepline';
+ *
+ * try {
+ *   const client = new DeeplineClient();
+ * } catch (err) {
+ *   if (err instanceof ConfigError) {
+ *     console.error('Run: deepline auth register');
+ *   }
+ * }
+ * ```
+ */
 declare class ConfigError extends DeeplineError {
     constructor(message: string);
 }
 
+/** Production API base URL. */
 declare const PROD_URL = "https://code.deepline.com";
+/**
+ * Resolve SDK configuration from all available sources.
+ *
+ * Merges explicit options, environment variables, and CLI-managed config files
+ * into a fully validated {@link ResolvedConfig}. See the module-level docs for
+ * the complete resolution order.
+ *
+ * @param options - Optional overrides (highest priority)
+ * @returns Fully resolved configuration with all fields populated
+ * @throws {@link ConfigError} if no API key can be found from any source
+ *
+ * @example
+ * ```typescript
+ * import { resolveConfig } from 'deepline';
+ *
+ * // Auto-resolve everything:
+ * const config = resolveConfig();
+ * console.log(config.baseUrl); // "http://localhost:3000" or "https://code.deepline.com"
+ *
+ * // Override specific values:
+ * const config2 = resolveConfig({ baseUrl: 'http://localhost:4000', timeout: 10_000 });
+ * ```
+ */
 declare function resolveConfig(options?: DeeplineClientOptions): ResolvedConfig;
 
-export { AuthError, ConfigError, DeeplineClient, type DeeplineClientOptions, DeeplineError, PROD_URL, type PlayRunResult, type PlayStatus, RateLimitError, type ResolvedConfig, type ToolDefinition, type ToolExecuteResult, resolveConfig };
+/**
+ * Result of converting a tool response to a list of records.
+ *
+ * @example
+ * ```typescript
+ * const conversion = tryConvertToList(toolResponse, {
+ *   listExtractorPaths: ['people', 'result.data'],
+ * });
+ * if (conversion) {
+ *   console.log(`Found ${conversion.rows.length} rows via ${conversion.strategy}`);
+ *   console.log(`Source path: ${conversion.sourcePath}`);
+ * }
+ * ```
+ */
+type ListConversionResult = {
+    /** Normalized array of record objects. Scalars are wrapped as `{ value: <scalar> }`. */
+    rows: Array<Record<string, unknown>>;
+    /**
+     * How the list was found:
+     * - `'configured_paths'` — matched one of the `listExtractorPaths`
+     * - `'auto_detected'` — found via recursive DFS (longest array wins)
+     */
+    strategy: 'configured_paths' | 'auto_detected';
+    /** Dotted path to where the list was found (e.g. `"result.data"`, `"people"`). */
+    sourcePath: string | null;
+};
+type Scalar = string | number | boolean | null;
+/** Ergonomic wrapper returned by high-level SDK tool execution. */
+type ToolCallResult = {
+    /** Raw tool response. Use this when a provider-specific shape matters. */
+    readonly value: unknown;
+    /** Best-effort email extraction from common response shapes. */
+    getEmail(): string | null;
+    /** Best-effort phone extraction from common response shapes. */
+    getPhone(): string | null;
+    /** Best-effort list extraction. Returns rows only; use `tryConvertToList` for metadata. */
+    tryList(options?: {
+        listExtractorPaths?: string[];
+    }): Array<Record<string, unknown>> | null;
+};
+/** Wrap a raw tool response with the high-level SDK result API. */
+declare function createToolCallResult(value: unknown): ToolCallResult;
+/**
+ * Extract a list of records from a tool response.
+ *
+ * Handles the common problem of tools returning data in varied shapes.
+ * First tries configured `listExtractorPaths` (from tool metadata), then
+ * falls back to automatic detection via recursive DFS.
+ *
+ * ## Extraction strategy
+ *
+ * 1. **Configured paths** — If `listExtractorPaths` is provided, each path is
+ *    tried against multiple candidate roots (raw payload, `.result`, `.result.data`).
+ *    First match wins.
+ *
+ * 2. **Auto-detection** — If no configured path matches, recursively searches
+ *    the response for the largest array of objects (up to depth 5).
+ *
+ * @param payload - Raw tool response
+ * @param options - Optional extraction configuration
+ * @returns Extracted list with metadata, or `null` if no list found
+ *
+ * @example Using configured paths (from tool metadata)
+ * ```typescript
+ * const meta = await client.getTool('apollo_people_search');
+ * const result = await client.executeTool('apollo_people_search', { query: 'cto' });
+ *
+ * const list = tryConvertToList(result, {
+ *   listExtractorPaths: meta.listExtractorPaths,
+ * });
+ * if (list) {
+ *   console.log(`${list.rows.length} people found via ${list.strategy}`);
+ *   // Write to CSV
+ *   const csv = writeCsvOutputFile(list.rows, 'apollo-people');
+ *   console.log(`Saved to ${csv.path}`);
+ * }
+ * ```
+ *
+ * @example Auto-detection (no configured paths)
+ * ```typescript
+ * const result = await client.executeTool('some_tool', { query: 'test' });
+ * const list = tryConvertToList(result);
+ * // Finds the largest array of objects anywhere in the response
+ * ```
+ */
+declare function tryConvertToList(payload: unknown, options?: {
+    listExtractorPaths?: string[];
+}): ListConversionResult | null;
+/**
+ * Write a JSON payload to a timestamped file.
+ *
+ * Output location: `~/.local/share/deepline/data/{stem}_{timestamp}.json`
+ *
+ * @param payload - Any JSON-serializable value
+ * @param stem - Filename prefix (e.g. tool ID or play name)
+ * @returns Absolute path to the written file
+ *
+ * @example
+ * ```typescript
+ * const result = await client.executeTool('test_company_search', { domain: 'stripe.com' });
+ * const path = writeJsonOutputFile(result, 'test_company_search');
+ * console.log(`Saved to ${path}`);
+ * // ~/.local/share/deepline/data/test_company_search_1713456789000.json
+ * ```
+ */
+declare function writeJsonOutputFile(payload: unknown, stem: string): string;
+/**
+ * Write an array of records to a CSV file.
+ *
+ * Columns are ordered by first appearance across all rows. Cells containing
+ * commas, quotes, or newlines are properly escaped. Objects and arrays are
+ * JSON-serialized.
+ *
+ * Output location: `~/.local/share/deepline/data/{stem}_{timestamp}.csv`
+ *
+ * @param rows - Array of record objects
+ * @param stem - Filename prefix
+ * @returns File metadata including path, row count, columns, and a 5×5 preview
+ *
+ * @example
+ * ```typescript
+ * const list = tryConvertToList(toolResponse);
+ * if (list) {
+ *   const csv = writeCsvOutputFile(list.rows, 'search-results');
+ *   console.log(`Wrote ${csv.rowCount} rows, ${csv.columns.length} columns`);
+ *   console.log(`File: ${csv.path}`);
+ *   console.log(`Preview:\n${csv.preview}`);
+ * }
+ * ```
+ */
+declare function writeCsvOutputFile(rows: Array<Record<string, unknown>>, stem: string): {
+    path: string;
+    rowCount: number;
+    columns: string[];
+    preview: string;
+};
+/**
+ * Extract scalar (non-nested) fields from a tool response for summary display.
+ *
+ * Searches through candidate roots (raw → `.result` → `.result.data`) and
+ * returns the first set of scalar fields found. Useful for displaying a
+ * quick summary of single-record responses.
+ *
+ * @param payload - Raw tool response
+ * @returns Object containing only scalar fields (string, number, boolean, null)
+ *
+ * @example
+ * ```typescript
+ * const result = await client.executeTool('test_company_search', { domain: 'stripe.com' });
+ * const summary = extractSummaryFields(result);
+ * // { name: "Stripe", industry: "Financial Services", employeeCount: 8000 }
+ * // (nested objects and arrays are excluded)
+ * ```
+ */
+declare function extractSummaryFields(payload: unknown): Record<string, Scalar>;
+
+interface PlayR2FileRef {
+    storageKind: 'r2';
+    storageKey: string;
+    logicalPath: string;
+    fileName: string;
+    contentHash: string;
+    contentType: string;
+    bytes: number;
+}
+type PlayExecutionFileRef = PlayR2FileRef;
+
+declare const PLAY_DATASET_BRAND: unique symbol;
+type PlayDatasetKind = 'csv' | 'map';
+type PlayDatasetBacking = {
+    storage: 'neon_sheet';
+    sheet: {
+        playName: string;
+        tableNamespace: string;
+    };
+} | {
+    storage: 'r2_file';
+    file: PlayExecutionFileRef;
+};
+type PlayDatasetInput<T> = ReadonlyArray<T> | Iterable<T> | AsyncIterable<T> | PlayDataset<T>;
+interface PlayDataset<T> extends AsyncIterable<T> {
+    readonly [PLAY_DATASET_BRAND]: true;
+    readonly datasetKind: PlayDatasetKind;
+    readonly datasetId: string;
+    readonly backing?: PlayDatasetBacking;
+    readonly sourceLabel?: string | null;
+    readonly tableNamespace?: string | null;
+    count(): Promise<number>;
+    peek(limit?: number): Promise<T[]>;
+    /**
+     * Explicit escape hatch for bounded result sets.
+     * Large datasets should flow by handle through Neon-backed storage, not
+     * through worker memory as giant arrays.
+     */
+    materialize(limit?: number): Promise<T[]>;
+    toJSON(): {
+        kind: 'dataset';
+        datasetKind: PlayDatasetKind;
+        datasetId: string;
+        count: number;
+        backing?: PlayDatasetBacking;
+        sourceLabel?: string | null;
+        tableNamespace?: string | null;
+        columns?: string[];
+        preview: T[];
+    };
+}
+
+/**
+ * Optional trigger bindings for a play.
+ *
+ * Plays can be triggered by webhooks (with HMAC signature verification)
+ * or cron schedules. Bindings are declared as the third argument to
+ * {@link definePlay}.
+ *
+ * @example Webhook with HMAC verification
+ * ```typescript
+ * definePlay('webhook-handler', handler, {
+ *   webhook: {
+ *     hmac: {
+ *       algorithm: 'sha256',
+ *       header: 'X-Hub-Signature-256',
+ *       secretEnv: 'WEBHOOK_SECRET',
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @example Cron schedule
+ * ```typescript
+ * definePlay('nightly-sync', handler, {
+ *   cron: { schedule: '0 2 * * *', timezone: 'UTC' },
+ * });
+ * ```
+ */
+type PlayBindings = {
+    /** Optional per-run billing controls enforced by the runtime. */
+    billing?: {
+        /** Stop the run before a billed action would push total run credits above this cap. */
+        maxCreditsPerRun?: number;
+    };
+    /** Webhook trigger with optional HMAC signature verification. */
+    webhook?: {
+        hmac?: {
+            /** Hash algorithm. Currently only `'sha256'` is supported. */
+            algorithm?: 'sha256';
+            /** HTTP header containing the signature (e.g. `'X-Hub-Signature-256'`). */
+            header?: string;
+            /** Environment variable name holding the HMAC secret. */
+            secretEnv: string;
+        };
+    };
+    /** Cron schedule trigger. */
+    cron?: {
+        /** Cron expression (e.g. `'0 9 * * *'` for daily at 9am). */
+        schedule: string;
+        /** IANA timezone (e.g. `'America/New_York'`). Defaults to UTC. */
+        timezone?: string;
+    };
+};
+type LoosePlayObject = {
+    [key: string]: LoosePlayObject;
+};
+type ToolExecutionRequest = {
+    id: string;
+    tool: string;
+    input: Record<string, unknown>;
+    description?: string;
+};
+type SdkToolExecutionRequest = {
+    tool: string;
+    input: Record<string, unknown>;
+};
+type ToolExecuteResult<TResult = unknown> = {
+    status: string;
+    result: TResult;
+    _metadata: {
+        toolId: string;
+        execution: {
+            idempotent: true;
+            cached: boolean;
+            source: 'live' | 'checkpoint' | 'cache';
+            cacheKey?: string;
+        };
+        targets: Record<string, {
+            value: unknown;
+            path: string;
+        }>;
+        lists: Record<string, {
+            path: string;
+            count: number | null;
+            keys: Record<string, string>;
+        }>;
+    };
+    get<T = unknown>(target: string): T | null;
+    getEmail(): string | null;
+    getPhone(): string | null;
+    getLinkedin(): string | null;
+    list<T = Record<string, unknown>>(name?: string): T[] | null;
+    listPick<const TKeys extends readonly string[]>(keys: TKeys, name?: string): Array<Record<TKeys[number], unknown>> | null;
+    listKeys(name?: string): Record<string, string>;
+};
+type StepResolver<Row, Value> = (row: Row, ctx: DeeplinePlayRuntimeContext, index: number) => Value | Promise<Value>;
+type ConditionalStepResolver<Row, Value, Else = null> = {
+    readonly kind: 'conditional';
+    readonly when: (row: Row, index: number) => boolean | Promise<boolean>;
+    readonly run: StepResolver<Row, Value>;
+    readonly elseValue: Else;
+    else<ValueElse>(value: ValueElse): ConditionalStepResolver<Row, Value, ValueElse>;
+};
+type StepProgram<Input, Output, Return = Output> = {
+    readonly kind: 'steps';
+    readonly steps: readonly PlayStepProgramStep[];
+    readonly returnResolver?: StepResolver<Output, Return>;
+    readonly __inputType?: (input: Input) => void;
+    step<Name extends string, Value>(name: Name, resolver: StepResolver<Output, Value> | ConditionalStepResolver<Output, Value> | StepProgramResolver<Output, Value>): StepProgram<Input, Output & Record<Name, Value>, Return>;
+    return<Value>(resolver: StepResolver<Output, Value>): StepProgram<Input, Output, Value>;
+};
+type StepProgramResolver<Input, Return> = {
+    readonly kind: 'steps';
+    readonly steps: readonly PlayStepProgramStep[];
+    readonly returnResolver?: StepResolver<never, Return>;
+    readonly __inputType?: (input: Input) => void;
+};
+type PlayStepProgramStep = {
+    readonly name: string;
+    readonly resolver: StepResolver<Record<string, unknown>, unknown> | ConditionalStepResolver<Record<string, unknown>, unknown> | StepProgramResolver<Record<string, unknown>, unknown>;
+};
+type MapStepResolver<Row, Value> = StepResolver<Row, Value> | ConditionalStepResolver<Row, Value> | StepProgramResolver<Row, Value>;
+type MapRowKey<InputRow extends object> = (keyof InputRow & string) | readonly (keyof InputRow & string)[] | ((row: InputRow, index: number) => string | number | readonly unknown[]);
+type MapDefinitionOptions<InputRow extends object> = {
+    staleAfterSeconds?: number;
+    key?: MapRowKey<InputRow>;
+};
+type MapRunOptions = {
+    description?: string;
+};
+type MapStepBuilder<InputRow extends object, OutputRow extends object> = {
+    step<Name extends string, Value>(name: Name, resolver: MapStepResolver<OutputRow, Value>): MapStepBuilder<InputRow, OutputRow & Record<Name, Value>>;
+    run(options?: MapRunOptions): Promise<PlayDataset<OutputRow>>;
+};
+/**
+ * Runtime context available inside a play function.
+ *
+ * Provides methods for calling tools, processing data, and emitting logs.
+ * This context is injected by the Temporal worker — you never construct it directly.
+ *
+ * @example
+ * ```typescript
+ * definePlay('example', async (ctx, input: { domain: string }) => {
+ *   // Call a tool
+ *   const company = await ctx.tools.execute({
+ *     id: 'company_search',
+ *     tool: 'test_company_search',
+ *     input: { domain: input.domain },
+ *     description: 'Look up company details by domain.',
+ *   });
+ *
+ *   // Fan-out: process items with named steps
+ *   const enriched = await ctx
+ *     .map('companies', [{ domain: 'a.com' }, { domain: 'b.com' }], { key: 'domain' })
+ *     .step('company', (row, rowCtx) =>
+ *       rowCtx.tool({
+ *         id: 'company_search',
+ *         tool: 'test_company_search',
+ *         input: { domain: row.domain },
+ *         description: 'Look up company details by domain.',
+ *       }))
+ *     .run({ description: 'Look up company details.' });
+ *
+ *   // Load CSV data
+ *   const leads = await ctx.csv('leads.csv');
+ *
+ *   // Emit a log line (visible in `play tail`)
+ *   ctx.log(`Loaded ${await leads.count()} leads`);
+ *
+ *   // Pause execution
+ *   await ctx.sleep(1000);
+ *
+ *   // Access the raw input object
+ *   console.log(ctx.input);
+ *
+ *   return { company, enriched };
+ * });
+ * ```
+ */
+interface DeeplinePlayRuntimeContext {
+    /**
+     * Load a CSV file as a dataset handle.
+     *
+     * The CSV must be staged or available at the given path. Each row becomes
+     * an object keyed by column headers.
+     *
+     * @typeParam T - Row type (defaults to `Record<string, unknown>`)
+     * @param path - Relative path to the CSV file
+     * The returned dataset supports `for await`, `peek()`, `count()`, and
+     * explicit `materialize()` for small result sets.
+     *
+     * @returns Parsed dataset rows
+     */
+    csv<T = Record<string, unknown>>(path: string, options?: {
+        description?: string;
+    }): Promise<PlayDataset<T>>;
+    /**
+     * Fan-out: process each item through one or more named columns.
+     *
+     * Each key in `columns` becomes an output column. Each value is an async
+     * callback `(row, ctx) => result` that receives the current row and the
+     * play context — call tools, run waterfalls, do arbitrary logic.
+     *
+     * Items are processed in parallel (paced by the rate-limit scheduler).
+     * The first argument identifies the logical map/table namespace. Use
+     * `options.key` to pin durable row identity to stable input fields instead of
+     * hashing the full input row.
+     * `options.staleAfterSeconds` intentionally partitions the durable cache on a
+     * relative time window. Use `86400` for daily reruns; retries inside the same
+     * window still replay safely.
+     *
+     * Returns a dataset handle containing the original rows merged with the new
+     * columns. Input may be a normal array, iterable, async iterable, or another
+     * play dataset handle.
+     *
+     * @typeParam T - Row type
+     * @param key - Logical map key used to isolate row identities (e.g. `'main_table'`, `'email_lookup'`)
+     * @param items - Input rows or dataset handle
+     * @returns Dataset of rows merged with the computed column values
+     *
+     * @example Single tool per row
+     * ```typescript
+     * const results = await ctx
+     *   .map('leads', leads, { key: 'domain' })
+     *   .step('company', (row, ctx) =>
+     *     ctx.tools.execute({
+     *       id: 'company_search',
+     *       tool: 'test_company_search',
+     *       input: { domain: row.domain },
+     *       description: 'Look up company details by domain.',
+     *     }))
+     *   .run({ description: 'Look up companies.' });
+     * // [{ domain: 'stripe.com', company: { name: 'Stripe', ... } }, ...]
+     * ```
+     *
+     * @example Multiple columns with pre/post logic
+     * ```typescript
+     * const results = await ctx
+     *   .map('leads', leads, { key: 'lead_id' })
+     *   .step('company', (row, ctx) =>
+     *     ctx.tools.execute({
+     *       id: 'company_search',
+     *       tool: 'test_company_search',
+     *       input: { domain: row.domain },
+     *       description: 'Look up company details by domain.',
+     *     }))
+     *   .step('score', (row) =>
+     *     row.company?.employeeCount > 100 ? 'enterprise' : 'smb')
+     *   .run({ description: 'Enrich leads.' });
+     * ```
+     */
+    map<TItem extends object>(key: string, items: PlayDatasetInput<TItem>, options?: MapDefinitionOptions<TItem>): MapStepBuilder<TItem, TItem>;
+    /** Tool execution namespace. */
+    tools: {
+        /**
+         * Execute a single tool by stable durable execution id and tool ID.
+         *
+         * @param request - Tool execution request. `id` is the durable execution id;
+         *   omit it in row/map steps when the surrounding step id is the execution id.
+         * @returns The tool's output
+         */
+        execute<TOutput = LoosePlayObject>(request: ToolExecutionRequest): Promise<ToolExecuteResult<TOutput>>;
+    };
+    /**
+     * Execute a single tool by stable durable execution id and tool ID.
+     *
+     * Shorthand for `ctx.tools.execute({ id, tool, input })`; this is the
+     * preferred spelling in row-level step programs.
+     */
+    tool<TOutput = LoosePlayObject>(request: ToolExecutionRequest): Promise<ToolExecuteResult<TOutput>>;
+    step<T>(id: string, run: () => T | Promise<T>): Promise<T>;
+    fetch(key: string, url: string | URL, init?: RequestInit): Promise<{
+        ok: boolean;
+        status: number;
+        statusText: string;
+        url: string;
+        headers: Record<string, string>;
+        bodyText: string;
+        json: unknown | null;
+    }>;
+    runPlay(key: string, playRef: string | PlayReferenceLike, input: Record<string, unknown>, options: {
+        description?: string;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * Emit a log line visible in `play tail` and the play's progress logs.
+     *
+     * @param message - Log message (plain text)
+     */
+    log(message: string): void;
+    /**
+     * Pause play execution for the specified duration.
+     *
+     * Uses Temporal's durable timer — safe across worker restarts.
+     *
+     * @param ms - Duration in milliseconds
+     */
+    sleep(ms: number): Promise<void>;
+    /** The raw input object passed when the play was started. */
+    readonly input: Record<string, unknown>;
+}
+/**
+ * Handle to a running play execution.
+ *
+ * Provides methods to check status, stream logs, wait for completion,
+ * or cancel the execution.
+ *
+ * This handle is the SDK-context equivalent of `deepline play run --watch` and
+ * `POST /api/v2/plays/run`: every surface returns a run id first, then exposes
+ * the completed user output through `PlayJob.get()` or the status endpoint's
+ * `result` field. Runtime logs are available from `status().progress.logs` and
+ * are intentionally separate from the returned output object.
+ *
+ * @typeParam TOutput - The play's return type
+ *
+ * @example
+ * ```typescript
+ * const job: PlayJob = await ctx.play('my-play').run({ domain: 'stripe.com' });
+ *
+ * // Poll status
+ * const status = await job.status();
+ * console.log(status.temporalStatus); // 'RUNNING'
+ *
+ * // Stream logs until completion
+ * const finalStatus = await job.tail({
+ *   onLog: (line) => console.log(`[play] ${line}`),
+ * });
+ *
+ * // Or just wait for the result
+ * const output = await job.get();
+ *
+ * // Cancel if needed
+ * await job.cancel();
+ * ```
+ */
+interface PlayJob<TOutput = unknown> {
+    /** Temporal workflow ID for this execution. */
+    id: string;
+    /** Get the current execution status (single poll). */
+    status(): Promise<PlayStatus>;
+    /**
+     * Stream logs and wait for completion.
+     *
+     * Polls until the play reaches a terminal state, invoking `onLog` for
+     * each new log line. Returns the final status.
+     *
+     * @param options.intervalMs - Poll interval in ms. Default: `500`.
+     * @param options.onLog - Callback for each log line. Default: `console.log`.
+     */
+    tail(options?: {
+        intervalMs?: number;
+        onLog?: (line: string) => void;
+    }): Promise<PlayStatus>;
+    /**
+     * Wait for the play to complete and return its output.
+     *
+     * Polls until terminal state. Throws {@link DeeplineError} if the play
+     * fails, is cancelled, or times out.
+     *
+     * @param options.intervalMs - Poll interval in ms. Default: `500`.
+     * @returns The play's return value
+     * @throws {@link DeeplineError} if the play did not complete successfully
+     */
+    get(options?: {
+        intervalMs?: number;
+    }): Promise<TOutput>;
+    /** Cancel this play execution. */
+    cancel(): Promise<void>;
+    /** Deep-stop this play execution, including open HITL waits. */
+    stop(options?: {
+        reason?: string;
+    }): Promise<StopPlayRunResult>;
+}
+/**
+ * Handle to a named play for remote lifecycle operations.
+ *
+ * Returned by {@link DeeplineContext.play} and attached to {@link DefinedPlay}.
+ * Provides methods to run, inspect, list runs, and publish a play by name.
+ *
+ * @typeParam TInput - The play's input type
+ * @typeParam TOutput - The play's return type
+ *
+ * @example
+ * ```typescript
+ * const ctx = await Deepline.connect();
+ * const play = ctx.play<{ domain: string }, Company>('company-lookup');
+ *
+ * // Get play definition
+ * const detail = await play.get();
+ * console.log(`Live: v${detail.play.currentPublishedVersion}`);
+ *
+ * // Run and wait
+ * const result = await play.runSync({ domain: 'stripe.com' });
+ *
+ * // Run async
+ * const job = await play.run({ domain: 'stripe.com' });
+ * const output = await job.get();
+ *
+ * // List recent runs
+ * const runs = await play.runs();
+ *
+ * // List saved versions
+ * const versions = await play.versions();
+ *
+ * // Publish the current draft
+ * await play.publish();
+ * ```
+ */
+interface DeeplineNamedPlay<TInput = Record<string, unknown>, TOutput = unknown> {
+    /** The play's name. */
+    readonly name: string;
+    /** Fetch the full play definition with revision history and run stats. */
+    get(): Promise<PlayDetail>;
+    /** List recent runs for this play. */
+    runs(): Promise<PlayRunListItem[]>;
+    /** List saved versions for this play (newest first). */
+    versions(): Promise<PlayRevisionSummary[]>;
+    /** Publish a play revision. Defaults to the current working revision. */
+    publish(options?: {
+        revisionId?: string;
+    }): Promise<PublishPlayVersionResult>;
+    /**
+     * Clear run history and durable sheet/result data for this play while keeping
+     * the play definition and revisions.
+     */
+    clearHistory(options?: {
+        tableNamespaces?: string[];
+    }): Promise<ClearPlayHistoryResult>;
+    /**
+     * Start a new run of this play. Returns a {@link PlayJob} for monitoring.
+     *
+     * @param input - Runtime input passed to the play function
+     */
+    run(input: TInput, options?: {
+        revisionId?: string;
+    }): Promise<PlayJob<TOutput>>;
+    /**
+     * Run this play and wait for completion.
+     *
+     * Equivalent to `play.run(input).then(job => job.get())`.
+     *
+     * @param input - Runtime input
+     * @returns The play's return value
+     */
+    runSync(input: TInput, options?: {
+        revisionId?: string;
+    }): Promise<TOutput>;
+}
+type PrebuiltPlayRef = {
+    readonly playName: string;
+    readonly name: string;
+};
+type PlayReferenceLike = {
+    readonly playName?: string;
+    readonly name?: string;
+};
+
+type PlayReturnObject = Record<string, unknown> & {
+    readonly _metadata?: never;
+};
+type PlayInputContract<TInput> = {
+    readonly schema: Record<string, unknown>;
+    readonly __inputType?: TInput;
+};
+type DefinePlayConfig<TInput, TOutput extends PlayReturnObject> = {
+    id: string;
+    input: PlayInputContract<TInput>;
+    run: (ctx: DeeplinePlayRuntimeContext, input: TInput) => Promise<TOutput>;
+    bindings?: PlayBindings;
+    billing?: PlayBindings['billing'];
+};
+declare function steps<TInput>(): StepProgram<TInput, TInput, TInput>;
+declare function when<Row, Value>(predicate: (row: Row, index: number) => boolean | Promise<boolean>, resolver: StepResolver<Row, Value>): ConditionalStepResolver<Row, Value, null>;
+/**
+ * A defined play: both a callable function and a named play handle.
+ *
+ * Created by {@link definePlay}. Can be:
+ * 1. Called directly as a function (for server-side Temporal execution)
+ * 2. Used as a {@link DeeplineNamedPlay} for remote lifecycle operations
+ *
+ * @typeParam TInput - The play's input type
+ * @typeParam TOutput - The play's return type
+ *
+ * @example
+ * ```typescript
+ * import { definePlay } from 'deepline';
+ *
+ * const myPlay = definePlay('my-play', async (ctx, input: { domain: string }) => {
+ *   const company = await ctx.tools.execute({
+ *     id: 'company_search',
+ *     tool: 'test_company_search',
+ *     input: { domain: input.domain },
+ *     description: 'Look up company details by domain.',
+ *   });
+ *   return { company: company.result };
+ * });
+ *
+ * // Type is: DefinedPlay<{ domain: string }, unknown>
+ *
+ * // Use as named play handle:
+ * const detail = await myPlay.get();
+ * const result = await myPlay.runSync({ domain: 'stripe.com' });
+ *
+ * // Access metadata:
+ * console.log(myPlay.playName); // "my-play"
+ * console.log(myPlay.bindings); // undefined (no cron/webhook)
+ * ```
+ */
+type DefinedPlay<TInput, TOutput extends PlayReturnObject> = ((ctx: DeeplinePlayRuntimeContext, input: TInput) => Promise<TOutput>) & DeeplineNamedPlay<TInput, TOutput> & {
+    /** Optional trigger bindings (cron, webhook). */
+    readonly bindings?: PlayBindings;
+    /** The play's name (same as `.name`). */
+    readonly playName: string;
+};
+type PlayMetadata = {
+    name: string;
+    bindings?: PlayBindings;
+    inputSchema?: Record<string, unknown>;
+    billing?: PlayBindings['billing'];
+};
+/**
+ * High-level SDK context with tool shortcuts and play handles.
+ *
+ * Created by {@link Deepline.connect}. Wraps a {@link DeeplineClient} with
+ * a friendlier API for common operations.
+ *
+ * @example
+ * ```typescript
+ * const ctx = await Deepline.connect();
+ *
+ * // Tools
+ * const tools = await ctx.tools.list();
+ * const result = await ctx.tools.execute({
+ *   tool: 'test_company_search',
+ *   input: { domain: 'stripe.com' },
+ * });
+ *
+ * // Plays
+ * const job = await ctx.play('email-waterfall').run({ domain: 'stripe.com' });
+ * const output = await job.get();
+ * ```
+ */
+declare class DeeplineContext {
+    private readonly client;
+    constructor(options?: DeeplineClientOptions);
+    /**
+     * Tool operations namespace.
+     *
+     * @example
+     * ```typescript
+     * const tools = await ctx.tools.list();
+     * const meta = await ctx.tools.get('apollo_people_search');
+     * const result = await ctx.tools.execute({
+     *   tool: 'test_company_search',
+     *   input: { domain: 'stripe.com' },
+     * });
+     * const rows = result.tryList({ listExtractorPaths: ['people'] });
+     * const email = result.getEmail();
+     * ```
+     */
+    get tools(): {
+        /** List all available tools. */
+        list: () => Promise<ToolDefinition[]>;
+        /** Get detailed metadata for a tool. */
+        get: (toolId: string) => Promise<ToolMetadata>;
+        /** Execute a tool and return an ergonomic result wrapper. */
+        execute: (request: SdkToolExecutionRequest) => Promise<ToolCallResult>;
+    };
+    get plays(): {
+        list: () => Promise<PlayListItem[]>;
+        get: <TInput = Record<string, unknown>, TOutput = unknown>(name: string) => DeeplineNamedPlay<TInput, TOutput>;
+    };
+    get prebuilt(): Record<string, PrebuiltPlayRef>;
+    /**
+     * Get a named play handle for remote lifecycle operations.
+     *
+     * @typeParam TInput - Expected input type
+     * @typeParam TOutput - Expected output type
+     * @param name - Play name (as registered on the server)
+     * @returns Named play handle with run, versions, get, publish, etc.
+     *
+     * @example
+     * ```typescript
+     * const play = ctx.play<{ domain: string }>('email-waterfall');
+     * const job = await play.run({ domain: 'stripe.com' });
+     * const result = await job.get();
+     * ```
+     */
+    play<TInput = Record<string, unknown>, TOutput = unknown>(name: string): DeeplineNamedPlay<TInput, TOutput>;
+    runPlay<TInput = Record<string, unknown>, TOutput = unknown>(playOrRef: string | PlayReferenceLike, input: TInput): Promise<TOutput>;
+}
+/**
+ * Static entry point for the Deepline SDK.
+ *
+ * @example
+ * ```typescript
+ * import { Deepline } from 'deepline';
+ *
+ * const ctx = await Deepline.connect();
+ * const tools = await ctx.tools.list();
+ * const result = await ctx.tools.execute({
+ *   tool: 'test_company_search',
+ *   input: { domain: 'stripe.com' },
+ * });
+ * ```
+ */
+declare class Deepline {
+    /**
+     * Create a connected SDK context.
+     *
+     * Resolves configuration from options, environment variables, and CLI config
+     * files. See {@link resolveConfig} for the resolution order.
+     *
+     * @param options - Optional overrides for API key, base URL, etc.
+     * @returns Ready-to-use SDK context
+     * @throws {@link ConfigError} if no API key can be resolved
+     *
+     * @example
+     * ```typescript
+     * // Auto-config (uses env vars / CLI auth):
+     * const ctx = await Deepline.connect();
+     *
+     * // Explicit config:
+     * const ctx2 = await Deepline.connect({
+     *   apiKey: 'dl_test_...',
+     *   baseUrl: 'http://localhost:3000',
+     * });
+     * ```
+     */
+    static connect(options?: DeeplineClientOptions): Promise<DeeplineContext>;
+}
+declare function defineInput<TInput>(schema: Record<string, unknown>): PlayInputContract<TInput>;
+/**
+ * Define a play — a composable TypeScript workflow for the Deepline platform.
+ *
+ * The returned value is both:
+ * 1. **A callable function** — invoked by the Temporal worker with a runtime context
+ * 2. **A named play handle** — with `.run()`, `.versions()`, `.get()`, `.publish()`, etc. for remote lifecycle management
+ *
+ * Plays are the primary abstraction for building repeatable data pipelines.
+ * They run on Temporal for durable execution with automatic retries and timeouts.
+ *
+ * @typeParam TInput - The input type accepted by the play
+ * @typeParam TOutput - The return type of the play
+ * @param name - Unique play name (used for publishing, running by name, and CLI reference)
+ * @param fn - Async function that receives a {@link DeeplinePlayRuntimeContext} and typed input
+ * @param bindings - Optional trigger bindings (cron schedule, webhook with HMAC)
+ * @returns A {@link DefinedPlay} that is both callable and has lifecycle methods
+ *
+ * @example Basic play
+ * ```typescript
+ * import { definePlay } from 'deepline';
+ *
+ * export default definePlay('company-lookup', async (ctx, input: { domain: string }) => {
+ *   ctx.log(`Searching for ${input.domain}`);
+ *   const company = await ctx.tools.execute({
+ *     id: 'company_search',
+ *     tool: 'test_company_search',
+ *     input: { domain: input.domain },
+ *     description: 'Look up company details by domain.',
+ *   });
+ *   return { company: company.result };
+ * });
+ * ```
+ *
+ * @example CSV processing play
+ * ```typescript
+ * export default definePlay('bulk-enrich', async (ctx) => {
+ *   const leads = await ctx.csv('leads.csv');
+ *   ctx.log(`Processing ${leads.length} rows`);
+ *   const results = await ctx
+ *     .map('domain', leads)
+ *     .step('company', (row, ctx) =>
+ *       ctx.tools.execute({
+ *         id: 'company_search',
+ *         tool: 'test_company_search',
+ *         input: { domain: row.domain },
+ *         description: 'Look up company details by domain.',
+ *       }))
+ *     .run({ description: 'Enrich lead companies.' });
+ *   return results;
+ * });
+ * ```
+ *
+ * @example With cron binding
+ * ```typescript
+ * export default definePlay('daily-report', async (ctx) => {
+ *   const data = await ctx.tools.execute({
+ *     id: 'crm_export',
+ *     tool: 'crm_export',
+ *     input: { since: 'yesterday' },
+ *     description: 'Export yesterday CRM records.',
+ *   });
+ *   return data;
+ * }, {
+ *   cron: { schedule: '0 9 * * *', timezone: 'America/New_York' },
+ * });
+ * ```
+ *
+ * @example Programmatic lifecycle
+ * ```typescript
+ * const myPlay = definePlay('my-play', handler);
+ *
+ * // Get play definition:
+ * const detail = await myPlay.get();
+ *
+ * // Run remotely:
+ * const result = await myPlay.runSync({ domain: 'stripe.com' });
+ *
+ * // Make the current draft live:
+ * await myPlay.publish();
+ * ```
+ */
+declare function definePlay<TInput, TOutput extends PlayReturnObject>(config: DefinePlayConfig<TInput, TOutput>): DefinedPlay<TInput, TOutput>;
+declare function definePlay<TInput, TOutput extends PlayReturnObject>(name: string, fn: (ctx: DeeplinePlayRuntimeContext, input: TInput) => Promise<TOutput>, bindings?: PlayBindings): DefinedPlay<TInput, TOutput>;
+/**
+ * Alias for {@link definePlay}. Workflows and plays share the same public
+ * Deepline SDK contract; the selected execution profile decides whether the
+ * run is backed by local Node, Temporal/Daytona, or Cloudflare Dynamic
+ * Workflows.
+ */
+declare const defineWorkflow: typeof definePlay;
+/**
+ * Extract play metadata from a value that may be a defined play.
+ *
+ * Used internally by the CLI and bundler to detect `definePlay()` exports
+ * and extract the play name and bindings.
+ *
+ * @param value - Any value (typically a module's default export)
+ * @returns Play metadata if the value is a defined play, `null` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { getDefinedPlayMetadata } from 'deepline';
+ *
+ * const mod = await import('./my-play.play.ts');
+ * const meta = getDefinedPlayMetadata(mod.default);
+ * if (meta) {
+ *   console.log(`Play name: ${meta.name}`);
+ *   console.log(`Bindings:`, meta.bindings);
+ * }
+ * ```
+ */
+declare function getDefinedPlayMetadata(value: unknown): PlayMetadata | null;
+
+export { AuthError, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ConditionalStepResolver, ConfigError, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, DeeplineError, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DefinePlayConfig, type DefinedPlay, type LiveEventEnvelope, type MapDefinitionOptions, type MapRowKey, type MapRunOptions, type MapStepBuilder, type MapStepResolver, PROD_URL, type PlayBindings, type PlayDataset, type PlayDatasetInput, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayRevisionSummary, type PlayRunResult, type PlayRunStart, type PlayStatus, type PlayStepProgramStep, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type ResolvedConfig, SDK_API_CONTRACT, SDK_VERSION, type StartPlayRunRequest, type StepProgram, type StepProgramResolver, type StepResolver, type ToolCallResult, type ToolDefinition, type ToolExecuteResult, type ToolMetadata, createToolCallResult, defineInput, definePlay, defineWorkflow, extractSummaryFields, getDefinedPlayMetadata, resolveConfig, steps, tryConvertToList, when, writeCsvOutputFile, writeJsonOutputFile };