deepline 0.1.0 → 0.1.2

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

@@ -0,0 +1,391 @@
+/**
+ * HTTP transport layer for the Deepline SDK.
+ *
+ * Handles authentication, retries with exponential backoff, localhost failover
+ * (tries both `localhost` and `127.0.0.1`), and structured error mapping.
+ *
+ * ## Retry behavior
+ *
+ * - **Max attempts**: `1 + maxRetries` (default: 4 total attempts)
+ * - **Backoff**: exponential — 1s, 2s, 4s, 8s, ... capped at 30s
+ * - **Retryable**: network errors, timeouts, HTTP 429 (rate limit)
+ * - **Not retryable**: HTTP 401/403 (auth errors), other 4xx/5xx API errors
+ *
+ * ## Localhost failover
+ *
+ * Local development hosts try loopback variants. This handles DNS resolution
+ * differences across platforms.
+ *
+ * @module
+ */
+import type { ResolvedConfig } from './types.js';
+import { AuthError, DeeplineError, RateLimitError } from './errors.js';
+import { SDK_API_CONTRACT, SDK_VERSION } from './version.js';
+import type { LiveEventEnvelope } from './types.js';
+import {
+  COORDINATOR_URL_OVERRIDE_HEADER,
+  WORKER_CALLBACK_URL_OVERRIDE_HEADER,
+} from '../../shared_libs/play-runtime/coordinator-headers.js';
+
+interface RequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  body?: unknown;
+  headers?: Record<string, string>;
+  /** Per-request timeout override in milliseconds. */
+  timeout?: number;
+}
+
+interface StreamOptions {
+  method?: 'GET' | 'POST';
+  body?: unknown;
+  headers?: Record<string, string>;
+  signal?: AbortSignal;
+}
+
+/**
+ * Low-level HTTP client used internally by {@link DeeplineClient}.
+ *
+ * You typically don't construct this directly — it's created automatically
+ * when you instantiate `DeeplineClient` or call `Deepline.connect()`.
+ *
+ * @example
+ * ```typescript
+ * // Internal usage pattern:
+ * const http = new HttpClient(resolvedConfig);
+ * const tools = await http.get<{ tools: ToolDefinition[] }>('/api/v2/tools');
+ * const result = await http.post('/api/v2/integrations/apollo/execute', { payload: input });
+ * ```
+ */
+export class HttpClient {
+  constructor(private config: ResolvedConfig) {}
+
+  private authHeaders(extra?: Record<string, string>): Record<string, string> {
+    const headers: Record<string, string> = {
+      'Authorization': `Bearer ${this.config.apiKey}`,
+      'User-Agent': `deepline-ts-sdk/${SDK_VERSION}`,
+      'X-Deepline-SDK-Version': SDK_VERSION,
+      'X-Deepline-API-Contract': SDK_API_CONTRACT,
+      ...extra,
+    };
+    const bypassToken = typeof process !== 'undefined'
+      ? process.env?.VERCEL_PROTECTION_BYPASS_TOKEN
+      : undefined;
+    if (bypassToken) {
+      headers['x-vercel-protection-bypass'] = bypassToken;
+    }
+    const playArtifactR2Prefix = typeof process !== 'undefined'
+      ? process.env?.DEEPLINE_PLAY_ARTIFACT_R2_PREFIX
+      : undefined;
+    if (playArtifactR2Prefix) {
+      headers['x-deepline-play-artifact-r2-prefix'] = playArtifactR2Prefix;
+    }
+    const coordinatorUrl = typeof process !== 'undefined'
+      ? process.env?.DEEPLINE_COORDINATOR_URL
+      : undefined;
+    if (coordinatorUrl?.trim()) {
+      headers[COORDINATOR_URL_OVERRIDE_HEADER] = coordinatorUrl.trim();
+    }
+    const workerCallbackUrl = typeof process !== 'undefined'
+      ? process.env?.DEEPLINE_WORKER_CALLBACK_URL
+      : undefined;
+    if (workerCallbackUrl?.trim()) {
+      headers[WORKER_CALLBACK_URL_OVERRIDE_HEADER] = workerCallbackUrl.trim();
+    }
+    return headers;
+  }
+
+  /**
+   * Send an HTTP request with automatic retries and error handling.
+   *
+   * @typeParam T - Expected response body type
+   * @param path - API path (e.g. `"/api/v2/tools"`)
+   * @param options - HTTP method, body, headers, and timeout
+   * @returns Parsed JSON response body
+   * @throws {@link AuthError} on HTTP 401/403 (immediate, no retry)
+   * @throws {@link RateLimitError} on HTTP 429 after all retries exhausted
+   * @throws {@link DeeplineError} on other API errors or connection failures
+   */
+  async request<T = unknown>(path: string, options?: RequestOptions): Promise<T> {
+    const baseUrl = this.config.baseUrl;
+    const url = `${baseUrl}${path}`;
+    const method = options?.method ?? 'GET';
+
+    const headers = this.authHeaders(options?.headers);
+
+    if (options?.body !== undefined) {
+      headers['Content-Type'] = 'application/json';
+    }
+
+    let lastError: Error | null = null;
+    const candidateUrls = buildCandidateUrls(url);
+    let retryAfterDelayMs: number | null = null;
+
+    for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
+      if (attempt > 0) {
+        const backoffMs = Math.min(1000 * Math.pow(2, attempt - 1), 30_000);
+        const delayMs =
+          retryAfterDelayMs === null
+            ? backoffMs
+            : Math.max(backoffMs, retryAfterDelayMs);
+        retryAfterDelayMs = null;
+        await sleep(delayMs);
+      }
+
+      for (const candidateUrl of candidateUrls) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(
+          () => controller.abort(),
+          options?.timeout ?? this.config.timeout,
+        );
+
+        try {
+          const response = await fetch(candidateUrl, {
+            method,
+            headers,
+            body: options?.body !== undefined ? JSON.stringify(options.body) : undefined,
+            signal: controller.signal,
+          });
+
+          clearTimeout(timeoutId);
+
+          if (response.status === 401 || response.status === 403) {
+            throw new AuthError();
+          }
+
+          if (response.status === 429) {
+            const retryAfter = parseRetryAfter(response);
+            lastError = new RateLimitError(retryAfter);
+            if (attempt < this.config.maxRetries) {
+              retryAfterDelayMs = retryAfter;
+              break;
+            }
+            throw lastError;
+          }
+
+          const body = await response.text();
+          let parsed: unknown;
+          try {
+            parsed = JSON.parse(body);
+          } catch {
+            parsed = body;
+          }
+
+          if (!response.ok) {
+            const msg =
+              typeof parsed === 'object' && parsed && 'error' in parsed
+                ? String((parsed as Record<string, unknown>).error)
+                : `HTTP ${response.status}`;
+            throw new DeeplineError(msg, response.status, 'API_ERROR', {
+              response: parsed,
+            });
+          }
+
+          return parsed as T;
+        } catch (error) {
+          clearTimeout(timeoutId);
+          if (error instanceof AuthError || error instanceof DeeplineError) {
+            throw error;
+          }
+          if (error instanceof RateLimitError) {
+            lastError = error;
+            break;
+          }
+          lastError = error instanceof Error ? error : new Error(String(error));
+        }
+      }
+
+      if (attempt < this.config.maxRetries) continue;
+    }
+
+    if (lastError instanceof DeeplineError) {
+      throw lastError;
+    }
+    const errorMessage = lastError?.message
+      ? `Unable to connect to ${baseUrl}. ${lastError.message}`
+      : `Unable to connect to ${baseUrl}. Is the computer able to access the url?`;
+    throw new DeeplineError(errorMessage);
+  }
+
+  /**
+   * Send a GET request.
+   *
+   * @typeParam T - Expected response body type
+   * @param path - API path (e.g. `"/api/v2/tools"`)
+   */
+  async get<T = unknown>(path: string): Promise<T> {
+    return this.request<T>(path, { method: 'GET' });
+  }
+
+  async *streamSse<TEvent extends LiveEventEnvelope = LiveEventEnvelope>(
+    path: string,
+    options?: StreamOptions,
+  ): AsyncGenerator<TEvent> {
+    const url = `${this.config.baseUrl}${path}`;
+    const method = options?.method ?? 'GET';
+    const headers = this.authHeaders({
+      Accept: 'text/event-stream',
+      ...options?.headers,
+    });
+    if (options?.body !== undefined) {
+      headers['Content-Type'] = 'application/json';
+    }
+    let lastError: Error | null = null;
+
+    for (const candidateUrl of buildCandidateUrls(url)) {
+      try {
+        const response = await fetch(candidateUrl, {
+          method,
+          headers,
+          body:
+            options?.body !== undefined
+              ? JSON.stringify(options.body)
+              : undefined,
+          signal: options?.signal,
+        });
+
+        if (response.status === 401 || response.status === 403) {
+          throw new AuthError();
+        }
+        if (!response.ok) {
+          throw new DeeplineError(
+            `HTTP ${response.status}`,
+            response.status,
+            'API_ERROR',
+          );
+        }
+        if (!response.body) {
+          throw new DeeplineError('SSE response did not include a body.');
+        }
+
+        yield* decodeSseStream<TEvent>(response.body);
+        return;
+      } catch (error) {
+        if (error instanceof AuthError || error instanceof DeeplineError) {
+          throw error;
+        }
+        lastError = error instanceof Error ? error : new Error(String(error));
+      }
+    }
+
+    throw new DeeplineError(
+      lastError?.message
+        ? `Unable to stream from ${this.config.baseUrl}. ${lastError.message}`
+        : `Unable to stream from ${this.config.baseUrl}.`,
+    );
+  }
+
+  /**
+   * Send a POST request with a JSON body.
+   *
+   * @typeParam T - Expected response body type
+   * @param path - API path
+   * @param body - Request body (will be JSON-serialized)
+   */
+  async post<T = unknown>(path: string, body: unknown): Promise<T> {
+    return this.request<T>(path, { method: 'POST', body });
+  }
+
+  /**
+   * Send a DELETE request.
+   *
+   * @typeParam T - Expected response body type
+   * @param path - API path
+   */
+  async delete<T = unknown>(path: string): Promise<T> {
+    return this.request<T>(path, { method: 'DELETE' });
+  }
+}
+
+/** Parse the `Retry-After` header as milliseconds. Falls back to 5000ms. */
+function parseRetryAfter(response: Response): number {
+  const header = response.headers.get('retry-after');
+  if (header) {
+    const seconds = Number(header);
+    if (Number.isFinite(seconds) && seconds > 0) {
+      return seconds * 1000;
+    }
+  }
+  return 5000;
+}
+
+/**
+ * For local development URLs, generate loopback variants to handle platform DNS
+ * differences.
+ */
+function buildCandidateUrls(url: string): string[] {
+  try {
+    const parsed = new URL(url);
+    const candidates = [url];
+    if (parsed.hostname === 'localhost') {
+      const loopback = new URL(url);
+      loopback.hostname = '127.0.0.1';
+      candidates.push(loopback.toString());
+    }
+    return [...new Set(candidates)];
+  } catch {
+    return [url];
+  }
+}
+
+async function* decodeSseStream<TEvent extends LiveEventEnvelope>(
+  body: ReadableStream<Uint8Array>,
+): AsyncGenerator<TEvent> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffered = '';
+
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buffered += decoder.decode(value, { stream: true });
+      const frames = buffered.split(/\r?\n\r?\n/);
+      buffered = frames.pop() ?? '';
+      for (const frame of frames) {
+        const event = decodeSseFrame<TEvent>(frame);
+        if (event) {
+          yield event;
+        }
+      }
+    }
+
+    buffered += decoder.decode();
+    const event = decodeSseFrame<TEvent>(buffered);
+    if (event) {
+      yield event;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+function decodeSseFrame<TEvent extends LiveEventEnvelope>(
+  frame: string,
+): TEvent | null {
+  const data = frame
+    .split(/\r?\n/)
+    .filter((line) => line.startsWith('data:'))
+    .map((line) => line.slice('data:'.length).trimStart())
+    .join('\n')
+    .trim();
+  if (!data) {
+    return null;
+  }
+  const parsed = JSON.parse(data) as Partial<LiveEventEnvelope>;
+  if (
+    !parsed ||
+    typeof parsed !== 'object' ||
+    typeof parsed.cursor !== 'string' ||
+    typeof parsed.streamId !== 'string' ||
+    typeof parsed.scope !== 'string' ||
+    typeof parsed.type !== 'string' ||
+    typeof parsed.at !== 'string'
+  ) {
+    return null;
+  }
+  return parsed as TEvent;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

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

@@ -0,0 +1,139 @@
+/**
+ * Deepline SDK — TypeScript client for the Deepline enrichment platform.
+ *
+ * ## Quick start
+ *
+ * ```typescript
+ * import { Deepline, definePlay } from 'deepline';
+ *
+ * // Connect (auto-resolves API key from env / CLI config)
+ * const ctx = await Deepline.connect();
+ *
+ * // Execute a tool
+ * const result = await ctx.tools.execute({
+ *   tool: 'test_company_search',
+ *   input: { domain: 'stripe.com' },
+ * });
+ * const company = result.value;
+ *
+ * // Run a named play
+ * const job = await ctx.play('email-waterfall').run({ domain: 'stripe.com' });
+ * const result = await job.get();
+ * ```
+ *
+ * ## Define a play
+ *
+ * ```typescript
+ * import { definePlay } from 'deepline';
+ *
+ * export default definePlay('my-play', async (ctx, input: { domain: string }) => {
+ *   ctx.log(`Looking up ${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;
+ * });
+ * ```
+ *
+ * Then run: `deepline play run --file my-play.play.ts --watch`
+ *
+ * ## Architecture
+ *
+ * - {@link DeeplineClient} — Low-level REST client (1:1 with API endpoints)
+ * - {@link DeeplineContext} / {@link Deepline} — High-level SDK with tool shortcuts and play handles
+ * - {@link definePlay} — Define plays as typed async functions with durable execution
+ * - {@link PlayJob} — Handle to a running play (status, logs, wait, cancel)
+ *
+ * ## Configuration
+ *
+ * The SDK auto-resolves configuration from multiple sources. See {@link resolveConfig}
+ * for the full resolution order. For most setups, just run `deepline auth register`
+ * once and the SDK works zero-config.
+ *
+ * @packageDocumentation
+ */
+
+// ——— Client ———
+export { DeeplineClient } from './client.js';
+export type { PlayStatus } from './client.js';
+export { SDK_API_CONTRACT, SDK_VERSION } from './version.js';
+
+// ——— Errors ———
+export {
+  DeeplineError,
+  AuthError,
+  RateLimitError,
+  ConfigError,
+} from './errors.js';
+
+// ——— Config ———
+export { resolveConfig, PROD_URL } from './config.js';
+
+// ——— Play framework ———
+export {
+  Deepline,
+  DeeplineContext,
+  defineInput,
+  definePlay,
+  defineWorkflow,
+  getDefinedPlayMetadata,
+  steps,
+  when,
+} from './play.js';
+
+// ——— Tool output processing ———
+export {
+  createToolCallResult,
+  tryConvertToList,
+  writeCsvOutputFile,
+  writeJsonOutputFile,
+  extractSummaryFields,
+} from './tool-output.js';
+
+export type { ToolCallResult } from './tool-output.js';
+
+// ——— Types (re-exported for consumers) ———
+export type {
+  DeeplineClientOptions,
+  ResolvedConfig,
+  ToolDefinition,
+  ToolMetadata,
+  LiveEventEnvelope,
+  PlayLiveEvent,
+  PlayRunResult,
+  PlayRunStart,
+  ClearPlayHistoryRequest,
+  ClearPlayHistoryResult,
+  PlayRevisionSummary,
+  PublishPlayVersionRequest,
+  PublishPlayVersionResult,
+  StartPlayRunRequest,
+  PlayListItem,
+} from './types.js';
+
+export type {
+  DefinePlayConfig,
+  DeeplineNamedPlay,
+  DeeplinePlayRuntimeContext,
+  DefinedPlay,
+  PlayBindings,
+  PlayInputContract,
+  PlayJob,
+  ConditionalStepResolver,
+  MapDefinitionOptions,
+  MapRowKey,
+  MapRunOptions,
+  MapStepBuilder,
+  MapStepResolver,
+  PlayDataset,
+  PlayDatasetInput,
+  PlayStepProgramStep,
+  PrebuiltPlayRef,
+  StepProgram,
+  StepProgramResolver,
+  StepResolver,
+  ToolExecuteResult,
+} from './play.js';