deepline 0.3.89 → 0.3.91

package/dist/bundling-sources/shared_libs/plays/share/types.ts

@@ -0,0 +1,197 @@
+/**
+ * Package-owned types for Shareable Play Pages.
+ *
+ * These types are imported by Convex functions (`packages/convex/playSharePages.ts`),
+ * Next.js API routes, and the public landing page. They are the single,
+ * bounded contract for everything that crosses the public boundary.
+ *
+ * See docs/shareable-play-pages-plan.md.
+ */
+// This Module is bundled by Convex through its workspace dependency graph.
+import type { PlayStaticSubstep } from '../static-pipeline';
+
+/** SEO indexing posture for a share page or a specific version URL. */
+export type PlayShareSeoIndexing = 'index' | 'noindex';
+
+/**
+ * Generated landing-page copy, tied to one immutable Play Revision.
+ *
+ * Every field is plain human/agent-readable text. Nothing here may contain
+ * provider spend, secrets, raw runtime internals, or unpublished source.
+ */
+export type PlayShareGeneratedCopy = {
+  /** Concrete, job-focused landing title. */
+  title: string;
+  /** One paragraph, plain English. */
+  shortDescription: string;
+  /** The job the Play performs (jobs-to-be-done). */
+  jtbd: string;
+  /** 3-5 bullets describing when to reach for this Play. */
+  whenToUse: string[];
+  /** Concrete required inputs. */
+  inputs: string[];
+  /** Concrete produced outputs. */
+  outputs: string[];
+  /** Paste-ready Claude Code/Cursor/Codex instruction. */
+  agentPrompt: string;
+  /** Explicit, readable summary for LLM ingestion. */
+  llmSummary: string;
+  /** Search-result title. */
+  seoTitle: string;
+  /** Search-result description. */
+  seoDescription: string;
+};
+
+/** Owner overrides merge over generated copy at read time. */
+export type PlayShareCopyOverrides = Partial<PlayShareGeneratedCopy>;
+
+/**
+ * A single node in the bounded pipeline preview. Never includes source code,
+ * params, secrets, or provider spend — only a shape and a human label.
+ */
+export type PlaySharePreviewStep = {
+  /** Human-readable action, e.g. "search people by domain". */
+  label: string;
+  /** Provider name backing this step, when known. */
+  provider: string | null;
+};
+
+export type PlaySharePreviewNode = {
+  type:
+    | 'csv'
+    | 'dataset'
+    | 'tool'
+    | 'waterfall'
+    | 'step_suite'
+    | 'control_flow'
+    | 'play_call'
+    | 'play_launch'
+    | 'run_javascript'
+    | 'code';
+  /** Human-readable label, e.g. "Apollo" or "Dataset rows". */
+  label: string;
+  /** Optional provider name when this node calls a provider. */
+  provider?: string | null;
+  /** Optional secondary line, e.g. an input field or step kind. */
+  detail?: string | null;
+  /** Ordered sub-steps for waterfall / step-suite nodes (bounded). */
+  steps?: PlaySharePreviewStep[];
+};
+
+/** Bounded static-pipeline summary safe for public display. */
+export type PlayShareStaticPipelineSummary = {
+  stepCount: number;
+  providerCount: number;
+  hasMap: boolean;
+  previewNodes: PlaySharePreviewNode[];
+};
+
+/** Bounded, safe representation of the revision's input/output shape. */
+export type PlayShareSchemaShape = {
+  fields: string[];
+} | null;
+
+/**
+ * The ONLY object consumed by the public page and the public share API.
+ * Everything here is safe to expose to anyone with the unlisted link.
+ */
+export type PublishedPlayPagePackage = {
+  page: {
+    /** Internal stable record id. Never a public URL — pages are namespaced. */
+    shareSlug: string;
+    /** Org URL handle; the public page lives at `/p/:orgSlug/:playName`. */
+    orgSlug: string;
+    visibility: 'unlisted';
+    seoIndexing: PlayShareSeoIndexing;
+    /** Canonical path, e.g. `/p/:orgSlug/:playName/v/:publishedVersion`. */
+    canonicalPath: string;
+    /** Whether the requested URL is the currently-published version. */
+    isPublishedVersion: boolean;
+    /** When this version's public page was last published/updated. */
+    publishedAt: number;
+  };
+  definition: {
+    name: string;
+    ownerDisplayName: string | null;
+  };
+  revision: {
+    id: string;
+    version: number;
+    graphHash: string | null;
+    staticPipelineSummary: PlayShareStaticPipelineSummary;
+    /** Sanitized top-level substeps for the real v2 step-graph render. */
+    substeps: PlayStaticSubstep[];
+    inputSchema: PlayShareSchemaShape;
+    outputSchema: PlayShareSchemaShape;
+  };
+  copy: PlayShareGeneratedCopy;
+  publicMetrics: PublishedPlayPageMetrics;
+};
+
+/**
+ * Which cost denominator is comparable across runs of different input sizes,
+ * derived from the play's map shape. See `classifyCostBasis`.
+ */
+export type PlayCostBasis = 'run' | 'row' | 'none';
+
+/** Public, credit-only metrics. Provider spend is never present. */
+export type PublishedPlayPageMetrics = {
+  averageDeeplineCostCredits: number | null;
+  averageCostPerInputRowCredits: number | null;
+  averageCostPerOutputLeadCredits: number | null;
+  averageLatencyMs: number | null;
+  sampleRunCount: number;
+  /**
+   * The only cost denominator that is comparable across runs of different input
+   * sizes, derived from the play's map shape: `'run'` (flat play), `'row'`
+   * (single dataset over input rows), or `'none'` (multiple/nested datasets — no honest
+   * denominator, so cost is suppressed). Drives which credit metric the page
+   * renders, if any.
+   */
+  costBasis: PlayCostBasis;
+};
+
+/**
+ * Authenticated owner view of a share page (returned by GET/POST/PATCH
+ * `/api/v2/plays/:name/share`). Includes management metadata not exposed
+ * to the public read model.
+ */
+export type PlaySharePageOwnerView = {
+  shareSlug: string;
+  /** Org URL handle; the public page lives at `/p/:orgSlug/:playName`. */
+  orgSlug: string;
+  publishedRevisionId: string;
+  publishedVersion: number;
+  visibility: 'unlisted';
+  seoIndexing: PlayShareSeoIndexing;
+  showAverageDeeplineCost: boolean;
+  showAverageLatency: boolean;
+  publicPath: string;
+  canonicalPath: string;
+  createdAt: number;
+  updatedAt: number;
+};
+
+/**
+ * One row in the byte-bounded owner-facing version picker. The status response
+ * includes recent revisions plus any older working, live, public, or explicitly
+ * selected dashboard revision.
+ */
+export type PlaySharePageRevisionOption = {
+  revisionId: string;
+  version: number;
+  hasMap: boolean;
+  createdAt: number;
+  isLive: boolean;
+  isWorking: boolean;
+  isPublished: boolean;
+  hasCard: boolean;
+};
+
+/** Full payload for GET `/api/v2/plays/:name/share`. */
+export type PlaySharePageStatusResponse = {
+  playName: string;
+  share: PlaySharePageOwnerView | null;
+  publishedCopy: PlayShareGeneratedCopy | null;
+  revisions: PlaySharePageRevisionOption[];
+};

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);
+}

package/dist/bundling-sources/shared_libs/plays/slack-hitl-timeout-error.ts

@@ -0,0 +1,37 @@
+import { ToolExecutionError } from './tool-execution-error';
+
+/** Stable code for an unanswered `slack_message_with_hitl` approval. */
+export const SLACK_HITL_TIMEOUT_ERROR_CODE = 'SLACK_HITL_TIMEOUT' as const;
+
+/**
+ * A Slack human-in-the-loop approval reached its deadline without a decision.
+ *
+ * Deepline first confirms that it replaced the Slack card with “Interaction
+ * timed out.” and removed its controls. The error is non-retryable and
+ * runner-fatal: an authored `try/catch` may observe it, but cannot settle the
+ * Play successfully or start another durable operation. Retry the Play only
+ * after changing its input or timeout policy.
+ *
+ */
+export class SlackHitlTimeoutError extends ToolExecutionError {
+  constructor(message?: string) {
+    const detail =
+      message?.trim() ||
+      'Slack approval timed out before a human decision was received.';
+    super(`${SLACK_HITL_TIMEOUT_ERROR_CODE}: ${detail}`, {
+      toolId: 'slack_message_with_hitl',
+      provider: 'slack',
+      operation: 'slack_message_with_hitl',
+      code: SLACK_HITL_TIMEOUT_ERROR_CODE,
+      origin: 'deepline',
+      category: 'conflict',
+      retryable: false,
+      statusCode: 408,
+      requestId: null,
+      retryAfterMs: null,
+      networkKind: null,
+      networkScope: null,
+    });
+    this.name = 'SlackHitlTimeoutError';
+  }
+}

package/dist/bundling-sources/shared_libs/plays/standard-webhooks.ts

@@ -0,0 +1,117 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import type { PlayStandardWebhookHeaderFamily } from './/authoring-contract';
+
+export const DEFAULT_STANDARD_WEBHOOK_TOLERANCE_SECONDS = 300;
+
+export type StandardWebhookVerificationFailure =
+  | 'missing_headers'
+  | 'invalid_event_id'
+  | 'invalid_timestamp'
+  | 'timestamp_out_of_tolerance'
+  | 'invalid_signature'
+  | 'invalid_secret';
+
+export type StandardWebhookVerification =
+  | { ok: true; eventId: string; timestamp: number }
+  | { ok: false; reason: StandardWebhookVerificationFailure };
+
+function headerNames(headerFamily: PlayStandardWebhookHeaderFamily) {
+  return headerFamily === 'svix'
+    ? {
+        id: 'svix-id',
+        timestamp: 'svix-timestamp',
+        signature: 'svix-signature',
+      }
+    : {
+        id: 'webhook-id',
+        timestamp: 'webhook-timestamp',
+        signature: 'webhook-signature',
+      };
+}
+
+function normalizedHeaders(headers: Record<string, string>) {
+  return Object.fromEntries(
+    Object.entries(headers).map(([name, value]) => [name.toLowerCase(), value]),
+  );
+}
+
+/** Standard Webhooks symmetric secrets are base64; providers commonly prefix them with `whsec_`. */
+function decodeSigningSecret(value: string): Buffer | null {
+  const serialized = value.trim();
+  const encoded = serialized.startsWith('whsec_')
+    ? serialized.slice('whsec_'.length)
+    : serialized;
+  if (!encoded || !/^[A-Za-z0-9+/]+={0,2}$/.test(encoded)) return null;
+  const unpadded = encoded.replace(/=+$/, '');
+  if (unpadded.length % 4 === 1) return null;
+  const decoded = Buffer.from(encoded, 'base64');
+  return decoded.length > 0 &&
+    decoded.toString('base64').replace(/=+$/, '') === unpadded
+    ? decoded
+    : null;
+}
+
+function signatureMatches(expected: Buffer, supplied: string): boolean {
+  const candidates = supplied.trim().split(/\s+/);
+  for (const candidate of candidates) {
+    const [version, encoded, ...extra] = candidate.split(',');
+    if (version !== 'v1' || !encoded || extra.length > 0) continue;
+    if (!/^[A-Za-z0-9+/]+={0,2}$/.test(encoded)) continue;
+    const actual = Buffer.from(encoded, 'base64');
+    if (actual.length !== expected.length) continue;
+    if (timingSafeEqual(expected, actual)) return true;
+  }
+  return false;
+}
+
+/**
+ * Verifies the Standard Webhooks v1 symmetric scheme against the unmodified
+ * request body. Call this before admitting any Play Run.
+ */
+export function verifyStandardWebhook(input: {
+  headers: Record<string, string>;
+  rawBody: string;
+  signingSecrets: readonly string[];
+  headerFamily: PlayStandardWebhookHeaderFamily;
+  toleranceSeconds?: number;
+  now?: Date;
+}): StandardWebhookVerification {
+  const names = headerNames(input.headerFamily);
+  const headers = normalizedHeaders(input.headers);
+  const eventId = headers[names.id]?.trim();
+  const timestampHeader = headers[names.timestamp]?.trim();
+  const signature = headers[names.signature];
+  if (!eventId || !timestampHeader || !signature) {
+    return { ok: false, reason: 'missing_headers' };
+  }
+  // A full stop is the signed-content delimiter, so the ID must be unambiguous.
+  if (eventId.includes('.')) return { ok: false, reason: 'invalid_event_id' };
+  if (!/^\d+$/.test(timestampHeader)) {
+    return { ok: false, reason: 'invalid_timestamp' };
+  }
+  const timestamp = Number(timestampHeader);
+  if (!Number.isSafeInteger(timestamp)) {
+    return { ok: false, reason: 'invalid_timestamp' };
+  }
+  const toleranceSeconds =
+    input.toleranceSeconds ?? DEFAULT_STANDARD_WEBHOOK_TOLERANCE_SECONDS;
+  const nowSeconds = Math.floor((input.now?.getTime() ?? Date.now()) / 1000);
+  if (Math.abs(nowSeconds - timestamp) > toleranceSeconds) {
+    return { ok: false, reason: 'timestamp_out_of_tolerance' };
+  }
+
+  const signedContent = `${eventId}.${timestampHeader}.${input.rawBody}`;
+  let usableSecret = false;
+  for (const secret of input.signingSecrets) {
+    const key = decodeSigningSecret(secret);
+    if (!key) continue;
+    usableSecret = true;
+    const expected = createHmac('sha256', key).update(signedContent).digest();
+    if (signatureMatches(expected, signature)) {
+      return { ok: true, eventId, timestamp };
+    }
+  }
+  return usableSecret
+    ? { ok: false, reason: 'invalid_signature' }
+    : { ok: false, reason: 'invalid_secret' };
+}