deepline 0.1.10 → 0.1.12

package/dist/repo/sdk/src/cli/commands/tools.ts

@@ -628,7 +628,7 @@ async function executeTool(args: string[]): Promise<number> {
     }
     throw error;
   }
-  const rawResponse = await client.executeToolRaw(parsed.toolId, parsed.params);
+  const rawResponse = await client.executeTool(parsed.toolId, parsed.params);
 
   const listConversion = tryConvertToList(rawResponse, {
     listExtractorPaths: metadata.listExtractorPaths ?? [],

package/dist/repo/sdk/src/cli/dataset-stats.ts

@@ -35,6 +35,66 @@ export type CanonicalRowsInfo = {
   source: string | null;
 };
 
+const CSV_PROJECTED_FIELDS_KEY = '__deeplineCsvProjectedFields';
+
+function csvProjectedFields(row: Record<string, unknown>): Set<string> {
+  const serialized = row[CSV_PROJECTED_FIELDS_KEY];
+  if (!Array.isArray(serialized)) {
+    return new Set();
+  }
+  return new Set(
+    serialized.filter((field): field is string => typeof field === 'string'),
+  );
+}
+
+function stripCsvProjectionFields(
+  row: Record<string, unknown>,
+): Record<string, unknown> {
+  const projectedFields = csvProjectedFields(row);
+  if (projectedFields.size === 0 && !(CSV_PROJECTED_FIELDS_KEY in row)) {
+    return row;
+  }
+  const stripped = { ...row };
+  for (const field of projectedFields) {
+    delete stripped[field];
+  }
+  delete stripped[CSV_PROJECTED_FIELDS_KEY];
+  return stripped;
+}
+
+function stripCsvProjectionColumns(
+  columns: string[],
+  rows: Array<Record<string, unknown>>,
+): string[] {
+  const projectedFields = new Set<string>();
+  let hasProjectionMetadata = false;
+  for (const row of rows) {
+    for (const field of csvProjectedFields(row)) {
+      projectedFields.add(field);
+    }
+    hasProjectionMetadata ||= CSV_PROJECTED_FIELDS_KEY in row;
+  }
+  if (!hasProjectionMetadata && projectedFields.size === 0) {
+    return columns;
+  }
+  return columns.filter(
+    (column) =>
+      column !== CSV_PROJECTED_FIELDS_KEY && !projectedFields.has(column),
+  );
+}
+
+function sanitizeCsvProjectionInfo(input: {
+  rows: Array<Record<string, unknown>>;
+  columns: string[];
+}): {
+  rows: Array<Record<string, unknown>>;
+  columns: string[];
+} {
+  const columns = stripCsvProjectionColumns(input.columns, input.rows);
+  const rows = input.rows.map(stripCsvProjectionFields);
+  return { rows, columns };
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value && typeof value === 'object' && !Array.isArray(value));
 }
@@ -118,16 +178,21 @@ export function extractCanonicalRowsInfo(statusOrResult: unknown): CanonicalRows
 
   for (const candidate of candidates) {
     if (isSerializedDataset(candidate.value)) {
-      const rows = rowArray(candidate.value.preview) ?? [];
-      const totalRows = readNumber(candidate.value.count) ?? rows.length;
+      const rawRows = rowArray(candidate.value.preview) ?? [];
+      const totalRows = readNumber(candidate.value.count) ?? rawRows.length;
+      const rawColumns =
+        Array.isArray(candidate.value.columns) &&
+        candidate.value.columns.every((column) => typeof column === 'string')
+          ? (candidate.value.columns as string[])
+          : inferColumns(rawRows);
+      const { rows, columns } = sanitizeCsvProjectionInfo({
+        rows: rawRows,
+        columns: rawColumns,
+      });
       return {
         rows,
         totalRows,
-        columns:
-          Array.isArray(candidate.value.columns) &&
-          candidate.value.columns.every((column) => typeof column === 'string')
-            ? (candidate.value.columns as string[])
-            : inferColumns(rows),
+        columns,
         complete: rows.length === totalRows,
         source: candidate.source,
       };
@@ -138,10 +203,14 @@ export function extractCanonicalRowsInfo(statusOrResult: unknown): CanonicalRows
       continue;
     }
     const totalRows = readNumber(candidate.total) ?? rows.length;
-    return {
+    const sanitized = sanitizeCsvProjectionInfo({
       rows,
-      totalRows,
       columns: inferColumns(rows),
+    });
+    return {
+      rows: sanitized.rows,
+      totalRows,
+      columns: sanitized.columns,
       complete: rows.length === totalRows,
       source: candidate.source,
     };
@@ -261,15 +330,16 @@ export function buildDatasetStats(
   totalRows = rows.length,
   columns = inferColumns(rows),
 ): DatasetStats {
+  const sanitized = sanitizeCsvProjectionInfo({ rows, columns });
   const columnStats: DatasetStats['columnStats'] = {};
-  for (const column of columns) {
+  for (const column of sanitized.columns) {
     let nonEmpty = 0;
     let empty = 0;
     let sampleValue: unknown;
     let sampleValueType: string | null = null;
     const valueCounts = new Map<string, number>();
 
-    for (const row of rows) {
+    for (const row of sanitized.rows) {
       const raw = row[column];
       const value = compactCell(raw);
       if (value) {
@@ -331,10 +401,14 @@ export function writeCanonicalRowsCsv(
       `Run output only includes ${rowsInfo.rows.length} preview row(s) of ${rowsInfo.totalRows}; cannot export a complete CSV from this status payload yet.`,
     );
   }
+  const sanitized = sanitizeCsvProjectionInfo({
+    rows: rowsInfo.rows,
+    columns: rowsInfo.columns,
+  });
   const resolved = resolve(outPath);
   writeFileSync(
     resolved,
-    csvStringFromRows(rowsInfo.rows, rowsInfo.columns),
+    csvStringFromRows(sanitized.rows, sanitized.columns),
     'utf-8',
   );
   return resolved;

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

@@ -64,6 +64,21 @@ import type { PlayCompilerManifest } from '../../shared_libs/plays/compiler-mani
 
 const TERMINAL_PLAY_STATUSES = new Set(['completed', 'failed', 'cancelled']);
 
+export type ToolExecution<TData = unknown, TMeta = Record<string, unknown>> = {
+  status: string;
+  job_id?: string;
+  result: {
+    data: TData;
+    meta?: TMeta;
+  };
+  billing?: Record<string, unknown>;
+  [key: string]: unknown;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
 function normalizePlayStatus(raw: Record<string, unknown>): PlayStatus {
   const status =
     typeof raw.status === 'string'
@@ -159,8 +174,29 @@ export class DeeplineClient {
     return fields.length > 0 ? { fields } : schema;
   }
 
-  private playRunCommand(name: string): string {
-    return `deepline plays run ${name} --input '{...}' --watch`;
+  private schemaMetadata(
+    schema: Record<string, unknown> | null | undefined,
+    key: string,
+  ): Record<string, unknown> | null {
+    if (!isRecord(schema)) return null;
+    const value = schema[key];
+    return isRecord(value) ? value : null;
+  }
+
+  private playRunCommand(
+    play: Pick<PlayListItem, 'name' | 'reference'>,
+    options?: { csvInput?: Record<string, unknown> | null },
+  ): string {
+    const target = play.reference || play.name;
+    if (options?.csvInput) {
+      const inputField =
+        typeof options.csvInput.inputField === 'string' &&
+        options.csvInput.inputField.trim()
+          ? options.csvInput.inputField.trim()
+          : 'csv';
+      return `deepline plays run ${target} --${inputField} leads.csv --watch`;
+    }
+    return `deepline plays run ${target} --input '{...}' --watch`;
   }
 
   private summarizePlayListItem(
@@ -168,7 +204,12 @@ export class DeeplineClient {
     options?: { compact?: boolean },
   ): PlayDescription {
     const aliases = play.aliases?.length ? play.aliases : [play.name];
-    const runCommand = this.playRunCommand(play.name);
+    const csvInput = this.schemaMetadata(play.inputSchema, 'csvInput');
+    const rowOutputSchema = this.schemaMetadata(
+      play.outputSchema,
+      'rowOutputSchema',
+    );
+    const runCommand = this.playRunCommand(play, { csvInput });
     return {
       name: play.name,
       ...(play.reference ? { reference: play.reference } : {}),
@@ -184,6 +225,8 @@ export class DeeplineClient {
       outputSchema: options?.compact
         ? this.compactSchema(play.outputSchema)
         : (play.outputSchema ?? null),
+      ...(csvInput ? { csvInput } : {}),
+      ...(rowOutputSchema ? { rowOutputSchema } : {}),
       runCommand,
       examples: [runCommand],
       currentPublishedVersion: play.currentPublishedVersion ?? null,
@@ -259,58 +302,18 @@ export class DeeplineClient {
   }
 
   /**
-   * Execute a tool and return the extracted result.
+   * Execute a tool and return the standard execution envelope.
    *
-   * Sends the input payload to the tool and returns the `.result` field from the
-   * response. For the full response envelope (including job_id, credits, etc.),
-   * use {@link executeToolRaw}.
-   *
-   * @param toolId - Tool identifier (e.g. `"test_company_search"`)
-   * @param input - Tool-specific input parameters
-   * @returns The tool's output (shape varies by tool)
-   * @throws {@link DeeplineError} if the tool execution fails
-   *
-   * @example
-   * ```typescript
-   * const company = await client.executeTool('test_company_search', {
-   *   domain: 'stripe.com',
-   * });
-   * console.log(company); // { name: "Stripe", industry: "Financial Services", ... }
-   * ```
-   */
-  async executeTool(
-    toolId: string,
-    input: Record<string, unknown>,
-  ): Promise<unknown> {
-    const res = await this.http.post<{ result: unknown }>(
-      `/api/v2/integrations/${encodeURIComponent(toolId)}/execute`,
-      { payload: input },
-    );
-    return res.result ?? res;
-  }
-
-  /**
-   * Execute a tool and return the full response envelope.
-   *
-   * Unlike {@link executeTool}, this returns the complete API response including
-   * `job_id`, `status`, `credits`, and the raw `result` object.
-   *
-   * @param toolId - Tool identifier
-   * @param input - Tool-specific input parameters
-   * @returns Full response with job metadata and result
-   *
-   * @example
-   * ```typescript
-   * const raw = await client.executeToolRaw('test_company_search', { domain: 'stripe.com' });
-   * console.log(`Job: ${raw.job_id}, Credits: ${raw.credits}`);
-   * console.log(`Result:`, raw.result);
-   * ```
+   * The `result.data` field contains the provider payload. `result.meta`
+   * contains provider/upstream metadata such as HTTP status or paging details.
+   * Top-level fields such as `status`, `job_id`, and `billing` describe the
+   * Deepline execution.
    */
-  async executeToolRaw(
+  async executeTool<TData = unknown, TMeta = Record<string, unknown>>(
     toolId: string,
     input: Record<string, unknown>,
-  ): Promise<Record<string, unknown>> {
-    return this.http.post<Record<string, unknown>>(
+  ): Promise<ToolExecution<TData, TMeta>> {
+    return this.http.post<ToolExecution<TData, TMeta>>(
       `/api/v2/integrations/${encodeURIComponent(toolId)}/execute`,
       { payload: input },
     );

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

@@ -10,11 +10,8 @@
  * 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;
+ * const result = await ctx.tools.execute('test_company_search', { domain: 'stripe.com' });
+ * const company = result.result.data;
  *
  * // Run a named play
  * const job = await ctx.play('email-waterfall').run({ domain: 'stripe.com' });
@@ -28,10 +25,7 @@
  *
  * 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 },
+ *   const company = await ctx.tools.execute('company_search', 'test_company_search', { domain: input.domain }, {
  *     description: 'Look up company details by domain.',
  *   });
  *   return company;
@@ -58,7 +52,7 @@
 
 // ——— Client ———
 export { DeeplineClient } from './client.js';
-export type { PlayStatus } from './client.js';
+export type { PlayStatus, ToolExecution } from './client.js';
 export { SDK_API_CONTRACT, SDK_VERSION } from './version.js';
 
 // ——— Errors ———
@@ -86,15 +80,12 @@ export {
 
 // ——— 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,
@@ -119,13 +110,13 @@ export type {
   DeeplineNamedPlay,
   DeeplinePlayRuntimeContext,
   DefinedPlay,
+  ColumnMap,
+  CsvInput,
   PlayBindings,
+  FileInput,
   PlayInputContract,
   PlayJob,
   ConditionalStepResolver,
-  MapDefinitionOptions,
-  MapRowKey,
-  MapRunOptions,
   MapStepBuilder,
   MapStepResolver,
   PlayDataset,