deepline 0.3.90 → 0.3.92

package/dist/bundling-sources/shared_libs/plays/run-input-summary.ts

@@ -0,0 +1,260 @@
+/**
+ * Display-only, size-bounded projection of a play run's input payload.
+ *
+ * The full input is intentionally NOT persisted in Convex: it can be up to
+ * `PLAY_SUBMIT_INPUT_MAX_BYTES` (1MB) and would bloat the hot-path run-start
+ * write (and risk the ~1MB Convex document limit). This builds a tiny summary —
+ * top-level keys with scalar values truncated and non-scalar values elided to a
+ * compact placeholder — purely so the runs UI can show "what was this called
+ * with". It is bounded hard so it only adds negligible bytes to the existing
+ * start-row write and never touches latency.
+ *
+ * Scalar values are passed through the shared secret redaction (key-aware, plus
+ * value-pattern/high-entropy heuristics) before truncation, mirroring the run
+ * *output* preview path — so an input field like `api_key`/`token`/`password`,
+ * or a secret-looking value, is never persisted or rendered back in the UI.
+ */
+
+import { redactSecretsInCustomerValue } from '../security/secret-redaction';
+
+const MAX_KEYS = 24;
+const MAX_STRING_CHARS = 120;
+const MAX_NESTED_VALUE_CHARS = 52;
+const MAX_OBJECT_PARTS = 4;
+const MAX_ARRAY_PARTS = 3;
+const MAX_TOTAL_BYTES = 2_000;
+
+const OBJECT_PREVIEW_KEYS = [
+  'full_name',
+  'fullName',
+  'name',
+  'first_name',
+  'firstName',
+  'last_name',
+  'lastName',
+  'title',
+  'role',
+  'company_name',
+  'companyName',
+  'company',
+  'domain',
+  'company_domain',
+  'companyDomain',
+  'email',
+  'work_email',
+  'workEmail',
+  'personal_email',
+  'personalEmail',
+  'linkedin_url',
+  'linkedinUrl',
+  'url',
+  'website',
+  'operation',
+  'changedAt',
+  'changed_at',
+  'createdAt',
+  'created_at',
+] as const;
+
+const LOW_SIGNAL_PREVIEW_KEYS = new Set([
+  'id',
+  '_id',
+  'key',
+  'metadata',
+  'raw',
+  'debug',
+  'payload',
+  'headers',
+]);
+
+function truncateString(value: string, maxChars: number): string {
+  return value.length > maxChars ? `${value.slice(0, maxChars)}…` : value;
+}
+
+function formatPreviewKey(key: string): string {
+  return key
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/[_-]+/g, ' ')
+    .trim()
+    .toLowerCase();
+}
+
+function scalarSummaryValue(
+  value: unknown,
+  key: string,
+  maxChars: number,
+): string | number | boolean | null | undefined {
+  if (value === null) return null;
+  switch (typeof value) {
+    case 'string': {
+      // Key-aware + value-pattern redaction before truncation, so secrets never
+      // land in the persisted summary even when the value is short.
+      // Customer-aware redaction: key-aware + explicit credential patterns,
+      // WITHOUT the high-entropy heuristic — a long opaque customer id
+      // (campaign ids, CRM record ids) must survive the summary.
+      const safe = redactSecretsInCustomerValue(value, key);
+      return truncateString(safe, maxChars);
+    }
+    case 'number':
+    case 'boolean':
+      return value;
+    case 'bigint':
+      return truncateString(value.toString(), maxChars);
+    default:
+      return undefined;
+  }
+}
+
+function formatScalarPreview(value: unknown, key: string): string | null {
+  const summarized = scalarSummaryValue(value, key, MAX_NESTED_VALUE_CHARS);
+  if (summarized === undefined || summarized === null || summarized === '') {
+    return null;
+  }
+  return String(summarized);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+function summarizeArrayValue(value: unknown[], key: string): string {
+  if (value.length === 0) return '[0 items]';
+
+  const parts: string[] = [];
+  for (const item of value.slice(0, MAX_ARRAY_PARTS)) {
+    const preview = isRecord(item)
+      ? summarizeObjectValue(item)
+      : Array.isArray(item)
+        ? `[${item.length} item${item.length === 1 ? '' : 's'}]`
+        : formatScalarPreview(item, key);
+    if (preview) parts.push(preview);
+  }
+
+  const suffixCount = value.length - parts.length;
+  const suffix =
+    suffixCount > 0
+      ? ` +${suffixCount} item${suffixCount === 1 ? '' : 's'}`
+      : '';
+  return parts.length > 0
+    ? truncateString(`${parts.join(', ')}${suffix}`, MAX_STRING_CHARS)
+    : `[${value.length} item${value.length === 1 ? '' : 's'}]`;
+}
+
+function summarizeObjectValue(record: Record<string, unknown>): string {
+  const entries = Object.entries(record);
+  const fieldCount = entries.length;
+  if (fieldCount === 0) return '{}';
+
+  const parts: string[] = [];
+  const usedRootKeys = new Set<string>();
+
+  const addPart = (path: string, rootKey: string, value: unknown): boolean => {
+    if (parts.length >= MAX_OBJECT_PARTS) return false;
+    const preview = formatScalarPreview(value, path);
+    if (!preview) return false;
+    parts.push(`${formatPreviewKey(path)}: ${preview}`);
+    usedRootKeys.add(rootKey);
+    return true;
+  };
+
+  const addPreferredFromRecord = (
+    source: Record<string, unknown>,
+    rootKey: string,
+    prefix = '',
+  ) => {
+    for (const preferredKey of OBJECT_PREVIEW_KEYS) {
+      if (preferredKey in source) {
+        addPart(
+          prefix ? `${prefix}.${preferredKey}` : preferredKey,
+          rootKey || preferredKey,
+          source[preferredKey],
+        );
+      }
+      if (parts.length >= MAX_OBJECT_PARTS) return;
+    }
+  };
+
+  addPreferredFromRecord(record, '');
+
+  for (const [rootKey, value] of entries) {
+    if (parts.length >= MAX_OBJECT_PARTS) break;
+    if (usedRootKeys.has(rootKey) || rootKey.startsWith('_')) continue;
+    if (isRecord(value)) {
+      addPreferredFromRecord(value, rootKey, rootKey);
+    }
+  }
+
+  for (const [rootKey, value] of entries) {
+    if (parts.length >= MAX_OBJECT_PARTS) break;
+    if (
+      usedRootKeys.has(rootKey) ||
+      rootKey.startsWith('_') ||
+      LOW_SIGNAL_PREVIEW_KEYS.has(rootKey)
+    ) {
+      continue;
+    }
+    if (Array.isArray(value)) {
+      const preview = summarizeArrayValue(value, rootKey);
+      if (preview) {
+        parts.push(`${formatPreviewKey(rootKey)}: ${preview}`);
+        usedRootKeys.add(rootKey);
+      }
+      continue;
+    }
+    addPart(rootKey, rootKey, value);
+  }
+
+  if (parts.length === 0) {
+    return `{${fieldCount} field${fieldCount === 1 ? '' : 's'}}`;
+  }
+
+  const remaining = Math.max(0, fieldCount - usedRootKeys.size);
+  const suffix =
+    remaining > 0 ? ` +${remaining} field${remaining === 1 ? '' : 's'}` : '';
+  return truncateString(`${parts.join(' · ')}${suffix}`, MAX_STRING_CHARS);
+}
+
+function summarizeValue(value: unknown, key: string): unknown {
+  const scalar = scalarSummaryValue(value, key, MAX_STRING_CHARS);
+  if (scalar !== undefined) {
+    return scalar;
+  }
+  if (Array.isArray(value)) {
+    return summarizeArrayValue(value, key);
+  }
+  if (isRecord(value)) {
+    return summarizeObjectValue(value);
+  }
+  // functions, symbols, undefined: not displayable
+  return undefined;
+}
+
+export function buildPlayRunInputSummary(
+  input: unknown,
+): Record<string, unknown> | undefined {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    return undefined;
+  }
+  const entries = Object.entries(input as Record<string, unknown>);
+  if (entries.length === 0) return undefined;
+
+  const summary: Record<string, unknown> = {};
+  let count = 0;
+  for (const [key, value] of entries) {
+    if (count >= MAX_KEYS) {
+      const remaining = entries.length - count;
+      summary['…'] = `+${remaining} more field${remaining === 1 ? '' : 's'}`;
+      break;
+    }
+    const summarized = summarizeValue(value, key);
+    if (summarized === undefined) continue;
+    summary[key] = summarized;
+    count += 1;
+    if (JSON.stringify(summary).length > MAX_TOTAL_BYTES) {
+      delete summary[key];
+      summary['…'] = 'truncated';
+      break;
+    }
+  }
+  return Object.keys(summary).length > 0 ? summary : undefined;
+}

package/dist/bundling-sources/shared_libs/plays/run-summary-types.ts

@@ -0,0 +1,49 @@
+/**
+ * Compact, truncated output preview attached to terminal runs by the runs-list
+ * endpoints. Lets the runs drawer render an output table without a blocking
+ * per-run detail fetch. Not the full sheet — capped rows/columns.
+ */
+export type PlayRunSummaryResultPreview = {
+  rows: Record<string, unknown>[];
+  stats: Record<string, unknown>;
+  tableNamespace: string;
+};
+
+export type PlayRunSummaryRecord = {
+  _id: string;
+  playId: string;
+  workflowId: string;
+  /** Backend runtime attempt identifier, when the scheduler exposes one. */
+  runId?: string;
+  playName?: string | null;
+  parentRunId?: string | null;
+  rootRunId?: string | null;
+  status: string;
+  createdAt: number;
+  startedAt?: number;
+  finishedAt?: number;
+  updatedAt: number;
+  artifactTableNamespace?: string;
+  artifactTableNamespaces?: string[];
+  error?: string;
+  outputPreview?: string;
+  billingTotalCredits?: number;
+  billingMaxCreditsPerRun?: number | null;
+  result?: PlayRunSummaryResultPreview;
+  /**
+   * Size-bounded projection of the play function's normalized return value.
+   * It drives run-list columns without fetching the full terminal result for
+   * every polling response. Use the explicit full-run endpoint for the exact
+   * return value.
+   */
+  output?: Record<string, unknown>;
+  /** The compact `output` projection omitted values or fields. */
+  outputPreviewTruncated?: true;
+  /**
+   * Display-only, size-bounded projection of the run's launch input (see
+   * packages/plays/run-input-summary.ts). Top-level keys with scalar values;
+   * large/nested values elided to placeholders. Undefined when the run had no
+   * input. NOT the full input payload.
+   */
+  inputSummary?: Record<string, unknown>;
+};

package/dist/bundling-sources/shared_libs/plays/secrets/errors.ts

@@ -0,0 +1,19 @@
+export const PLAY_SECRET_UNAVAILABLE = 'PLAY_SECRET_UNAVAILABLE' as const;
+
+export class PlaySecretUnavailableError extends Error {
+  readonly code = PLAY_SECRET_UNAVAILABLE;
+
+  constructor(readonly secretName: string) {
+    super(`Secret ${secretName} is not active or does not exist.`);
+    this.name = 'PlaySecretUnavailableError';
+  }
+}
+
+export function playSecretUnavailableErrorFrom(
+  error: unknown,
+): PlaySecretUnavailableError | null {
+  const message = error instanceof Error ? error.message : String(error);
+  const match =
+    /Secret ([A-Z][A-Z0-9_]*) is not active or does not exist\./.exec(message);
+  return match ? new PlaySecretUnavailableError(match[1]) : null;
+}

package/dist/bundling-sources/shared_libs/plays/sheet-filter.ts

@@ -0,0 +1,347 @@
+// Full-table view basic filters. A tiny, deliberately closed predicate model
+// that compiles mechanically to a parameterized SQL WHERE clause against a
+// runtime sheet's physical (jsonb) user-data columns.
+//
+// This is NOT free-text SQL: operators come from a closed enum, columns must
+// be on a caller-supplied allowlist (the sheet's real columns), and every value
+// is bound as a query parameter. Multiple filters AND together. No OR groups.
+//
+// Sheet user-data columns are stored one-per-column as `jsonb` (a JSON scalar
+// like "completed", 19991, or an object). `col #>> '{}'` extracts the scalar as
+// text; numeric comparisons cast that text to numeric.
+
+// ── The operator set, and why it grew ────────────────────────────────────────
+//
+// The filter UI is `src/components/data-table-filter` — the repo's shadcn
+// faceted filter, the same one the customer-db grid and the integrations run
+// table use. Its operator vocabulary per column type is fixed by the package,
+// so this enum has to cover it exactly or a filter the user can build is one
+// the server cannot compile.
+//
+// Everything added here is a single clause with a NOT in it, which is precisely
+// what could not be expressed by composing the operators that were already
+// here: this model AND-joins and has no OR groups, so `is not between` cannot
+// be decomposed into two filters. Where a package operator CAN be decomposed it
+// still gets its own entry rather than a rewrite rule, so the payload on the
+// wire reads the same as the chip the user built.
+//
+// `is_empty` / `not_empty` have no operator in the package and are therefore
+// unreachable from the UI. They stay compilable — the API accepts them and an
+// agent can send them — and adding them to the shared package is a deliberate
+// change that has to update every consumer's compiler at the same time.
+export const SHEET_FILTER_TEXT_OPS = [
+  'equals',
+  'not_equals',
+  'contains',
+  'not_contains',
+  'is_empty',
+  'not_empty',
+] as const;
+
+export const SHEET_FILTER_NUMERIC_OPS = [
+  'gt',
+  'lt',
+  'gte',
+  'lte',
+  'num_equals',
+  'num_not_equals',
+  'between',
+  'not_between',
+] as const;
+
+export const SHEET_FILTER_OPS = [
+  ...SHEET_FILTER_TEXT_OPS,
+  ...SHEET_FILTER_NUMERIC_OPS,
+] as const;
+
+export type SheetFilterOp = (typeof SHEET_FILTER_OPS)[number];
+
+const SHEET_FILTER_OP_SET: ReadonlySet<string> = new Set(SHEET_FILTER_OPS);
+const SHEET_FILTER_NUMERIC_OP_SET: ReadonlySet<string> = new Set(
+  SHEET_FILTER_NUMERIC_OPS,
+);
+// Ops that carry no value (the value input is hidden in the UI).
+const SHEET_FILTER_VALUELESS_OP_SET: ReadonlySet<SheetFilterOp> = new Set([
+  'is_empty',
+  'not_empty',
+]);
+
+/** Ops whose `value` is an inclusive `[min, max]` pair rather than a scalar. */
+const SHEET_FILTER_RANGE_OP_SET: ReadonlySet<SheetFilterOp> = new Set([
+  'between',
+  'not_between',
+]);
+
+export function isRangeSheetFilterOp(op: SheetFilterOp): boolean {
+  return SHEET_FILTER_RANGE_OP_SET.has(op);
+}
+
+export type SheetFilter = {
+  column: string;
+  op: SheetFilterOp;
+  /** A scalar for most ops; an inclusive `[min, max]` pair for the range ops
+   *  (`between`, `not_between`); absent for the valueless ops. */
+  value?: unknown;
+};
+
+export type CompiledSheetFilter = {
+  /** WHERE-clause body WITHOUT the leading `WHERE` (empty string when no
+   *  filters). AND-joined; callers combine it with their own conditions. */
+  sql: string;
+  /** Parameters bound in `$n` order, starting at `startParamIndex`. */
+  params: unknown[];
+  /** Next free `$n` index after the compiled params. */
+  nextParamIndex: number;
+};
+
+export class SheetFilterError extends Error {
+  readonly code = 'invalid_sheet_filter';
+  constructor(message: string) {
+    super(message);
+    this.name = 'SheetFilterError';
+  }
+}
+
+export function isSheetFilterOp(value: unknown): value is SheetFilterOp {
+  return typeof value === 'string' && SHEET_FILTER_OP_SET.has(value);
+}
+
+export function isNumericSheetFilterOp(op: SheetFilterOp): boolean {
+  return SHEET_FILTER_NUMERIC_OP_SET.has(op);
+}
+
+/**
+ * Parse an untrusted `filters` payload (from a query param or request body)
+ * into a typed, validated filter list. Throws `SheetFilterError` (→ 400) on any
+ * malformed entry so the read path fails loudly rather than silently dropping a
+ * predicate.
+ */
+export function parseSheetFilters(raw: unknown): SheetFilter[] {
+  if (raw == null || raw === '') return [];
+  let value = raw;
+  if (typeof value === 'string') {
+    try {
+      value = JSON.parse(value);
+    } catch {
+      throw new SheetFilterError('filters must be a JSON array');
+    }
+  }
+  if (!Array.isArray(value)) {
+    throw new SheetFilterError('filters must be a JSON array');
+  }
+  return value.map((entry, index) => parseSheetFilterEntry(entry, index));
+}
+
+function parseSheetFilterEntry(entry: unknown, index: number): SheetFilter {
+  if (entry == null || typeof entry !== 'object' || Array.isArray(entry)) {
+    throw new SheetFilterError(`filters[${index}] must be an object`);
+  }
+  const record = entry as Record<string, unknown>;
+  const column = record.column;
+  if (typeof column !== 'string' || column.trim() === '') {
+    throw new SheetFilterError(
+      `filters[${index}].column must be a non-empty string`,
+    );
+  }
+  const op = record.op;
+  if (!isSheetFilterOp(op)) {
+    throw new SheetFilterError(
+      `filters[${index}].op "${String(op)}" is not a supported operator`,
+    );
+  }
+  return { column: column.trim(), op, value: record.value };
+}
+
+function coerceFilterText(value: unknown, index: number): string {
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return String(value);
+  }
+  throw new SheetFilterError(
+    `filters[${index}].value must be a string, number, or boolean`,
+  );
+}
+
+const NUMERIC_SQL_OPERATOR: Record<string, string> = {
+  gt: '>',
+  lt: '<',
+  gte: '>=',
+  lte: '<=',
+  num_equals: '=',
+  num_not_equals: '<>',
+};
+
+function coerceFilterRange(value: unknown, index: number): [number, number] {
+  if (!Array.isArray(value) || value.length !== 2) {
+    throw new SheetFilterError(
+      `filters[${index}].value must be a [min, max] pair for a range operator`,
+    );
+  }
+  const min = coerceFilterNumber(value[0], index);
+  const max = coerceFilterNumber(value[1], index);
+  // Accept either order rather than rejecting it: the filter UI's two number
+  // inputs have no opinion about which the user fills first, and a silently
+  // empty result is the worse failure here.
+  return min <= max ? [min, max] : [max, min];
+}
+
+function coerceFilterNumber(value: unknown, index: number): number {
+  const parsed =
+    typeof value === 'number'
+      ? value
+      : typeof value === 'string' && value.trim() !== ''
+        ? Number(value)
+        : NaN;
+  if (!Number.isFinite(parsed)) {
+    throw new SheetFilterError(
+      `filters[${index}].value must be a finite number for the "${'numeric'}" operator`,
+    );
+  }
+  return parsed;
+}
+
+// Extract a jsonb column's scalar as text: `"completed"` → completed, `19991`
+// → 19991, an object → its JSON text. The single-arg `#>> '{}'` path returns the
+// whole value as text (Postgres jsonb → text).
+function columnAsText(quotedColumn: string): string {
+  return `(${quotedColumn} #>> '{}')`;
+}
+
+function quoteIdentifier(value: string): string {
+  return `"${value.replace(/"/g, '""')}"`;
+}
+
+/**
+ * Compile validated filters against an allowlist of real column names into a
+ * parameterized WHERE body. Unknown columns and numeric ops on non-numeric
+ * columns throw `SheetFilterError` (→ 400).
+ *
+ * @param numericColumns Columns whose UI type is numeric; numeric ops are only
+ *   admitted on these. Text ops work on every allowed column.
+ */
+export function compileSheetFilterWhere(input: {
+  filters: readonly SheetFilter[];
+  allowedColumns: ReadonlySet<string>;
+  numericColumns?: ReadonlySet<string>;
+  startParamIndex?: number;
+}): CompiledSheetFilter {
+  const startParamIndex = input.startParamIndex ?? 1;
+  const numericColumns = input.numericColumns ?? new Set<string>();
+  const clauses: string[] = [];
+  const params: unknown[] = [];
+  let paramIdx = startParamIndex;
+
+  input.filters.forEach((filter, index) => {
+    if (!input.allowedColumns.has(filter.column)) {
+      throw new SheetFilterError(
+        `filters[${index}].column "${filter.column}" is not a column of this table`,
+      );
+    }
+    const quoted = quoteIdentifier(filter.column);
+    const asText = columnAsText(quoted);
+
+    if (
+      isNumericSheetFilterOp(filter.op) &&
+      !numericColumns.has(filter.column)
+    ) {
+      throw new SheetFilterError(
+        `filters[${index}].op "${filter.op}" is only valid on numeric columns; "${filter.column}" is not numeric`,
+      );
+    }
+
+    switch (filter.op) {
+      case 'equals': {
+        const text = coerceFilterText(filter.value, index);
+        clauses.push(`${asText} = $${paramIdx}`);
+        params.push(text);
+        paramIdx += 1;
+        break;
+      }
+      case 'not_equals': {
+        const text = coerceFilterText(filter.value, index);
+        // NULL-safe: a NULL/absent cell is "not equal" to a concrete value.
+        clauses.push(`(${asText} IS DISTINCT FROM $${paramIdx})`);
+        params.push(text);
+        paramIdx += 1;
+        break;
+      }
+      case 'contains': {
+        const text = coerceFilterText(filter.value, index);
+        clauses.push(`${asText} ILIKE $${paramIdx}`);
+        params.push(`%${escapeLikePattern(text)}%`);
+        paramIdx += 1;
+        break;
+      }
+      case 'not_contains': {
+        const text = coerceFilterText(filter.value, index);
+        // NULL-safe, like `not_equals`: a cell with no value does not contain
+        // the needle, and `NOT (NULL ILIKE ...)` is NULL, which filters it out.
+        clauses.push(`(${asText} IS NULL OR ${asText} NOT ILIKE $${paramIdx})`);
+        params.push(`%${escapeLikePattern(text)}%`);
+        paramIdx += 1;
+        break;
+      }
+      case 'is_empty': {
+        clauses.push(
+          `(${quoted} IS NULL OR ${asText} IS NULL OR ${asText} = '')`,
+        );
+        break;
+      }
+      case 'not_empty': {
+        clauses.push(
+          `(${quoted} IS NOT NULL AND ${asText} IS NOT NULL AND ${asText} <> '')`,
+        );
+        break;
+      }
+      case 'gt':
+      case 'lt':
+      case 'gte':
+      case 'lte':
+      case 'num_equals':
+      case 'num_not_equals': {
+        const num = coerceFilterNumber(filter.value, index);
+        const sqlOp = NUMERIC_SQL_OPERATOR[filter.op];
+        // Guard the numeric cast to jsonb numbers only, so a stray non-numeric
+        // cell can never abort the whole query with a cast error.
+        clauses.push(
+          `(jsonb_typeof(${quoted}) = 'number' AND ${asText}::numeric ${sqlOp} $${paramIdx})`,
+        );
+        params.push(num);
+        paramIdx += 1;
+        break;
+      }
+      case 'between':
+      case 'not_between': {
+        const [min, max] = coerceFilterRange(filter.value, index);
+        // `BETWEEN` is inclusive on both ends, which is what the filter UI's
+        // range control means by it. The guard is the same one the scalar
+        // comparisons use: a non-numeric cell simply does not match, rather
+        // than aborting the query on a cast.
+        const body = `${asText}::numeric BETWEEN $${paramIdx} AND $${paramIdx + 1}`;
+        clauses.push(
+          `(jsonb_typeof(${quoted}) = 'number' AND ${
+            filter.op === 'between' ? body : `NOT (${body})`
+          })`,
+        );
+        params.push(min, max);
+        paramIdx += 2;
+        break;
+      }
+    }
+  });
+
+  return {
+    sql: clauses.join(' AND '),
+    params,
+    nextParamIndex: paramIdx,
+  };
+}
+
+// Escape LIKE/ILIKE metacharacters so a `contains` value is matched literally.
+function escapeLikePattern(value: string): string {
+  return value.replace(/([\\%_])/g, '\\$1');
+}
+
+export function sheetFilterHasValue(op: SheetFilterOp): boolean {
+  return !SHEET_FILTER_VALUELESS_OP_SET.has(op);
+}