@zibby/workflow-templates 0.3.0 → 0.4.2

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

@@ -0,0 +1,303 @@
+/**
+ * notify-lark node — deterministic, no LLM.
+ *
+ * Sends a Lark Interactive Card via /open-apis/im/v1/messages. Same
+ * design philosophy as notify-slack: parent makes all the decisions
+ * (severity, title, body, who to mention), this node just renders the
+ * card and POSTs it.
+ *
+ * Auth differs from Slack:
+ *   - resolveIntegrationToken('lark') returns { appId, appSecret, host }
+ *     not a ready-to-use bearer token.
+ *   - We exchange app credentials for a `tenant_access_token` via
+ *     /open-apis/auth/v3/tenant_access_token/internal, then use that as
+ *     Bearer auth on the message send. Same flow @zibby/skills/lark.js
+ *     uses; we reimplement here so the node stays decoupled from the
+ *     MCP-tool path (which only the LLM nodes use).
+ *
+ * The token has ~2h TTL — we cache per-process so a parent dispatching
+ * many alerts only pays the auth round-trip once.
+ *
+ * Severity → Lark header template (named themes, not hex):
+ *   low      → grey
+ *   medium   → yellow
+ *   high     → orange
+ *   critical → red
+ *
+ * The Lark API quirk: `content` on the message body must be a
+ * JSON-encoded STRING (not the object itself). Easy to miss.
+ */
+
+import { z } from 'zod';
+import { SKILLS } from '@zibby/core';
+import { resolveIntegrationToken } from '@zibby/core/backend-client.js';
+// Universal renderer — see notify-slack-node.js for the design note;
+// when state.report is present the legacy buildLarkCard path is bypassed.
+import { reportToLarkCard } from '@zibby/skills/report';
+
+const SEVERITY_TEMPLATE = Object.freeze({
+  low:      'grey',
+  medium:   'yellow',
+  high:     'orange',
+  critical: 'red',
+});
+
+const SEVERITY_EMOJI = Object.freeze({
+  low:      '⚪',
+  medium:   '🟡',
+  high:     '🟠',
+  critical: '🚨',
+});
+
+const NotifyLarkOutputSchema = z.object({
+  delivered: z.boolean(),
+  receiveId: z.string(),
+  receiveIdType: z.string(),
+  messageId: z.string().optional(),
+});
+
+/**
+ * Build the Lark Interactive Card body. Returns the card OBJECT (not
+ * the JSON-stringified form the API expects — callers stringify it).
+ * Exposed for unit tests so we can pin the rendered shape.
+ */
+export function buildLarkCard(input) {
+  const {
+    severity = 'medium',
+    title,
+    body,
+    sentryLink,
+    affectedUsers,
+    events,
+    release,
+    firstSeen,
+    codeSnippet,
+    actionUrl,
+    actionLabel,
+    mentions,
+  } = input;
+
+  const elements = [];
+
+  // Metadata grid — 2-column layout via `is_short: true` on each field.
+  const fields = [];
+  if (typeof affectedUsers === 'number') {
+    fields.push({
+      is_short: true,
+      text: { tag: 'lark_md', content: `**Users affected**\n${affectedUsers}` },
+    });
+  }
+  if (typeof events === 'number') {
+    fields.push({
+      is_short: true,
+      text: { tag: 'lark_md', content: `**Events**\n${events}` },
+    });
+  }
+  if (release) {
+    fields.push({
+      is_short: true,
+      text: { tag: 'lark_md', content: `**Release**\n\`${release}\`` },
+    });
+  }
+  if (firstSeen) {
+    fields.push({
+      is_short: true,
+      text: { tag: 'lark_md', content: `**First seen**\n${firstSeen}` },
+    });
+  }
+  if (fields.length > 0) {
+    elements.push({ tag: 'div', fields });
+  }
+
+  // Body — rendered as lark_md (Lark's markdown variant).
+  if (body && body.trim().length > 0) {
+    elements.push({
+      tag: 'div',
+      text: { tag: 'lark_md', content: body },
+    });
+  }
+
+  // Code snippet — fenced triple-backtick block.
+  if (codeSnippet) {
+    elements.push({
+      tag: 'div',
+      text: { tag: 'lark_md', content: '```\n' + codeSnippet + '\n```' },
+    });
+  }
+
+  // Action buttons — same logic as Slack: primary "Open in Sentry"
+  // when sentryLink set, plus secondary actionUrl/Label pair if both
+  // supplied.
+  const actions = [];
+  if (sentryLink) {
+    actions.push({
+      tag: 'button',
+      text: { tag: 'plain_text', content: 'Open in Sentry' },
+      type: 'primary',
+      url: sentryLink,
+    });
+  }
+  if (actionUrl && actionLabel) {
+    actions.push({
+      tag: 'button',
+      text: { tag: 'plain_text', content: actionLabel.slice(0, 40) },
+      type: 'default',
+      url: actionUrl,
+    });
+  }
+  if (actions.length > 0) {
+    elements.push({ tag: 'action', actions });
+  }
+
+  // Mentions — small-text note at bottom. Caller pre-formatted as
+  // `<at user_id="ou_xxx">@name</at>` strings.
+  if (Array.isArray(mentions) && mentions.length > 0) {
+    elements.push({
+      tag: 'note',
+      elements: [{ tag: 'lark_md', content: mentions.join(' ') }],
+    });
+  }
+
+  const emoji = SEVERITY_EMOJI[severity] || SEVERITY_EMOJI.medium;
+  const template = SEVERITY_TEMPLATE[severity] || SEVERITY_TEMPLATE.medium;
+
+  return {
+    config: { wide_screen_mode: true },
+    header: {
+      template,
+      title: {
+        tag: 'plain_text',
+        content: `${emoji} ${severity.toUpperCase()}  ${title}`.slice(0, 150),
+      },
+    },
+    elements,
+  };
+}
+
+/**
+ * Infer the Lark receive_id_type query param from the id prefix.
+ * Mirrors @zibby/skills/lark.js's inferReceiveIdType — duplicated to
+ * keep the node self-contained.
+ */
+export function inferReceiveIdType(id) {
+  if (!id || typeof id !== 'string') return 'chat_id';
+  if (id.startsWith('oc_')) return 'chat_id';
+  if (id.startsWith('ou_')) return 'open_id';
+  if (id.startsWith('on_')) return 'union_id';
+  if (id.startsWith('cli_')) return 'app_id';
+  if (id.includes('@')) return 'email';
+  return 'chat_id';
+}
+
+// Per-process cache. Tenant access tokens last ~2h; we cache 100m to
+// avoid the boundary case where a 119-min-old token is rejected mid-call.
+const TOKEN_TTL_MS = 100 * 60 * 1000;
+let _tenantTokenCache = null;
+
+async function getTenantAccessToken() {
+  const { appId, appSecret, host } = await resolveIntegrationToken('lark');
+  if (
+    _tenantTokenCache
+    && _tenantTokenCache.appId === appId
+    && _tenantTokenCache.expiresAt > Date.now()
+  ) {
+    return { token: _tenantTokenCache.token, host };
+  }
+  const url = `${host}/open-apis/auth/v3/tenant_access_token/internal`;
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ app_id: appId, app_secret: appSecret }),
+  });
+  const data = await res.json().catch(() => ({}));
+  if (data.code !== 0) {
+    const e = new Error(`Lark tenant_access_token failed: ${data.msg || data.code}`);
+    e.code = data.code;
+    throw e;
+  }
+  _tenantTokenCache = {
+    appId,
+    token: data.tenant_access_token,
+    expiresAt: Date.now() + TOKEN_TTL_MS,
+  };
+  return { token: data.tenant_access_token, host };
+}
+
+/** Test hook — resets the per-process token cache. */
+export function _resetTokenCache() { _tenantTokenCache = null; }
+
+/**
+ * Send the Lark card. Exposed for unit tests so we can stub fetch +
+ * assert payload shape without going through token resolution.
+ */
+export async function postToLark({ token, host, receiveId, receiveIdType, card }) {
+  const url = `${host}/open-apis/im/v1/messages?receive_id_type=${encodeURIComponent(receiveIdType)}`;
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${token}`,
+      'Content-Type': 'application/json; charset=utf-8',
+    },
+    body: JSON.stringify({
+      receive_id: receiveId,
+      msg_type: 'interactive',
+      // Lark wants `content` as a JSON-encoded STRING, not an object.
+      content: JSON.stringify(card),
+    }),
+  });
+  const data = await res.json().catch(() => ({}));
+  if (data.code !== 0) {
+    const e = new Error(`Lark send message failed: ${data.msg || `code ${data.code} / http ${res.status}`}`);
+    e.code = data.code || 'unknown';
+    e.status = res.status;
+    throw e;
+  }
+  return { messageId: data.data?.message_id };
+}
+
+export const notifyLarkNode = {
+  name: 'notify_lark',
+  // Declares Lark as a hard requirement for marketplace gating (same
+  // pattern as notify-slack — see that file's comment for rationale).
+  skills: [SKILLS.LARK],
+  outputSchema: NotifyLarkOutputSchema,
+  timeout: 15 * 1000,
+  execute: async (context) => {
+    const state = (context?.state && typeof context.state.getAll === 'function')
+      ? context.state.getAll()
+      : context;
+
+    const receiveId = state.receiveId;
+    if (!receiveId) {
+      throw new Error('notify-lark: input.receiveId is required');
+    }
+    if (!state.report && !state.title) {
+      throw new Error('notify-lark: input.title is required when input.report is absent');
+    }
+    const receiveIdType = inferReceiveIdType(receiveId);
+
+    const { token, host } = await getTenantAccessToken();
+    // Two rendering paths (symmetric with notify-slack):
+    //   1. state.report present → reportToLarkCard renders the full
+    //      structured digest. Legacy fields are ignored.
+    //   2. Legacy severity/title/body shape → buildLarkCard renders
+    //      the simple alert (sentry-triage et al.).
+    const card = (state.report && typeof state.report === 'object')
+      ? reportToLarkCard(state.report)
+      : buildLarkCard(state);
+    const { messageId } = await postToLark({
+      token,
+      host,
+      receiveId,
+      receiveIdType,
+      card,
+    });
+
+    return {
+      delivered: true,
+      receiveId,
+      receiveIdType,
+      messageId,
+    };
+  },
+};

package/notify-lark/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "notify-lark",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Post a structured alert card to a Lark / Feishu chat — child workflow, dispatched by parent workflows via sub-graph.",
+  "main": "graph.mjs",
+  "scripts": {
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@zibby/core": "^0.5.1",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.5"
+  }
+}

package/notify-lark/state.js

@@ -0,0 +1,85 @@
+/**
+ * notify-lark — three-schema state model.
+ *
+ * Mirrors notify-slack's input shape EXACTLY (provider-neutral fields)
+ * so a parent workflow that wants to fan-out alerts to both Slack and
+ * Lark can use the same `input: (state) => ({...})` block for both
+ * dispatchSubgraph calls. The notifier-specific bits (`receiveId` vs
+ * `channel`, mention syntax) are caller-supplied; we don't try to
+ * translate between providers.
+ *
+ * Lark differences vs Slack:
+ *   - Target is `receiveId` (chat_id `oc_…`, open_id `ou_…`, or email)
+ *     — Lark needs the right `receive_id_type` query param, inferred
+ *     from the id prefix.
+ *   - Color is a theme template name (`red`, `orange`, `yellow`, `grey`,
+ *     `purple`, `green`), not a hex.
+ *   - Mention syntax: `<at user_id="ou_xxx">name</at>` — caller passes
+ *     these strings ready-formatted, same as Slack.
+ */
+
+import { z } from 'zod';
+
+export const SEVERITIES = /** @type {const} */ (['low', 'medium', 'high', 'critical']);
+
+export const notifyLarkInputSchema = z.object({
+  severity: z.enum(SEVERITIES)
+    .default('medium')
+    .describe('Alert severity. Drives header color + mention strategy.'),
+
+  // Required in legacy-mode; rich-mode (when `report` is set) sources
+  // the title from `report.title` instead. See notify-slack/state.js
+  // for the symmetric design.
+  title: z.string().min(1).max(300).optional()
+    .describe('Card header text. Required when `report` is absent (rich-mode sources from report.title).'),
+
+  body: z.string().max(3000).optional()
+    .describe('Body text. Supports Lark lark_md (e.g. **bold**, `code`, [text](url)).'),
+
+  receiveId: z.string().min(1).max(120)
+    .describe(
+      'Lark target. Format determines receive_id_type automatically:\n' +
+      '  oc_…  → chat_id (group/DM)\n' +
+      '  ou_…  → open_id (user)\n' +
+      '  on_…  → union_id\n' +
+      '  email → email',
+    ),
+
+  // Sentry-flavored fields (same shape as notify-slack).
+  sentryLink: z.string().url().optional()
+    .describe('Sentry issue URL — adds an "Open in Sentry" primary button.'),
+  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(),
+  actionUrl: z.string().url().optional(),
+  actionLabel: z.string().max(40).optional(),
+
+  // Mentions — caller-supplied Lark <at> strings.
+  mentions: z.array(z.string().max(200))
+    .max(20)
+    .optional()
+    .describe('Lark @-mentions, e.g. [\'<at user_id="ou_alice">@Alice</at>\'].'),
+
+  idempotencyKey: z.string().max(128).optional(),
+
+  // ── Rich-report mode ──────────────────────────────────────────────
+  // When `report` is present, the node renders the report-object via
+  // reportToLarkCard() and IGNORES the legacy severity/title/body
+  // fields. See notify-slack/state.js for the symmetric design.
+  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 Lark Card.'),
+});
+
+export const notifyLarkContextSchema = z.object({
+  notify_lark: z.object({
+    delivered: z.boolean(),
+    receiveId: z.string(),
+    receiveIdType: z.string(),
+    messageId: z.string().optional(),
+  }).optional(),
+});
+
+export const notifyLarkStateSchema =
+  notifyLarkInputSchema.merge(notifyLarkContextSchema);

package/notify-notion/README.md

@@ -0,0 +1,71 @@
+# notify-notion
+
+A reusable **child workflow** that posts a structured page (or appends blocks) to a Notion workspace.
+
+Designed to be dispatched via sub-graph from any parent workflow — most commonly digest workflows (`ai-spend-weekly-digest`) that want to archive a weekly report to a Notion database, or alert workflows (`sentry-triage`) that want a durable record of each incident.
+
+## What it does
+
+- Takes a provider-neutral payload (severity, title, body, target, optional Sentry-flavored fields)
+- Builds a Notion page (or block-children array) — including rich-report mode that delegates to `@zibby/skills/report`'s `reportToNotionBlocks`
+- Posts via `POST /v1/pages` (when `databaseId` is supplied) or `PATCH /v1/blocks/{pageId}/children` (when `pageId` is supplied)
+- Returns the page id + URL so the parent can link to it from downstream notifications
+
+No LLM call — single deterministic API request, typically ~1-2s depending on block count.
+
+## Dispatch shape (parent workflow)
+
+```js
+import { WorkflowGraph, SKILLS } from '@zibby/core';
+
+const g = new WorkflowGraph();
+g.addNode('archive_to_notion', {
+  workflow: 'notify-notion',
+  input: (state) => ({
+    // Either databaseId OR pageId — not both:
+    databaseId: process.env.NOTION_INCIDENT_DB,
+    severity: 'critical',
+    title: 'Checkout: TypeError on session.user.id',
+    body: '12 users affected in the last 1h.',
+    sentryLink: 'https://sentry.io/.../1234567890/',
+    affectedUsers: 12,
+    events: 47,
+    release: '1.42.0',
+  }),
+});
+```
+
+For digest workflows, pass a `report` object instead of severity/title/body — the node renders the full structured page via `reportToNotionBlocks`:
+
+```js
+g.addNode('archive_digest', {
+  workflow: 'notify-notion',
+  input: (state) => ({
+    databaseId: process.env.NOTION_REPORTS_DB,
+    report: state.analyze.report,  // produced by an upstream digest node
+  }),
+});
+```
+
+## Output
+
+```ts
+{
+  delivered: boolean,
+  pageId: string,
+  pageUrl?: string,    // only set on the create branch (Notion returns it)
+  blocksCount?: number // diagnostic — how many blocks were posted
+}
+```
+
+## Auth
+
+The bot's OAuth token is resolved via `resolveIntegrationToken('notion')`. Connect your workspace in **Settings → Integrations → Notion** in the Zibby dashboard before running.
+
+## Failure modes
+
+- **401** — Notion rejected the token (revoked, or wrong workspace).
+- **404** — Page/database not found, OR the Notion integration isn't added to the target page (Notion's quirk — share the page with the integration explicitly).
+- **429** — Rate-limited. The parent should backoff + retry.
+
+All three surface as typed errors with `.status` set; the parent's `onComplete` sees a failed execution row and can re-dispatch.

package/notify-notion/graph.mjs

@@ -0,0 +1,64 @@
+/**
+ * notify-notion — single-node child workflow.
+ *
+ * Companion to notify-slack / notify-lark; same provider-neutral input
+ * shape so a parent can dispatch the same payload to all three (just
+ * swap the destination field: `channel` → `receiveId` → `databaseId`
+ * or `pageId`).
+ *
+ * Two write modes:
+ *   - Create a NEW page in a database     (`input.databaseId` set)
+ *   - APPEND blocks to an existing page   (`input.pageId` set)
+ * Exactly one must be supplied — the node throws clearly if neither
+ * or both are present.
+ *
+ * Returns `{ delivered, pageId, pageUrl, blocksCount }`. The `pageUrl`
+ * is only populated on the create-page branch (Notion returns the URL
+ * in the response); appended pages reuse the caller-supplied pageId.
+ *
+ * Example dispatch shape (parent workflow):
+ *
+ *   g.addNode('notify', { workflow: 'notify-notion',
+ *     input: (state) => ({
+ *       severity: 'critical',
+ *       title:    'Checkout: TypeError',
+ *       body:     '12 users affected in last 1h',
+ *       databaseId: 'abc123...',   // create new page in this DB
+ *       sentryLink: 'https://sentry.io/.../1234567890/',
+ *     }),
+ *   });
+ *
+ * For digest / report workflows, drop the legacy severity/title/body
+ * fields and pass a `report` object instead — the node delegates to
+ * @zibby/skills's reportToNotionBlocks() for the full structured page.
+ */
+
+import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
+import { notifyNotionNode } from './nodes/notify-notion-node.js';
+import {
+  notifyNotionInputSchema,
+  notifyNotionContextSchema,
+} from './state.js';
+
+export class NotifyNotionAgent extends WorkflowAgent {
+  buildGraph() {
+    const graph = new WorkflowGraph();
+    graph
+      .setInputSchema(notifyNotionInputSchema)
+      .setContextSchema(notifyNotionContextSchema);
+
+    graph.addNode('notify_notion', notifyNotionNode);
+    graph.setEntryPoint('notify_notion');
+    graph.addEdge('notify_notion', 'END');
+
+    return graph;
+  }
+
+  async onComplete(result) {
+    const delivered = !!result?.state?.notify_notion?.delivered;
+    const pageId = result?.state?.notify_notion?.pageId || '?';
+    console.log(`[notify-notion] ${delivered ? 'delivered' : 'failed'} (pageId=${pageId})`);
+  }
+}
+
+export default NotifyNotionAgent;