deepline 0.1.186 → 0.1.187

package/dist/bundling-sources/sdk/src/play.ts

@@ -117,9 +117,16 @@ import type { ToolExecution } from './client.js';
 /**
  * Optional trigger bindings for a play.
  *
- * Plays can be triggered by webhooks (with HMAC signature verification)
- * or cron schedules. Bindings are declared as the third argument to
- * {@link definePlay}.
+ * A play can be triggered three ways, declared as the third argument to
+ * {@link definePlay}:
+ * - `webhook` — an inbound HTTP call (with optional HMAC signature verification);
+ * - `cron` — a schedule; or
+ * - `sqlListeners` — a **monitor**: the play runs whenever a monitor writes a new
+ *   row to its output stream. This is how you build a play "on top of" a monitor
+ *   (e.g. run enrichment every time a watched company posts a new job). Each
+ *   listener binds to a monitor tool id + one of its output stream keys (see
+ *   `deepline monitors available <id>` for a tool's streams and row columns).
+ *   The changed row is delivered to the handler as the listener event's `after`.
  *
  * @example Webhook with HMAC verification
  * ```typescript
@@ -141,6 +148,20 @@ import type { ToolExecution } from './client.js';
  * });
  * ```
  *
+ * @example Monitor-triggered (run a play on a monitor's output)
+ * ```typescript
+ * definePlay('on-new-job-opening', handler, {
+ *   sqlListeners: [
+ *     {
+ *       id: 'jobs',
+ *       tool: 'tamradar.company_radar',
+ *       stream: 'company_job_openings',
+ *       operations: ['INSERT'],
+ *     },
+ *   ],
+ * });
+ * ```
+ *
  * @sdkReference runtime 030
  */
 export type PlayBindings = {

package/dist/bundling-sources/sdk/src/release.ts

@@ -105,10 +105,10 @@ export const SDK_RELEASE = {
   // 0.1.154 removes the short-lived generated enrich StepOptions recompute
   // fields shipped in 0.1.153.
   // 0.1.175 ships loud `deepline enrich` empty-waterfall reporting.
-  version: '0.1.186',
+  version: '0.1.187',
   apiContract: '2026-06-dataset-handle-results-hard-cutover',
   supportPolicy: {
-    latest: '0.1.186',
+    latest: '0.1.187',
     minimumSupported: '0.1.53',
     deprecatedBelow: '0.1.53',
     commandMinimumSupported: [

package/dist/bundling-sources/sdk/src/types.ts

@@ -922,10 +922,98 @@ export interface PlayCheckResult {
   warnings?: string[];
   staticPipeline?: Record<string, unknown> | null;
   toolGetterHints?: PlayCheckToolGetterHint[];
+  /**
+   * Recognized trigger bindings parsed from the play source (`sqlListeners` /
+   * cron / webhook). Present only when the play declares at least one trigger,
+   * so an author can confirm the binding was recognized rather than silently
+   * dropped. Field names mirror the `definePlay` binding contract.
+   */
+  triggers?: PlayCheckTriggersSummary | null;
+  /**
+   * Structured, machine-actionable issues surfaced by the check. An ADDITIVE
+   * channel alongside `errors[]`: every `error`-severity issue is also present
+   * in `errors[]` (so string-level tooling keeps working), while an agent can
+   * read `code` / `validOptions` / `docsHint` to self-correct. `warning`
+   * severity issues do NOT make the check invalid.
+   */
+  issues?: PlayCheckIssue[];
+  /**
+   * Affirmative echo of what Deepline recognized — triggers, tools,
+   * datasets/columns, inputs, outputs — so a valid check reflects the parsed
+   * shape rather than a bare "ok".
+   */
+  recognized?: PlayCheckRecognizedSummary;
+  /**
+   * Human one-liner over {@link PlayCheckResult.recognized}, e.g.
+   * `1 trigger · 2 tools · 1 dataset · 14 columns`.
+   */
+  summary?: string;
   artifactHash?: string | null;
   graphHash?: string | null;
 }
 
+/** Severity of a {@link PlayCheckIssue}. `error` fails the check; `warning` does not. */
+export type PlayCheckIssueSeverity = 'error' | 'warning';
+
+/**
+ * One structured, machine-actionable issue surfaced by `deepline plays check`.
+ * Mirrors the server-side `PlayCheckIssue` contract. `code` is a stable machine
+ * code from a closed server-side set; `validOptions` enumerates the valid values
+ * (tool ids / stream keys / columns / operators) so an agent self-corrects by
+ * reading the structure instead of brute-forcing the compiler.
+ */
+export interface PlayCheckIssue {
+  code: string;
+  severity: PlayCheckIssueSeverity;
+  message: string;
+  path?: string;
+  hint?: string;
+  validOptions?: string[];
+  docsHint?: string;
+}
+
+/**
+ * Affirmative "here's what Deepline recognized" echo returned alongside a
+ * check's issues. Field names reuse the public play binding contract.
+ */
+export interface PlayCheckRecognizedSummary {
+  triggers?: PlayCheckTriggersSummary;
+  tools?: string[];
+  datasets?: { name: string; columns?: string[] }[];
+  inputs?: string[];
+  outputs?: string[];
+}
+
+/**
+ * One recognized SQL-listener trigger echoed back by {@link DeeplineClient.checkPlayArtifact}.
+ */
+export interface PlayCheckSqlListenerTrigger {
+  id: string;
+  tool?: string;
+  stream?: string;
+  operations: string[];
+  /**
+   * The recognized `sqlListeners.where` row filter, echoed back so an author can
+   * confirm Deepline bound it. Mirrors the server `StoredSqlListenerWhere` shape
+   * (`before` / `after` maps of column → operator filter). Absent when the
+   * listener declares no `where`.
+   */
+  where?: {
+    before?: Record<string, Record<string, unknown>>;
+    after?: Record<string, Record<string, unknown>>;
+  };
+}
+
+/**
+ * Concise summary of the trigger bindings the server recognized for a play.
+ * Only present triggers are populated.
+ */
+export interface PlayCheckTriggersSummary {
+  sqlListeners?: PlayCheckSqlListenerTrigger[];
+  cron?: { schedule: string; timezone?: string };
+  webhook?: true;
+}
+
 export interface PlayCheckToolGetterHint {
   toolId: string;
   lists: Array<{