@zibby/workflow-templates 0.2.1 → 0.4.1

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

@@ -0,0 +1,290 @@
+/**
+ * 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';
+
+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');
+    }
+    const receiveIdType = inferReceiveIdType(receiveId);
+
+    const { token, host } = await getTenantAccessToken();
+    const card = 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,75 @@
+/**
+ * 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.'),
+
+  title: z.string().min(1).max(300)
+    .describe('Card header text (Lark caps at ~100 chars; we truncate to 150).'),
+
+  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(),
+});
+
+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-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;