deepline 0.1.0 → 0.1.2

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

@@ -0,0 +1,669 @@
+import type { PlayCompilerManifest } from '../../shared_libs/plays/compiler-manifest';
+
+// ——————————————————————————————————————————————————————————
+// Config
+// ——————————————————————————————————————————————————————————
+
+/**
+ * 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,
+ * });
+ * ```
+ */
+export 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.
+ */
+export 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;
+}
+
+export interface CustomerDbColumn {
+  name: string;
+  table_id: number | null;
+  data_type_id: number | null;
+}
+
+export 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}`);
+ * }
+ * ```
+ */
+export 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: {...} }
+ * ```
+ */
+export 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>;
+}
+
+// ——————————————————————————————————————————————————————————
+// Play results
+// ——————————————————————————————————————————————————————————
+
+/**
+ * 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'));
+ * }
+ * ```
+ */
+export interface PlayRunResult {
+  /** `true` if the play completed successfully (`status === 'completed'`). */
+  success: boolean;
+  /** 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}.
+ */
+export 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);
+ * }
+ * ```
+ */
+export 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;
+}
+
+export type LiveEventScope = 'play' | 'agent';
+
+export interface LiveEventEnvelope<TPayload = unknown> {
+  cursor: string;
+  streamId: string;
+  scope: LiveEventScope;
+  type: string;
+  at: string;
+  payload: TPayload;
+}
+
+export type PlayLiveEvent = LiveEventEnvelope<unknown> & {
+  scope: 'play';
+};
+
+/**
+ * Result returned by {@link DeeplineClient.stopPlay}.
+ */
+export 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}.
+ */
+export 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.
+ */
+export 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.
+ */
+export interface PlaySheetStats {
+  total: number;
+  queued: number;
+  running: number;
+  completed: number;
+  failed: number;
+}
+
+/**
+ * Per-column processing stats within a play's sheet.
+ */
+export interface PlaySheetColumnStats {
+  queued: number;
+  running: number;
+  completed: number;
+  failed: number;
+  cached: number;
+}
+
+/**
+ * Summary of a play's data sheet state.
+ */
+export 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}.
+ */
+export 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;
+}
+
+export 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[];
+}
+
+export 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));
+ * ```
+ */
+export 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;
+}
+
+export interface ClearPlayHistoryRequest {
+  /** Optional explicit ctx.map keys to clear. Omit to clear all discovered sheets for the play. */
+  tableNamespaces?: string[];
+}
+
+export 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}`);
+ * ```
+ */
+export 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.
+ */
+export 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' },
+ * });
+ * ```
+ */
+export 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.
+ */
+export interface PublishPlayVersionRequest {
+  /** Explicit revision ID to make live. */
+  revisionId?: string;
+}
+
+/**
+ * Result returned after making a play revision live.
+ */
+export interface PublishPlayVersionResult {
+  success: boolean;
+  name: string;
+  liveVersion?: number;
+  triggerMetadata?: unknown;
+  triggerBindings?: unknown;
+}
+
+/**
+ * Result returned after deleting an org-owned play.
+ */
+export interface DeletePlayResult {
+  deleted: boolean;
+  name: string;
+  deletedRevisionCount: number;
+  deletedBindingCount: number;
+  deletedRunCount: number;
+}

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

@@ -0,0 +1,2 @@
+export const SDK_VERSION = "0.1.2";
+export const SDK_API_CONTRACT = "2026-04-plays-v1";