@relayflows/surface 2.0.8 → 2.0.10

package/src/provider-trigger.ts

@@ -0,0 +1,26 @@
+import { webhook, type TriggerSource, type WebhookFilter } from "./triggers.js";
+
+/** A provider inbox subscription over an envelope's type and payload. */
+export interface ProviderTriggerSource<Provider extends string, Event extends string> extends TriggerSource {
+  readonly name: Provider;
+  readonly filter: WebhookFilter & { readonly provider: Provider; readonly type: Event };
+}
+
+/** Shared implementation for generated provider declarations. */
+export function providerTrigger<P extends string, E extends string>(
+  provider: P, event: E, payload?: WebhookFilter,
+): ProviderTriggerSource<P, E> {
+  if (typeof event !== "string" || event.length === 0) throw new TypeError("provider event type must not be empty");
+  // Validate separately so an invalid payload cannot become a scalar filter leaf.
+  const filter = webhook(provider, payload).filter;
+  return webhook(provider, {
+    provider, type: event, ...(filter === undefined ? {} : { payload: filter }),
+  }) as ProviderTriggerSource<P, E>;
+}
+
+export function triggerArgument(value: string, name: string): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new TypeError(`${name} must be a nonempty string`);
+  }
+  return value;
+}

package/src/runtime.ts

@@ -3,5 +3,13 @@ export {
   type AuthoredFlowDefinition,
   type FlowBody,
   type FlowHandle,
+  type TriggerHandler,
+  type TriggeredFlowHandle,
   type ReadonlyFlowHeader,
 } from "./flow.js";
+export { slackPostBody } from "./slack.js";
+
+export { createHelpers } from "./helpers/index.js";
+export { helperProviders } from "./helpers/providers.js";
+export { helperClients } from "./helpers/clients.js";
+export { invokeHelper, type HelperCall } from "./effect-transport.js";

package/src/slack.ts

@@ -0,0 +1,47 @@
+import type { Step } from "./step.js";
+import type { SlackAttachment, SlackBlock } from "./helpers/slack.js";
+
+export type { SlackAttachment, SlackBlock } from "./helpers/slack.js";
+
+/** Structured message content. Text supplies the notification/accessibility fallback. */
+export interface SlackPostMessage {
+  text?: string;
+  blocks?: SlackBlock[];
+  attachments?: SlackAttachment[];
+}
+
+export interface SlackPostOptions extends Omit<SlackPostMessage, "text"> {
+  replyTo?: string;
+}
+
+export interface SlackReceipt {
+  channel: string;
+  ts: string;
+  ref: string;
+}
+
+/** Slack writeback helpers; every call is a journal-backed effect. */
+export interface SlackHelper {
+  post(channel: string, text: string | SlackPostMessage, opts?: SlackPostOptions): Step<SlackReceipt>;
+  dm(user: string, text: string): Step<{ user: string; ts: string }>;
+  reply(channel: string, threadTs: string, text: string): Step<SlackReceipt>;
+  react(channel: string, messageTs: string, emoji: string): Step<void>;
+}
+
+/** Normalize both authoring forms to the adapter's JSON writeback body. */
+export function slackPostBody(text: string | SlackPostMessage, opts?: SlackPostOptions): SlackPostMessage & { parentRef?: string } {
+  const message = typeof text === "string" ? { text } : text;
+  const blocks = opts?.blocks ?? message.blocks;
+  const attachments = opts?.attachments ?? message.attachments;
+  return {
+    ...(message.text === undefined ? {} : { text: message.text }),
+    ...(blocks === undefined ? {} : { blocks }),
+    ...(attachments === undefined ? {} : { attachments }),
+    ...(opts?.replyTo ? { parentRef: opts.replyTo } : {}),
+  };
+}
+
+/** Stable across attempts; deliberately independent of process-tick ordinals. */
+export function flowRunWritebackIdempotency(runId: string, stepId: string): string {
+  return `${runId}:${stepId}`;
+}

package/src/step.ts

@@ -1,5 +1,56 @@
 /** A journal-backed step result with its postfix verification gate. */
 export interface Step<T> extends PromiseLike<T> {
-  /** Fail the step with `verification_failed` when the predicate is false. */
+  /**
+   * Attach a named data gate to this step's `verification:` field. The gate is
+   * lowered by the SDK into a slice-P journal-honest check that survives
+   * replay — its shape is data, not code, so covenant 1 (journal-as-truth)
+   * holds. See `packages/sdk/src/named-gates.ts` for the enforcement.
+   */
+  gate(config: NamedGate): Step<T>;
+  /**
+   * Predicate gates cannot be journaled — the JavaScript closure would not
+   * survive replay — so the executor refuses this branch with
+   * `unsupported_gate`. Use a `NamedGate` config-object gate above, or the
+   * declarative `verification:` field on the compiled step spec, when you
+   * need journal-honest verification.
+   */
   gate(predicate: (value: T) => boolean, because?: string): Step<T>;
 }
+
+/**
+ * Slice-P named data gates the authored surface can attach postfix via
+ * `.gate(config)`. The SDK's named-gate lowering enforces these exactly (see
+ * `packages/sdk/src/named-gates.ts`); the shapes here are the surface-visible
+ * subset kept in sync with `NamedDataGate` in the SDK spec.
+ */
+export type NamedGate =
+  | ReferencesInputNamedGate
+  | SubprocessNamedGate
+  | WordCountBoundsNamedGate
+  | RegexMatchNamedGate;
+
+export interface ReferencesInputNamedGate {
+  type: 'references_input';
+  input_key: string;
+  in_output_at?: Array<string | number>;
+}
+
+export interface SubprocessNamedGate {
+  type: 'subprocess_gate';
+  command: string;
+  from_output?: Array<string | number>;
+}
+
+export interface WordCountBoundsNamedGate {
+  type: 'word_count_bounds';
+  min?: number;
+  max?: number;
+}
+
+export interface RegexMatchNamedGate {
+  type: 'regex_match';
+  pattern: string;
+  /** Only i, m, and s; evaluated by a non-backtracking RE2 engine. */
+  flags?: string;
+  in_output_at?: Array<string | number>;
+}

package/src/triggers/README.md

@@ -0,0 +1,75 @@
+# Provider event triggers
+
+```ts
+import { flow, slack, github } from '@relayflows/surface';
+
+export default flow('triage')
+  .on(slack.mention('C123'), async (f, event) => { f.done('success'); })
+  .on(slack.reaction('eyes'), async (f, event) => { f.done('success'); })
+  .on(github.pull_request('opened'), async (f, event) => { f.done('success'); });
+```
+
+Provider namespaces also export from `@relayflows/surface/triggers` and
+`@relayflows/surface/triggers/slack` (or `/github`). Declarations are immutable
+webhook sources: their executor/inbox name is the provider, and their filter
+matches the provider, event type, and requested payload fields. Register those
+provider names in `flows.json`'s `executors` array for preflight.
+
+`slack.mention(channel)` subscribes to Slack's `app_mention` event;
+`slack.reaction(emoji)` subscribes to `reaction_added`. Arguments match provider
+values exactly: use the channel ID and reaction name from the incoming event.
+`github.pull_request(action)` filters `payload.action`; omitting the action
+accepts every pull request event. Upstream mappings do not declare action enums,
+so the action parameter is a string. Other generated methods accept an optional
+recursive payload filter, for example `github.push({ ref: 'refs/heads/main' })`.
+
+The receiver accepts `POST /providers/slack` with this JSON:
+
+```json
+{"type":"app_mention","payload":{"channel":"C123","text":"Please review"}}
+```
+
+It writes `{ "provider": "slack", "type": "app_mention", "payload": {...} }`
+atomically to `inbox/slack/<id>.json`. The path supplies the provider; a conflicting
+provider in the body or unknown event type is rejected. `payload` is the provider
+event body (Slack's inner `event` object). The event names are the exact mapping
+keys; dots and hyphens become underscores only in TypeScript method names.
+Ingress expects this envelope, not a raw vendor HTTP delivery. Signature
+verification and public ingress remain part of the deployment work tracked in
+#301. Generic `POST /<name>` retains its existing arbitrary-JSON contract.
+
+The SDK's `webhookTriggerSpec(id, source)` lowers a declaration to `TriggerSpec`
+for `compileSpec`/`toKernelSpec`. Provision the resulting RunSpec in
+`triggers/<provider>.json`, with executable steps, as in the existing webhook
+executor. The watcher applies the generated filters, journals matching events,
+deduplicates by inbox file ID, and archives consumed events. For example:
+
+```ts
+import { compileSpec, toKernelSpec, webhookTriggerSpec } from '@relayflows/sdk';
+import { slack } from '@relayflows/surface';
+
+const binding = toKernelSpec(compileSpec({
+  version: '0.1.0', name: 'mentions',
+  triggers: [webhookTriggerSpec('mention', slack.mention('C123'))],
+  steps: [{ id: 'ack', type: 'deterministic', command: 'printf accepted' }],
+})); // Write binding as JSON to triggers/slack.json before ingress starts.
+```
+
+Each provider inbox still binds one RunSpec. This extends E's declaration and
+inbox contract; deploying TypeScript handler bodies remains the separate #301
+binding step.
+
+Generation requires the SDK's development dependencies. The default input is
+the mapping YAML shipped in the pinned `@relayfile/adapter-core` dependency
+(currently Slack and GitHub). A checkout supplies additional providers:
+
+```sh
+node scripts/generate-triggers.mjs
+node scripts/generate-triggers.mjs --check
+node scripts/generate-triggers.mjs --adapters-dir /path/to/relayfile-adapters
+```
+
+The generator reads `packages/core/mappings/*.mapping.yaml`, then each adapter's
+`packages/<adapter>/*.mapping.yaml`; adapter-local mappings take precedence.
+Only adapters with a nonempty `webhooks:` section produce modules. It never
+imports or executes adapter code. Rebuild the surface and SDK after regeneration.

package/src/triggers/github.ts

@@ -0,0 +1,19 @@
+// GENERATED by scripts/generate-triggers.mjs — do not edit.
+
+import { providerTrigger, triggerArgument } from "../provider-trigger.js";
+import type { WebhookFilter } from "../triggers.js";
+
+export const github = Object.freeze({
+  issues(filter?: WebhookFilter) {
+    return providerTrigger("github", "issues", filter);
+  },
+  pull_request(action?: string) {
+    return providerTrigger("github", "pull_request", action === undefined ? undefined : { action: triggerArgument(action, "action") });
+  },
+  pull_request_review(filter?: WebhookFilter) {
+    return providerTrigger("github", "pull_request_review", filter);
+  },
+  push(filter?: WebhookFilter) {
+    return providerTrigger("github", "push", filter);
+  },
+});

package/src/triggers/index.ts

@@ -0,0 +1,10 @@
+// GENERATED by scripts/generate-triggers.mjs — do not edit.
+
+export { github } from "./github.js";
+export { slack } from "./slack.js";
+
+/** Exact upstream event names, plus the generated Slack mention shorthand. */
+export const providerEventTypes = Object.freeze({
+  "github": Object.freeze(["issues","pull_request","pull_request_review","push"] as const),
+  "slack": Object.freeze(["app_mention","message","reaction_added"] as const),
+});

package/src/triggers/slack.ts

@@ -0,0 +1,19 @@
+// GENERATED by scripts/generate-triggers.mjs — do not edit.
+
+import { providerTrigger, triggerArgument } from "../provider-trigger.js";
+import type { WebhookFilter } from "../triggers.js";
+
+export const slack = Object.freeze({
+  message(filter?: WebhookFilter) {
+    return providerTrigger("slack", "message", filter);
+  },
+  reaction_added(filter?: WebhookFilter) {
+    return providerTrigger("slack", "reaction_added", filter);
+  },
+  mention(channel: string) {
+    return providerTrigger("slack", "app_mention", { channel: triggerArgument(channel, "channel") });
+  },
+  reaction(emoji: string) {
+    return providerTrigger("slack", "reaction_added", { reaction: triggerArgument(emoji, "emoji") });
+  },
+});

package/src/triggers.ts

@@ -0,0 +1,49 @@
+export type WebhookValue = null | boolean | number | string
+  | readonly WebhookValue[] | { readonly [key: string]: WebhookValue };
+
+/** Recursive object subset; array and scalar leaves match exactly. */
+export type WebhookFilter = { readonly [key: string]: WebhookValue };
+
+export interface TriggerSource {
+  readonly kind: "webhook";
+  readonly name: string;
+  readonly filter?: WebhookFilter;
+}
+
+/** Plain, immutable data. Constructing a source opens no receiver. */
+export function webhook(name: string, filter?: WebhookFilter): TriggerSource {
+  if (typeof name !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(name)) {
+    throw new TypeError("webhook name must be 1-128 letters, digits, underscores or hyphens, starting with a letter or digit");
+  }
+  if (filter === undefined) return Object.freeze({ kind: "webhook", name });
+  if (filter === null || typeof filter !== "object" || Array.isArray(filter)) {
+    throw new TypeError("webhook filter must be a JSON object");
+  }
+  return Object.freeze({ kind: "webhook", name, filter: snapshot(filter) as WebhookFilter });
+}
+
+function snapshot(value: unknown, ancestors = new Set<object>()): WebhookValue {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value !== "object" || value === null || ancestors.has(value)) {
+    throw new TypeError("webhook filter must contain finite, acyclic JSON data");
+  }
+  const array = Array.isArray(value);
+  if (!array && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+    throw new TypeError("webhook filter must contain plain JSON objects");
+  }
+  ancestors.add(value);
+  const entries: [string, WebhookValue][] = [];
+  for (const key of Reflect.ownKeys(value)) {
+    if (array && key === "length") continue;
+    const descriptor = Object.getOwnPropertyDescriptor(value, key)!;
+    if (typeof key !== "string" || !descriptor.enumerable || !("value" in descriptor)) {
+      throw new TypeError("webhook filter must contain JSON data properties");
+    }
+    if (array && !/^(0|[1-9][0-9]*)$/.test(key)) throw new TypeError("invalid JSON array property");
+    entries.push([key, snapshot(descriptor.value, ancestors)]);
+  }
+  ancestors.delete(value);
+  if (array && entries.length !== value.length) throw new TypeError("webhook filter arrays must not be sparse");
+  return Object.freeze(array ? entries.map(([, item]) => item) : Object.fromEntries(entries));
+}