@oomol-lab/open-connector 1.6.5 → 1.8.0

package/src/providers/notion/trigger-on-database-page-event.d.ts

@@ -0,0 +1,2 @@
+import type { PollDefinition } from "../../triggers/common/poll.ts";
+export declare const notionDatabasePageEvent: PollDefinition;

package/src/providers/notion/trigger-on-database-page-event.definition.d.ts

@@ -0,0 +1,4 @@
+import type { TriggerKeySnapshot } from "../../triggers/common/types.ts";
+export declare const snapshot: TriggerKeySnapshot & {
+    readonly type: "poll";
+};

package/src/providers/notion/trigger-on-database-page-event.definition.js

@@ -0,0 +1,63 @@
+import { jsonSchema as s } from "../../core/json-schema.js";
+const idPattern = "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{12}$";
+const eventSchema = s.object({
+    createdBy: { type: "object" },
+    createdTime: s.string(),
+    dataSourceId: s.string(),
+    databaseId: s.string(),
+    event: s.stringEnum(["page_added", "page_updated"]),
+    lastEditedBy: { type: "object" },
+    lastEditedTime: s.string(),
+    pageId: s.string(),
+    properties: { type: "object" },
+    title: s.string(),
+    url: s.string(),
+}, {
+    additionalProperties: false,
+    required: [
+        "event",
+        "pageId",
+        "databaseId",
+        "dataSourceId",
+        "url",
+        "title",
+        "createdTime",
+        "lastEditedTime",
+        "createdBy",
+        "lastEditedBy",
+    ],
+});
+export const snapshot = {
+    configInputs: [
+        {
+            handle: "dataSourceId",
+            jsonSchema: s.string({
+                pattern: "^(?:|[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{12})$",
+            }),
+            nullable: false,
+            value: "",
+        },
+        { handle: "databaseId", jsonSchema: s.string({ pattern: idPattern }), nullable: false },
+        {
+            handle: "events",
+            jsonSchema: s.array(s.stringEnum(["page_added", "page_updated"]), { minItems: 1, uniqueItems: true }),
+            nullable: false,
+            value: ["page_added"],
+        },
+        { handle: "includeProperties", jsonSchema: s.boolean(), nullable: false, value: true },
+        {
+            handle: "maxItemsPerPoll",
+            jsonSchema: s.integer({ maximum: 100, minimum: 1 }),
+            nullable: false,
+            value: 25,
+        },
+    ],
+    definitionVersion: 2,
+    description: "Polls a Notion database and triggers when a page is added to it or an existing page is edited.",
+    displayName: "Database Page Added or Updated",
+    key: "notion.on_database_page_event",
+    name: "on_database_page_event",
+    outputs: [{ handle: "events", jsonSchema: s.array(eventSchema), nullable: false }],
+    provider: "notion",
+    type: "poll",
+};

package/src/providers/notion/trigger-on-database-page-event.js

@@ -0,0 +1,293 @@
+import { eventsPollOutputs, PermanentPollError, PollConnectionError, TransientPollError, } from "../../triggers/common/poll.js";
+import { snapshot } from "./trigger-on-database-page-event.definition.js";
+export const notionDatabasePageEvent = {
+    buildOutputs: eventsPollOutputs,
+    snapshot,
+    async poll(context) {
+        const config = resolveConfig(context.config);
+        if (context.checkpoint === null)
+            return seed(context, config);
+        const stored = readCheckpoint(context.checkpoint);
+        if (stored.target !== target(config))
+            return seed(context, config);
+        return drain(context, config, alignField(stored, cursorField(config.events)));
+    },
+};
+function resolveConfig(value) {
+    return {
+        dataSourceId: value.dataSourceId,
+        databaseId: value.databaseId,
+        events: [...new Set(value.events)],
+        includeProperties: value.includeProperties,
+        maxItemsPerPoll: value.maxItemsPerPoll,
+    };
+}
+async function seed(context, config) {
+    const dataSourceId = await resolveDataSource(context, config);
+    const field = cursorField(config.events);
+    const result = await request(context, {
+        body: { page_size: 1, sorts: [{ direction: "ascending", timestamp: field }] },
+        endpoint: `/data_sources/${encodeURIComponent(dataSourceId)}/query`,
+        method: "POST",
+    });
+    success(result, "seed probe query");
+    return {
+        checkpoint: {
+            cursorField: field,
+            dataSourceId,
+            since: new Date(Math.ceil(context.now.getTime() / 60_000) * 60_000).toISOString(),
+            target: target(config),
+        },
+        events: [],
+    };
+}
+async function resolveDataSource(context, config) {
+    const result = await request(context, {
+        endpoint: `/databases/${encodeURIComponent(config.databaseId)}`,
+        method: "GET",
+    });
+    success(result, "database resolve");
+    const raw = record(result.data)?.data_sources;
+    const candidates = Array.isArray(raw)
+        ? raw.flatMap((value) => {
+            const id = record(value)?.id;
+            return typeof id == "string" && id.length > 0 ? [id] : [];
+        })
+        : [];
+    if (config.dataSourceId.length > 0) {
+        const wanted = normalizeId(config.dataSourceId);
+        const match = candidates.find((id) => normalizeId(id) == wanted);
+        if (match == null)
+            throw new PermanentPollError("The Notion data source does not belong to the configured database.");
+        return match;
+    }
+    if (candidates.length == 1)
+        return candidates[0];
+    if (candidates.length == 0)
+        throw new PermanentPollError("The Notion database has no data sources.");
+    throw new PermanentPollError("The Notion database has multiple data sources; configure dataSourceId.");
+}
+function readCheckpoint(value) {
+    const checkpoint = record(value);
+    const field = checkpoint?.cursorField;
+    if (typeof checkpoint?.dataSourceId != "string" ||
+        checkpoint.dataSourceId.length == 0 ||
+        (field !== "created_time" && field !== "last_edited_time") ||
+        typeof checkpoint.since != "string" ||
+        checkpoint.since.length == 0) {
+        throw new PermanentPollError("Notion checkpoint is invalid; recreate the Trigger.");
+    }
+    return {
+        cursorField: field,
+        dataSourceId: checkpoint.dataSourceId,
+        since: checkpoint.since,
+        target: typeof checkpoint.target == "string" ? checkpoint.target : "",
+        ...(typeof checkpoint.startCursor == "string" && checkpoint.startCursor.length > 0
+            ? { startCursor: checkpoint.startCursor }
+            : {}),
+        ...(checkpoint.sinceExclusive === true ? { sinceExclusive: true } : {}),
+        ...(checkpoint.sinceOnly === true ? { sinceOnly: true } : {}),
+    };
+}
+function cursorField(events) {
+    return events.length == 1 && events[0] == "page_added" ? "created_time" : "last_edited_time";
+}
+function alignField(checkpoint, field) {
+    return checkpoint.cursorField == field
+        ? checkpoint
+        : {
+            cursorField: field,
+            dataSourceId: checkpoint.dataSourceId,
+            since: checkpoint.since,
+            target: checkpoint.target,
+        };
+}
+async function drain(context, config, checkpoint) {
+    const events = [];
+    let filtered = 0;
+    let consumed = 0;
+    let newest = null;
+    let startCursor = checkpoint.startCursor;
+    let ending = null;
+    for (let attempt = 0; attempt < 5; attempt += 1) {
+        const result = await request(context, {
+            body: queryBody(checkpoint, config.maxItemsPerPoll - consumed, startCursor),
+            endpoint: `/data_sources/${encodeURIComponent(checkpoint.dataSourceId)}/query`,
+            method: "POST",
+        });
+        if (result.status == 400 && startCursor != null) {
+            ending = "restarted";
+            break;
+        }
+        success(result, "data source query");
+        const page = (record(result.data) ?? {});
+        for (const row of page.results ?? []) {
+            consumed += 1;
+            const timestamp = checkpoint.cursorField == "created_time" ? row.created_time : row.last_edited_time;
+            if (timestamp != null && timestamp.length > 0)
+                newest = later(newest, timestamp);
+            const kind = classify(row);
+            if (!config.events.includes(kind))
+                filtered += 1;
+            else
+                events.push(event(row, kind, config, checkpoint));
+        }
+        if (page.request_status?.type == "incomplete") {
+            ending = "truncated";
+            break;
+        }
+        if (page.has_more !== true || typeof page.next_cursor != "string" || page.next_cursor.length == 0) {
+            ending = "complete";
+            break;
+        }
+        startCursor = page.next_cursor;
+        if (consumed >= config.maxItemsPerPoll) {
+            ending = { nextCursor: page.next_cursor };
+            break;
+        }
+    }
+    if (ending == null)
+        ending = { nextCursor: startCursor };
+    const base = {
+        cursorField: checkpoint.cursorField,
+        dataSourceId: checkpoint.dataSourceId,
+        target: checkpoint.target,
+    };
+    const next = typeof ending == "object"
+        ? {
+            ...base,
+            since: checkpoint.since,
+            startCursor: ending.nextCursor,
+            ...modifiers(checkpoint),
+        }
+        : { ...base, ...advance(checkpoint, ending, newest, context.now) };
+    return {
+        checkpoint: next,
+        events,
+        filtered,
+        ...(ending == "complete" ? {} : { hasMore: true }),
+    };
+}
+function advance(checkpoint, ending, newest, now) {
+    const pinned = { since: checkpoint.since, ...modifiers(checkpoint) };
+    const closed = Date.parse(checkpoint.since) + 60_000 <= now.getTime();
+    const escaped = closed ? { since: checkpoint.since, sinceExclusive: true } : pinned;
+    if (newest != null && after(newest, checkpoint.since))
+        return { since: newest };
+    if (ending == "restarted")
+        return pinned;
+    if (ending == "complete")
+        return checkpoint.sinceOnly === true || newest != null ? escaped : pinned;
+    if (newest == null)
+        return pinned;
+    return checkpoint.sinceOnly === true ? escaped : { since: checkpoint.since, sinceOnly: true };
+}
+function modifiers(checkpoint) {
+    return {
+        ...(checkpoint.sinceExclusive === true ? { sinceExclusive: true } : {}),
+        ...(checkpoint.sinceOnly === true ? { sinceOnly: true } : {}),
+    };
+}
+function queryBody(checkpoint, budget, startCursor) {
+    const field = checkpoint.cursorField;
+    const filter = checkpoint.sinceOnly === true
+        ? {
+            and: [
+                { [field]: { on_or_after: checkpoint.since }, timestamp: field },
+                { [field]: { on_or_before: checkpoint.since }, timestamp: field },
+            ],
+        }
+        : {
+            [field]: {
+                [checkpoint.sinceExclusive === true ? "after" : "on_or_after"]: checkpoint.since,
+            },
+            timestamp: field,
+        };
+    return {
+        filter,
+        page_size: Math.min(100, budget),
+        sorts: [{ direction: "ascending", timestamp: field }],
+        ...(startCursor == null ? {} : { start_cursor: startCursor }),
+    };
+}
+function classify(page) {
+    return instant(page.created_time) === instant(page.last_edited_time) ? "page_added" : "page_updated";
+}
+function event(page, kind, config, checkpoint) {
+    return {
+        dedupeKey: kind == "page_added"
+            ? `added:${page.id}`
+            : `updated:${page.id}:${instant(page.last_edited_time) ?? page.last_edited_time ?? ""}`,
+        payload: {
+            createdBy: { id: page.created_by?.id ?? "" },
+            createdTime: page.created_time ?? "",
+            dataSourceId: checkpoint.dataSourceId,
+            databaseId: canonicalId(config.databaseId),
+            event: kind,
+            lastEditedBy: { id: page.last_edited_by?.id ?? "" },
+            lastEditedTime: page.last_edited_time ?? "",
+            pageId: page.id,
+            ...(config.includeProperties ? { properties: page.properties ?? {} } : {}),
+            title: title(page.properties ?? {}),
+            url: page.url ?? "",
+        },
+    };
+}
+function title(properties) {
+    for (const value of Object.values(properties)) {
+        const property = record(value);
+        if (property?.type !== "title" || !Array.isArray(property.title))
+            continue;
+        return property.title
+            .map((part) => (typeof record(part)?.plain_text == "string" ? record(part).plain_text : ""))
+            .join("");
+    }
+    return "";
+}
+async function request(context, value) {
+    try {
+        return await context.connector.execute(value, context.signal);
+    }
+    catch (cause) {
+        throw new TransientPollError(`Notion proxy request to ${value.endpoint} failed.`, { cause });
+    }
+}
+function success(result, operation) {
+    if (result.status >= 200 && result.status < 300)
+        return;
+    if (result.status == 401 || result.status == 403)
+        throw new PollConnectionError(`Notion ${operation} rejected the Connection.`);
+    if (result.status == 404)
+        throw new PermanentPollError("The Notion target was not found or is not shared with the Connection.");
+    if (result.status == 400)
+        throw new PermanentPollError(`Notion ${operation} rejected the configuration.`);
+    throw new TransientPollError(`Notion ${operation} failed with status ${result.status}.`);
+}
+function target(config) {
+    return `${config.databaseId}|${config.dataSourceId}`;
+}
+function normalizeId(value) {
+    return value.replaceAll("-", "").toLowerCase();
+}
+function canonicalId(value) {
+    const hex = normalizeId(value);
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+function later(current, candidate) {
+    const timestamp = Date.parse(candidate);
+    return Number.isNaN(timestamp) || (current != null && timestamp < Date.parse(current)) ? current : candidate;
+}
+function after(left, right) {
+    return !Number.isNaN(Date.parse(left)) && !Number.isNaN(Date.parse(right)) && Date.parse(left) > Date.parse(right);
+}
+function instant(value) {
+    if (value == null || value.length == 0)
+        return null;
+    const milliseconds = Date.parse(value);
+    return Number.isNaN(milliseconds) ? null : new Date(milliseconds).toISOString();
+}
+function record(value) {
+    return value != null && typeof value == "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}

package/src/providers/notion_mcp/endpoints.d.ts

@@ -0,0 +1,3 @@
+/** Notion's official remote MCP server, which its own OAuth authorization server protects (RFC 9728). */
+export declare const notionMcpEndpoint = "https://mcp.notion.com/mcp";
+export declare const notionMcpIssuer = "https://mcp.notion.com";

package/src/providers/notion_mcp/endpoints.js

@@ -0,0 +1,3 @@
+/** Notion's official remote MCP server, which its own OAuth authorization server protects (RFC 9728). */
+export const notionMcpEndpoint = "https://mcp.notion.com/mcp";
+export const notionMcpIssuer = "https://mcp.notion.com";

package/src/providers/notion_mcp/executors.d.ts

@@ -0,0 +1,3 @@
+import type { CredentialValidators, ProviderExecutors } from "../../core/types.ts";
+export declare const executors: ProviderExecutors;
+export declare const credentialValidators: CredentialValidators;

package/src/providers/notion_mcp/executors.js

@@ -0,0 +1,176 @@
+import { ProtocolError, SdkHttpError, UnauthorizedError } from "@modelcontextprotocol/client";
+import { compactObject, looseArray, optionalBoolean, optionalInteger, optionalNumber, optionalRawString, optionalRecord, optionalString, optionalStringArray, requiredRawString, } from "../../core/cast.js";
+import { withMcpClient } from "../mcp-client.js";
+import { defineOAuthProviderExecutors, mapProviderActionSources, providerResponseError, providerUserAgent, ProviderRequestError, requiredInputString, requiredResponseRecord, runProviderRequest, } from "../provider-runtime.js";
+import { notionMcpEndpoint } from "./endpoints.js";
+import { decodeNotionToolText, parseNotionComments, parseNotionPage, parseNotionSearch, parseNotionSelf, parseNotionToolAccess, } from "./mcp-response.js";
+const service = "notion_mcp";
+const selfUserId = "self";
+const toolsByAction = {
+    get_self: {
+        tool: "notion-get-users",
+        arguments: () => ({ user_id: selfUserId }),
+        parse: (value) => compactObject({ user: parseNotionSelf(value) }),
+    },
+    search: {
+        tool: "notion-search",
+        arguments: searchArguments,
+        parse: (value) => ({ ...parseNotionSearch(value) }),
+    },
+    fetch_page: {
+        tool: "notion-fetch",
+        arguments: (input) => ({ id: requiredInputString(input.id, "id") }),
+        parse: (value, input) => ({ id: requiredInputString(input.id, "id"), ...parseNotionPage(value) }),
+    },
+    list_comments: {
+        tool: "notion-get-comments",
+        arguments: (input) => ({
+            page_id: requiredInputString(input.page_id, "page_id"),
+            include_all_blocks: optionalBoolean(input.include_all_blocks) ?? true,
+            include_resolved: optionalBoolean(input.include_resolved) ?? true,
+        }),
+        parse: (value) => ({ comments: parseNotionComments(value) }),
+    },
+    tool_access: {
+        tool: "notion-get-tool-access",
+        arguments: () => ({}),
+        parse: (value) => ({ tools: parseNotionToolAccess(value) }),
+    },
+};
+const handlers = mapProviderActionSources(service, toolsByAction, (_actionName, source) => async (input, context) => {
+    const result = await callNotionTool(context, source.tool, source.arguments(input));
+    return { ...source.parse(result.value, input), raw: result.raw };
+});
+export const executors = defineOAuthProviderExecutors(service, handlers, {
+    skipDnsValidation: true,
+});
+export const credentialValidators = {
+    /** Require every tool the actions map, then identify the user so the account key is the Notion user ID. */
+    async oauth2(input, { fetcher, signal }) {
+        const context = { accessToken: input.accessToken, fetcher, signal };
+        const { toolCount, self } = await withNotionMcpClient(context, "validate", async (client, signal) => {
+            const tools = await listNotionTools(client, signal);
+            const available = new Set(tools.map((tool) => tool.name));
+            const missing = Object.values(toolsByAction)
+                .map((source) => source.tool)
+                .filter((tool) => !available.has(tool));
+            if (missing.length > 0) {
+                throw new ProviderRequestError(502, `Notion MCP did not expose the tools this connector needs: ${[...new Set(missing)].join(", ")}.`);
+            }
+            const result = await client.callTool({ name: toolsByAction.get_self.tool, arguments: toolsByAction.get_self.arguments({}) }, { signal });
+            return {
+                toolCount: tools.length,
+                self: parseNotionSelf(readNotionToolResult(toolsByAction.get_self.tool, result).value),
+            };
+        });
+        const accountId = self?.id;
+        if (!accountId)
+            throw providerResponseError("Notion MCP did not identify the connected user.");
+        return {
+            profile: { accountId, displayName: self.name ?? self.email ?? accountId },
+            grantedScopes: optionalString(input.metadata.scope)?.split(" ") ?? [],
+            metadata: { mcpEndpoint: notionMcpEndpoint, discoveredToolCount: toolCount },
+        };
+    },
+};
+/** The recorded notion-search arguments: typed filters nest under `filters`; extra ones pass through beneath them. */
+function searchArguments(input) {
+    const filters = compactObject({
+        ...optionalRecord(input.filters),
+        last_edited_date_range: optionalRecord(input.last_edited_date_range),
+        created_date_range: optionalRecord(input.created_date_range),
+        created_by_user_ids: optionalStringArray(input.created_by_user_ids),
+        edited_by_user_ids: optionalStringArray(input.edited_by_user_ids),
+    });
+    return compactObject({
+        query: optionalRawString(input.query) ?? "",
+        sort: optionalString(input.sort),
+        page_size: optionalInteger(input.page_size),
+        max_highlight_length: optionalInteger(input.max_highlight_length),
+        filters: Object.keys(filters).length > 0 ? filters : undefined,
+    });
+}
+async function listNotionTools(client, signal) {
+    const tools = [];
+    const cursors = new Set();
+    let cursor;
+    do {
+        const page = await client.listTools(cursor === undefined ? {} : { cursor }, { signal });
+        tools.push(...page.tools);
+        cursor = page.nextCursor;
+        if (cursor !== undefined) {
+            if (cursors.has(cursor))
+                throw providerResponseError("Notion MCP tools/list returned a repeated cursor.");
+            cursors.add(cursor);
+        }
+    } while (cursor !== undefined);
+    return tools;
+}
+async function callNotionTool(context, name, input) {
+    const result = await withNotionMcpClient(context, "execute", (client, signal) => client.callTool({ name, arguments: input }, { signal }));
+    return readNotionToolResult(name, result);
+}
+/** The text blocks joined are the raw answer; structured content, when the server sends it, is the value. */
+function readNotionToolResult(name, result) {
+    const record = requiredResponseRecord(result, "Notion MCP result");
+    if (record.isError === true)
+        throw notionToolError(name, record);
+    const texts = looseArray(record.content).flatMap((block) => {
+        const item = optionalRecord(block);
+        return item?.type === "text" ? [requiredRawString(item.text, "Notion MCP text", providerResponseError)] : [];
+    });
+    const structured = optionalRecord(record.structuredContent);
+    if (texts.length === 0 && structured === undefined)
+        throw providerResponseError("Notion MCP returned no content.");
+    const raw = texts.length > 0 ? texts.join("\n") : JSON.stringify(structured);
+    return { raw, value: structured ?? decodeNotionToolText(raw) };
+}
+/**
+ * A tool error. Notion returns a rate limit it does not wait out as a tool error whose `structuredContent.error`
+ * carries `code: "rate_limited"` and, when known, `retry_after_seconds`; that one is a 429, the rest a 502.
+ */
+function notionToolError(name, record) {
+    const error = optionalRecord(optionalRecord(record.structuredContent)?.error);
+    if (error?.code === "rate_limited") {
+        const retryAfter = optionalNumber(error.retry_after_seconds);
+        const wait = retryAfter === undefined ? "" : `; retry after ${retryAfter} seconds`;
+        return new ProviderRequestError(429, `Notion MCP tool ${name} was rate limited${wait}.`, record);
+    }
+    return new ProviderRequestError(502, `Notion MCP tool ${name} failed.`, record);
+}
+function withNotionMcpClient(context, phase, run) {
+    return runProviderRequest({ signal: context.signal, label: "Notion MCP" }, (signal) => withMcpClient({
+        endpoint: new URL(notionMcpEndpoint),
+        transport: "streamable_http",
+        fetcher: context.fetcher,
+        headers: { authorization: `Bearer ${context.accessToken}`, "user-agent": providerUserAgent },
+        redirect: "manual",
+        signal,
+        mapError: (error) => mapNotionMcpError(error, phase),
+    }, (client) => run(client, signal)));
+}
+/**
+ * Sign-in reports a rejected token as invalid input (400); a run reports it as an expired authorization (401).
+ * Anything unrecognized is left to runProviderRequest, which tells a timeout (504) from a failure (502).
+ */
+function mapNotionMcpError(error, phase) {
+    if (error instanceof ProviderRequestError)
+        return error;
+    const credentialStatus = phase === "validate" ? 400 : 401;
+    if (error instanceof UnauthorizedError) {
+        return new ProviderRequestError(credentialStatus, "Notion MCP credential is invalid or expired.");
+    }
+    if (error instanceof SdkHttpError) {
+        const status = error.status;
+        if (status === 401 || status === 403) {
+            return new ProviderRequestError(credentialStatus, "Notion MCP credential is invalid or expired.");
+        }
+        // The SDK error carries the response body; only the status is reported so a token echoed in it never is.
+        const providerStatus = 400 <= status && status < 500 ? status : 502;
+        return new ProviderRequestError(providerStatus, `Notion MCP request failed with HTTP ${status}.`);
+    }
+    if (error instanceof ProtocolError) {
+        return new ProviderRequestError(502, `Notion MCP request failed: ${error.message}`);
+    }
+    return error;
+}

package/src/providers/notion_mcp/mcp-response.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Readers for the text envelopes Notion's beta MCP tools answer in, as they were recorded live. Every reader is
+ * defensive: a field the server omits is absent from the typed result, an unrecognized shape yields an empty
+ * result, and nothing here throws, because the caller keeps the raw text beside the typed fields.
+ */
+interface NotionMcpUser {
+    id?: string;
+    name?: string;
+    email?: string;
+    type?: string;
+}
+interface NotionMcpSearchResult {
+    id?: string;
+    title?: string;
+    url?: string;
+    type?: string;
+    timestamp?: string;
+    path?: string;
+}
+interface NotionMcpSearch {
+    type: string | undefined;
+    results: NotionMcpSearchResult[];
+    notices: string[];
+}
+interface NotionMcpPage {
+    title?: string;
+    url?: string;
+    page_last_edited_at?: string;
+    properties?: string;
+    content?: string;
+    truncated: boolean;
+}
+interface NotionMcpComment {
+    id?: string;
+    discussion_id?: string;
+    plain_text?: string;
+    created_time?: string;
+    created_by?: NotionMcpUser;
+}
+interface NotionMcpToolRestriction {
+    parameter: string;
+    reason: string;
+}
+interface NotionMcpToolAccess {
+    tool: string;
+    status: string | undefined;
+    restricted_parameters: NotionMcpToolRestriction[];
+    upgrade_url: string | undefined;
+    full_version_url: string | undefined;
+    landing_page_url: string | undefined;
+    landing_page_action: string | undefined;
+}
+/** Notion's tools answer JSON in a text block on most calls and prose or XML fragments on the rest. */
+export declare function decodeNotionToolText(text: string): unknown;
+/**
+ * The connected user as notion-get-users answers `user_id: "self"`: the first listed user of
+ * `{results: [{type, id, name, email}], has_more}` that carries an ID or an email, or the answer itself when it is a
+ * single user.
+ */
+export declare function parseNotionSelf(value: unknown): NotionMcpUser | undefined;
+/**
+ * Search results plus the server's notices, such as a filter dropped on the connected plan, and the search `type`
+ * the server reports: `workspace_search`, or `ai_search` when it routed a keyword query to Notion AI search.
+ */
+export declare function parseNotionSearch(value: unknown): NotionMcpSearch;
+/**
+ * The page envelope notion-fetch answers: a preamble line, then
+ * `<page url="..."><properties>...</properties><content>MARKDOWN</content></page>`, either bare in the text block or
+ * under `text` of a `{title, url, page_last_edited_at, text}` object. A page the server cut says so with a
+ * `truncated` flag on the object or on the tag.
+ */
+export declare function parseNotionPage(value: unknown): NotionMcpPage;
+/**
+ * Comments as notion-get-comments answers them, in both recorded shapes: the structured
+ * `{discussions: [{id, comments: [{id, plain_text, created_time, created_by}]}]}` (or a flat `{comments: [...]}`),
+ * or the XML twin `<discussion id><comment id author author_id created_time>text</comment></discussion>`.
+ */
+export declare function parseNotionComments(value: unknown): NotionMcpComment[];
+/**
+ * The plan report notion-get-tool-access answers: `{current_tool_access: {<tool>: {status, restricted_parameters?,
+ * upgrade_url?, full_version_url?, landing_page_url?, landing_page_action?}}}`, keyed by each tool's base name
+ * (`search`, `ai_search`), where `restricted_parameters` maps a parameter path such as `filters.title_only` to the
+ * reason it is unavailable. The reason is kept as text and never interpreted.
+ */
+export declare function parseNotionToolAccess(value: unknown): NotionMcpToolAccess[];
+export {};