@open-everywhere/provider-notion 0.1.0

package/dist/agent/channels/notion-api.d.ts

@@ -0,0 +1,655 @@
+import { type CredentialEndpointRules, type RateLimitRetryOptions } from "@open-everywhere/core/agent/adapter-api.js";
+import type { NotionParentLink } from "./notion-ancestry-trust.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 declare const NOTION_API_BASE = "https://api.notion.com";
+/**
+ * Resolve the Notion CHANNEL-PLUMBING API key through the credential BROKER, so the notion
+ * `channel-key` credential's custody stamp — its `broker` + `secretRef` (agent/access/providers.ts) —
+ * governs every host-side communication-channel REST path (reply posts, the webhook two-step,
+ * page/comment reads), not a hard-coded env pin. Looks the credential up in the registered provider
+ * set (access/providers.ts findConnectorCredential, populated at boot from the app's provider list) and
+ * resolves it via `getSecretVia(broker, secretRef)`. There is no selected default: an api-key
+ * credential always carries its mandatory `broker` stamp, and an absent broker would fail closed
+ * (caught below ⇒ undefined).
+ *
+ * CHANNEL vs WORK-SURFACE SPLIT (decision, Tommy 2026-07-21): the notion provider carries TWO api-key
+ * credentials. `channel-key` (secretRef `db:notion:channel-key`, broker `db` — OPE-408 step 2) is
+ * this communication-channel plumbing — provisioned by the operator via `oe secret set
+ * db:notion:channel-key`. It is a DISTINCT ref from `team-key` (secretRef `db:notion:team-key`), the
+ * WORK-SURFACE credential (the notion-rest egress connection). Even if an operator stores both refs
+ * with the same value, they are separate credentials with separate custody. There is NO fallback
+ * between them: if `db:notion:channel-key` has no stored value, this resolves undefined and channel
+ * Notion fails closed exactly as an unset value does today.
+ *
+ * PER-DOMAIN OVERRIDE (OPE-467). `credentialId` selects WHICH notion channel credential to resolve
+ * and defaults to the org-default `channel-key`, so every existing call site is byte-identical. A
+ * domain that binds its own Notion integration (memory/domain.ts `credentials`) passes that
+ * integration's credential id instead — see channels/notion-credentials.ts for the one rule that
+ * decides it. There is still exactly ONE resolution mechanism: whichever id arrives is looked up in
+ * the registered provider set and resolved through its own custody stamp.
+ *
+ * 🔴 A NAMED-BUT-MISSING CREDENTIAL FAILS CLOSED, and that is the point. When a bound domain's
+ * credential is absent from the provider set this returns undefined and the caller refuses, exactly
+ * as an unset secret does. It NEVER retries under the org default: a domain bound away from the org
+ * key must not be handed the org key by a fallback.
+ *
+ * Fail-closed, two ways, both returning undefined — the exact unset-env semantics every caller
+ * already branches on, NEVER a silent fallback to the work-surface key or an env pin:
+ *   • the provider/credential is UNREGISTERED or carries no `secretRef` (an instance that removed
+ *     the notion provider, or a unit test that never registered one) ⇒ unconfigured ⇒ undefined;
+ *   • the broker resolves no value (the secret is unset) ⇒ the same CredentialError-catch as before.
+ */
+/**
+ * One resolved Notion credential: the key to call with, PAIRED WITH the endpoint rules that key may
+ * be used inside (OPE-505). Spread it straight into a {@link NotionCallOpts} — `{ ...cred, fetch }` —
+ * so the fence and the key can never be threaded separately.
+ *
+ * 🔴 THERE IS DELIBERATELY NO KEY-ONLY RESOLVER. An earlier `resolveNotionApiKey` returned the bare
+ * string, and every call site that used it produced an UNFENCED request: `guardCredentialFetch`
+ * returns the base fetch by identity when it is handed no rules, so a bare key silently disables the
+ * check rather than failing. Deleting that function is what makes the fence total on this module's
+ * paths — a caller cannot obtain a Notion key without also obtaining its rules.
+ */
+export interface ResolvedNotionCredential {
+    readonly apiKey: string;
+    /** The credential's declared endpoint narrowing, or undefined when it declares none. */
+    readonly endpoints?: CredentialEndpointRules;
+}
+/**
+ * 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 declare function resolveNotionCredential(credentialId?: string): Promise<ResolvedNotionCredential | undefined>;
+/**
+ * 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 declare function parseVerificationHandshake(rawBody: string): string | 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 declare function verifyNotionSignature(secret: string, rawBody: string, signatureHeader: string | null | undefined): boolean;
+/**
+ * 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 declare function gateNotionDelivery(secret: string | undefined, rawBody: string, signatureHeader: string | null, allowUnverified: boolean): string | null;
+/** One integration's inbound signing key, paired with the credential that integration calls Notion
+ *  with (channels/notion-credentials.ts). `secret` is undefined when nothing is stored under that
+ *  integration's operator-secret name — an unconfigured integration, skipped by the gate. */
+export interface NotionSigningKey {
+    readonly credentialId: string;
+    readonly secret: string | undefined;
+}
+/** The gate's answer. `rejection` non-null ⇒ send the 401 and stop. `credentialId` names the
+ *  integration whose secret VERIFIED the delivery — the identity a signature proves. `verified` is
+ *  true only when a real signature was checked against a configured secret (never under the dev
+ *  hatch), and it is what admits a delivery into the routing plane. */
+export interface NotionGateVerdict {
+    readonly rejection: string | null;
+    readonly credentialId?: string;
+    readonly verified: boolean;
+}
+/**
+ * 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 declare function gateNotionDeliveryAcross(keys: readonly NotionSigningKey[], rawBody: string, signatureHeader: string | null, allowUnverified: boolean): NotionGateVerdict;
+export interface NotionWebhookEvent {
+    readonly type?: string;
+    /** Some API versions name the discriminator `event_type` instead of `type`. */
+    readonly event_type?: string;
+    readonly workspace_id?: string;
+    readonly entity?: {
+        readonly id?: string;
+        readonly type?: string;
+    };
+    readonly data?: {
+        readonly page_id?: string;
+        readonly parent?: {
+            readonly id?: string;
+            readonly type?: string;
+        };
+    };
+    readonly authors?: ReadonlyArray<{
+        readonly id?: string;
+        readonly type?: string;
+    }>;
+}
+/** The event discriminator, tolerating both the `type` and `event_type` spellings. */
+export declare function notionEventType(ev: NotionWebhookEvent): string | undefined;
+/** 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 declare function commentIdFromEvent(ev: NotionWebhookEvent): string | 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 declare function pageIdFromEvent(ev: NotionWebhookEvent): string | undefined;
+/** One rich-text item as returned inside a comment's `rich_text` array. Loosely typed —
+ *  the shapes are probed defensively (a mis-shaped item never throws). */
+export interface NotionRichText {
+    readonly type?: string;
+    readonly plain_text?: string;
+    readonly text?: {
+        readonly content?: string;
+    };
+    readonly mention?: {
+        readonly type?: string;
+        readonly user?: {
+            readonly id?: string;
+        };
+    };
+}
+/** Flatten a comment's rich_text to plain text (concatenated `plain_text`). */
+export declare function richTextToPlainText(richText: ReadonlyArray<NotionRichText> | undefined): string;
+/**
+ * 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 declare function mentionsUser(richText: ReadonlyArray<NotionRichText> | undefined, userId: string | undefined): boolean;
+/** The subset of the global `fetch` this module uses — injectable so tests mock it. */
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+/** The credential + transport options every Notion REST helper here takes. EXPORTED so a caller that
+ *  threads these options onward (channels/notion-webhook.ts) names this ONE shape rather than
+ *  re-declaring a structural copy that could silently drop `endpoints` and lose the fence. */
+export interface NotionCallOpts {
+    readonly apiKey: string;
+    readonly fetch?: FetchLike;
+    readonly version?: string;
+    /**
+     * The ENDPOINT RULES of the credential `apiKey` came from (OPE-505), carried alongside the key so
+     * the fence travels with it. Every REST call in this module goes out through {@link notionFetch},
+     * which refuses before dispatch when the URL is outside these rules.
+     *
+     * Absent ⇒ unnarrowed, byte-identical to the pre-OPE-505 path. Build the pair with
+     * {@link resolveNotionCredential} rather than assembling it by hand — that is what keeps the rules
+     * and the key from drifting apart, which is the one way this fence could silently stop being one.
+     */
+    readonly endpoints?: CredentialEndpointRules;
+    /**
+     * The 429 backoff policy {@link notionFetch} applies (OPE-1233). A caller that passes none takes
+     * the shared defaults from `channels/rate-limit-retry.ts`. The webhook ingress passes
+     * {@link NOTION_INGRESS_RETRY} because the shared defaults do not fit its ceiling — see there. A
+     * test injects `sleep` and `now` so a retry sequence is driven by a stub clock and waits nothing.
+     */
+    readonly retry?: Pick<RateLimitRetryOptions, "maxAttempts" | "capMs" | "fallbackMs" | "totalBudgetMs" | "sleep" | "now">;
+}
+/**
+ * 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 declare const NOTION_INGRESS_RETRY: {
+    readonly maxAttempts: 2;
+    readonly capMs: 2000;
+    readonly totalBudgetMs: 4000;
+};
+/**
+ * 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 declare function notionOperation(method: string | undefined, url: string): string;
+export interface NotionComment {
+    readonly id?: string;
+    readonly discussion_id?: string;
+    readonly parent?: {
+        readonly type?: string;
+        readonly page_id?: string;
+        readonly block_id?: string;
+    };
+    readonly rich_text?: ReadonlyArray<NotionRichText>;
+    readonly created_by?: {
+        readonly id?: string;
+        readonly object?: string;
+        readonly type?: string;
+    };
+    /** ISO-8601 creation time, when Notion supplies it — the wake message's `sent-at`. */
+    readonly created_time?: string;
+}
+/** 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 declare function retrieveComment(commentId: string, opts: NotionCallOpts): Promise<NotionComment>;
+/** 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 declare function retrieveBotUser(opts: NotionCallOpts): Promise<{
+    id?: string;
+    type?: string;
+    name?: string;
+}>;
+/** 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 declare function listBlockComments(blockId: string, opts: NotionCallOpts & {
+    readonly maxPages?: number;
+    readonly onPageLimit?: () => void;
+}): Promise<NotionComment[]>;
+/** One comment, flattened for the read tool. `text` is UNTRUSTED (commenter-authored); the tool
+ *  wraps it. `authorId`/`authorKind` come off the comment's partial `created_by` (id + object,
+ *  and `type` when Notion supplies it) — surfaced as DATA, never a trust signal. */
+/** The subset of a Notion block object the domain fence reads — its `parent`, i.e. which page (or
+ *  which enclosing block) owns it. */
+export interface NotionBlockParent {
+    readonly id?: string;
+    readonly parent?: {
+        readonly type?: string;
+        readonly page_id?: string;
+        readonly block_id?: string;
+    };
+}
+/** 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 declare function retrieveBlock(blockId: string, opts: NotionCallOpts): Promise<NotionBlockParent>;
+/**
+ * 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 declare const BLOCK_PARENT_MAX_HOPS = 5;
+export declare function resolveBlockOwningPage(blockId: string, opts: NotionCallOpts): Promise<string | undefined>;
+/** The subset of a Notion PAGE object the ancestor walk reads — its `parent`, i.e. what owns it. */
+export interface NotionPageParent {
+    readonly parent?: {
+        readonly type?: string;
+        readonly page_id?: string;
+        readonly block_id?: string;
+        readonly database_id?: string;
+        readonly data_source_id?: string;
+        readonly workspace?: boolean;
+    };
+}
+/** 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 declare function retrievePage(pageId: string, opts: NotionCallOpts): Promise<NotionPageParent>;
+/**
+ * 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 declare function readNotionPageIdentity(pageId: string, opts: NotionCallOpts): Promise<{
+    readonly title?: string;
+    readonly url?: string;
+}>;
+/** 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 declare function toNotionParentLink(parent: NotionPageParent["parent"]): NotionParentLink;
+/**
+ * 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 declare function notionParentLink(id: string, opts: NotionCallOpts): Promise<NotionParentLink>;
+export interface NotionCommentSummary {
+    /**
+     * The comment's OWN Notion id. 🔴 LOAD-BEARING FOR THE SEAT CATCH-UP (OPE-1847): the wake route
+     * passes the trigger's comment id as `SeatCatchUpRequest.excludeId`, and removing the wake's own
+     * message from its catch-up window is done BY ID and never by time — on a surface that floors
+     * `created_time` to the minute, the trigger shares its instant with the comments the seat is
+     * reading for. Absent only when Notion served a comment without one.
+     */
+    readonly id?: string;
+    readonly discussionId?: string;
+    /** The block (or page) the discussion anchors to — distinct inline discussions differ here. */
+    readonly anchorId?: string;
+    /**
+     * The plain text of the ANCHOR BLOCK, when the sweep read the block object that carries it
+     * (OPE-988). It is what a Notion discussion is ABOUT, and the generic `read_channel` / `read_thread`
+     * render it as the discussion's topic — without it a list of discussions is a list of ids.
+     *
+     * ABSENT for a page-level comment (the anchor is the page, which has no block text) and for the
+     * `block` drill-in (which addresses a block by id and never reads the block object). Absence means
+     * "no anchor text was read", never "the block is empty".
+     */
+    readonly anchorText?: string;
+    readonly authorId?: string;
+    readonly authorKind?: string;
+    readonly createdTime?: string;
+    readonly text: string;
+}
+/** 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 declare function toNotionCommentSummary(c: NotionComment, fallbackAnchor: string, anchorText?: string): NotionCommentSummary;
+/**
+ * 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 declare function readNotionComments(pageId: string, opts: NotionCallOpts & {
+    readonly block?: string;
+    readonly maxComments?: number;
+    readonly maxBlockScans?: number;
+    /**
+     * Epoch ms of the OLDEST comment worth collecting. A comment older than this — or one Notion gave
+     * no readable `created_time` for — is skipped BEFORE the `maxComments` cap is charged.
+     * 🔴 THE ORDER OF THOSE TWO IS THE WHOLE POINT (OPE-1831). Notion serves comments OLDEST-FIRST,
+     * so a cap that counts every comment it walks past fills with the anchor's most ANCIENT ones and
+     * then reports `truncated` — the exact opposite of what a "since the seat last woke" read needs.
+     * Filtering first makes the cap count comments IN the window. Absent ⇒ no time filter, which is
+     * the whole-history read every existing caller already makes.
+     */
+    readonly sinceMs?: number;
+    /** Pages of comments to follow per anchor ({@link listBlockComments}). Default 1 — one call. */
+    readonly maxCommentPages?: number;
+    /**
+     * Which END of the page's top-level blocks the `maxBlockScans` budget is spent on (OPE-1843).
+     *
+     * `"document"` (the default, and what every caller got before this option existed) scans from
+     * the TOP of the page and stops at the cap. `"newest-first"` lists the children first, then
+     * spends the same budget on the LAST ones, newest block first.
+     *
+     * 🔴 A CATCH-UP READ WANTS THE OTHER END, AND THE DEFAULT ORDER MADE IT BLIND. Notion serves a
+     * page's children in document order and a page GROWS BY APPENDING, so on a page past
+     * `maxBlockScans` top-level blocks the budget is spent entirely on the page's oldest material
+     * and a discussion anchored on a recently appended block is never scanned. The sweep then
+     * returns zero comments with no error — the same answer a genuinely quiet page gives. That is
+     * the `J-ENGAGED-notion` shape: the journey appends a paragraph block per run and opens a
+     * BLOCK-anchored discussion on it (`core/scripts/e2e/scenarios.ts`), and a page-id comment
+     * query never returns a child block's comments, so the block walk is the only code that can
+     * find it.
+     *
+     * 🔴 IT MOVES THE BLIND SPOT, IT DOES NOT REMOVE IT, AND SAYING OTHERWISE WOULD BE A FALSE
+     * CLAIM. A comment posted TODAY on an ANCIENT block of a page past the cap is unread under
+     * `"newest-first"` and was read under `"document"`. Notion offers no "blocks with recent
+     * comments" query and a comment does not touch its block's `last_edited_time`, so no order is
+     * complete and only raising the cap would be — at one list call per block, against the shared
+     * 60 s-per-call 429 budget. `newest-first` is chosen for the CATCH-UP because the growth shape
+     * that crosses the cap at all is append-only, so the newest blocks are where the live
+     * conversation is. `truncated` still reports the read as partial either way.
+     *
+     * A page whose children fit inside `maxBlockScans` scans exactly the same blocks under both
+     * orders, so only an over-cap page pays or gains anything here.
+     */
+    readonly blockScanOrder?: "document" | "newest-first";
+    /**
+     * Pages of block children to list when `blockScanOrder` is `"newest-first"`. Default 10 — a
+     * thousand top-level blocks, because finding the LAST child means paging to the end.
+     * A page longer than this is scanned from the end of what was listed and reports `truncated`.
+     * Cheap next to the scan itself: one `getBlockChildren` call per hundred blocks against one
+     * `listBlockComments` call per SCANNED block.
+     */
+    readonly maxChildPages?: number;
+}): Promise<{
+    readonly comments: NotionCommentSummary[];
+    readonly discussionCount: number;
+    readonly blocksScanned: number;
+    readonly truncated: boolean;
+}>;
+/** One block as returned by GET /v1/blocks/{id}/children. Loosely typed — the per-type
+ *  `rich_text` array is probed defensively (a mis-shaped block never throws). */
+export interface NotionBlock {
+    readonly id?: string;
+    readonly type?: string;
+    readonly has_children?: boolean;
+    readonly [key: string]: unknown;
+}
+/** 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 declare function blockPlainText(block: NotionBlock): string;
+/** 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 declare function getBlockChildren(blockId: string, opts: NotionCallOpts & {
+    readonly startCursor?: string;
+    readonly pageSize?: number;
+}): Promise<{
+    readonly blocks: NotionBlock[];
+    readonly nextCursor?: string;
+}>;
+/** 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 declare function readNotionPage(pageId: string, opts: NotionCallOpts & {
+    readonly maxBlocks?: number;
+    readonly maxChars?: number;
+}): Promise<{
+    readonly text: string;
+    readonly blockCount: number;
+    readonly truncated: boolean;
+}>;
+/**
+ * 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 declare const NOTION_MAX_ATTACHMENTS = 3;
+/** 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 declare function createCommentReply(args: {
+    discussionId: string;
+    text: string;
+    attachments?: readonly string[];
+} & NotionCallOpts): Promise<string>;
+/** 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 declare function createPageComment(args: {
+    pageId: string;
+    text: string;
+    attachments?: readonly string[];
+} & NotionCallOpts): Promise<string>;
+/** 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 declare function updateComment(args: {
+    commentId: string;
+    text: string;
+} & NotionCallOpts): Promise<void>;
+/**
+ * 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 declare function createFileUpload(args: {
+    readonly filename: string;
+    readonly contentType: string;
+} & NotionCallOpts): Promise<{
+    readonly id: string;
+    readonly uploadUrl: string;
+}>;
+/**
+ * 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 declare function sendFileUploadBytes(args: {
+    readonly uploadUrl: string;
+    readonly filename: string;
+    readonly contentType: string;
+    readonly bytes: Uint8Array;
+} & NotionCallOpts): Promise<void>;
+/**
+ * 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 declare function uploadNotionFile(args: {
+    readonly filename: string;
+    readonly contentType: string;
+    readonly bytes: Uint8Array;
+} & NotionCallOpts): Promise<string>;
+/** 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 declare function richTextChunks(text: string): Array<{
+    type: "text";
+    text: {
+        content: string;
+    };
+}>;
+/** One hit from {@link searchNotion} — ids and a title, never page CONTENT. */
+export interface NotionSearchHit {
+    readonly id: string;
+    /** "page" | "database", as Notion reports it. */
+    readonly object: string;
+    /** The item's title in plain text, or "" when Notion returns none (an untitled page). */
+    readonly title: string;
+    /** Notion's own URL for the item, when it returns one. */
+    readonly url?: string;
+}
+/**
+ * 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 declare function searchNotion(query: string, opts: NotionCallOpts & {
+    readonly pageSize?: number;
+    readonly filter?: "page" | "database";
+}): Promise<readonly NotionSearchHit[]>;
+//# sourceMappingURL=notion-api.d.ts.map