@zibby/workflow-templates 0.4.1 → 0.4.2

package/index.js

@@ -255,6 +255,57 @@ export const TEMPLATES = {
     },
   },
 
+  // ── notify-notion: same as notify-slack/-lark, Notion variant ────
+  // Two write modes: create a new page in a database, or append blocks
+  // to an existing page. Rich-mode delegates to
+  // @zibby/skills/report's reportToNotionBlocks. See notify-notion/README.md.
+  'notify-notion': {
+    name: 'notify-notion',
+    displayName: 'Notify Notion',
+    description: 'Reusable child workflow — creates a Notion page in a database OR appends blocks to an existing page. Dispatched by other workflows (digest, incident archives, weekly reports) via sub-graph.',
+    path: join(__dirname, 'notify-notion'),
+    defaultSlug: 'archive-notion',
+    deps: { zod: '^3.23.0', '@zibby/skills': '^0.1.25' },
+    features: [
+      'Single-node, no LLM — deterministic ~1-2s Notion REST call',
+      'Two write modes: create page in database OR append children to existing page',
+      'Rich-mode renders report objects via @zibby/skills/report (heading, callouts, tables, trend code blocks)',
+      'Legacy-mode renders simple severity / title / body alerts (sentry-triage et al.)',
+      'Severity-mapped page-icon emoji (low/medium/high/critical or rich-mode delta severity)',
+      'Surfaces typed errors for 401 (token revoked), 404 (target not shared with bot), 429 (rate-limited)',
+      'Returns pageId + pageUrl for downstream linkage from notify-slack / notify-lark messages',
+    ],
+    marketplace: {
+      slug: 'notify-notion',
+      tagline: 'Reusable Notion archiver — durable record for any workflow.',
+      iconPrompt: [
+        'Hand-painted gouache illustration with soft brushwork and gentle painterly texture, in the same family as the sentry-triage and generate-test-cases marketplace icons but with its own distinct character.',
+        'Subject: a friendly anthropomorphic notebook-document mascot — a small rounded notebook character with two big smiling eyes and a rosy blush, its open pages showing three painted horizontal ink-lines and a tiny checkmark in the corner. A soft halo of two or three little pastel page-flutter sparkles dance around it, suggesting a freshly-written entry being archived.',
+        'Background: a pale neutral Notion-flavored off-white gradient — warm cream at the top blending into a soft dove-grey at the base (#F7F3EC → #E8E4DA), with a single faint paper-grain texture and a couple of small floating pastel ink-spot dots for friendliness.',
+        'Centered composition with the notebook character as the focal point in the lower-center, sparkles arcing across the upper third; plenty of breathing room so the silhouette reads at 64×64 in the marketplace grid.',
+        'Mood is calm, archival, gently studious — the friendly notebook companion that keeps a tidy record, NOT corporate productivity or wall-of-text database.',
+        'Soft rounded square 1024×1024 canvas with a subtle paper-grain texture.',
+        'NO text, NO logo or trademarked marks, NO photo-realism, NO sleek 3D render, NO literal Notion trademark.',
+      ].join('\n'),
+      category: 'Operations',
+      tags: ['notion', 'docs', 'reporting', 'knowledge-base', 'archive'],
+      capabilities: [
+        'Create a new page in a Notion database (POST /v1/pages)',
+        'Append blocks to an existing page (PATCH /v1/blocks/{pageId}/children)',
+        'Renders rich report-objects to native Notion blocks (headings, callouts, tables, code, embeds)',
+        'Severity-mapped page-icon emoji + colored callout backgrounds',
+        'Sub-graph dispatchable from any parent workflow',
+        'Maps 401 / 404 / 429 to typed errors so callers can react cleanly',
+      ],
+      conversationStarters: [
+        'Archive the weekly digest to our Notion reports database',
+        'Append today\'s incident summary to the on-call runbook page',
+        'Create a Notion page for every new Sentry CRITICAL',
+        'Drop the deploy-summary into our engineering Notion every Friday',
+      ],
+    },
+  },
+
   // ── sentry-triage: parent workflow that uses notify-slack/-lark ──
   'sentry-triage': {
     name: 'sentry-triage',
@@ -301,6 +352,54 @@ export const TEMPLATES = {
         'Page on-call when a CRITICAL error appears in checkout',
       ],
     },
+  },
+
+  // ── ai-spend-weekly-digest: cross-silo billing digest ─────────────
+  'ai-spend-weekly-digest': {
+    name: 'ai-spend-weekly-digest',
+    displayName: 'AI Spend Weekly Digest',
+    description: 'Weekly digest of OpenAI / Anthropic / Cursor admin billing — pulls trailing-28d cost+usage across all three providers, detects per-project anomalies vs 3-week baseline, and posts a rich report card to Lark and/or Slack via in-process sub-graph dispatch.',
+    path: join(__dirname, 'ai-spend-weekly-digest'),
+    defaultSlug: 'ai-spend-weekly-digest',
+    deps: { zod: '^3.23.0', '@zibby/skills': '^0.1.25' },
+    features: [
+      '3-node graph: fetch_spending → analyze (LLM narrative) → dispatch_digest',
+      'Parallel admin-API fetch via Promise.allSettled — one provider down doesn\'t kill the run',
+      'Customer attribution via OpenAI project / Anthropic workspace / Cursor user metadata (no manual mapping required)',
+      'Anomaly detection over per-key σ + ratio fallback — flags spend spikes vs 3-week baseline',
+      'Renders to native Slack Block-Kit / Lark Card via reportToBlockKit / reportToLarkCard — zero chart-image dependency',
+      'Parallel sub-graph dispatch to notify-slack + notify-lark (~5ms in-process overhead)',
+      'Cron-friendly: weekly schedule, default Monday 08:00 local',
+    ],
+    marketplace: {
+      slug: 'ai-spend-weekly-digest',
+      tagline: 'Track and explain your OpenAI / Anthropic / Cursor spending — every Monday morning, in Lark or Slack.',
+      iconPrompt: [
+        'Hand-painted gouache illustration with soft brushwork and gentle painterly texture, featuring a friendly chubby pastel-pink piggy-bank character with two big smiling eyes and rosy blush, its body marked with a soft glowing dollar-sign sigil; the piggy is gently cradling a small stack of three coloured coins floating just above its back — a sky-blue coin for OpenAI-ish, a warm violet coin for Anthropic-ish, and a soft mint-green coin for Cursor-ish — each coin painted in the same loose gouache style with no logos or text on them, just abstract round chips.',
+        'A thin painterly trend-line ribbon arcs gently upward behind the piggy from lower-left to upper-right, suggesting "money over time", rendered as a soft watercolor ribbon in dusty rose with a tiny gentle peak near the top right.',
+        'Background is a calm sunrise gradient of pale buttercream at the top blending through soft peach into a gentle wash of pale mint at the base, with a few small pastel clouds for friendliness.',
+        'Centered composition with the piggy as the immediate focal point in the lower-center, the floating coins arcing across the upper third, the trend ribbon as background scaffolding; plenty of breathing room so the silhouette reads at 64×64.',
+        'Mood is warm, optimistic, gently informative — feels like a thoughtful finance friend, NOT corporate spreadsheet, NOT alarmist red.',
+        'Soft rounded square 1024×1024 canvas with a subtle paper-grain texture.',
+        'NO text, NO letters, NO numbers, NO photo-realism, NO sleek 3D render, NO chart axes or grid lines, NO dark navy or near-black backgrounds, NO literal OpenAI / Anthropic / Cursor logos or wordmarks, NO bar charts.',
+      ].join('\n'),
+      category: 'Operations',
+      tags: ['cost', 'finance', 'reporting', 'openai', 'anthropic', 'cursor', 'digest', 'weekly'],
+      capabilities: [
+        'Pulls org-wide cost+usage from OpenAI, Anthropic, and Cursor admin APIs in parallel',
+        'Joins customer attribution from provider-native project / workspace / member metadata',
+        'Detects per-project anomalies (σ + ratio) against a 3-week rolling baseline',
+        'Drafts the leadership-grade narrative with an LLM, falls back to deterministic copy if model is unavailable',
+        'Posts a rich Block-Kit / Lark Card report (trend bars, top spenders table, anomalies, provider breakdown)',
+        'Fan-out to Lark + Slack in parallel — partial-failure resilient',
+      ],
+      conversationStarters: [
+        'Run a weekly AI spend digest every Monday morning',
+        'Tell me which OpenAI projects spiked spending this week',
+        'Compare Anthropic spend vs the 3-week baseline',
+        'Post the digest to our #leadership Lark group + #eng Slack channel',
+      ],
+    },
   }
 };
 

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

@@ -31,6 +31,9 @@
 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',
@@ -268,10 +271,20 @@ export const notifyLarkNode = {
     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();
-    const card = buildLarkCard(state);
+    // 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,

package/notify-lark/state.js

@@ -27,8 +27,11 @@ export const notifyLarkInputSchema = z.object({
     .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).'),
+  // 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)).'),
@@ -60,6 +63,13 @@ export const notifyLarkInputSchema = z.object({
     .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({

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;

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/nodes/notify-slack-node.js

@@ -37,6 +37,11 @@
 import { z } from 'zod';
 import { SKILLS } from '@zibby/core';
 import { resolveIntegrationToken } from '@zibby/core/backend-client.js';
+// reportToBlockKit lives in @zibby/skills (universal renderer for any
+// destination). When the parent passes a `report` object, we delegate
+// rendering entirely; the legacy severity/title/body path is unchanged
+// for sentry-triage and other callers still on the simple shape.
+import { reportToBlockKit } from '@zibby/skills/report';
 
 const SEVERITY_COLORS = Object.freeze({
   low:      '#7f8c8d',
@@ -215,17 +220,42 @@ export const notifySlackNode = {
     if (!channel) {
       throw new Error('notify-slack: input.channel is required');
     }
+    if (!state.report && !state.title) {
+      throw new Error('notify-slack: 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('slack');
 
-    const blocks = buildSlackBlocks(state);
-    // Plain-text fallback — Slack renders this in mobile push
-    // notifications when blocks are absent. Severity + title is the
-    // most useful summary in <100 chars.
-    const text = `${(state.severity || 'medium').toUpperCase()}: ${state.title}`.slice(0, 200);
+    // Two rendering paths:
+    //   1. Rich `report` object (digest workflows like
+    //      ai-spend-weekly-digest) → reportToBlockKit produces the full
+    //      structured card. The plain-text fallback is sourced from
+    //      report.title (best summary for mobile push).
+    //   2. Legacy severity/title/body shape (sentry-triage et al.) →
+    //      buildSlackBlocks renders the simple alert card.
+    //
+    // The two paths are mutually exclusive at runtime; `report` wins
+    // if both are present (a misconfiguration the parent shouldn't do,
+    // but we resolve it predictably rather than mixing the outputs).
+    let blocks;
+    let text;
+    if (state.report && typeof state.report === 'object') {
+      blocks = reportToBlockKit(state.report);
+      const title = state.report.title || 'Report';
+      const headline = state.report.headline?.primary
+        ? `: ${state.report.headline.primary}`
+        : '';
+      text = `${title}${headline}`.slice(0, 200);
+    } else {
+      blocks = buildSlackBlocks(state);
+      // Plain-text fallback — Slack renders this in mobile push
+      // notifications when blocks are absent. Severity + title is the
+      // most useful summary in <100 chars.
+      text = `${(state.severity || 'medium').toUpperCase()}: ${state.title}`.slice(0, 200);
+    }
 
     const result = await postToSlack({ token, channel, blocks, text });
     return {

package/notify-slack/state.js

@@ -27,8 +27,12 @@ export const notifySlackInputSchema = z.object({
     .default('medium')
     .describe('Alert severity. Drives color + mention strategy.'),
 
-  title: z.string().min(1).max(300)
-    .describe('Short one-line headline (renders in the Slack header).'),
+  // Required in legacy-mode (severity/title/body alerts from sentry-triage
+  // and friends). In rich-mode (when `report` is set), title is sourced
+  // from `report.title` so the top-level field is optional. The execute
+  // path enforces "at least one source of title" at runtime.
+  title: z.string().min(1).max(300).optional()
+    .describe('Short one-line headline (renders in the Slack header). Required when `report` is absent.'),
 
   body: z.string().max(3000).optional()
     .describe('Body text. Supports Slack mrkdwn (e.g. *bold*, `code`, <url|text>).'),
@@ -76,6 +80,21 @@ export const notifySlackInputSchema = z.object({
   // the output for thread replies later.
   idempotencyKey: z.string().max(128).optional()
     .describe('Caller-supplied dedup key. The node still posts; idempotency is the parent\'s job today.'),
+
+  // ── Rich-report mode ──────────────────────────────────────────────
+  // When `report` is present, the node renders the report-object via
+  // reportToBlockKit() and IGNORES severity/title/body/sentryLink/etc.
+  // (those legacy fields are exclusively for the simple-alert path
+  // used by sentry-triage et al.).
+  //
+  // Schema validation is intentionally permissive here — the contract
+  // lives in @zibby/skills's reportObjectSchema. We declare it as a
+  // free-form object on the wire so old runtimes that don't know about
+  // the field don't fail validation, and the actual structure is
+  // validated by reportToBlockKit 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 Block-Kit card.'),
 });
 
 export const notifySlackContextSchema = z.object({

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zibby/workflow-templates",
-  "version": "0.4.1",
-  "description": "Built-in workflow templates for Zibby — browser-test-automation, code-analysis, generate-test-cases, notify-slack, notify-lark, sentry-triage.",
+  "version": "0.4.2",
+  "description": "Built-in workflow templates for Zibby — browser-test-automation, code-analysis, generate-test-cases, notify-slack, notify-lark, notify-notion, sentry-triage.",
   "type": "module",
   "main": "index.js",
   "exports": {
@@ -19,8 +19,12 @@
     "./notify-slack/*": "./notify-slack/*",
     "./notify-lark": "./notify-lark/graph.mjs",
     "./notify-lark/*": "./notify-lark/*",
+    "./notify-notion": "./notify-notion/graph.mjs",
+    "./notify-notion/*": "./notify-notion/*",
     "./sentry-triage": "./sentry-triage/graph.mjs",
     "./sentry-triage/*": "./sentry-triage/*",
+    "./ai-spend-weekly-digest": "./ai-spend-weekly-digest/graph.mjs",
+    "./ai-spend-weekly-digest/*": "./ai-spend-weekly-digest/*",
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -50,6 +54,7 @@
     "generate-test-cases/",
     "notify-slack/",
     "notify-lark/",
+    "notify-notion/",
     "sentry-triage/",
     "index.js",
     "register-nodes.js",