brains-mcp 1.61.2

package/dist/tools/suggestLinks.js

@@ -0,0 +1,214 @@
+import { z } from "zod";
+import { parsePage } from "../wiki/frontmatter.js";
+import { getPostgresSearchIndex } from "../search/postgresIndex.js";
+import { extractWikiLinks } from "../wiki/links.js";
+export const suggestLinksInputSchema = z.object({
+    tags: z
+        .array(z.string())
+        .optional()
+        .describe("Filter pages by tag (any match). At least one of tags or folder is required."),
+    folder: z
+        .string()
+        .optional()
+        .describe("Filter pages by name prefix (e.g. 'projects/brainsapp')."),
+    maxPages: z
+        .number()
+        .optional()
+        .describe("Maximum number of candidate pages to analyze for missing Related sections. Default 20, max 50."),
+});
+const MAX_SUGGESTIONS_PER_PAGE = 5;
+const DEFAULT_MAX_PAGES = 20;
+const HARD_MAX_PAGES = 50;
+function hasRelatedPagesSection(content) {
+    return /^## Related pages/im.test(content);
+}
+/** Priority score for display ordering: open-loop first, decisions second, canonical last. */
+function priorityScore(name) {
+    if (name.includes("open-loop"))
+        return 0;
+    if (/(?:^|\/)decisions\//.test(name))
+        return 1;
+    if (/(?:^|\/)canonical\//.test(name))
+        return 2;
+    return 3;
+}
+/** Build a root-relative wiki link path from a page name. */
+function pageToLink(name, title) {
+    const withoutExt = name.endsWith(".md") ? name.slice(0, -3) : name;
+    return `- [${title}](/${withoutExt})`;
+}
+/** Build the ## Related pages patch block for a page. */
+function buildPatch(suggestions) {
+    const links = suggestions.map((s) => pageToLink(s.name, s.title)).join("\n");
+    return `\n## Related pages\n\n${links}`;
+}
+export async function suggestLinks(drive, input, userId = "") {
+    const tags = (input.tags ?? []).map((t) => t.trim()).filter(Boolean);
+    const folder = input.folder?.trim();
+    if (tags.length === 0 && !folder) {
+        throw new Error("At least one filter is required: tags or folder");
+    }
+    const maxPages = Math.min(input.maxPages ?? DEFAULT_MAX_PAGES, HARD_MAX_PAGES);
+    const pgIndex = getPostgresSearchIndex();
+    const useGraph = pgIndex.isConfigured();
+    // ── Step 1: collect candidate page metadata ─────────────────────────────────
+    const candidatePages = [];
+    if (useGraph) {
+        // Single-tag fast path through Postgres
+        const rows = await pgIndex.listPages({
+            tag: tags.length === 1 ? tags[0] : undefined,
+            userId,
+        });
+        for (const r of rows) {
+            if (r.name === "index.md" || r.name === "log.md")
+                continue;
+            if (folder) {
+                const prefix = folder.endsWith("/") ? folder : `${folder}/`;
+                if (!r.name.startsWith(prefix))
+                    continue;
+            }
+            if (tags.length > 1 && !tags.some((t) => r.tags.includes(t)))
+                continue;
+            candidatePages.push({ name: r.name, title: r.title, summary: r.summary, tags: r.tags });
+        }
+    }
+    else {
+        // Storage scan fallback
+        const files = await drive.listFiles();
+        for (const file of files) {
+            if (!file.name.endsWith(".md"))
+                continue;
+            if (file.name === "index.md" || file.name === "log.md")
+                continue;
+            if (folder) {
+                const prefix = folder.endsWith("/") ? folder : `${folder}/`;
+                if (!file.name.startsWith(prefix))
+                    continue;
+            }
+            try {
+                const f = await drive.readFile(file.name);
+                const { frontmatter } = parsePage(f.content);
+                const pageTags = frontmatter.tags ?? [];
+                if (tags.length > 0 && !tags.some((t) => pageTags.includes(t)))
+                    continue;
+                candidatePages.push({
+                    name: file.name,
+                    title: String(frontmatter.title ?? file.name),
+                    summary: String(frontmatter.summary ?? ""),
+                    tags: pageTags,
+                });
+            }
+            catch {
+                // skip unparseable files
+            }
+        }
+    }
+    // Build a name→metadata lookup for suggestion resolution
+    const pageMap = new Map(candidatePages.map((p) => [p.name, p]));
+    // ── Step 2: sort by priority, then filter to those missing ## Related pages ──
+    candidatePages.sort((a, b) => priorityScore(a.name) - priorityScore(b.name) || a.name.localeCompare(b.name));
+    const toAnalyze = [];
+    for (const page of candidatePages) {
+        if (toAnalyze.length >= maxPages)
+            break;
+        let content;
+        try {
+            const f = await drive.readFile(page.name);
+            content = f.content;
+        }
+        catch {
+            continue;
+        }
+        if (hasRelatedPagesSection(content))
+            continue;
+        const existingLinks = new Set(extractWikiLinks(page.name, content).map((l) => l.target));
+        toAnalyze.push({ name: page.name, title: page.title, tags: page.tags, existingLinks });
+    }
+    // ── Step 3: resolve all unique page names referenced in graph suggestions ────
+    // Build a shared full-wiki metadata map (only if Postgres is available and we
+    // need to resolve page titles that are outside the candidate set).
+    let allPagesMap = null;
+    async function resolveTitle(name) {
+        const inCandidates = pageMap.get(name);
+        if (inCandidates)
+            return inCandidates;
+        if (useGraph) {
+            if (!allPagesMap) {
+                const rows = await pgIndex.listPages({ userId }).catch(() => []);
+                allPagesMap = new Map(rows.map((r) => [r.name, { title: r.title }]));
+            }
+            return allPagesMap.get(name) ?? null;
+        }
+        return null;
+    }
+    // ── Step 4: generate suggestions for each candidate ─────────────────────────
+    const patches = [];
+    for (const page of toAnalyze) {
+        const seen = new Set();
+        const suggestions = [];
+        if (useGraph) {
+            const [related, backlinks] = await Promise.all([
+                pgIndex.getRelatedPages(page.name, userId).catch(() => []),
+                pgIndex.getBacklinks(page.name, userId).catch(() => []),
+            ]);
+            for (const rel of related) {
+                if (suggestions.length >= MAX_SUGGESTIONS_PER_PAGE)
+                    break;
+                if (seen.has(rel) || rel === page.name || page.existingLinks.has(rel))
+                    continue;
+                const meta = await resolveTitle(rel);
+                if (meta) {
+                    suggestions.push({ name: rel, title: meta.title, reason: "shared context" });
+                    seen.add(rel);
+                }
+            }
+            for (const bl of backlinks) {
+                if (suggestions.length >= MAX_SUGGESTIONS_PER_PAGE)
+                    break;
+                if (seen.has(bl) || bl === page.name || page.existingLinks.has(bl))
+                    continue;
+                const meta = await resolveTitle(bl);
+                if (meta) {
+                    suggestions.push({ name: bl, title: meta.title, reason: "links here" });
+                    seen.add(bl);
+                }
+            }
+        }
+        // Tag-overlap fallback (runs in both modes; supplements graph results)
+        if (suggestions.length < MAX_SUGGESTIONS_PER_PAGE && page.tags.length > 0) {
+            for (const other of candidatePages) {
+                if (suggestions.length >= MAX_SUGGESTIONS_PER_PAGE)
+                    break;
+                if (seen.has(other.name) || other.name === page.name || page.existingLinks.has(other.name))
+                    continue;
+                const sharedTags = page.tags.filter((t) => other.tags.includes(t));
+                if (sharedTags.length > 0) {
+                    suggestions.push({
+                        name: other.name,
+                        title: other.title,
+                        reason: `shared tags: ${sharedTags.join(", ")}`,
+                    });
+                    seen.add(other.name);
+                }
+            }
+        }
+        if (suggestions.length > 0) {
+            patches.push({
+                page: page.name,
+                suggestedLinks: suggestions,
+                patch: buildPatch(suggestions),
+            });
+        }
+    }
+    const msg = patches.length === 0
+        ? "No link suggestions found. All analyzed pages either already have ## Related pages or no cross-references were identified."
+        : `Found ${patches.length} page(s) with link suggestions. Review each patch and apply with patch_page (append operation). No changes have been made — suggestions require explicit confirmation.`;
+    return {
+        pagesChecked: candidatePages.length,
+        pagesWithoutRelatedSection: toAnalyze.length,
+        pagesWithSuggestions: patches.length,
+        patches,
+        message: msg,
+    };
+}
+//# sourceMappingURL=suggestLinks.js.map

package/dist/tools/suggestLinks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggestLinks.js","sourceRoot":"","sources":["../../src/tools/suggestLinks.ts"],"names":[],"mappings":"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"}

package/dist/tools/updatePage.d.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import { type StorageClient } from "../storage/client.js";
+export declare const updatePageInputSchema: z.ZodObject<{
+    name: z.ZodString;
+    fileId: z.ZodString;
+    revision: z.ZodString;
+    body: z.ZodString;
+    frontmatterPatch: z.ZodOptional<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodUnknown>, Record<string, unknown>, unknown>>;
+    summary: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    fileId: string;
+    body: string;
+    name: string;
+    revision: string;
+    summary?: string | undefined;
+    frontmatterPatch?: Record<string, unknown> | undefined;
+}, {
+    fileId: string;
+    body: string;
+    name: string;
+    revision: string;
+    summary?: string | undefined;
+    frontmatterPatch?: unknown;
+}>;
+export type UpdatePageInput = z.infer<typeof updatePageInputSchema>;
+export declare function updatePage(drive: StorageClient, input: UpdatePageInput, userId?: string): Promise<object>;
+//# sourceMappingURL=updatePage.d.ts.map

package/dist/tools/updatePage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"updatePage.d.ts","sourceRoot":"","sources":["../../src/tools/updatePage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,KAAK,aAAa,EAA4B,MAAM,sBAAsB,CAAC;AAYpF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;EAYhC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,wBAAsB,UAAU,CAC9B,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,eAAe,EACtB,MAAM,SAAK,GACV,OAAO,CAAC,MAAM,CAAC,CA+GjB"}

package/dist/tools/updatePage.js

@@ -0,0 +1,118 @@
+import { z } from "zod";
+import { resolveIndexOwnerSubject } from "../storage/client.js";
+import { parsePage, serializePage } from "../wiki/frontmatter.js";
+import { getIngestRoutingWarnings } from "../wiki/ingestPolicy.js";
+import { normalizeWikiPath } from "../wiki/path.js";
+import { upsertIndexEntry } from "../wiki/index.js";
+import { appendLogEntry } from "../wiki/log.js";
+import { getPostgresSearchIndex } from "../search/postgresIndex.js";
+import { assertPageSize } from "../wiki/storageLimits.js";
+import { tryParseJson } from "./coerce.js";
+import { dispatchPageWebhook } from "../webhooks/dispatch.js";
+import { snapshotPage } from "./pageHistory.js";
+export const updatePageInputSchema = z.object({
+    name: z.string().describe("Relative path of the page to update (e.g. 'projects/my-topic.md')"),
+    fileId: z.string().describe("Drive file ID — must match the file you read"),
+    revision: z
+        .string()
+        .describe("Revision from your last read_page call — used for conflict detection"),
+    body: z.string().describe("New full markdown body (without frontmatter)"),
+    frontmatterPatch: z
+        .preprocess(tryParseJson, z.record(z.unknown()))
+        .optional()
+        .describe("Optional partial frontmatter overrides (e.g. {status: 'archived'})"),
+    summary: z.string().optional().describe("Updated one-line summary for the index"),
+});
+export async function updatePage(drive, input, userId = "") {
+    const normalizedName = normalizeWikiPath(input.name);
+    const pgIndex = getPostgresSearchIndex();
+    // Cross-account sharing (BRA-381): attribute index/webhook writes to the
+    // true storage owner, not the raw authenticated actor.
+    const indexOwner = resolveIndexOwnerSubject(drive, normalizedName, userId);
+    // Hot path: read from the Postgres row (authoritative when configured) —
+    // matches patchPage.ts. Also lets us compare input.revision against the
+    // *current* row instead of trusting a possibly-stale Storage mirror.
+    const dbRow = await pgIndex.fetchPageRow(normalizedName, indexOwner).catch(() => null);
+    const existing = dbRow ?? await drive.readFile(normalizedName);
+    if (dbRow && dbRow.revision !== input.revision) {
+        // Someone else wrote this page after our caller last read it — refuse
+        // the blind overwrite rather than silently clobbering their change.
+        return {
+            success: false,
+            conflict: true,
+            name: normalizedName,
+            reason: "Page was modified by someone else since your last read_page call. Call read_page again to see the current content, then retry with the new revision or a merged body.",
+            yourRevision: input.revision,
+            currentRevision: dbRow.revision,
+        };
+    }
+    const { frontmatter } = parsePage(existing.content);
+    const mergedFrontmatter = {
+        ...frontmatter,
+        ...(input.frontmatterPatch ?? {}),
+    };
+    const routingWarnings = getIngestRoutingWarnings({
+        name: normalizedName,
+        title: String(mergedFrontmatter.title ?? normalizedName),
+        tags: mergedFrontmatter.tags ?? [],
+        body: input.body,
+    });
+    const newContent = serializePage(mergedFrontmatter, input.body);
+    assertPageSize(userId, normalizedName, newContent);
+    // Validate the content actually about to be written — not the pre-merge
+    // content being replaced — so returned warnings describe what read_page
+    // will see afterward (GH #464).
+    const { warnings } = parsePage(newContent);
+    await snapshotPage(drive, normalizedName, existing.content);
+    const writeResult = await drive.updateFile(input.fileId, newContent, input.revision);
+    // Update Postgres index — best-effort. Stores the FULL serialized content
+    // (frontmatter included), matching patchPage.ts's DB-primary convention —
+    // read_page/patch_page read this column back as the complete file.
+    pgIndex.upsertPage(normalizedName, mergedFrontmatter, newContent, writeResult.revision, writeResult.modifiedTime, indexOwner).catch(() => { });
+    // Fire-and-forget: the link graph is a derived index, and nothing in this
+    // response depends on it. Awaiting it put three sequential Supabase round
+    // trips (~350-525ms) on the caller's critical path purely to decide whether
+    // to attach a cosmetic warning (GH #424). Staleness is self-healing —
+    // links_extracted_at drives extract_links' catch-up pass.
+    pgIndex
+        .syncPageLinks(normalizedName, input.body, indexOwner)
+        .catch((err) => {
+        console.warn(`[links] sync failed for '${normalizedName}'`, err instanceof Error ? err.message : err);
+    });
+    upsertIndexEntry(drive, {
+        name: normalizedName,
+        title: String(mergedFrontmatter.title ?? normalizedName),
+        summary: input.summary ?? String(mergedFrontmatter.summary ?? ""),
+        updated: new Date().toISOString().slice(0, 10),
+    }).catch(() => { });
+    appendLogEntry(drive, {
+        type: "update",
+        title: String(mergedFrontmatter.title ?? normalizedName),
+        detail: `Updated ${normalizedName}`,
+    }, indexOwner).catch((err) => {
+        // Surfaced rather than swallowed: a silent stop here is how an
+        // oversized log.md would go unnoticed (GH #417).
+        console.warn("[log] append failed:", err instanceof Error ? err.message : err);
+    });
+    // Dispatch outbound webhooks — fire-and-forget, never blocks the write
+    dispatchPageWebhook(indexOwner, "update", {
+        name: normalizedName,
+        title: String(mergedFrontmatter.title ?? normalizedName),
+        tags: mergedFrontmatter.tags ?? [],
+        summary: input.summary ?? String(mergedFrontmatter.summary ?? ""),
+        at: writeResult.modifiedTime ?? new Date().toISOString(),
+    });
+    return {
+        success: true,
+        name: normalizedName,
+        fileId: writeResult.fileId,
+        revision: writeResult.revision,
+        modifiedTime: writeResult.modifiedTime,
+        bytesWritten: Buffer.byteLength(newContent, "utf8"),
+        warnings: [
+            ...warnings.map((w) => ({ field: w.field, message: w.message })),
+            ...routingWarnings,
+        ],
+    };
+}
+//# sourceMappingURL=updatePage.js.map

package/dist/tools/updatePage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"updatePage.js","sourceRoot":"","sources":["../../src/tools/updatePage.ts"],"names":[],"mappings":"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"}

package/dist/webhooks/dispatch.d.ts

@@ -0,0 +1,49 @@
+/**
+ * dispatch.ts
+ *
+ * Outbound webhook dispatch: pattern matching (glob/regex) + HMAC-SHA256
+ * signing + async fire-and-forget HTTP POST.
+ *
+ * Design:
+ *  - One POST per matching rule per write operation (not per page).
+ *  - Never blocks or fails the originating write.
+ *  - Patterns are tested as minimatch globs first, then as RegExp.
+ */
+import { type WebhookRule } from "./webhookRules.js";
+export interface WebhookPayload {
+    event: "page.created" | "page.updated";
+    name: string;
+    title: string;
+    tags: string[];
+    summary: string;
+    at: string;
+}
+/**
+ * Returns true if `pageName` matches the given glob or regex pattern.
+ *
+ * Glob matching rules (subset of minimatch):
+ *   *  — any sequence of characters EXCEPT /
+ *   ** — any sequence including /
+ *   ?  — single character except /
+ *
+ * If the pattern is enclosed in /…/ it is treated as a regex.
+ */
+export declare function matchesPattern(pageName: string, pattern: string): boolean;
+/** Returns true if the rule matches the event and at least one pattern matches pageName. */
+export declare function ruleMatchesPage(rule: WebhookRule, event: "create" | "update", pageName: string): boolean;
+/**
+ * Fire webhooks for a single page write.  Async fire-and-forget — never throws.
+ */
+export declare function dispatchPageWebhook(userId: string, event: "create" | "update", payload: Omit<WebhookPayload, "event">): void;
+/**
+ * Fire webhooks for a bundle push (coalesced per rule).
+ * Accepts a list of (name, event) pairs and fires one POST per matching rule.
+ */
+export declare function dispatchBundleWebhooks(userId: string, pages: Array<{
+    name: string;
+    event: "create" | "update";
+    title: string;
+    tags: string[];
+    summary: string;
+}>): void;
+//# sourceMappingURL=dispatch.d.ts.map

package/dist/webhooks/dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../src/webhooks/dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAiC,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEpF,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,cAAc,GAAG,cAAc,CAAC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;CACZ;AAID;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAczE;AAuCD,4FAA4F;AAC5F,wBAAgB,eAAe,CAC7B,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,QAAQ,GAAG,QAAQ,EAC1B,QAAQ,EAAE,MAAM,GACf,OAAO,CAGT;AA6BD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,QAAQ,GAAG,QAAQ,EAC1B,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC,GACrC,IAAI,CAcN;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,GACzG,IAAI,CA0BN"}

package/dist/webhooks/dispatch.js

@@ -0,0 +1,159 @@
+/**
+ * dispatch.ts
+ *
+ * Outbound webhook dispatch: pattern matching (glob/regex) + HMAC-SHA256
+ * signing + async fire-and-forget HTTP POST.
+ *
+ * Design:
+ *  - One POST per matching rule per write operation (not per page).
+ *  - Never blocks or fails the originating write.
+ *  - Patterns are tested as minimatch globs first, then as RegExp.
+ */
+import { createHmac } from "crypto";
+import { getEnabledWebhookRulesForUser } from "./webhookRules.js";
+// ── Pattern matching ──────────────────────────────────────────────────────────
+/**
+ * Returns true if `pageName` matches the given glob or regex pattern.
+ *
+ * Glob matching rules (subset of minimatch):
+ *   *  — any sequence of characters EXCEPT /
+ *   ** — any sequence including /
+ *   ?  — single character except /
+ *
+ * If the pattern is enclosed in /…/ it is treated as a regex.
+ */
+export function matchesPattern(pageName, pattern) {
+    // Regex shorthand: /pattern/ or /pattern/flags
+    const regexMatch = /^\/(.+)\/([gimsuy]*)$/.exec(pattern);
+    if (regexMatch) {
+        try {
+            const re = new RegExp(regexMatch[1], regexMatch[2]);
+            return re.test(pageName);
+        }
+        catch {
+            return false;
+        }
+    }
+    // Glob matching — hand-rolled to avoid adding minimatch as a dep
+    return globMatch(pageName, pattern);
+}
+function globMatch(str, pattern) {
+    // Convert glob to regex
+    let reStr = "^";
+    let i = 0;
+    while (i < pattern.length) {
+        const ch = pattern[i];
+        if (ch === "*") {
+            if (pattern[i + 1] === "*") {
+                // ** — match everything including /
+                reStr += ".*";
+                i += 2;
+                // consume optional trailing /
+                if (pattern[i] === "/")
+                    i++;
+                continue;
+            }
+            // * — match anything except /
+            reStr += "[^/]*";
+            i++;
+            continue;
+        }
+        if (ch === "?") {
+            reStr += "[^/]";
+            i++;
+            continue;
+        }
+        // Escape regex special chars
+        reStr += ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+        i++;
+    }
+    reStr += "$";
+    try {
+        return new RegExp(reStr).test(str);
+    }
+    catch {
+        return false;
+    }
+}
+/** Returns true if the rule matches the event and at least one pattern matches pageName. */
+export function ruleMatchesPage(rule, event, pageName) {
+    if (!rule.events.includes(event))
+        return false;
+    return rule.patterns.some((p) => matchesPattern(pageName, p));
+}
+// ── HMAC signing ──────────────────────────────────────────────────────────────
+function signPayload(body, secret) {
+    return createHmac("sha256", secret).update(body).digest("hex");
+}
+// ── HTTP dispatch ─────────────────────────────────────────────────────────────
+async function sendWebhook(rule, payload) {
+    const body = JSON.stringify(payload);
+    const headers = {
+        "Content-Type": "application/json",
+        "User-Agent": "brains-webhooks/1.0",
+    };
+    if (rule.secret) {
+        headers["X-Brains-Signature"] = "sha256=" + signPayload(body, rule.secret);
+    }
+    await fetch(rule.url, {
+        method: "POST",
+        headers,
+        body,
+        signal: AbortSignal.timeout(10000),
+    });
+}
+// ── Public dispatch helpers ───────────────────────────────────────────────────
+/**
+ * Fire webhooks for a single page write.  Async fire-and-forget — never throws.
+ */
+export function dispatchPageWebhook(userId, event, payload) {
+    if (!userId)
+        return;
+    setImmediate(async () => {
+        try {
+            const rules = await getEnabledWebhookRulesForUser(userId);
+            for (const rule of rules) {
+                if (ruleMatchesPage(rule, event, payload.name)) {
+                    await sendWebhook(rule, { ...payload, event: event === "create" ? "page.created" : "page.updated" }).catch(() => { });
+                }
+            }
+        }
+        catch {
+            // non-fatal
+        }
+    });
+}
+/**
+ * Fire webhooks for a bundle push (coalesced per rule).
+ * Accepts a list of (name, event) pairs and fires one POST per matching rule.
+ */
+export function dispatchBundleWebhooks(userId, pages) {
+    if (!userId || pages.length === 0)
+        return;
+    const at = new Date().toISOString();
+    setImmediate(async () => {
+        try {
+            const rules = await getEnabledWebhookRulesForUser(userId);
+            for (const rule of rules) {
+                const matching = pages.filter((p) => ruleMatchesPage(rule, p.event, p.name));
+                if (matching.length === 0)
+                    continue;
+                // Coalesce: one POST per rule, payload = first matching page
+                const first = matching[0];
+                const webhookEvent = first.event === "create" ? "page.created" : "page.updated";
+                await sendWebhook(rule, {
+                    event: webhookEvent,
+                    name: first.name,
+                    title: first.title,
+                    tags: first.tags,
+                    summary: first.summary,
+                    at,
+                }).catch(() => { });
+            }
+        }
+        catch {
+            // non-fatal
+        }
+    });
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/webhooks/dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../../src/webhooks/dispatch.ts"],"names":[],"mappings":"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"}

package/dist/webhooks/webhookRules.d.ts

@@ -0,0 +1,34 @@
+/**
+ * webhookRules.ts
+ *
+ * Postgres CRUD for user-configured outbound webhook rules.
+ * Table schema: scripts/webhooks-migration.sql
+ */
+export interface WebhookRule {
+    id: string;
+    userId: string;
+    name: string;
+    url: string;
+    secret: string;
+    events: string[];
+    patterns: string[];
+    enabled: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+export declare function listWebhookRules(userId: string): Promise<WebhookRule[]>;
+export declare function getWebhookRule(id: string, userId: string): Promise<WebhookRule | null>;
+export declare function upsertWebhookRule(userId: string, rule: {
+    id?: string;
+    name: string;
+    url: string;
+    secret?: string;
+    events?: string[];
+    patterns?: string[];
+    enabled?: boolean;
+}): Promise<WebhookRule>;
+export declare function deleteWebhookRule(id: string, userId: string): Promise<boolean>;
+export declare function addPatternToRule(id: string, userId: string, pattern: string): Promise<WebhookRule | null>;
+/** Returns enabled rules for a user that have at least one pattern configured. */
+export declare function getEnabledWebhookRulesForUser(userId: string): Promise<WebhookRule[]>;
+//# sourceMappingURL=webhookRules.d.ts.map

package/dist/webhooks/webhookRules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhookRules.d.ts","sourceRoot":"","sources":["../../src/webhooks/webhookRules.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAkDD,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAc7E;AAED,wBAAsB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAW5F;AAED,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE;IACJ,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GACA,OAAO,CAAC,WAAW,CAAC,CA+BtB;AAED,wBAAsB,iBAAiB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUpF;AAED,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAS7B;AAED,kFAAkF;AAClF,wBAAsB,6BAA6B,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAG1F"}