@zibby/workflow-templates 0.3.0 → 0.4.2

package/notify-notion/nodes/notify-notion-node.js

@@ -0,0 +1,342 @@
+/**
+ * notify-notion node — deterministic, no LLM.
+ *
+ * Posts a single page (or appends blocks to an existing page) to a
+ * Notion workspace via the official Notion REST API. Same design
+ * philosophy as notify-slack and notify-lark: parent makes all the
+ * decisions (severity, title, body, where), this node just renders
+ * the blocks and dispatches the API call.
+ *
+ * Auth: pulls the Notion OAuth bearer token via @zibby/core's
+ * `resolveIntegrationToken('notion')`. Backend's notion handler
+ * returns `{ token, workspaceId }` — we only need the token, but
+ * tests / debugging consume the workspaceId too.
+ *
+ * Two write paths:
+ *   - databaseId → POST /v1/pages   (creates a new page in a database)
+ *   - pageId     → PATCH /v1/blocks/{pageId}/children
+ *                                   (appends blocks to an existing page)
+ *
+ * Mutual exclusion is enforced at runtime — see state.js for why we
+ * don't do it in the zod schema.
+ *
+ * Failure modes (no retry — sub-graph caller handles retries):
+ *   - Token missing / wrong scope → resolveIntegrationToken throws
+ *     "notion is not connected".
+ *   - 401 → Notion rejected token (token revoked or wrong workspace).
+ *   - 404 → page/database not found (or bot not added to it).
+ *   - 429 → Notion rate-limited (rare; caller should backoff + retry).
+ *   - 5xx → typed error with .status set; caller can re-dispatch.
+ */
+
+import { z } from 'zod';
+import { SKILLS } from '@zibby/core';
+import { resolveIntegrationToken } from '@zibby/core/backend-client.js';
+// Universal renderer — see notify-slack-node.js / notify-lark-node.js
+// for the design note. When state.report is present the legacy
+// buildNotionPayload path is bypassed entirely.
+import { reportToNotionBlocks } from '@zibby/skills/report';
+
+// Notion REST API root. Hardcoded — there's no on-prem variant and
+// the backend doesn't return a host.
+const NOTION_API_BASE = 'https://api.notion.com/v1';
+
+// Notion-Version pin. As of 2026-05 this is the latest stable version.
+// Notion's API is versioned at the request level (header), not the
+// URL path, so we MUST send this to get a deterministic schema.
+const NOTION_VERSION = '2022-06-28';
+
+const SEVERITY_ICON = Object.freeze({
+  low:      '⚪',
+  medium:   '🟡',
+  high:     '🟠',
+  critical: '🚨',
+});
+
+const NotifyNotionOutputSchema = z.object({
+  delivered: z.boolean().describe('true if the Notion API request returned 2xx'),
+  pageId: z.string().describe('ID of the page that was created (databaseId branch) or appended to (pageId branch)'),
+  pageUrl: z.string().optional().describe('Notion URL for the page — set only on the create branch (Notion returns it in the response). Empty on append.'),
+  blocksCount: z.number().int().optional().describe('Block count posted — diagnostic only.'),
+});
+
+/**
+ * Build the Notion page-creation OR block-append request body from
+ * the input. Exposed for unit tests so we can pin the rendered shape
+ * without going through fetch.
+ *
+ * Returns one of two shapes:
+ *   - `{ kind: 'page',   url: '<api>/pages', body: {...} }`
+ *   - `{ kind: 'append', url: '<api>/blocks/{pageId}/children', body: {...} }`
+ *
+ * The shape is determined by which of databaseId / pageId is supplied;
+ * exactly one must be present (the caller's runtime guard catches the
+ * "neither/both" case before this is called).
+ *
+ * @param {Object} input
+ * @returns {{ kind: 'page'|'append', url: string, body: Object, blocksCount: number, title: string, icon?: string }}
+ */
+export function buildNotionPayload(input) {
+  const {
+    severity = 'medium',
+    title: inputTitle,
+    body,
+    databaseId,
+    pageId,
+    sentryLink,
+    affectedUsers,
+    events,
+    release,
+    firstSeen,
+    codeSnippet,
+    actionUrl,
+    actionLabel,
+    mentions,
+    report,
+  } = input;
+
+  // ── Rich-mode: defer entirely to @zibby/skills's renderer ─────────
+  if (report && typeof report === 'object') {
+    const rendered = reportToNotionBlocks(report);
+    if (databaseId) {
+      const pageBody = {
+        parent: { database_id: databaseId },
+        properties: {
+          Name: {
+            title: [{ text: { content: rendered.title } }],
+          },
+        },
+        children: rendered.blocks,
+      };
+      if (rendered.icon) {
+        pageBody.icon = { type: 'emoji', emoji: rendered.icon };
+      }
+      return {
+        kind: 'page',
+        url: `${NOTION_API_BASE}/pages`,
+        body: pageBody,
+        blocksCount: rendered.blocks.length,
+        title: rendered.title,
+        icon: rendered.icon,
+      };
+    }
+    // pageId branch — append children (no title/icon — those are page
+    // properties and can't be updated via the children endpoint).
+    return {
+      kind: 'append',
+      url: `${NOTION_API_BASE}/blocks/${encodeURIComponent(pageId)}/children`,
+      body: { children: rendered.blocks },
+      blocksCount: rendered.blocks.length,
+      title: rendered.title,
+      icon: rendered.icon,
+    };
+  }
+
+  // ── Legacy-mode: render severity/title/body into a simple Notion page ─
+  const titleText = `${severity.toUpperCase()}: ${inputTitle || ''}`.trim();
+  const icon = SEVERITY_ICON[severity] || SEVERITY_ICON.medium;
+  const children = [];
+
+  if (body && body.trim().length > 0) {
+    children.push({
+      object: 'block',
+      type: 'paragraph',
+      paragraph: { rich_text: [{ type: 'text', text: { content: body.slice(0, 2000) } }] },
+    });
+  }
+
+  // Sentry-flavored metadata — rendered as a bulleted list when at
+  // least one field is present. Mirrors notify-slack's "fields" block.
+  const metaLines = [];
+  if (typeof affectedUsers === 'number') metaLines.push(`Users affected: ${affectedUsers}`);
+  if (typeof events === 'number')        metaLines.push(`Events: ${events}`);
+  if (release)                            metaLines.push(`Release: ${release}`);
+  if (firstSeen)                          metaLines.push(`First seen: ${firstSeen}`);
+  for (const line of metaLines) {
+    children.push({
+      object: 'block',
+      type: 'bulleted_list_item',
+      bulleted_list_item: { rich_text: [{ type: 'text', text: { content: line } }] },
+    });
+  }
+
+  if (codeSnippet) {
+    children.push({
+      object: 'block',
+      type: 'code',
+      code: {
+        rich_text: [{ type: 'text', text: { content: codeSnippet.slice(0, 2000) } }],
+        language: 'plain text',
+      },
+    });
+  }
+
+  // Action links — embeds (Notion's closest equivalent to buttons).
+  if (sentryLink) {
+    children.push({
+      object: 'block',
+      type: 'embed',
+      embed: { url: sentryLink },
+    });
+  }
+  if (actionUrl && actionLabel) {
+    children.push({
+      object: 'block',
+      type: 'embed',
+      embed: { url: actionUrl },
+    });
+  }
+
+  // Mentions — plain-text bulleted list at the bottom.
+  if (Array.isArray(mentions) && mentions.length > 0) {
+    children.push({
+      object: 'block',
+      type: 'heading_3',
+      heading_3: { rich_text: [{ type: 'text', text: { content: 'Notify' } }] },
+    });
+    for (const m of mentions) {
+      children.push({
+        object: 'block',
+        type: 'bulleted_list_item',
+        bulleted_list_item: { rich_text: [{ type: 'text', text: { content: m } }] },
+      });
+    }
+  }
+
+  if (databaseId) {
+    return {
+      kind: 'page',
+      url: `${NOTION_API_BASE}/pages`,
+      body: {
+        parent: { database_id: databaseId },
+        icon: { type: 'emoji', emoji: icon },
+        properties: {
+          Name: {
+            title: [{ text: { content: titleText.slice(0, 200) } }],
+          },
+        },
+        children,
+      },
+      blocksCount: children.length,
+      title: titleText,
+      icon,
+    };
+  }
+  // pageId branch — append children only.
+  return {
+    kind: 'append',
+    url: `${NOTION_API_BASE}/blocks/${encodeURIComponent(pageId)}/children`,
+    body: { children },
+    blocksCount: children.length,
+    title: titleText,
+    icon,
+  };
+}
+
+/**
+ * Post the request to Notion. Exposed for unit tests so we can stub
+ * fetch + assert payload shape without going through token resolution.
+ *
+ * Notion's API uses POST for page creation and PATCH for children
+ * append — the `kind` field of the buildNotionPayload result tells us
+ * which method to use.
+ */
+export async function postToNotion({ token, kind, url, body }) {
+  const method = kind === 'append' ? 'PATCH' : 'POST';
+  const res = await fetch(url, {
+    method,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      'Notion-Version': NOTION_VERSION,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(body),
+  });
+  // Notion returns JSON for both success and error responses; the
+  // status code distinguishes. We parse defensively because a network
+  // proxy might return non-JSON on a 5xx.
+  const data = await res.json().catch(() => ({}));
+  if (res.status < 200 || res.status >= 300) {
+    // Map common status codes to friendly messages. The mapping below
+    // mirrors the Notion API docs:
+    //   401 unauthorized  — token revoked / wrong workspace
+    //   404 object_not_found — page/database not found OR bot not added
+    //   429 rate_limited
+    let msg;
+    if (res.status === 401)      msg = 'Notion rejected token';
+    else if (res.status === 404) msg = 'Notion page/database not found';
+    else if (res.status === 429) msg = 'Notion rate-limited';
+    else                          msg = data.message || `http ${res.status}`;
+    const err = new Error(`Notion API failed: ${msg}`);
+    err.code = data.code || `http_${res.status}`;
+    err.status = res.status;
+    throw err;
+  }
+  return data;
+}
+
+export const notifyNotionNode = {
+  name: 'notify_notion',
+  // Declares Notion as a hard requirement for marketplace gating —
+  // same pattern as notify-slack / notify-lark. See those for the
+  // rationale. The MCP notion tool isn't actually invoked here
+  // (custom-execute path); the declaration wires the gate only.
+  skills: [SKILLS.NOTION],
+  outputSchema: NotifyNotionOutputSchema,
+  // 20s — Notion's page-create can be slower than Slack/Lark when
+  // appending many children (each child block adds ~10ms server-side).
+  timeout: 20 * 1000,
+  execute: async (context) => {
+    // Custom-execute gets either the merged state object or the new
+    // {state, agent, ...} context wrapper. Normalize to a plain state.
+    const state = (context?.state && typeof context.state.getAll === 'function')
+      ? context.state.getAll()
+      : context;
+
+    const { databaseId, pageId } = state;
+    // Mutual exclusion: exactly one destination must be supplied. We
+    // check both directions explicitly so the error message points at
+    // the actual misconfiguration (rather than "Invalid input" from a
+    // zod refinement).
+    if (!databaseId && !pageId) {
+      throw new Error('notify-notion: must supply exactly one of input.databaseId or input.pageId');
+    }
+    if (databaseId && pageId) {
+      throw new Error('notify-notion: databaseId and pageId are mutually exclusive — pick one');
+    }
+    if (!state.report && !state.title) {
+      throw new Error('notify-notion: input.title is required when input.report is absent');
+    }
+
+    // Resolve the bot token. The cache inside resolveIntegrationToken
+    // means this is a single HTTP RTT the first time per process; later
+    // dispatches in the same Fargate task are zero-cost.
+    const { token } = await resolveIntegrationToken('notion');
+
+    const payload = buildNotionPayload(state);
+    const response = await postToNotion({
+      token,
+      kind: payload.kind,
+      url: payload.url,
+      body: payload.body,
+    });
+
+    // For the create-page branch, Notion returns the new page object
+    // (with `id` + `url`). For the append-children branch, the
+    // response is `{ object: 'list', results: [...blocks] }` and we
+    // already know the page id (the caller supplied it).
+    const resultPageId = payload.kind === 'page'
+      ? response.id
+      : pageId;
+    const resultPageUrl = payload.kind === 'page'
+      ? response.url
+      : undefined;
+
+    return {
+      delivered: true,
+      pageId: resultPageId,
+      pageUrl: resultPageUrl,
+      blocksCount: payload.blocksCount,
+    };
+  },
+};

package/notify-notion/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "notify-notion",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Post a structured page (or append blocks) to Notion — child workflow, dispatched by parent workflows via sub-graph.",
+  "main": "graph.mjs",
+  "scripts": {
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@zibby/core": "^0.5.1",
+    "@zibby/skills": "^0.1.25",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.5"
+  }
+}

package/notify-notion/state.js

@@ -0,0 +1,110 @@
+/**
+ * notify-notion — three-schema state model.
+ *
+ * Posts to Notion as either:
+ *   - a NEW page inside a database (`databaseId`), or
+ *   - APPENDED blocks on an existing page (`pageId`)
+ * EXACTLY ONE of these must be supplied. The execute path enforces
+ * mutual exclusion at runtime — we keep both fields optional at the
+ * schema level so the wire format degrades gracefully (e.g. when a
+ * parent workflow forgets to set one, the error message is clearer
+ * than a zod refinement failure on an unfamiliar field name).
+ *
+ * Mirrors notify-slack / notify-lark's provider-neutral envelope so a
+ * parent can fan-out the same alert to all three notifiers with a
+ * single `input: (state) => ({...})` block (swapping the target field
+ * per provider: `channel`, `receiveId`, or `pageId`/`databaseId`).
+ *
+ * Three schemas:
+ *   - notifyNotionInputSchema   — payload from the parent's
+ *                                  `dispatchSubgraph('notify-notion', { input: … })`
+ *   - notifyNotionContextSchema — runner-injected fields + node outputs
+ *   - notifyNotionStateSchema   — merge of the two (tests + tooling)
+ */
+
+import { z } from 'zod';
+
+export const SEVERITIES = /** @type {const} */ (['low', 'medium', 'high', 'critical']);
+
+export const notifyNotionInputSchema = z.object({
+  severity: z.enum(SEVERITIES)
+    .default('medium')
+    .describe('Alert severity. Drives legacy-mode page-icon emoji + decoration.'),
+
+  // Required in legacy-mode (severity/title/body alerts); rich-mode
+  // (when `report` is set) sources the title from `report.title`. The
+  // execute path enforces "at least one source of title" at runtime —
+  // see notify-slack/state.js for the symmetric design.
+  title: z.string().min(1).max(300).optional()
+    .describe('Page title. Required when `report` is absent (rich-mode sources from report.title).'),
+
+  body: z.string().max(3000).optional()
+    .describe('Body text. Rendered as a paragraph block in the page.'),
+
+  // ── Destination — EXACTLY ONE must be set ─────────────────────────
+  // We don't enforce mutual exclusion via zod refinement because the
+  // resulting error message ("Invalid input") is less helpful than the
+  // execute-path's typed runtime checks ("notify-notion: must supply
+  // exactly one of databaseId or pageId"). Schema-level validation is
+  // intentionally permissive on the wire.
+  databaseId: z.string().min(1).max(100).optional()
+    .describe('Notion database id to create a new page in (e.g. "abc123def...32hex"). Mutually exclusive with pageId.'),
+
+  pageId: z.string().min(1).max(100).optional()
+    .describe('Existing Notion page id to append blocks to. Mutually exclusive with databaseId.'),
+
+  // ── Sentry-flavored optional context (legacy-mode) ────────────────
+  // Same fields as notify-slack so a parent can dispatch a single
+  // payload to all three notifiers. notify-notion renders these as
+  // bulleted-list items in the page body when present.
+  sentryLink: z.string().url().optional()
+    .describe('Sentry issue URL — rendered as an embed/link in the page.'),
+  affectedUsers: z.number().int().min(0).optional(),
+  events: z.number().int().min(0).optional(),
+  release: z.string().max(120).optional(),
+  firstSeen: z.string().optional(),
+  codeSnippet: z.string().max(2000).optional()
+    .describe('Optional code snippet — rendered as a Notion `code` block.'),
+
+  actionUrl: z.string().url().optional(),
+  actionLabel: z.string().max(40).optional(),
+
+  // Mentions — Notion's mention syntax (`@user`) requires user UUIDs
+  // that don't survive serialization to a generic alert payload, so we
+  // pass through caller-supplied strings as plain text in a bulleted
+  // list. Useful for "cc'ing" team names without requiring the caller
+  // to resolve user IDs upfront.
+  mentions: z.array(z.string().max(200))
+    .max(20)
+    .optional()
+    .describe('Plain-text mentions, rendered as a "Notify" bulleted list at the bottom of the page.'),
+
+  idempotencyKey: z.string().max(128).optional(),
+
+  // ── Rich-report mode ──────────────────────────────────────────────
+  // When `report` is present, the node renders the report-object via
+  // reportToNotionBlocks() and IGNORES severity/title/body/sentryLink/etc.
+  // (those legacy fields are exclusively for the simple-alert path).
+  //
+  // The contract lives in @zibby/skills's reportObjectSchema. We
+  // declare it as record(any) on the wire so old runtimes that don't
+  // know about the field don't fail validation, and the actual
+  // structure is validated by reportToNotionBlocks at render time.
+  // New consumers should import reportObjectSchema from @zibby/skills
+  // for tighter typing.
+  report: z.record(z.any()).optional()
+    .describe('Rich report-object (see @zibby/skills/report). When set, supersedes severity/title/body — the node renders a full Notion blocks payload.'),
+});
+
+export const notifyNotionContextSchema = z.object({
+  notify_notion: z.object({
+    delivered: z.boolean(),
+    pageId: z.string(),
+    pageUrl: z.string().optional(),
+    blocksCount: z.number().int().optional(),
+  }).optional()
+    .describe('Output of the notify_notion node — set after dispatch completes.'),
+});
+
+export const notifyNotionStateSchema =
+  notifyNotionInputSchema.merge(notifyNotionContextSchema);

package/notify-slack/README.md

@@ -0,0 +1,94 @@
+# notify-slack
+
+A reusable **child workflow** that posts a structured Block Kit alert to a Slack channel.
+
+Designed to be dispatched via sub-graph from any parent workflow — most commonly the Sentry templates (`sentry-triage`, `sentry-autofix`, `sentry-incident`), but works anywhere you want a structured Slack message: cron summaries, deploy notifications, PR review pings, etc.
+
+## What it does
+
+- Takes a provider-neutral payload (severity, title, body, channel, optional Sentry-flavored fields)
+- Builds a Slack Block Kit message with severity-coded color + emoji + action buttons
+- Posts via `chat.postMessage` to the channel you specify
+- Returns the message timestamp so the parent can thread follow-ups
+
+No LLM call — single deterministic API request, typically <500ms.
+
+## Dispatch shape (parent workflow)
+
+```js
+import { WorkflowGraph, SKILLS } from '@zibby/core';
+
+const graph = new WorkflowGraph();
+
+graph.addNode('alert', {
+  workflow: 'notify-slack',
+  async: false,
+  input: (state) => ({
+    severity:      'critical',
+    title:         'Checkout: TypeError on session.user.id',
+    body:          '*12 users* affected in the last 1h. Likely regression from `1.42.0`.',
+    channel:       '#sentry-alerts',
+    sentryLink:    'https://sentry.io/.../1234567890/',
+    affectedUsers: 12,
+    events:        47,
+    release:       '1.42.0',
+    firstSeen:     '8 min ago',
+    codeSnippet:   'src/handlers/checkout.ts:142\nconst userId = session.user.id;',
+    mentions:      ['<!subteam^S0BACKEND>'],
+  }),
+  output: 'notify_slack.messageTs',  // capture the message ts for thread replies
+});
+```
+
+## Inputs
+
+| Field | Required | Description |
+|---|---|---|
+| `severity` | yes | `low \| medium \| high \| critical` — drives color + emoji |
+| `title` | yes | Headline (max 300 chars) |
+| `channel` | yes | Slack channel id (`C012345`) or `#name` |
+| `body` | no | mrkdwn body (max 3000 chars) |
+| `sentryLink` | no | Renders an "Open in Sentry" primary button |
+| `affectedUsers` | no | Renders in the metadata grid |
+| `events` | no | " |
+| `release` | no | " |
+| `firstSeen` | no | " |
+| `codeSnippet` | no | Renders as a fenced code block |
+| `actionUrl` + `actionLabel` | no | Secondary button (e.g. "View PR") |
+| `mentions` | no | Array of Slack mention strings appended in the context block |
+
+## Output
+
+```js
+{ delivered: true, channel: 'C012345', messageTs: '1716109330.123456', blocksCount: 5 }
+```
+
+The `messageTs` is what you pass back as `thread_ts` if you want to reply in-thread later (use case: incident-commander posting periodic updates).
+
+## Prerequisites
+
+The deploying project must have the **Slack** integration connected. Bot needs:
+- `chat:write` (post messages)
+- `chat:write.public` (optional — post to public channels the bot isn't a member of)
+
+## Severity → color
+
+| Severity | Hex | Emoji |
+|---|---|---|
+| low | `#7f8c8d` | ⚪ |
+| medium | `#f1c40f` | 🟡 |
+| high | `#e67e22` | 🟠 |
+| critical | `#c0392b` | 🚨 |
+
+## Tests
+
+```bash
+cd packages/workflow-templates/notify-slack
+npm test
+```
+
+Tests cover:
+- Block-Kit rendering for each severity
+- Conditional sections (omits fields/code/actions when input missing)
+- Slack API contract (mocked `fetch`)
+- Error mapping (channel_not_found, not_in_channel, network blip)

package/notify-slack/graph.mjs

@@ -0,0 +1,51 @@
+/**
+ * notify-slack — single-node child workflow.
+ *
+ * Designed to be dispatched as a sub-graph from parent workflows
+ * (sentry-triage, sentry-autofix, sentry-incident, etc.) via
+ *
+ *   g.addNode('notify', { workflow: 'notify-slack',
+ *     input: (state) => ({
+ *       severity: 'critical',
+ *       title:    'Checkout: TypeError',
+ *       body:     '12 users affected in last 1h',
+ *       channel:  '#sentry-alerts',
+ *       sentryLink: 'https://sentry.io/.../1234567890/',
+ *       affectedUsers: 12,
+ *     }),
+ *   });
+ *
+ * Returns `{ delivered, channel, messageTs }` — the parent typically
+ * stores `messageTs` if it wants to post follow-up replies as thread
+ * messages later (e.g. incident-commander posting progress updates).
+ */
+
+import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
+import { notifySlackNode } from './nodes/notify-slack-node.js';
+import {
+  notifySlackInputSchema,
+  notifySlackContextSchema,
+} from './state.js';
+
+export class NotifySlackAgent extends WorkflowAgent {
+  buildGraph() {
+    const graph = new WorkflowGraph();
+    graph
+      .setInputSchema(notifySlackInputSchema)
+      .setContextSchema(notifySlackContextSchema);
+
+    graph.addNode('notify_slack', notifySlackNode);
+    graph.setEntryPoint('notify_slack');
+    graph.addEdge('notify_slack', 'END');
+
+    return graph;
+  }
+
+  async onComplete(result) {
+    const delivered = !!result?.state?.notify_slack?.delivered;
+    const ts = result?.state?.notify_slack?.messageTs || '?';
+    console.log(`[notify-slack] ${delivered ? 'delivered' : 'failed'} (ts=${ts})`);
+  }
+}
+
+export default NotifySlackAgent;