deepline 0.1.83 → 0.1.88

package/dist/index.js

@@ -22,11 +22,15 @@ var src_exports = {};
 __export(src_exports, {
   AuthError: () => AuthError,
   ConfigError: () => ConfigError,
+  DEEPLINE_EXTRACTOR_TARGETS: () => DEEPLINE_EXTRACTOR_TARGETS,
+  DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS: () => DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS,
   DEEPLINE_TOOL_CATEGORIES: () => DEEPLINE_TOOL_CATEGORIES,
   Deepline: () => Deepline,
   DeeplineClient: () => DeeplineClient,
   DeeplineContext: () => DeeplineContext,
   DeeplineError: () => DeeplineError,
+  JOB_CHANGE_STATUS_VALUES: () => JOB_CHANGE_STATUS_VALUES,
+  PHONE_STATUS_VALUES: () => PHONE_STATUS_VALUES,
   PLAY_BOOTSTRAP_COMPANY_FIELDS: () => PLAY_BOOTSTRAP_COMPANY_FIELDS,
   PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY: () => PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY,
   PLAY_BOOTSTRAP_CONTACT_FIELDS: () => PLAY_BOOTSTRAP_CONTACT_FIELDS,
@@ -49,6 +53,7 @@ __export(src_exports, {
   formatPlayBootstrapFinderKindsForSentence: () => formatPlayBootstrapFinderKindsForSentence,
   formatPlayBootstrapTemplates: () => formatPlayBootstrapTemplates,
   getDefinedPlayMetadata: () => getDefinedPlayMetadata,
+  isDeeplineExtractorTarget: () => isDeeplineExtractorTarget,
   isPlayBootstrapFinderKind: () => isPlayBootstrapFinderKind,
   isPlayBootstrapTemplate: () => isPlayBootstrapTemplate,
   resolveConfig: () => resolveConfig,
@@ -241,10 +246,10 @@ var import_node_path2 = require("path");
 
 // src/release.ts
 var SDK_RELEASE = {
-  version: "0.1.83",
+  version: "0.1.88",
   apiContract: "2026-06-dataset-column-cell-stale-hard-cutover",
   supportPolicy: {
-    latest: "0.1.83",
+    latest: "0.1.88",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53"
   }
@@ -258,6 +263,7 @@ var SDK_API_CONTRACT = SDK_RELEASE.apiContract;
 var COORDINATOR_INTERNAL_TOKEN_HEADER = "x-deepline-internal-token";
 var COORDINATOR_URL_OVERRIDE_HEADER = "x-deepline-coordinator-url";
 var WORKER_CALLBACK_URL_OVERRIDE_HEADER = "x-deepline-worker-callback-url";
+var SYNTHETIC_RUN_HEADER = "x-deepline-synthetic-run";
 
 // src/http.ts
 var MAX_DIAGNOSTIC_HEADER_LENGTH = 120;
@@ -325,6 +331,10 @@ var HttpClient = class {
     if (workerCallbackUrl?.trim()) {
       headers[WORKER_CALLBACK_URL_OVERRIDE_HEADER] = workerCallbackUrl.trim();
     }
+    const syntheticRun = typeof process !== "undefined" ? process.env?.DEEPLINE_SYNTHETIC_RUN : void 0;
+    if (syntheticRun && syntheticRun.trim() && syntheticRun.trim() !== "0") {
+      headers[SYNTHETIC_RUN_HEADER] = "1";
+    }
     return headers;
   }
   /**
@@ -615,6 +625,21 @@ function isTransientCompileManifestError(error) {
 function isRecord(value) {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
+function isPrebuiltPlayDescription(play) {
+  return play.origin === "prebuilt" || play.ownerType === "deepline";
+}
+function preferPrebuiltPlayDescriptions(plays) {
+  const prebuilt = [];
+  const owned = [];
+  for (const play of plays) {
+    if (isPrebuiltPlayDescription(play)) {
+      prebuilt.push(play);
+    } else {
+      owned.push(play);
+    }
+  }
+  return [...prebuilt, ...owned];
+}
 function isPlayRunPackage(value) {
   return Boolean(
     value && typeof value === "object" && !Array.isArray(value) && value.kind === "play_run" && value.run && typeof value.run?.id === "string"
@@ -738,8 +763,14 @@ function playRunStatusFromState(state) {
 var DeeplineClient = class {
   http;
   config;
+  /** Canonical run lifecycle namespace backed by `/api/v2/runs`. */
   runs;
   /**
+   * Create a low-level SDK client.
+   *
+   * Most callers can omit options and let the SDK resolve auth/config from
+   * environment variables and CLI-managed credentials.
+   *
    * @param options - Optional overrides for API key, base URL, timeout, and retries.
    * @throws {@link ConfigError} if no API key can be resolved from any source.
    */
@@ -841,12 +872,19 @@ var DeeplineClient = class {
   // ——————————————————————————————————————————————————————————
   // Secrets
   // ——————————————————————————————————————————————————————————
+  /** List secret metadata visible to the current workspace. */
   async listSecrets() {
     const response = await this.http.get(
       "/api/v2/secrets"
     );
     return Array.isArray(response.secrets) ? response.secrets : [];
   }
+  /**
+   * Check whether a named secret exists, is active, and has a stored value.
+   *
+   * @param name - Secret name. It is normalized to uppercase before lookup.
+   * @returns Matching active secret metadata, or `null`.
+   */
   async checkSecret(name) {
     const normalized = name.trim().toUpperCase();
     const secrets = await this.listSecrets();
@@ -959,9 +997,21 @@ var DeeplineClient = class {
       headers
     );
   }
+  /**
+   * Back-compatible alias for {@link executeTool}.
+   *
+   * Retained for callers that still use the older raw naming while the response
+   * envelope remains the same.
+   */
   async executeToolRaw(toolId, input, options) {
     return this.executeTool(toolId, input, options);
   }
+  /**
+   * Run a bounded SQL query against the customer data plane.
+   *
+   * Use this from trusted backend or agent contexts only. The API enforces
+   * workspace scoping and row limits.
+   */
   async queryCustomerDb(input) {
     return this.http.post("/api/v2/db/query", {
       sql: input.sql,
@@ -1033,6 +1083,17 @@ var DeeplineClient = class {
     );
     return normalizePlayRunStart(response);
   }
+  /**
+   * Start a play run and stream live runtime events from the same request.
+   *
+   * Use this when a caller wants low-level event handling instead of submitting
+   * first and then connecting to `streamPlayRunEvents(runId)`.
+   *
+   * @param request - Play run configuration.
+   * @param options - Optional streaming options.
+   * @param options.signal - Optional abort signal for the streaming request.
+   * @returns Async stream of play-scoped live events.
+   */
   async *startPlayRunStream(request, options) {
     const body = {
       ...request.name ? { name: request.name } : {},
@@ -1085,6 +1146,12 @@ var DeeplineClient = class {
       compilerManifest
     });
   }
+  /**
+   * Register multiple bundled play artifacts in one request.
+   *
+   * Used by packaging and prebuilt publication flows. Each artifact is compiled
+   * first when a compiler manifest is not already supplied.
+   */
   async registerPlayArtifacts(artifacts) {
     const compiledArtifacts = await Promise.all(
       artifacts.map(async (artifact) => ({
@@ -1101,6 +1168,13 @@ var DeeplineClient = class {
       artifacts: compiledArtifacts
     });
   }
+  /**
+   * Compile a bundled play artifact into the server-side compiler manifest.
+   *
+   * The manifest records imports, trigger bindings, static pipeline shape, and
+   * runtime metadata needed before a play artifact can be checked, registered,
+   * or run.
+   */
   async compilePlayManifest(input) {
     const retryDelays = COMPILE_MANIFEST_RETRY_DELAYS_MS.slice(
       0,
@@ -1129,9 +1203,21 @@ var DeeplineClient = class {
   async checkPlayArtifact(input) {
     return this.http.post("/api/v2/plays/check", input);
   }
+  /**
+   * Compile legacy enrich command arguments into a runtime plan.
+   *
+   * This is primarily used by CLI compatibility paths that translate older
+   * enrichment commands onto the play runtime.
+   */
   async compileEnrichPlan(input) {
     return this.http.post("/api/v2/enrich/compile", input);
   }
+  /**
+   * Register an already-bundled play artifact and start a run from it.
+   *
+   * This is the low-level file-backed run path used by SDK/CLI packaging
+   * wrappers after local bundling has produced the runtime artifact.
+   */
   async startPlayRunFromBundle(input) {
     const compilerManifest = input.compilerManifest ?? await this.compilePlayManifest({
       name: input.name,
@@ -1289,6 +1375,12 @@ var DeeplineClient = class {
     const response = await this.http.postFormData("/api/v2/plays/files/stage", buildFormData);
     return response.files;
   }
+  /**
+   * Resolve staged play files by content hash without uploading bytes.
+   *
+   * Missing files are returned so callers can upload only the files the server
+   * does not already have.
+   */
   async resolveStagedPlayFiles(files) {
     return this.http.post("/api/v2/plays/files/stage", { files });
   }
@@ -1505,6 +1597,12 @@ var DeeplineClient = class {
       entries
     };
   }
+  /**
+   * Export persisted runtime-sheet rows for a play dataset/table namespace.
+   *
+   * This is the SDK form of exporting `ctx.dataset(...).run()` output for a
+   * specific play and optional run id.
+   */
   async getPlaySheetRows(input) {
     const params = new URLSearchParams({
       tableNamespace: input.tableNamespace,
@@ -1533,6 +1631,12 @@ var DeeplineClient = class {
       options?.reason ? { reason: options.reason } : {}
     );
   }
+  /**
+   * List callable plays visible to the workspace.
+   *
+   * Pass `origin: "prebuilt"` for Deepline-managed prebuilts or
+   * `origin: "owned"` for org-owned plays.
+   */
   async listPlays(options) {
     const params = new URLSearchParams();
     if (options?.origin) params.set("origin", options.origin);
@@ -1547,15 +1651,32 @@ var DeeplineClient = class {
     );
     return response.plays ?? [];
   }
+  /**
+   * Search callable plays and return compact play descriptions.
+   *
+   * Prebuilt plays are preferred by default because they have maintained
+   * contracts and stable run behavior.
+   */
   async searchPlays(options) {
     const params = new URLSearchParams();
     params.set("search", options.query.trim());
+    const scope = options.scope ?? "prebuilt";
+    if (scope !== "all") {
+      params.set("origin", scope);
+    }
     const response = await this.http.get(
       `/api/v2/plays?${params.toString()}`
     );
-    return (response.plays ?? []).map(
+    const plays = (response.plays ?? []).map(
       (play) => this.summarizePlayListItem(play, options)
     );
+    if (scope === "prebuilt") {
+      return plays.filter(isPrebuiltPlayDescription);
+    }
+    if (scope === "owned") {
+      return plays.filter((play) => !isPrebuiltPlayDescription(play));
+    }
+    return preferPrebuiltPlayDescriptions(plays);
   }
   /**
    * Get the full definition and state of a named play.
@@ -1578,6 +1699,12 @@ var DeeplineClient = class {
     const encodedName = encodeURIComponent(name);
     return this.http.get(`/api/v2/plays/${encodedName}`);
   }
+  /**
+   * Get a normalized play description suitable for agents and CLIs.
+   *
+   * The description includes runnable examples, input/output summaries, clone
+   * guidance, revision state, and latest run metadata when available.
+   */
   async describePlay(name, options) {
     const detail = await this.getPlay(name);
     return this.summarizePlayDetail(detail, options);
@@ -2064,6 +2191,58 @@ function buildEmailStatus({
   };
 }
 
+// ../shared_libs/play-runtime/extractor-targets.ts
+var JOB_CHANGE_STATUS_VALUES = [
+  "moved",
+  "no_change",
+  "left_company",
+  "unknown",
+  "profile_unavailable",
+  "no_new_company"
+];
+var PHONE_STATUS_VALUES = ["valid", "invalid", "unknown"];
+var DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS = {
+  id: { identity: true, valueKind: "string" },
+  name: { identity: true, valueKind: "string" },
+  email: { identity: true, valueKind: "string" },
+  personal_email: { identity: true, valueKind: "string" },
+  phone: { identity: true, valueKind: "string" },
+  linkedin: { identity: true, valueKind: "string" },
+  linkedin_url: { identity: true, valueKind: "string" },
+  domain: { identity: true, valueKind: "string" },
+  website: { identity: true, valueKind: "string" },
+  first_name: { identity: true, valueKind: "string" },
+  last_name: { identity: true, valueKind: "string" },
+  full_name: { identity: true, valueKind: "string" },
+  company: { identity: true, valueKind: "string" },
+  company_name: { identity: true, valueKind: "string" },
+  organization_name: { identity: true, valueKind: "string" },
+  company_domain: { identity: true, valueKind: "string" },
+  company_website: { identity: true, valueKind: "string" },
+  company_linkedin_url: { identity: true, valueKind: "string" },
+  title: { identity: false, valueKind: "string" },
+  industry: { identity: false, valueKind: "string" },
+  status: { identity: false, valueKind: "string" },
+  job_change: { identity: false, valueKind: "job_change" },
+  job_change_status: {
+    identity: false,
+    valueKind: "job_change_status",
+    enum: JOB_CHANGE_STATUS_VALUES
+  },
+  email_status: { identity: false, valueKind: "email_status" },
+  phone_status: {
+    identity: false,
+    valueKind: "phone_status",
+    enum: PHONE_STATUS_VALUES
+  }
+};
+var DEEPLINE_EXTRACTOR_TARGETS = Object.keys(
+  DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS
+);
+function isDeeplineExtractorTarget(value) {
+  return value in DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS;
+}
+
 // ../shared_libs/play-runtime/tool-result.ts
 var TARGET_FALLBACK_KEYS = {
   email: [/^email$/i, /^address$/i, /email/i],
@@ -2337,10 +2516,61 @@ function normalizePhoneStatus(value) {
   }
   return normalized;
 }
+function normalizeJobChangeStatus(value) {
+  if (typeof value === "boolean") return value ? "moved" : "no_change";
+  const normalized = normalizeString(value)?.toLowerCase().replace(/[\s-]+/g, "_");
+  if (!normalized) return "unknown";
+  if (["true", "yes", "moved", "changed", "new_company"].includes(normalized)) {
+    return "moved";
+  }
+  if (["false", "no", "same", "no_change"].includes(normalized))
+    return "no_change";
+  if (["left", "left_company"].includes(normalized)) return "left_company";
+  if (JOB_CHANGE_STATUS_VALUES.includes(normalized)) {
+    return normalized;
+  }
+  return "unknown";
+}
+function firstExperienceDate(value) {
+  if (!Array.isArray(value)) return null;
+  for (const entry of value) {
+    if (!isRecord2(entry)) continue;
+    const date = normalizeString(
+      entry.start_date ?? entry.started_at ?? entry.startDate
+    );
+    if (date) return date;
+  }
+  return null;
+}
+function normalizeJobChange(value) {
+  const record = isRecord2(value) ? value : {};
+  const nested = isRecord2(record.job_change) ? record.job_change : record;
+  const output = isRecord2(nested.output) ? nested.output : nested;
+  const person = isRecord2(output.person) ? output.person : {};
+  const status = normalizeJobChangeStatus(
+    output.status ?? output.job_change_status ?? output.job_changed ?? output.changed
+  );
+  const moved = status === "moved";
+  return {
+    status,
+    date: moved ? normalizeString(
+      output.date ?? output.job_change_date ?? output.change_date ?? output.changed_at
+    ) ?? firstExperienceDate(person.experiences) : null,
+    new_company: moved ? normalizeString(
+      output.new_company ?? output.current_company ?? person.company_name ?? person.current_company
+    ) : null,
+    new_title: moved ? normalizeString(
+      output.new_title ?? output.current_title ?? person.title ?? person.headline
+    ) : null
+  };
+}
 function applyExtractorTransforms(value, descriptor) {
   return (descriptor.transforms ?? []).reduce((current, transform) => {
     if (transform.endsWith("emailStatus")) return normalizeEmailStatus(current);
     if (transform.endsWith("phoneStatus")) return normalizePhoneStatus(current);
+    if (transform === "jobChange") return normalizeJobChange(current);
+    if (transform === "jobChangeStatus")
+      return normalizeJobChangeStatus(current);
     return current;
   }, value);
 }
@@ -2628,7 +2858,10 @@ var DeeplineStepProgram = class _DeeplineStepProgram {
         ...this.steps,
         {
           name,
-          resolver: stepResolver
+          resolver: stepResolver,
+          ...options?.staleAfterSeconds !== void 0 ? {
+            staleAfterSeconds: options.staleAfterSeconds
+          } : {}
         }
       ],
       this.returnResolver
@@ -2728,6 +2961,14 @@ function createNamedPlayHandle(clientFactory, name) {
 }
 var DeeplineContext = class {
   client;
+  /**
+   * Create a high-level SDK context.
+   *
+   * Most callers should use {@link Deepline.connect}; direct construction is
+   * equivalent when you already have explicit client options.
+   *
+   * @param options - Optional SDK client configuration.
+   */
   constructor(options) {
     this.client = new DeeplineClient(options);
   }
@@ -2757,12 +2998,25 @@ var DeeplineContext = class {
       }
     };
   }
+  /**
+   * Play discovery and named-play handles.
+   *
+   * Use `plays.list()` for discovery and `plays.get(name)` when you prefer a
+   * namespace spelling over `ctx.play(name)`.
+   */
   get plays() {
     return {
       list: () => this.client.listPlays(),
       get: (name) => this.play(name)
     };
   }
+  /**
+   * Convenience references for Deepline-managed prebuilt plays.
+   *
+   * Known prebuilts are exposed by camel-cased aliases. Any other property is
+   * converted into `prebuilt/<property>` so callers can pass the reference to
+   * `ctx.runPlay(...)`.
+   */
   get prebuilt() {
     const explicit = {
       companyToContact: {
@@ -2817,6 +3071,17 @@ var DeeplineContext = class {
   play(name) {
     return createNamedPlayHandle(() => this.client, name);
   }
+  /**
+   * Run a named or prebuilt play and wait for its output.
+   *
+   * This is the high-level SDK equivalent of `ctx.play(name).runSync(input)`.
+   * Inside a play runtime, prefer the in-play `ctx.runPlay(key, playRef, input,
+   * options)` form so the child run is checkpointed under a stable key.
+   *
+   * @param playOrRef - Play name or prebuilt/reference object.
+   * @param input - JSON input passed to the play.
+   * @returns Completed play output.
+   */
   async runPlay(playOrRef, input) {
     const name = typeof playOrRef === "string" ? playOrRef : playOrRef.playName ?? playOrRef.name ?? "";
     return await this.play(name).runSync(input);
@@ -3191,11 +3456,15 @@ function extractSummaryFields(payload) {
 0 && (module.exports = {
   AuthError,
   ConfigError,
+  DEEPLINE_EXTRACTOR_TARGETS,
+  DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS,
   DEEPLINE_TOOL_CATEGORIES,
   Deepline,
   DeeplineClient,
   DeeplineContext,
   DeeplineError,
+  JOB_CHANGE_STATUS_VALUES,
+  PHONE_STATUS_VALUES,
   PLAY_BOOTSTRAP_COMPANY_FIELDS,
   PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY,
   PLAY_BOOTSTRAP_CONTACT_FIELDS,
@@ -3218,6 +3487,7 @@ function extractSummaryFields(payload) {
   formatPlayBootstrapFinderKindsForSentence,
   formatPlayBootstrapTemplates,
   getDefinedPlayMetadata,
+  isDeeplineExtractorTarget,
   isPlayBootstrapFinderKind,
   isPlayBootstrapTemplate,
   resolveConfig,