@open-everywhere/provider-notion 0.1.0

package/dist/agent/channels/notion-api.js

@@ -0,0 +1,938 @@
+// Pure Notion webhook + REST helpers — the testable core behind the Notion comment
+// surface (notion.ts). Everything here is either a pure function over a payload/string or
+// a thin REST call with an INJECTABLE `fetch` (defaults to global fetch), so the whole
+// inbound→reply loop can be unit-tested against a mock Notion API with no live calls.
+//
+// The loop this backs (see notion.ts for the wiring):
+//   webhook  → verify HMAC (verifyNotionSignature) / handle the one-time handshake
+//   comment.created is a SIGNAL ONLY (no text/mentions on the event) →
+//     retrieveComment(entity.id) → richText → mentionsUser(botUserId)?  → dispatch
+//   model reply → createCommentReply(discussionId) back into the SAME thread
+//
+// Signature scheme (Notion Docs — Webhooks): every delivery carries
+//   X-Notion-Signature: sha256=<hex>
+// which is HMAC-SHA256 of the EXACT RAW request body, keyed by the `verification_token`
+// Notion issued once at subscription time (echoed to the endpoint, then a permanent
+// signing secret). It MUST be computed over the bytes as they arrived — re-serialising the
+// parsed JSON produces different bytes and fails verification — so notion.ts reads
+// `req.text()` and hands that raw string here untouched.
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { getSecretVia, CredentialError, findConnectorCredential, guardCredentialFetch, withRetryAfter, } from "@open-everywhere/core/agent/adapter-api.js";
+import { NOTION_CHANNEL_CREDENTIAL, NOTION_PROVIDER } from "./notion-credentials.js";
+/** Notion REST base + the API version header value (override via NOTION_VERSION). The
+ *  default is a stable version that supports the comment retrieve/create endpoints and
+ *  rich-text `mention` objects — everything this surface needs. */
+export const NOTION_API_BASE = "https://api.notion.com";
+function notionVersion() {
+    const v = process.env.NOTION_VERSION;
+    return v && v.trim().length > 0 ? v.trim() : "2022-06-28";
+}
+/**
+ * File uploads are a NEWER Notion API surface than the rest of this module. Notion's own docs
+ * (developers.notion.com/reference/create-a-file-upload, confirmed live 2026-08-23) name
+ * `2026-03-11` as the only accepted `Notion-Version` for the file-upload endpoints — the
+ * deployment's regular {@link notionVersion} (default `2022-06-28`, override via NOTION_VERSION)
+ * covers the comment/page/block surface this module already calls and does not carry file uploads.
+ * So {@link createFileUpload}, {@link sendFileUploadBytes}, and a create-comment call that attaches
+ * files all pin THIS version, rather than inheriting a caller's `opts.version` — a deployment that
+ * pins an older NOTION_VERSION for its comment traffic must not also break its attachment traffic.
+ */
+const NOTION_FILE_UPLOAD_VERSION = "2026-03-11";
+/**
+ * THE ONLY way to resolve a Notion channel credential — the key together with its endpoint rules.
+ * Fail-closed exactly as before: `undefined` for an unregistered provider, a credential carrying no
+ * `secretRef`, or a broker that resolves no value. A named-but-missing credential NEVER retries
+ * under the org default.
+ *
+ * WHY THE PAIR IS THE UNIT. A credential's endpoint rules are a property OF THAT KEY. Resolving the
+ * key through one function and the rules through another invites exactly the drift the rules exist
+ * to catch: a call site that threads the key from credential A and the rules from credential B has
+ * a fence that permits the leak it was written to block. Returning them together removes that
+ * failure mode by construction rather than by review.
+ */
+export async function resolveNotionCredential(credentialId = NOTION_CHANNEL_CREDENTIAL) {
+    const cred = findConnectorCredential(NOTION_PROVIDER, credentialId);
+    // Unregistered provider / non-secretRef credential = unconfigured — identical to the env being
+    // unset. Return undefined; do NOT fall back to a process.env / env-broker pin.
+    if (!cred?.secretRef)
+        return undefined;
+    try {
+        const k = await getSecretVia(cred.broker, cred.secretRef);
+        return k.length > 0 ? { apiKey: k, endpoints: cred.endpoints } : undefined;
+    }
+    catch (err) {
+        if (err instanceof CredentialError)
+            return undefined;
+        throw err;
+    }
+}
+// --- webhook verification ---------------------------------------------------
+/**
+ * The one-time subscription handshake: when a webhook subscription is created, Notion POSTs
+ * `{ "verification_token": "secret_…" }` (and nothing else — no `type`/`event_type`) to the
+ * endpoint. Return that token so the route can LOG it (the operator pastes it back into
+ * Notion's UI to confirm the endpoint, and stores it as NOTION_WEBHOOK_SECRET — the HMAC
+ * key for every subsequent delivery). Returns null for a normal event payload.
+ */
+export function parseVerificationHandshake(rawBody) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawBody);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object")
+        return null;
+    const o = parsed;
+    const token = o.verification_token;
+    // Only a bare handshake (has the token, carries no event discriminator) qualifies.
+    if (typeof token === "string" && token.length > 0 && o.type === undefined && o.event_type === undefined) {
+        return token;
+    }
+    return null;
+}
+/**
+ * Verify a Notion webhook's HMAC-SHA256 signature (`X-Notion-Signature: sha256=<hex>`)
+ * against the verification token, over the RAW body. Constant-time compare. Mirrors
+ * routines/events.ts's verifyGithubSignature (same scheme, different header/secret).
+ */
+export function verifyNotionSignature(secret, rawBody, signatureHeader) {
+    if (!signatureHeader)
+        return false;
+    const expected = "sha256=" + createHmac("sha256", secret).update(rawBody, "utf8").digest("hex");
+    const a = Buffer.from(signatureHeader);
+    const b = Buffer.from(expected);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+/**
+ * Gate an inbound Notion delivery FAIL-CLOSED. No configured secret means the sender can't
+ * be authenticated, so the delivery is REJECTED — this route dispatches agent sessions, and
+ * accepting unsigned payloads would let anyone on the internet drive the bot. The dev escape
+ * hatch `webhooks.allowUnverifiedNotion` restores unverified acceptance for local smoke
+ * tests. Returns null when the delivery may proceed, else the one-line 401 rejection reason.
+ * (Same shape/posture as gateGithubDelivery.)
+ */
+export function gateNotionDelivery(secret, rawBody, signatureHeader, allowUnverified) {
+    if (!secret) {
+        return allowUnverified
+            ? null
+            : "NOTION_WEBHOOK_SECRET is not set — rejecting unverified delivery (set the verification token, or turn on webhooks.allowUnverifiedNotion in agent/settings/settings.ts for local dev)";
+    }
+    return verifyNotionSignature(secret, rawBody, signatureHeader) ? null : "invalid signature";
+}
+/**
+ * Gate an inbound delivery against EVERY configured Notion integration (OPE-467) — the
+ * multi-integration form of {@link gateNotionDelivery}, and the whole of the ingress-routing answer.
+ *
+ * An operator running ten Notion integrations has ten `verification_token`s, and a delivery from
+ * integration #7 cannot verify against integration #1's secret. So the gate tries each in turn and
+ * THE SECRET THAT VERIFIES IDENTIFIES THE SENDER. That is a proof, not an inference: nothing in the
+ * payload is consulted, so no field a caller controls can steer the routing. Trying N keys is the
+ * same shape `webhooks/secrets.ts` already uses for a rotation window, and each comparison stays
+ * constant-time (`verifyNotionSignature` → `timingSafeEqual`).
+ *
+ * Same fail-closed posture as the single-secret gate, with the same wording for the same case:
+ *   • NO integration has a stored secret ⇒ reject, unless the dev hatch is on (and then `verified`
+ *     is false, so the delivery still may not reach the routing plane);
+ *   • at least one secret configured, none verifies ⇒ "invalid signature".
+ */
+export function gateNotionDeliveryAcross(keys, rawBody, signatureHeader, allowUnverified) {
+    const configured = keys.filter((k) => typeof k.secret === "string" && k.secret.length > 0);
+    if (configured.length === 0) {
+        const rejection = gateNotionDelivery(undefined, rawBody, signatureHeader, allowUnverified);
+        return { rejection, verified: false };
+    }
+    for (const key of configured) {
+        if (verifyNotionSignature(key.secret, rawBody, signatureHeader)) {
+            return { rejection: null, credentialId: key.credentialId, verified: true };
+        }
+    }
+    return { rejection: "invalid signature", verified: false };
+}
+/** The event discriminator, tolerating both the `type` and `event_type` spellings. */
+export function notionEventType(ev) {
+    return ev.type ?? ev.event_type;
+}
+/** The comment id a `comment.created` event points at — it lives on `entity` (a signal only;
+ *  the comment TEXT is not on the event), not on `data`. Returns undefined if the entity
+ *  isn't a comment (defensive: never dispatch off a mis-shaped event). */
+export function commentIdFromEvent(ev) {
+    const e = ev.entity;
+    if (e && e.type === "comment" && typeof e.id === "string" && e.id.length > 0)
+        return e.id;
+    return undefined;
+}
+/**
+ * The page a `comment.created` event CLAIMS to be anchored on (data.page_id, else data.parent.id).
+ *
+ * 🔴 A CLAIM, NOT A FACT — nothing authenticates a webhook body's fields, and `data.parent.id` is a
+ * block id as often as a page id. It must never select a session's surface, its domain, or a
+ * credential on a VERIFIED delivery: `notion-webhook.ts` step 8 establishes the real page from the
+ * comment Notion returns under the verifying integration's own key instead (OPE-496). The one
+ * remaining caller is the `webhooks.allowUnverifiedNotion` dev hatch, where the gate identifies
+ * no integration and nothing at all has been proven.
+ */
+export function pageIdFromEvent(ev) {
+    return ev.data?.page_id ?? ev.data?.parent?.id;
+}
+/** Flatten a comment's rich_text to plain text (concatenated `plain_text`). */
+export function richTextToPlainText(richText) {
+    if (!Array.isArray(richText))
+        return "";
+    return richText.map((r) => (typeof r.plain_text === "string" ? r.plain_text : "")).join("").trim();
+}
+/**
+ * Detect whether the comment @mentions a specific user id. A Notion @mention is a rich-text
+ * item `{ type:"mention", mention:{ type:"user", user:{ id } } }`; an @mention of an
+ * integration/agent appears as a user mention whose id is the integration's own bot-user id.
+ * So "was the bot mentioned?" = does any mention item's `mention.user.id` equal the bot's
+ * user id (resolveBotUserId). Returns false for an empty id (never dispatch on an
+ * unresolved bot identity — fail closed to "not mentioned").
+ */
+export function mentionsUser(richText, userId) {
+    if (!userId || !Array.isArray(richText))
+        return false;
+    return richText.some((r) => r.type === "mention" && r.mention?.type === "user" && r.mention.user?.id === userId);
+}
+/**
+ * The 429 policy for a call the WEBHOOK INGRESS awaits before it acks Notion (OPE-1254).
+ *
+ * 🔴 THE ARITHMETIC, AGAINST A MEASURED CEILING. `handleNotionDelivery` is awaited before the route
+ * acks, and it fires about 15 calls in sequence: `retrieveBotUser`, `retrieveComment`, up to five
+ * `retrieveBlock` parent hops, `listBlockComments`, and the ancestry walk's `notionParentLink`. On
+ * the shared defaults — 4 attempts, a 30 s per-wait cap, a 60 s budget PER CALL — a rate-limit
+ * episode costs that delivery up to ~15 minutes. The deployed Notion route runs on the INGRESS
+ * function, whose `maxDuration` is 300 s (measured on OPE-1289, `docs/extending/provider-rate-limits.md`
+ * § "Measured: the function maxDuration against the backoff"). So the shared policy does not make
+ * the delivery slow — it makes the function get killed mid-sequence, which is a DROPPED delivery.
+ *
+ * This policy spends at most one 2 s wait per call — `maxAttempts: 2` allows one, and the cap binds
+ * before the 4 s budget can, which is left in place for a later edit that raises the attempts. So
+ * the whole ~15-call sequence spends at most ~30 s of backoff and leaves ~270 s of the ingress
+ * ceiling for the work itself. Every one of those calls is covered: the four `deliver` issues
+ * directly, through `ingressCallOpts`, and `retrieveBotUser` behind `deps.resolveBotUserId`, which
+ * `notion.ts` passes this same policy (it is awaited FIRST, ahead of them all). It is Slack's answer to the
+ * same problem (`slack-web-api.ts`'s `PROBE_OPERATIONS`, 2 attempts / 2 s cap for the calls its
+ * 3-second ack awaits), with the total budget stated too so the arithmetic closes rather than
+ * resting on the shared 60 s.
+ *
+ * ⚠️ IT IS PER CALL, NOT PER DELIVERY. A shared budget consumed ACROSS the sequence is the stronger
+ * shape and it is a change to the shared primitive every provider inherits — still open on OPE-1254.
+ * What this bounds is the worst case, and it bounds it under the ceiling.
+ */
+export const NOTION_INGRESS_RETRY = {
+    maxAttempts: 2,
+    capMs: 2_000,
+    totalBudgetMs: 4_000,
+};
+function notionHeaders(opts) {
+    return {
+        authorization: `Bearer ${opts.apiKey}`,
+        "notion-version": opts.version ?? notionVersion(),
+        "content-type": "application/json",
+    };
+}
+/**
+ * The vendor operation name a Notion request carries into {@link RateLimitExhaustedError} — the
+ * request's method plus its endpoint SHAPE, with every id segment replaced by `{id}`.
+ *
+ * 🔴 THE REDACTION IS THE POINT, not tidiness. `RateLimitExhaustedError` states that every field on
+ * it is safe to log, and this string is one of those fields. A raw Notion path carries page, block
+ * and comment ids, which name workspace content — so the shape goes in the failure and the ids stay
+ * out of it. `/v1/comments/abc…` becomes `GET /v1/comments/{id}`.
+ *
+ * The query string is dropped whole for the same reason: `?block_id=…` is an id too.
+ *
+ * Every url this is handed is built from a literal in this file, save one: {@link sendFileUploadBytes}
+ * posts to the `upload_url` Notion itself issued. A value that does not parse as a URL falls back to
+ * the method alone. Naming the method is honest; guessing a path from a string that is not a URL is
+ * not.
+ */
+export function notionOperation(method, url) {
+    const verb = (method ?? "GET").toUpperCase();
+    let path;
+    try {
+        path = new URL(url).pathname;
+    }
+    catch {
+        return verb;
+    }
+    const shape = path
+        .split("/")
+        // A Notion id is a UUID, sent with or without its dashes. Anything else — `v1`, `comments`,
+        // `me`, `children` — is a fixed segment and stays readable.
+        .map((seg) => (/^[0-9a-f]{32}$/i.test(seg.replaceAll("-", "")) ? "{id}" : seg))
+        .join("/");
+    return `${verb} ${shape}`;
+}
+/**
+ * THE ONE PLACE a Notion REST call leaves this host. Every helper below dispatches through here, so
+ * the credential's endpoint fence ({@link NotionCallOpts.endpoints}) is applied on every path
+ * without each call site remembering to.
+ *
+ * Funnelling matters more than the guard itself: a fence applied at six call sites is a fence a
+ * seventh call site will not have. With one funnel, a new helper is fenced the moment it is written.
+ *
+ * THE 429 BACKOFF RIDES THE SAME FUNNEL (OPE-1233). Notion answers a rate-limited call with HTTP 429
+ * and a `Retry-After` header, and nothing here read it before: the first refusal became whatever
+ * `${caller} failed: 429 …` message the helper throws, so a reply was simply lost. `withRetryAfter`
+ * now honours that delay with bounded attempts and a bounded total wait, and then throws the NAMED
+ * `RateLimitExhaustedError`. Every non-429 answer — a 2xx, a 404, a 5xx — comes back untouched, and
+ * a transport throw still propagates unretried (the request may have applied; repeating it could
+ * double a comment).
+ *
+ * ORDER MATTERS: the fence wraps the transport and the retry wraps the fence, so `guardCredentialFetch`
+ * re-checks the URL on EVERY attempt rather than once before the first.
+ *
+ * 🔴 THE BUDGET IS PER CALL, AND A PATH THAT FIRES A SEQUENCE PAYS IT ONCE EACH. The webhook ingress
+ * fires about 15 calls in sequence and now passes {@link NOTION_INGRESS_RETRY}, which bounds the
+ * whole sequence to ~30 s under that function's 300 s ceiling (OPE-1254). `readNotionComments` does
+ * NOT: it sweeps up to ~82 blocks at the shared 60 s per call, so ~82 minutes worst case, on the turn
+ * function's 800 s ceiling. That one is still open on OPE-1254.
+ * 🔴 AND `maxCommentPages` MULTIPLIES THAT NUMBER (OPE-1831). Each anchor may now cost up to that
+ * many list calls rather than one, so a caller passing 5 — the seat catch-up does — raises the same
+ * worst case about fivefold. It is a CEILING, not a cost: the follow stops the moment Notion reports
+ * no more, so every anchor under 100 comments is still exactly one call and the multiplier is paid
+ * only by an anchor that genuinely overflows. Reaching the ceiling needs all ~82 anchors to overflow
+ * at once, which no real page does.
+ * {@link NotionCallOpts.retry} is the seam a caller uses to tighten its own path.
+ * `docs/extending/provider-rate-limits.md` carries the table.
+ *
+ * A RETRY RE-SENDS `init` UNCHANGED, which is safe for every body this module builds: a JSON string,
+ * and {@link sendFileUploadBytes}'s `FormData` over a `Blob`. Both are values `fetch` re-serialises
+ * per call, not streams a first attempt would consume. A body that WAS a stream could not be replayed
+ * — do not introduce one here without giving `send` a fresh body per attempt.
+ */
+function notionFetch(url, init, opts) {
+    const base = opts.fetch ?? globalThis.fetch;
+    const send = guardCredentialFetch(opts.endpoints, "notion credential", base);
+    return withRetryAfter(() => send(url, init), {
+        ...opts.retry,
+        surface: "notion",
+        operation: notionOperation(init.method, url),
+    });
+}
+/** GET /v1/comments/{comment_id} — the second step of the two-step (webhook signal → fetch
+ *  the actual comment body + discussion id + author). Throws on a non-2xx response. */
+export async function retrieveComment(commentId, opts) {
+    const res = await notionFetch(`${NOTION_API_BASE}/v1/comments/${encodeURIComponent(commentId)}`, {
+        method: "GET",
+        headers: notionHeaders(opts),
+    }, opts);
+    if (!res.ok)
+        throw new Error(`retrieveComment ${commentId} failed: ${res.status} ${await safeText(res)}`);
+    return (await res.json());
+}
+/** GET /v1/users/me — the integration's own bot user: its `id` (the loop-guard self-identity)
+ *  AND its `name` (the display name a person types in a name-drop — a judge input, never a
+ *  bypass; design §2.2/Step 4). Resolved once and cached by the channel; env NOTION_BOT_USER_ID /
+ *  NOTION_BOT_NAME short-circuit these — but the ID override applies to the ORG-DEFAULT `channel-key`
+ *  credential ONLY (OPE-1921: two Notion integrations never share a bot user, so one pinned id
+ *  cannot stand for a sibling's, and pinning it for every credential would reopen the
+ *  cross-integration loop). Throws on a non-2xx response. */
+export async function retrieveBotUser(opts) {
+    const res = await notionFetch(`${NOTION_API_BASE}/v1/users/me`, { method: "GET", headers: notionHeaders(opts) }, opts);
+    if (!res.ok)
+        throw new Error(`retrieveBotUser failed: ${res.status} ${await safeText(res)}`);
+    return (await res.json());
+}
+/** GET /v1/comments?block_id=… — list unresolved comments on a page/block, for surrounding
+ *  thread context (best-effort). Returns the raw results array (caller filters by
+ *  discussion + renders untrusted). Throws on a non-2xx response.
+ *
+ *  🔴 NOTION SERVES THIS ENDPOINT OLDEST-FIRST AND PAGINATED, AND ONE PAGE IS THE OLDEST 100
+ *  (OPE-1831). A single unpaginated call therefore reads the anchor's FIRST hundred comments and can
+ *  never reach a comment posted today — which is not a partial read on a long-lived anchor, it is a
+ *  read that structurally cannot answer "what was said since the seat last looked". A PAGE-ANCHORED
+ *  discussion on any long-lived doc is unreachable this way.
+ *  🔴 THIS IS NOT WHAT RED `J-ENGAGED-notion` ON SHIP #208 — do not carry that story forward. That
+ *  journey's comment sits in a BLOCK-anchored discussion, which a page query never returns however
+ *  many pages it follows; the cause there was `readNotionComments`' comment CAP ending the sweep
+ *  before the block walk began (see that function, and `notion-catch-up.ts`). This bound is a real
+ *  and separate one, closed while the file was open.
+ *
+ *  `maxPages` bounds the follow. It DEFAULTS TO 1 — the single call every existing caller already
+ *  made — so a caller that wants the newest comments asks for the pages, and no other read changes
+ *  its cost. The loop stops the moment Notion reports no more, so even at a high `maxPages` an anchor
+ *  with under 100 comments still costs exactly one call.
+ *  🔴 `onPageLimit` FIRES WHEN THE BOUND CUT THE ANCHOR OFF — Notion still had more and this stopped
+ *  asking. Without it a page-limited anchor is indistinguishable from a complete read, so
+ *  {@link readNotionComments} would report `truncated: false` over a read it knows was partial, and
+ *  the coverage disclosure the model sees would be a false claim. A callback rather than a changed
+ *  return type, so the eight existing call sites are untouched. */
+export async function listBlockComments(blockId, opts) {
+    const maxPages = Math.max(1, Math.trunc(opts.maxPages ?? 1));
+    const out = [];
+    let cursor;
+    for (let page = 0; page < maxPages; page++) {
+        const qs = new URLSearchParams({ block_id: blockId, page_size: "100" });
+        if (cursor)
+            qs.set("start_cursor", cursor);
+        const res = await notionFetch(`${NOTION_API_BASE}/v1/comments?${qs.toString()}`, {
+            method: "GET",
+            headers: notionHeaders(opts),
+        }, opts);
+        if (!res.ok)
+            throw new Error(`listBlockComments ${blockId} failed: ${res.status} ${await safeText(res)}`);
+        const body = (await res.json());
+        if (Array.isArray(body.results))
+            out.push(...body.results);
+        cursor = body.has_more && body.next_cursor ? body.next_cursor : undefined;
+        if (!cursor)
+            break;
+        // Notion has more and this was the last page the bound allows ⇒ the read is PARTIAL, and the
+        // caller is told rather than handed a short list that looks complete.
+        if (page === maxPages - 1)
+            opts.onPageLimit?.();
+    }
+    return out;
+}
+/** GET /v1/blocks/{block_id} — used ONLY to answer "which page owns this block?" for the domain
+ *  fence (channels/notion-scope.ts). Throws on a non-2xx response. */
+export async function retrieveBlock(blockId, opts) {
+    const res = await notionFetch(`${NOTION_API_BASE}/v1/blocks/${encodeURIComponent(blockId)}`, { method: "GET", headers: notionHeaders(opts) }, opts);
+    if (!res.ok)
+        throw new Error(`retrieveBlock ${blockId} failed: ${res.status} ${await safeText(res)}`);
+    return (await res.json());
+}
+/**
+ * The PAGE that owns a block — walk `parent` upward until a `page_id`, or give up. The domain fence
+ * needs it because `readNotionComments`' `block` drill-in addresses a block DIRECTLY (it never
+ * touches the `pageId` argument), so without this a block id is an unfenced way into another
+ * domain's page. Bounded at {@link BLOCK_PARENT_MAX_HOPS} hops — the realistic case is ONE (the
+ * sweep only ever surfaces top-level blocks, whose parent IS the page) and an unbounded walk over
+ * attacker-chosen ids is its own problem.
+ *
+ * Returns `undefined` when the chain ends anywhere other than a page (a workspace/database parent),
+ * runs out of hops, or the lookup throws — every one of which the caller must treat as a REFUSAL,
+ * never as permission.
+ */
+export const BLOCK_PARENT_MAX_HOPS = 5;
+export async function resolveBlockOwningPage(blockId, opts) {
+    let id = blockId;
+    for (let hop = 0; hop < BLOCK_PARENT_MAX_HOPS; hop++) {
+        let block;
+        try {
+            block = await retrieveBlock(id, opts);
+        }
+        catch {
+            return undefined; // an id the integration can't see resolves to nothing ⇒ the caller refuses
+        }
+        const parent = block.parent;
+        if (parent?.type === "page_id" && parent.page_id)
+            return parent.page_id;
+        if (parent?.type === "block_id" && parent.block_id && parent.block_id !== id) {
+            id = parent.block_id;
+            continue;
+        }
+        return undefined;
+    }
+    return undefined;
+}
+/** GET /v1/pages/{page_id} — used ONLY to answer "what owns this page?" for the ancestor walk
+ *  (channels/notion-ancestry-trust.ts). Throws on a non-2xx response. */
+export async function retrievePage(pageId, opts) {
+    const res = await notionFetch(`${NOTION_API_BASE}/v1/pages/${encodeURIComponent(pageId)}`, { method: "GET", headers: notionHeaders(opts) }, opts);
+    if (!res.ok)
+        throw new Error(`retrievePage ${pageId} failed: ${res.status} ${await safeText(res)}`);
+    return (await res.json());
+}
+/**
+ * GET /v1/pages/{page_id}, read for the page's own DISPLAY IDENTITY — its title and its canonical
+ * Notion url (OPE-1714).
+ *
+ * The title is the same `properties`-by-type extraction a search hit takes ({@link notionItemTitle}),
+ * because a page's title property is named by whoever made the page and can only be found by type.
+ * The url is Notion's own `url` field, never assembled here from an id.
+ *
+ * 🔴 FAIL-SOFT, AND SEPARATE FROM THE READ IT DECORATES. A page body read must not fail because this
+ * extra call did, so every error answers an empty identity and the caller renders the page without a
+ * title or a link. Both fields are UNTRUSTED: a workspace member chooses the title.
+ */
+export async function readNotionPageIdentity(pageId, opts) {
+    try {
+        const res = await notionFetch(`${NOTION_API_BASE}/v1/pages/${encodeURIComponent(pageId)}`, { method: "GET", headers: notionHeaders(opts) }, opts);
+        if (!res.ok)
+            return {};
+        const page = (await res.json());
+        const title = notionItemTitle(page);
+        return {
+            ...(title.length > 0 ? { title } : {}),
+            ...(typeof page.url === "string" && page.url.length > 0 ? { url: page.url } : {}),
+        };
+    }
+    catch {
+        return {};
+    }
+}
+/** Map a raw Notion `parent` object onto the closed union the ancestor walk decides over. An
+ *  unrecognised shape maps to `unresolvable`, never to `workspace` — "we do not know what owns this"
+ *  and "this sits at the workspace root" are different answers and only one of them ends a walk
+ *  cleanly. `data_source_id` is the 2025-09-03 spelling of a row's database parent; both map to
+ *  `database`, which is where the walk stops. */
+export function toNotionParentLink(parent) {
+    if (!parent)
+        return { kind: "unresolvable" };
+    if (parent.type === "page_id" && parent.page_id)
+        return { kind: "page", pageId: parent.page_id };
+    if (parent.type === "block_id" && parent.block_id)
+        return { kind: "block", blockId: parent.block_id };
+    if (parent.type === "database_id" && parent.database_id)
+        return { kind: "database", databaseId: parent.database_id };
+    if (parent.type === "data_source_id" && parent.data_source_id)
+        return { kind: "database", databaseId: parent.data_source_id };
+    if (parent.type === "workspace")
+        return { kind: "workspace" };
+    return { kind: "unresolvable" };
+}
+/**
+ * What owns `id` — the live `parentOf` the ancestor walk injects (channels/notion-ancestry-trust.ts).
+ *
+ * A PAGE first (`GET /v1/pages/{id}`), because the walk starts on a page id and every level above a
+ * nested page is a page too. A page id that Notion will not serve as a page falls back to the BLOCK
+ * endpoint, which is how a page nested inside a column or a toggle keeps its chain walkable. Both
+ * failing is `unresolvable`, which the walk treats as a refusal — this function NEVER throws, so a
+ * Notion outage degrades to "not trusted" instead of to an exception on the ingestion path.
+ */
+export async function notionParentLink(id, opts) {
+    try {
+        return toNotionParentLink((await retrievePage(id, opts)).parent);
+    }
+    catch {
+        // fall through to the block endpoint
+    }
+    try {
+        return toNotionParentLink((await retrieveBlock(id, opts)).parent);
+    }
+    catch {
+        return { kind: "unresolvable" };
+    }
+}
+/** Flatten ONE raw comment into the read shape. Exported (OPE-988) so the read adapter's cheap
+ *  page-level path maps a `listBlockComments` result the SAME way the sweep does — two spellings of
+ *  one flatten is how an author field goes missing on one path only. */
+export function toNotionCommentSummary(c, fallbackAnchor, anchorText) {
+    return {
+        ...(c.id === undefined ? {} : { id: c.id }),
+        discussionId: c.discussion_id,
+        anchorId: c.parent?.block_id ?? c.parent?.page_id ?? fallbackAnchor,
+        ...(anchorText !== undefined && anchorText.length > 0 ? { anchorText } : {}),
+        authorId: c.created_by?.id,
+        authorKind: c.created_by?.type,
+        createdTime: c.created_time,
+        text: richTextToPlainText(c.rich_text),
+    };
+}
+/**
+ * Read a Notion page's comments + inline discussions, bounded. When `block` is given, reads ONLY
+ * that block's discussion (one list call — the cheap drill-in). Otherwise sweeps the page's own
+ * comments then walks its top-level blocks (≤ `maxBlockScans`, default 80) listing each block's
+ * comments, stopping once `maxComments` (default 100) is collected. `blockScanOrder` decides WHICH
+ * `maxBlockScans` blocks a page past that cap spends the budget on — the page's first by default,
+ * its last under `"newest-first"` (OPE-1843). Returns the flattened comments
+ * (oldest-first per anchor), the distinct-discussion count, the number of blocks scanned, and
+ * `truncated` (a cap bit, or Notion still had more blocks). Comment bodies are UNTRUSTED — the
+ * caller wraps them. Pure over the injectable fetch.
+ */
+export async function readNotionComments(pageId, opts) {
+    const maxComments = opts.maxComments ?? 100;
+    const maxBlockScans = opts.maxBlockScans ?? 80;
+    const comments = [];
+    const discussions = new Set();
+    let truncated = false;
+    let blocksScanned = 0;
+    const listOpts = {
+        ...opts,
+        ...(opts.maxCommentPages === undefined ? {} : { maxPages: opts.maxCommentPages }),
+        // An anchor the page bound cut off makes the WHOLE read partial — `truncated` is the coverage
+        // disclosure `read_notion_comments` shows the model, and a cut-off anchor reported as complete
+        // would be a false claim about what the sweep saw.
+        onPageLimit: () => {
+            truncated = true;
+        },
+    };
+    /** Whether this comment is inside the caller's time window. No window ⇒ every comment is. */
+    const inWindow = (c) => {
+        if (opts.sinceMs === undefined)
+            return true;
+        const ms = Date.parse(c.created_time ?? "");
+        return Number.isFinite(ms) && ms >= opts.sinceMs;
+    };
+    const take = (raw, anchor, anchorText) => {
+        // Returns true if the caller should STOP (comment cap hit).
+        for (const c of raw) {
+            if (!inWindow(c))
+                continue;
+            if (comments.length >= maxComments) {
+                truncated = true;
+                return true;
+            }
+            comments.push(toNotionCommentSummary(c, anchor, anchorText));
+            if (typeof c.discussion_id === "string" && c.discussion_id.length > 0)
+                discussions.add(c.discussion_id);
+        }
+        return false;
+    };
+    // Drill-in: a single block's inline discussion.
+    if (opts.block) {
+        take(await listBlockComments(opts.block, listOpts), opts.block);
+        return { comments, discussionCount: discussions.size, blocksScanned: 1, truncated };
+    }
+    // Full sweep: page-level comments first, then per-block inline discussions.
+    if (take(await listBlockComments(pageId, listOpts), pageId)) {
+        return { comments, discussionCount: discussions.size, blocksScanned, truncated };
+    }
+    // NEWEST-FIRST: list the children to the end (bounded), then spend the block budget on the LAST
+    // ones. Separate from the streaming walk below on purpose — that one cannot know which block is
+    // last until it has paged past it, which is the whole reason the budget used to be spent on the
+    // page's oldest material. See `blockScanOrder`.
+    if (opts.blockScanOrder === "newest-first") {
+        const maxChildPages = opts.maxChildPages ?? 10;
+        const children = [];
+        let childCursor;
+        let pagesRead = 0;
+        do {
+            const { blocks, nextCursor } = await getBlockChildren(pageId, { ...opts, startCursor: childCursor });
+            children.push(...blocks);
+            pagesRead += 1;
+            childCursor = nextCursor && pagesRead < maxChildPages ? nextCursor : undefined;
+            // More children than we listed ⇒ the "last block" we scan is not the page's last, so the read
+            // is partial however the budget is then spent.
+            if (nextCursor && childCursor === undefined)
+                truncated = true;
+        } while (childCursor);
+        if (children.length > maxBlockScans)
+            truncated = true;
+        const tail = children.slice(Math.max(0, children.length - maxBlockScans));
+        for (let i = tail.length - 1; i >= 0; i--) {
+            const b = tail[i];
+            blocksScanned += 1;
+            const id = typeof b.id === "string" ? b.id : undefined;
+            if (!id)
+                continue;
+            if (take(await listBlockComments(id, listOpts), id, blockPlainText(b)))
+                break;
+        }
+        return { comments, discussionCount: discussions.size, blocksScanned, truncated };
+    }
+    let cursor;
+    outer: do {
+        const { blocks, nextCursor } = await getBlockChildren(pageId, { ...opts, startCursor: cursor });
+        for (const b of blocks) {
+            if (blocksScanned >= maxBlockScans) {
+                truncated = true;
+                break outer;
+            }
+            blocksScanned += 1;
+            const id = typeof b.id === "string" ? b.id : undefined;
+            // Only blocks Notion flags as comment-bearing are worth a list call — `has_children` does NOT
+            // signal comments, so we probe every block, but cheaply: a comment-free block returns [].
+            if (!id)
+                continue;
+            // The block's own text rides with its comments (OPE-988) — the anchor snippet the generic read
+            // verbs render as a discussion's topic. It is free here: the sweep already holds the block.
+            if (take(await listBlockComments(id, listOpts), id, blockPlainText(b)))
+                break outer;
+        }
+        // More blocks we won't scan (cap or simply more) ⇒ partial read.
+        if (nextCursor && blocksScanned < maxBlockScans) {
+            cursor = nextCursor;
+        }
+        else {
+            if (nextCursor)
+                truncated = true;
+            cursor = undefined;
+        }
+    } while (cursor);
+    return { comments, discussionCount: discussions.size, blocksScanned, truncated };
+}
+/** Flatten ONE block to plain text: read the `rich_text` array nested under the block's own type
+ *  key (`block[block.type].rich_text`) — the shape every text-bearing Notion block uses — and
+ *  concatenate its `plain_text`. Returns "" for a block with no readable text (a divider, image,
+ *  etc.), so a page of only such blocks flattens to empty rather than throwing. */
+export function blockPlainText(block) {
+    const t = typeof block.type === "string" ? block.type : undefined;
+    if (!t)
+        return "";
+    const inner = block[t];
+    if (!inner || typeof inner !== "object")
+        return "";
+    const rich = inner.rich_text;
+    return richTextToPlainText(Array.isArray(rich) ? rich : undefined);
+}
+/** GET /v1/blocks/{block_id}/children — one page of a block's children (top-level only; nested
+ *  children are NOT recursed here — the tool reads the doc's own top-level blocks, which is what
+ *  a comment usually anchors to). Returns the results array + the next cursor (undefined when
+ *  there are no more). Throws on a non-2xx response. */
+export async function getBlockChildren(blockId, opts) {
+    const qs = new URLSearchParams({ page_size: String(opts.pageSize ?? 100) });
+    if (opts.startCursor)
+        qs.set("start_cursor", opts.startCursor);
+    const res = await notionFetch(`${NOTION_API_BASE}/v1/blocks/${encodeURIComponent(blockId)}/children?${qs.toString()}`, {
+        method: "GET",
+        headers: notionHeaders(opts),
+    }, opts);
+    if (!res.ok)
+        throw new Error(`getBlockChildren ${blockId} failed: ${res.status} ${await safeText(res)}`);
+    const body = (await res.json());
+    return {
+        blocks: Array.isArray(body.results) ? body.results : [],
+        nextCursor: body.has_more && body.next_cursor ? body.next_cursor : undefined,
+    };
+}
+/** Read a Notion page's top-level text, paginating block-children and flattening each block's
+ *  rich-text, bounded by BOTH a block count (`maxBlocks`, default 200) and a total-char cap
+ *  (`maxChars`, default 20,000 — well under the wake backscroll budget so the model can hold it).
+ *  `truncated` is true when either cap was hit or Notion still had more blocks — so the agent
+ *  knows the read is partial. Pure over the injectable fetch (no live Notion in tests). */
+export async function readNotionPage(pageId, opts) {
+    const maxBlocks = opts.maxBlocks ?? 200;
+    const maxChars = opts.maxChars ?? 20_000;
+    const lines = [];
+    let chars = 0;
+    let blockCount = 0;
+    let truncated = false;
+    let cursor;
+    do {
+        const { blocks, nextCursor } = await getBlockChildren(pageId, { ...opts, startCursor: cursor });
+        let stop = false;
+        for (const b of blocks) {
+            if (blockCount >= maxBlocks) {
+                truncated = true;
+                stop = true;
+                break;
+            }
+            blockCount += 1;
+            const text = blockPlainText(b);
+            if (!text)
+                continue;
+            if (chars + text.length > maxChars && lines.length > 0) {
+                truncated = true;
+                stop = true;
+                break;
+            }
+            chars += text.length;
+            lines.push(text);
+        }
+        // A remaining page we won't read (either we stopped on a cap, or there simply is more) means
+        // the read is partial — mark truncated and stop paginating.
+        if (stop) {
+            cursor = undefined;
+        }
+        else if (nextCursor) {
+            cursor = nextCursor;
+        }
+        else {
+            cursor = undefined;
+        }
+    } while (cursor);
+    return { text: lines.join("\n"), blockCount, truncated };
+}
+/**
+ * Notion's own per-comment attachment cap (developers.notion.com/reference/create-a-comment,
+ * confirmed live 2026-08-23: "attachments — Array of file objects — Maximum entries: 3"). Exported
+ * so {@link notionMessageOps.postFiles} (notion-message-ops.ts) can refuse a too-large batch BEFORE
+ * uploading a single byte, rather than uploading four files and discarding the fourth's upload.
+ */
+export const NOTION_MAX_ATTACHMENTS = 3;
+/** Build the `attachments` field of a create-comment body from completed `file_upload` ids, or `{}`
+ *  when there are none (so a spread `...attachmentsBody(...)` never adds an empty array to a plain
+ *  text comment). Throws over the cap — the same fail-loud posture as `MAX_FILE_BYTES` in
+ *  `post_file.ts`: a caller that hands too many ids gets a clear reason, never a silently truncated
+ *  batch or a 400 from Notion with no context. */
+function attachmentsBody(fileUploadIds) {
+    if (!fileUploadIds || fileUploadIds.length === 0)
+        return {};
+    if (fileUploadIds.length > NOTION_MAX_ATTACHMENTS) {
+        throw new Error(`Notion comments accept at most ${NOTION_MAX_ATTACHMENTS} attachments; got ${fileUploadIds.length}.`);
+    }
+    return { attachments: fileUploadIds.map((id) => ({ file_upload_id: id, type: "file_upload" })) };
+}
+/** POST /v1/comments — reply into the SAME discussion thread. Notion caps a single rich-text
+ *  item at 2000 chars, so the reply is chunked across items (≤100). Throws on non-2xx. Returns
+ *  the created comment's id (Notion echoes the comment object) so the mid-turn `reply` tool can
+ *  hand it back — empty string if the response carries none. Notion DOES expose an update verb
+ *  now (`PATCH /v1/comments/{id}`, {@link updateComment}) — the reply tool itself does not wire to
+ *  it (that is `edit_reply`'s seam, `channels/post-arms.ts`'s `editMessage`, a separate decision
+ *  with its own scope). `attachments`, when given, names completed `file_upload` ids
+ *  ({@link uploadNotionFile}) — see {@link attachmentsBody} for the cap. */
+export async function createCommentReply(args) {
+    const attach = attachmentsBody(args.attachments);
+    const res = await notionFetch(`${NOTION_API_BASE}/v1/comments`, {
+        method: "POST",
+        headers: notionHeaders(Object.keys(attach).length > 0 ? { ...args, version: NOTION_FILE_UPLOAD_VERSION } : args),
+        body: JSON.stringify({ discussion_id: args.discussionId, rich_text: richTextChunks(args.text), ...attach }),
+    }, args);
+    if (!res.ok) {
+        // The numeric HTTP status rides on the error (OPE-825), so the reply/unified post spines can
+        // classify a failed post here the same way they already do for Slack/Discord/Teams
+        // (channels/platform-failure.ts) — a number only, never the response body or a token.
+        throw Object.assign(new Error(`createCommentReply failed: ${res.status} ${await safeText(res)}`), { status: res.status });
+    }
+    const body = (await res.json().catch(() => ({})));
+    return typeof body.id === "string" ? body.id : "";
+}
+/** POST /v1/comments — start a FRESH top-level comment (a new discussion) on a PAGE, rather than
+ *  replying into an existing one. This is what {@link routeNotionStopComment}'s acknowledgement and
+ *  every other host-driven, no-discussion-in-hand notice (`notion-message-ops.ts`'s `postText`/
+ *  `postFiles`) use: they are handed a PAGE address, never a discussion id. Same chunking/error
+ *  shape and `attachments` handling as {@link createCommentReply}. */
+export async function createPageComment(args) {
+    const attach = attachmentsBody(args.attachments);
+    const res = await notionFetch(`${NOTION_API_BASE}/v1/comments`, {
+        method: "POST",
+        headers: notionHeaders(Object.keys(attach).length > 0 ? { ...args, version: NOTION_FILE_UPLOAD_VERSION } : args),
+        body: JSON.stringify({ parent: { page_id: args.pageId }, rich_text: richTextChunks(args.text), ...attach }),
+    }, args);
+    if (!res.ok) {
+        throw Object.assign(new Error(`createPageComment failed: ${res.status} ${await safeText(res)}`), { status: res.status });
+    }
+    const body = (await res.json().catch(() => ({})));
+    return typeof body.id === "string" ? body.id : "";
+}
+/** PATCH /v1/comments/{comment_id} — rewrite a comment THIS integration created, in place
+ *  (developers.notion.com/reference/update-a-comment, confirmed live 2026-08-23: the endpoint takes
+ *  exactly one of `rich_text`/`markdown`, and 404s on a comment the calling connection did not
+ *  create). Chunked the same way `richTextChunks` chunks a create. Throws on non-2xx, carrying the
+ *  numeric status the same way every other write in this module does. */
+export async function updateComment(args) {
+    const res = await notionFetch(`${NOTION_API_BASE}/v1/comments/${encodeURIComponent(args.commentId)}`, {
+        method: "PATCH",
+        headers: notionHeaders(args),
+        body: JSON.stringify({ rich_text: richTextChunks(args.text) }),
+    }, args);
+    if (!res.ok) {
+        throw Object.assign(new Error(`updateComment ${args.commentId} failed: ${res.status} ${await safeText(res)}`), { status: res.status });
+    }
+}
+/**
+ * POST /v1/file_uploads — step 1: reserve an upload slot for one small (≤20 MB, single-part) file.
+ * Returns the object's `id` (what a comment's `attachments` entry references, once uploaded) and the
+ * `upload_url` step 2 posts bytes to (the SAME host, `api.notion.com`, so it rides the credential
+ * fence like every other call here). Throws on non-2xx, or a response missing either field —
+ * never invents one.
+ */
+export async function createFileUpload(args) {
+    const res = await notionFetch(`${NOTION_API_BASE}/v1/file_uploads`, {
+        method: "POST",
+        headers: notionHeaders({ ...args, version: NOTION_FILE_UPLOAD_VERSION }),
+        body: JSON.stringify({ filename: args.filename, content_type: args.contentType }),
+    }, args);
+    if (!res.ok)
+        throw new Error(`createFileUpload failed: ${res.status} ${await safeText(res)}`);
+    const body = (await res.json().catch(() => ({})));
+    if (typeof body.id !== "string" || body.id.length === 0 || typeof body.upload_url !== "string" || body.upload_url.length === 0) {
+        throw new Error("createFileUpload: Notion response carried no usable id/upload_url.");
+    }
+    return { id: body.id, uploadUrl: body.upload_url };
+}
+/**
+ * POST {uploadUrl} — step 2: send the file's bytes as `multipart/form-data`, field name `file`
+ * (the shape Notion's send-file-upload endpoint requires). No explicit content-type header — like
+ * Discord's `postFiles` (discord-message-ops.ts), `fetch` derives the multipart boundary from the
+ * FormData body itself; setting one by hand would omit the boundary and the upload would 400.
+ * Throws on non-2xx.
+ */
+export async function sendFileUploadBytes(args) {
+    const form = new FormData();
+    // A fresh ArrayBuffer copy so the Blob owns contiguous bytes regardless of the source view
+    // (mirrors discord-message-ops.ts's postFiles — the same reason: a Uint8Array over a larger
+    // backing buffer must not leak neighbouring bytes into the multipart body).
+    const ab = args.bytes.buffer.slice(args.bytes.byteOffset, args.bytes.byteOffset + args.bytes.byteLength);
+    form.append("file", new Blob([ab], { type: args.contentType }), args.filename);
+    const res = await notionFetch(args.uploadUrl, {
+        method: "POST",
+        headers: { authorization: `Bearer ${args.apiKey}`, "notion-version": NOTION_FILE_UPLOAD_VERSION },
+        body: form,
+    }, args);
+    if (!res.ok)
+        throw new Error(`sendFileUploadBytes failed: ${res.status} ${await safeText(res)}`);
+}
+/**
+ * The whole two-step upload (create + send), returning the `file_upload` id — ready to attach to a
+ * comment via {@link createCommentReply}/{@link createPageComment}'s `attachments` argument. ONE
+ * call so a caller (notion-message-ops.ts's `postFiles`) never has to remember the two-step order
+ * or thread the intermediate `upload_url` itself.
+ */
+export async function uploadNotionFile(args) {
+    const { id, uploadUrl } = await createFileUpload(args);
+    await sendFileUploadBytes({ ...args, uploadUrl });
+    return id;
+}
+/** Split reply text into Notion rich-text items, each ≤2000 chars (Notion's per-item cap),
+ *  up to 100 items (Notion's per-comment cap). Exported for the test. */
+export function richTextChunks(text) {
+    const MAX_ITEM = 2000;
+    const MAX_ITEMS = 100;
+    const body = text.length > 0 ? text : "(no content)";
+    const chunks = [];
+    for (let i = 0; i < body.length && chunks.length < MAX_ITEMS; i += MAX_ITEM) {
+        chunks.push({ type: "text", text: { content: body.slice(i, i + MAX_ITEM) } });
+    }
+    return chunks;
+}
+/**
+ * Search the workspace the credential is shared into (`POST /v1/search`), the WORK-plane read
+ * (OPE-913).
+ *
+ * 🔴 THE CREDENTIAL IS THE BOUNDARY, AND OE ADDS NO SECOND ONE. Tommy ruled this on 2026-08-21:
+ * "scope can only be controlled at the CREDENTIAL level; the vendor exposes one search tool and we
+ * just use it. OE never filters search results as a boundary (a post-hoc filter is not
+ * enforcement)." Notion enforces it properly — an internal integration sees only the page trees a
+ * human shared with it — so a domain that wants a narrow search shares a narrow integration. Do NOT
+ * add a domain filter over these results: it would read as a boundary while being none.
+ *
+ * Returns ids + titles only. A caller that wants a body reads the page through the fenced page read.
+ */
+export async function searchNotion(query, opts) {
+    const body = { page_size: Math.min(Math.max(opts.pageSize ?? 10, 1), 100) };
+    if (query.length > 0)
+        body.query = query;
+    if (opts.filter)
+        body.filter = { property: "object", value: opts.filter };
+    const res = await notionFetch(`${NOTION_API_BASE}/v1/search`, {
+        method: "POST",
+        headers: notionHeaders(opts),
+        body: JSON.stringify(body),
+    }, opts);
+    if (!res.ok)
+        throw new Error(`notion search failed: ${res.status} ${await safeText(res)}`);
+    const parsed = (await res.json());
+    const results = Array.isArray(parsed.results) ? parsed.results : [];
+    const hits = [];
+    for (const raw of results) {
+        const item = raw;
+        if (typeof item.id !== "string" || item.id.length === 0)
+            continue;
+        hits.push({
+            id: item.id,
+            object: typeof item.object === "string" ? item.object : "unknown",
+            title: notionItemTitle(item),
+            ...(typeof item.url === "string" ? { url: item.url } : {}),
+        });
+    }
+    return hits;
+}
+/** The plain-text title of a search hit. A DATABASE carries `title` directly; a PAGE carries it
+ *  under whichever `properties` entry has `type: "title"` (the name of that property is the user's
+ *  choice, so it must be found by type, never by a guessed key like "Name"). */
+function notionItemTitle(item) {
+    if (Array.isArray(item.title))
+        return richTextToPlainText(item.title);
+    const props = item.properties;
+    for (const value of Object.values(props ?? {})) {
+        if (value?.type === "title" && Array.isArray(value.title))
+            return richTextToPlainText(value.title);
+    }
+    return "";
+}
+async function safeText(res) {
+    try {
+        return (await res.text()).slice(0, 300);
+    }
+    catch {
+        return "";
+    }
+}
+//# sourceMappingURL=notion-api.js.map