@zackbart/connecta 0.28.1 → 0.30.0

package/dist/providers/{notion.js → notion/index.js}

@@ -1,8 +1,12 @@
-import { apiConnector as api, defined } from "../connectors/api-connector.js";
-import { remoteMcp } from "../connectors/remote-mcp.js";
-import { vettedCatalog, withVettedCatalog } from "../catalog-drift.js";
-import { guardedFetch, retryAfterMs, } from "../connectors/guarded-fetch.js";
-import { ConnectorCallError } from "../errors.js";
+import { skill } from "./skill.generated.js";
+import { apiConnector as api } from "../../connectors/api-connector.js";
+import { remoteMcp } from "../../connectors/remote-mcp.js";
+import { reviewedCatalog } from "../../catalog-drift.js";
+import { guardedFetch, retryAfterMs } from "../../connectors/guarded-fetch.js";
+import { ConnectorCallError } from "../../errors.js";
+import { keys, optionsOf, variants } from "../../config-schema.js";
+import { PROVIDER_COMMON } from "../../connectors/option-shapes.js";
+import { defineProvider } from "../../provider.js";
 /** Notion's REST origin. Every tool below speaks to exactly this host. */
 export const NOTION_API_BASE_URL = "https://api.notion.com";
 /** Notion's official hosted MCP endpoint. */
@@ -23,7 +27,7 @@ const DEFAULT_PAGE_SIZE = 25;
 /** Notion's cap on `children` per append, and on blocks per page create. */
 const MAX_CHILDREN_PER_REQUEST = 100;
 /**
- * Ceiling on the fetches one `get_page_content` walk may spend. Call admission
+ * Ceiling on the fetches one `integration_get_page_content` walk may spend. Call admission
  * meters tool calls, not the requests inside them, so a deep `depth` would
  * otherwise drain the budget invisibly; the walk stops here and reports
  * `truncated: true` instead.
@@ -86,13 +90,15 @@ function notionFailure(status, body, headers) {
     }
     if (status === 529) {
         // Notion documents 529 alongside 429: back off and respect Retry-After.
-        return new ConnectorCallError("unavailable", `${labelled} Notion is overloaded; retry after the reported window.`, { retryAfterMs: retryAfter ?? 5_000 });
+        return new ConnectorCallError("unavailable", `${labelled} Notion is overloaded; retry after the reported window.`, {
+            retryAfterMs: retryAfter ?? 5_000,
+        });
     }
     if (status === 401) {
         return new ConnectorCallError("auth_required", `${labelled} The Notion integration token is missing or invalid. Call authorize_connector for recovery options. When available, an operator can set a valid token in this connection in the operator UI.`);
     }
     if (status === 403) {
-        return new ConnectorCallError("connector_call_failed", `${labelled} The token is valid but this integration is not allowed to perform this operation. An operator must enable the matching capability on the Notion integration (comment capabilities are off by default) or share the object with it. Re-authorizing will not help.`, { retryable: false });
+        return new ConnectorCallError("provider_permission_denied", `${labelled} The token is valid but this integration is not allowed to perform this operation. An operator must enable the matching capability on the Notion integration (comment capabilities are off by default) or share the object with it. Re-authorizing will not help.`, { retryable: false });
     }
     if (status === 404) {
         return new ConnectorCallError("connector_call_failed", `${labelled} Notion returns this both for an object that does not exist and for one that exists but has not been shared with this integration — do not treat it as proof of deletion. Confirm the id, then confirm the page or database is shared with the integration in Notion.`, { retryable: false });
@@ -141,9 +147,7 @@ const send = guardedFetch({
 async function notionRequest(ctx, request) {
     return await send(request, ctx, async (response) => {
         const parsed = await response.jsonResult();
-        const payload = "value" in parsed
-            ? parsed.value
-            : undefined;
+        const payload = "value" in parsed ? parsed.value : undefined;
         if (!response.ok) {
             throw notionFailure(response.status, payload, response.headers);
         }
@@ -167,9 +171,7 @@ async function notionRequest(ctx, request) {
 function plainText(value) {
     if (!Array.isArray(value))
         return "";
-    return value
-        .map((run) => (typeof run?.plain_text === "string" ? run.plain_text : ""))
-        .join("");
+    return value.map((run) => (typeof run?.plain_text === "string" ? run.plain_text : "")).join("");
 }
 /** Wrap a plain string as the single-run rich-text array Notion expects. */
 function richText(value) {
@@ -349,7 +351,7 @@ function projectPage(page, select) {
 /**
  * Identity fields only, no properties. A 25-result search across a populated
  * database would otherwise drag back hundreds of flattened values for results
- * the agent is about to discard; `get_page` fetches them for the one that hit.
+ * the agent is about to discard; `integration_get_page` fetches them for the one that hit.
  */
 function projectSearchHit(hit) {
     if (hit?.object === "data_source") {
@@ -492,7 +494,7 @@ function projectSchemaProperty(property) {
 // Shared schema fragments
 // ---------------------------------------------------------------------------
 // The compact renderer inlines every property description, so these three
-// shared strings are paid for once per tool that uses them. `query_data_source`
+// shared strings are paid for once per tool that uses them. `integration_query_data_source`
 // carries all three plus a filter grammar and rendered past the 1,024-byte
 // compact budget until they were cut to the fact each one actually adds
 // ([#342](https://github.com/zackbart/connecta/issues/342)); the long versions
@@ -568,12 +570,12 @@ const PAGE_OUTPUT_SCHEMA = {
                     name: { type: "string" },
                     id: {
                         type: ["string", "null"],
-                        description: "Pass as property_id to get_page_property.",
+                        description: "Pass as property_id to integration_get_page_property.",
                     },
                 },
                 required: ["name", "id"],
             },
-            description: "Properties Notion truncated at 25 entries. Each carries the property_id get_page_property needs to read the complete value.",
+            description: "Properties Notion truncated at 25 entries. Each carries the property_id integration_get_page_property needs to read the complete value.",
         },
     },
     required: ["id", "title", "properties"],
@@ -656,9 +658,7 @@ function pagination(args, defaultPageSize) {
 function requireExactlyOne(provided, hint) {
     const present = provided.filter(([, value]) => value !== undefined && value !== null && value !== "");
     if (present.length !== 1) {
-        throw new ConnectorCallError("invalid_args", `Provide exactly one of ${provided
-            .map(([name]) => name)
-            .join(", ")}. ${hint}`);
+        throw new ConnectorCallError("invalid_args", `Provide exactly one of ${provided.map(([name]) => name).join(", ")}. ${hint}`);
     }
     return present[0];
 }
@@ -666,8 +666,8 @@ function buildTools(defaultPageSize) {
     return [
         // ---------------------------------------------------------------- reads
         {
-            name: "search",
-            description: "Find pages and data sources by title across everything shared with this integration. Never searches page content — use query_data_source for rows inside a database. Returns identity fields only.",
+            name: "integration_search",
+            description: "Find pages and data sources by title across everything shared with this integration. Never searches page content — use integration_query_data_source for rows inside a database. Returns identity fields only.",
             annotations: { readOnlyHint: true },
             inputSchema: {
                 type: "object",
@@ -736,8 +736,8 @@ function buildTools(defaultPageSize) {
             },
         },
         {
-            name: "get_page",
-            description: "Fetch one page's metadata and flattened property values by id. Returns the page's properties, not its body content — use get_page_content for the blocks.",
+            name: "integration_get_page",
+            description: "Fetch one page's metadata and flattened property values by id. Returns the page's properties, not its body content — use integration_get_page_content for the blocks.",
             annotations: { readOnlyHint: true },
             inputSchema: {
                 type: "object",
@@ -764,7 +764,7 @@ function buildTools(defaultPageSize) {
             },
         },
         {
-            name: "get_page_content",
+            name: "integration_get_page_content",
             // `raw: true` returns the requested level exactly as Notion sent it and
             // does not walk nested children, so `depth` is ignored alongside it: a
             // raw read of a deep page yields one level.
@@ -847,8 +847,8 @@ function buildTools(defaultPageSize) {
             },
         },
         {
-            name: "get_page_property",
-            description: "Fetch one page property completely, paginating past the 25-entry limit that get_page reports in truncated_properties. Use for title, rich_text, relation, and people properties — the four Notion paginates.",
+            name: "integration_get_page_property",
+            description: "Fetch one page property completely, paginating past the 25-entry limit that integration_get_page reports in truncated_properties. Use for title, rich_text, relation, and people properties — the four Notion paginates.",
             annotations: { readOnlyHint: true },
             inputSchema: {
                 type: "object",
@@ -856,7 +856,7 @@ function buildTools(defaultPageSize) {
                     page_id: { type: "string", description: "Notion page id." },
                     property_id: {
                         type: "string",
-                        description: "The property's id, from get_data_source_schema or get_page's truncated_properties — not its name.",
+                        description: "The property's id, from integration_get_data_source_schema or integration_get_page's truncated_properties — not its name.",
                     },
                     page_size: PAGE_SIZE_PROPERTY,
                     start_cursor: START_CURSOR_PROPERTY,
@@ -871,7 +871,7 @@ function buildTools(defaultPageSize) {
                 properties: {
                     type: {
                         type: ["string", "null"],
-                        description: "The property's own type, never the \"property_item\" envelope.",
+                        description: 'The property\'s own type, never the "property_item" envelope.',
                     },
                     value: { description: "Flattened value for a single-value property." },
                     results: {
@@ -906,8 +906,8 @@ function buildTools(defaultPageSize) {
             },
         },
         {
-            name: "get_database",
-            description: "Fetch a database container and list the data sources inside it. A database id cannot be queried directly — start here to get the data_source_id that query_data_source and get_data_source_schema need.",
+            name: "integration_get_database",
+            description: "Fetch a database container and list the data sources inside it. A database id cannot be queried directly — start here to get the data_source_id that integration_query_data_source and integration_get_data_source_schema need.",
             annotations: { readOnlyHint: true },
             inputSchema: {
                 type: "object",
@@ -958,7 +958,7 @@ function buildTools(defaultPageSize) {
             },
         },
         {
-            name: "get_data_source_schema",
+            name: "integration_get_data_source_schema",
             description: "List a data source's properties with their ids, types, and select/status options. Read this before filtering, sorting, or writing — filters and property names that do not match the schema exactly are rejected.",
             annotations: { readOnlyHint: true },
             inputSchema: {
@@ -966,7 +966,7 @@ function buildTools(defaultPageSize) {
                 properties: {
                     data_source_id: {
                         type: "string",
-                        description: "Data source id from get_database or search, not a database id.",
+                        description: "Data source id from integration_get_database or integration_search, not a database id.",
                     },
                     raw: RAW_PROPERTY,
                 },
@@ -981,7 +981,7 @@ function buildTools(defaultPageSize) {
                     database_id: { type: ["string", "null"] },
                     title_property: {
                         type: ["string", "null"],
-                        description: "Name of the title-typed property. create_page needs this to title a row.",
+                        description: "Name of the title-typed property. integration_create_page needs this to title a row.",
                     },
                     properties: {
                         type: "object",
@@ -1014,7 +1014,7 @@ function buildTools(defaultPageSize) {
             },
         },
         {
-            name: "query_data_source",
+            name: "integration_query_data_source",
             description: "List rows in a data source with optional filtering and sorting, returning each row's properties already flattened. Requires a data_source_id, never a database_id. Narrow with the properties argument to keep results small.",
             annotations: { readOnlyHint: true },
             inputSchema: {
@@ -1022,11 +1022,11 @@ function buildTools(defaultPageSize) {
                 properties: {
                     data_source_id: {
                         type: "string",
-                        description: "Data source id from get_database or search.",
+                        description: "Data source id from integration_get_database or integration_search.",
                     },
                     filter: {
                         type: "object",
-                        description: 'Notion filter object, passed through unchanged. Single condition: {"property":"Status","status":{"equals":"Done"}}. Compound: {"and":[...]} or {"or":[...]}. Property names must match get_data_source_schema exactly.',
+                        description: 'Notion filter object, passed through unchanged. Single condition: {"property":"Status","status":{"equals":"Done"}}. Compound: {"and":[...]} or {"or":[...]}. Property names must match integration_get_data_source_schema exactly.',
                     },
                     sorts: {
                         type: "array",
@@ -1078,7 +1078,7 @@ function buildTools(defaultPageSize) {
             },
         },
         {
-            name: "list_users",
+            name: "integration_list_users",
             description: "List workspace users and bots with their ids, for assigning people properties or attributing edits. Requires the integration's user-information capability.",
             annotations: { readOnlyHint: true },
             inputSchema: {
@@ -1101,7 +1101,7 @@ function buildTools(defaultPageSize) {
             },
         },
         {
-            name: "get_self",
+            name: "integration_get_self",
             description: "Identify the integration this connector authenticates as, and the workspace it is installed in. The cheapest way to confirm the token works before a longer sequence.",
             annotations: { readOnlyHint: true },
             inputSchema: {
@@ -1132,7 +1132,7 @@ function buildTools(defaultPageSize) {
             },
         },
         {
-            name: "list_comments",
+            name: "integration_list_comments",
             description: "List unresolved comments on a page or block as plain text with their discussion ids. Requires the integration's read-comment capability, which is off by default.",
             annotations: { readOnlyHint: true },
             inputSchema: {
@@ -1166,7 +1166,7 @@ function buildTools(defaultPageSize) {
         },
         // --------------------------------------------------------------- writes
         {
-            name: "create_page",
+            name: "integration_create_page",
             description: "Create a page, either as a child of another page or as a row in a data source. Notion has no idempotency key: a retried create makes a second page, so confirm with search before repeating one.",
             annotations: { readOnlyHint: false },
             inputSchema: {
@@ -1189,11 +1189,11 @@ function buildTools(defaultPageSize) {
                     title: { type: "string", description: "Plain-text title." },
                     title_property: {
                         type: "string",
-                        description: 'Name of the title-typed property, from get_data_source_schema. Required in practice for a data-source parent, whose title column is rarely called "title". Defaults to "title", which is the only valid key under a page parent.',
+                        description: 'Name of the title-typed property, from integration_get_data_source_schema. Required in practice for a data-source parent, whose title column is rarely called "title". Defaults to "title", which is the only valid key under a page parent.',
                     },
                     properties: {
                         type: "object",
-                        description: "Additional Notion property values, keyed by property name and in Notion's own wrapped form, e.g. {\"Status\":{\"status\":{\"name\":\"Todo\"}}}. Read get_data_source_schema first.",
+                        description: 'Additional Notion property values, keyed by property name and in Notion\'s own wrapped form, e.g. {"Status":{"status":{"name":"Todo"}}}. Read integration_get_data_source_schema first.',
                     },
                     markdown: {
                         type: "string",
@@ -1214,7 +1214,7 @@ function buildTools(defaultPageSize) {
                 const [parentKey, parentValue] = requireExactlyOne([
                     ["parent_page_id", args.parent_page_id],
                     ["parent_data_source_id", args.parent_data_source_id],
-                ], "A page needs exactly one parent, and a data source is addressed by its data_source_id from get_database — never by a database_id.");
+                ], "A page needs exactly one parent, and a data source is addressed by its data_source_id from integration_get_database — never by a database_id.");
                 if (args.markdown !== undefined && args.children !== undefined) {
                     throw new ConnectorCallError("invalid_args", "Provide either markdown or children for the page body, not both.");
                 }
@@ -1245,7 +1245,7 @@ function buildTools(defaultPageSize) {
             },
         },
         {
-            name: "append_blocks",
+            name: "integration_append_blocks",
             description: "Append content to the end of a page or block, or insert it at a chosen position. Appending only adds: existing blocks are never moved or replaced, and an appended block cannot be relocated later through the API.",
             annotations: { readOnlyHint: false },
             inputSchema: {
@@ -1329,7 +1329,7 @@ function buildTools(defaultPageSize) {
             },
         },
         {
-            name: "update_page_properties",
+            name: "integration_update_page_properties",
             // Deliberately no locking, templates, or `erase_content` (#409): locking
             // is coordination state, templates finish asynchronously, and
             // `erase_content` permanently deletes every child block. None belongs
@@ -1347,11 +1347,11 @@ function buildTools(defaultPageSize) {
                     },
                     title_property: {
                         type: "string",
-                        description: 'Name of the title-typed property, from get_data_source_schema. Defaults to "title".',
+                        description: 'Name of the title-typed property, from integration_get_data_source_schema. Defaults to "title".',
                     },
                     properties: {
                         type: "object",
-                        description: "Notion property values keyed by property name, in Notion's wrapped form. Read get_data_source_schema for names, types, and valid option names.",
+                        description: "Notion property values keyed by property name, in Notion's wrapped form. Read integration_get_data_source_schema for names, types, and valid option names.",
                     },
                     icon: { type: "string", description: "Replacement emoji icon." },
                 },
@@ -1383,7 +1383,7 @@ function buildTools(defaultPageSize) {
             },
         },
         {
-            name: "trash_page",
+            name: "integration_trash_page",
             description: "Move a page to the workspace trash, or restore one from it. Trashing hides the page and its content from reads; it is reversible through this same tool with restore: true.",
             annotations: { readOnlyHint: false, destructiveHint: true },
             inputSchema: {
@@ -1421,7 +1421,7 @@ function buildTools(defaultPageSize) {
             },
         },
         {
-            name: "add_comment",
+            name: "integration_add_comment",
             description: "Start a comment discussion on a page, or reply to an existing discussion. Requires the integration's insert-comment capability, which is off by default.",
             annotations: { readOnlyHint: false },
             inputSchema: {
@@ -1433,7 +1433,7 @@ function buildTools(defaultPageSize) {
                     },
                     discussion_id: {
                         type: "string",
-                        description: "Reply to this existing discussion, from list_comments.",
+                        description: "Reply to this existing discussion, from integration_list_comments.",
                     },
                     text: { type: "string", description: "Comment body as plain text." },
                 },
@@ -1451,9 +1451,7 @@ function buildTools(defaultPageSize) {
                 }
                 const body = {
                     rich_text: richText(args.text),
-                    ...(kind === "page_id"
-                        ? { parent: { type: "page_id", page_id: value } }
-                        : { discussion_id: value }),
+                    ...(kind === "page_id" ? { parent: { type: "page_id", page_id: value } } : { discussion_id: value }),
                 };
                 return projectComment(await notionRequest(ctx, {
                     method: "POST",
@@ -1470,205 +1468,182 @@ function buildTools(defaultPageSize) {
 /**
  * Marked `required` for one reason: a Notion database is a container, and the
  * rows and schema live in a data source inside it. The id in a database URL is a
- * database id, and passing it to `query_data_source` or `create_page` fails —
+ * database id, and passing it to `integration_query_data_source` or `integration_create_page` fails —
  * a trap no input schema can teach, so the guide has to.
  */
 function apiUsageGuide(purpose, instructions) {
     const accountInstructions = instructions?.trim();
     return `# Notion usage
 
-Workspace purpose: ${purpose}
-
-## Databases contain data sources
-
-A Notion database is a container; the rows and the schema live in a *data
-source* inside it. The two ids are not interchangeable and Notion rejects the
-wrong one.
-
-- The id in a Notion database URL is a **database id**.
-- \`get_database\` turns it into the \`data_sources\` list — usually one entry.
-- \`get_data_source_schema\` and \`query_data_source\` take that
-  **data_source_id**, and so does \`create_page\` when adding a row.
-
-So the sequence for "find rows in this database" is \`get_database\` →
-\`get_data_source_schema\` → \`query_data_source\`. \`search\` returns data
-sources directly and skips the first step.
-
-## Property quirks that break writes
-
-- Property names in filters, sorts, and writes must match the schema exactly,
-  including case. Read \`get_data_source_schema\` before composing one.
-- \`select\` and \`status\` writes must use an existing option name; inventing
-  one fails. The schema lists the valid options.
-- Writes **replace** a property. Sending one item to a \`multi_select\` or
-  \`relation\` drops the others, so send the complete intended value.
-- \`rollup\`, \`formula\`, \`unique_id\`, and the created/edited fields are
-  computed. They cannot be written.
-- A page's title column is rarely called "title" — pass \`title_property\` from
-  the schema when creating or updating a row.
-- Notion truncates \`title\`, \`rich_text\`, \`relation\`, and \`people\` at 25
-  entries. \`get_page\` reports each one in \`truncated_properties\` as
-  \`{ name, id }\`; pass that \`id\` as \`property_id\` to
-  \`get_page_property\` for the complete value.
-
-## Reading page content
-
-\`get_page\` returns properties. \`get_page_content\` returns the body as flat
-blocks. Nested blocks (toggles, list children, table rows) need \`depth\`, and
-each level multiplies requests — a deep read stops at an internal ceiling and
-reports \`truncated: true\` rather than spending the whole rate-limit budget.
-
-## Appending is append-only
-
-\`append_blocks\` adds children and nothing else. It cannot move, reorder, or
-replace an existing block, and a block appended through the API can never be
-relocated by it afterwards. Get the position right the first time with
-\`position\` and \`after_block_id\`. Notion caps one call at 100 blocks.
-
-## Lean by default, raw on request
-
-Every read projects Notion's payload down to ids, plain text, and flattened
-property values. Where the dropped detail can matter — \`search\`, \`get_page\`,
-\`get_page_content\`, \`get_page_property\`, \`get_data_source_schema\`,
-\`query_data_source\`, \`list_comments\` — pass \`raw: true\` to get Notion's
-untouched response instead. It is much larger; reach for it only when a
-specific field is missing. Narrow \`query_data_source\` and \`get_page\` with
-\`properties\` instead whenever the goal is fewer fields, not more.
-
-\`get_page_content\` with \`raw: true\` returns one level exactly as Notion
-sent it and does not walk nested children, so \`depth\` is ignored alongside
-it. A block type this projection does not model keeps its payload under
-\`raw\` on the block itself, so nothing silently flattens to an empty string.
-
-## Failures worth reading carefully
-
-- **404** means "no such object" *or* "not shared with this integration", and
-  Notion will not say which. Never conclude a page was deleted from it; check
-  that the page is shared with the integration in Notion.
-- **403** is not an expired token. The integration is missing a capability
-  (comment capabilities are off by default) or the object was never shared.
-  Re-authorizing cannot fix it; an operator must change it in Notion.
-- **429** carries a retry window. Notion allows roughly three requests per
-  second per integration, so wait it out rather than retrying immediately.
-
-## No escape hatch
-
-This connection has no guarded raw-REST tool, deliberately. Notion's public
-API is small and slow-moving enough for the named surface to cover it, so
-there is no \`notion_api_*\` to reach for — an operation absent from the tool
-list is absent from this connection, not hidden behind a generic call.
-
-## Writes and pagination
-
-- Notion has **no idempotency key**. A retried \`create_page\` or
-  \`add_comment\` creates a duplicate. Confirm with \`search\` before repeating
-  a write that may have partially succeeded.
-- List tools take \`page_size\` (max 100) and return \`has_more\` with
-  \`next_cursor\`. Pass a cursor back verbatim — it is opaque and must never be
-  parsed or constructed. Follow pages inside \`execute_code\` and reduce there.
-${accountInstructions
-        ? `\n## Workspace instructions\n\n${accountInstructions}\n`
-        : ""}`;
+Workspace purpose: ${purpose}${skill.fragments.guide_0}${accountInstructions ? `\n## ${skill.instructionsHeading}\n\n${accountInstructions}\n` : ""}`;
 }
-/** Release-reviewed Notion MCP inventory and safety verdicts. */
-export const NOTION_MCP_VETTED_CATALOG = vettedCatalog({
-    reads: new Set([
-        "notion-search",
-        "notion-search-skills",
-        "notion-fetch",
-        "notion-download-attachment",
-        "notion-query-data-sources",
-        "notion-query-meeting-notes",
-        "notion-search-agents",
-        "notion-list-agents",
-        "notion-query-sessions",
-        "notion-search-sessions",
-        "notion-get-session-status",
-        "notion-wait-session",
-        "notion-list-session-events",
-        "notion-read-session-event",
-        "notion-get-comments",
-        "notion-get-teams",
-        "notion-get-users",
-        "notion-get-async-task",
-    ]),
-    writes: new Map([
-        ["notion-create-file-upload", "additive"],
-        ["notion-create-attachment", "additive"],
-        ["notion-create-pages", "additive"],
-        ["notion-duplicate-page", "additive"],
-        ["notion-create-database", "additive"],
-        ["notion-create-folder", "additive"],
-        ["notion-create-view", "additive"],
-        ["notion-spawn-session", "additive"],
-        ["notion-send-message-to-session", "additive"],
-        ["notion-create-comment", "additive"],
-        ["notion-update-page", "destructive"],
-        ["notion-convert-page-to-skill", "destructive"],
-        ["notion-move-pages", "destructive"],
-        ["notion-update-data-source", "destructive"],
-        ["notion-update-view", "destructive"],
-        ["notion-stop-session", "destructive"],
-    ]),
-});
+/**
+ * Reviewed in #705's provider audit against https://developers.notion.com/guides/mcp/mcp-supported-tools.
+ * Retains the release-reviewed inventory, including names absent from today's
+ * public reference. Live annotations were not reverified without credentials.
+ * No schema digest is asserted without a captured schema to review.
+ */
+const NOTION_MCP_CLASSIFICATION = {
+    tools: {
+        "notion-search": { "verdict": "read", "reason": "Retrieves Notion  information without changing vendor state." },
+        "notion-search-skills": {
+            "verdict": "read",
+            "reason": "Retrieves Notion skills information without changing vendor state.",
+        },
+        "notion-fetch": {
+            "verdict": "read",
+            "reason": "Retrieves Notion fetch information without changing vendor state.",
+        },
+        "notion-download-attachment": {
+            "verdict": "read",
+            "reason": "Reads attachment content; creating uploads and attachments uses separate writes.",
+        },
+        "notion-query-data-sources": {
+            "verdict": "read",
+            "reason": "Retrieves Notion query data sources information without changing vendor state.",
+        },
+        "notion-query-meeting-notes": {
+            "verdict": "read",
+            "reason": "Retrieves Notion query meeting notes information without changing vendor state.",
+        },
+        "notion-search-agents": {
+            "verdict": "read",
+            "reason": "Retrieves Notion agents information without changing vendor state.",
+        },
+        "notion-list-agents": {
+            "verdict": "read",
+            "reason": "Retrieves Notion agents information without changing vendor state.",
+        },
+        "notion-query-sessions": {
+            "verdict": "read",
+            "reason": "Retrieves Notion query sessions information without changing vendor state.",
+        },
+        "notion-search-sessions": {
+            "verdict": "read",
+            "reason": "Retrieves Notion sessions information without changing vendor state.",
+        },
+        "notion-get-session-status": {
+            "verdict": "read",
+            "reason": "Retrieves Notion session status information without changing vendor state.",
+        },
+        "notion-wait-session": {
+            "verdict": "read",
+            "reason": "Waits for existing session state; it does not start or message a session.",
+        },
+        "notion-list-session-events": {
+            "verdict": "read",
+            "reason": "Retrieves Notion session events information without changing vendor state.",
+        },
+        "notion-read-session-event": {
+            "verdict": "read",
+            "reason": "Retrieves Notion read session event information without changing vendor state.",
+        },
+        "notion-get-comments": {
+            "verdict": "read",
+            "reason": "Retrieves Notion comments information without changing vendor state.",
+        },
+        "notion-get-teams": {
+            "verdict": "read",
+            "reason": "Retrieves Notion teams information without changing vendor state.",
+        },
+        "notion-get-users": {
+            "verdict": "read",
+            "reason": "Retrieves Notion users information without changing vendor state.",
+        },
+        "notion-get-async-task": {
+            "verdict": "read",
+            "reason": "Retrieves Notion async task information without changing vendor state.",
+        },
+        "notion-create-file-upload": { "verdict": "write", "reason": "Allocates upload state for a workspace file." },
+        "notion-create-attachment": {
+            "verdict": "write",
+            "reason": "create attachment creates or appends Notion state; it has side effects.",
+        },
+        "notion-create-pages": {
+            "verdict": "write",
+            "reason": "create pages creates or appends Notion state; it has side effects.",
+        },
+        "notion-duplicate-page": {
+            "verdict": "write",
+            "reason": "duplicate page creates or appends Notion state; it has side effects.",
+        },
+        "notion-create-database": {
+            "verdict": "write",
+            "reason": "create database creates or appends Notion state; it has side effects.",
+        },
+        "notion-create-folder": {
+            "verdict": "write",
+            "reason": "create folder creates or appends Notion state; it has side effects.",
+        },
+        "notion-create-view": {
+            "verdict": "write",
+            "reason": "create view creates or appends Notion state; it has side effects.",
+        },
+        "notion-spawn-session": {
+            "verdict": "write",
+            "reason": "Starts asynchronous agent work and creates session state.",
+        },
+        "notion-send-message-to-session": {
+            "verdict": "write",
+            "reason": "Appends a message to a running session and may trigger further work.",
+        },
+        "notion-create-comment": {
+            "verdict": "write",
+            "reason": "create comment creates or appends Notion state; it has side effects.",
+        },
+        "notion-update-page": {
+            "verdict": "destructive",
+            "reason": "update page changes existing Notion state or removes it.",
+        },
+        "notion-convert-page-to-skill": {
+            "verdict": "destructive",
+            "reason": "Changes the role and content of an existing workspace page.",
+        },
+        "notion-move-pages": {
+            "verdict": "destructive",
+            "reason": "move pages changes existing Notion state or removes it.",
+        },
+        "notion-update-data-source": {
+            "verdict": "destructive",
+            "reason": "update data source changes existing Notion state or removes it.",
+        },
+        "notion-update-view": {
+            "verdict": "destructive",
+            "reason": "update view changes existing Notion state or removes it.",
+        },
+        "notion-stop-session": { "verdict": "destructive", "reason": "Stops an existing session and interrupts its work." },
+    },
+};
 function mcpUsageGuide(purpose, instructions) {
     const accountInstructions = instructions?.trim();
-    return `# Notion MCP usage
-
-Official MCP interface: tool names, descriptions, argument schemas, and result
-schemas come from Notion's live server. Connecta preserves that catalog and
-only fills in release-reviewed safety annotations when Notion leaves them out.
-
-Workspace purpose: ${purpose}
-
-- Discover the live catalog before assuming a tool exists. Notion can gate
-  tools by workspace, account, client, and rollout independently of Connecta.
-- Start broad discovery with \`notion-search\`, then use \`notion-fetch\` on
-  the exact page, database, data source, or object before changing it.
-- Use the live input schema as the contract. Notion owns these MCP schemas;
-  the REST schemas in Connecta's API interface do not apply to MCP tools with
-  similar names.
-- Session and agent tools can launch asynchronous work. Read session state and
-  events before sending another message, waiting, or stopping a session.
-- File uploads and attachment tools create durable workspace state. Keep
-  downloads inside the requested task and do not expose signed attachment URLs.
-- An \`auth_required\` failure means this connector's OAuth grant is missing or
-  expired. Run \`authorize_connector\` for this connector id, then retry.
-${accountInstructions
-        ? `\n## Workspace instructions\n\n${accountInstructions}\n`
-        : ""}`;
+    return `${skill.fragments.guide_1}${purpose}${skill.fragments.guide_2}${accountInstructions ? `\n## ${skill.instructionsHeading}\n\n${accountInstructions}\n` : ""}`;
 }
-function notionMcp(id, purpose, options) {
+function notionMcp(id, purpose, options, provider) {
     const connector = remoteMcp(id, {
         url: NOTION_MCP_ENDPOINT,
-        ...defined({
-            authScope: options.authScope,
-            callAdmission: options.callAdmission,
-            maxResultBytes: options.maxResultBytes,
-        }),
+        ...provider.connectorOptions,
         title: options.title ?? "Notion (MCP)",
         description: `Notion's official hosted MCP interface: ${purpose}`,
         auth: { type: "oauth" },
         requireHttps: true,
+        classify: provider.classify,
         usageGuide: {
             content: mcpUsageGuide(purpose, options.instructions),
             summary: "Official MCP. Live Notion schemas, object discovery, sessions, agents, attachments, and OAuth ownership.",
             required: true,
         },
     });
-    return withVettedCatalog(connector, NOTION_MCP_VETTED_CATALOG);
+    return connector;
 }
 function notionApi(id, purpose, options) {
     const defaultPageSize = options.defaultPageSize ?? DEFAULT_PAGE_SIZE;
-    if (!Number.isInteger(defaultPageSize) ||
-        defaultPageSize < 1 ||
-        defaultPageSize > MAX_PAGE_SIZE) {
+    if (!Number.isInteger(defaultPageSize) || defaultPageSize < 1 || defaultPageSize > MAX_PAGE_SIZE) {
         throw new Error(`notion() defaultPageSize must be a whole number between 1 and ${MAX_PAGE_SIZE}.`);
     }
     return api(id, {
         ...(options.authScope ? { authScope: options.authScope } : {}),
-        title: options.title ?? "Notion",
-        description: `Notion workspace — ${purpose}`,
+        title: options.title ?? "Notion integration",
+        description: `Notion internal integration: ${purpose}`,
         credential: {
             label: options.credentialLabel ?? "Notion integration token",
             description: "Internal integration token from notion.so/profile/integrations. Every page or database the agent should reach must also be shared with that integration, and its capabilities decide which tools succeed — comment capabilities are off by default.",
@@ -1685,31 +1660,43 @@ function notionApi(id, purpose, options) {
             catch (error) {
                 return {
                     ok: false,
-                    message: error instanceof ConnectorCallError
-                        ? error.message
-                        : "Notion rejected the token.",
+                    message: error instanceof ConnectorCallError ? error.message : "Notion rejected the token.",
                 };
             }
         },
         callAdmission: NOTION_ADMISSION,
         usageGuide: {
             content: apiUsageGuide(purpose, options.instructions),
-            summary: "Database-to-data-source lookup, property write rules, lean-vs-raw results, and Notion's overloaded 403/404.",
+            summary: "Internal integration identity. Exact REST queries, JSON blocks, properties, paging and bot-scoped content writes.",
             required: true,
         },
         tools: buildTools(defaultPageSize),
-        ...(options.maxResultBytes !== undefined
-            ? { maxResultBytes: options.maxResultBytes }
-            : {}),
+        ...(options.maxResultBytes !== undefined ? { maxResultBytes: options.maxResultBytes } : {}),
     });
 }
+/** The closed options notion() accepts; see `assertKnownOptions`. */
+const NOTION_OPTIONS = variants("surface", {
+    api: optionsOf()({
+        ...keys("title", "authScope", "purpose", "instructions", "maxResultBytes"),
+        ...keys("surface", "credentialLabel", "defaultPageSize"),
+    }).shape,
+    mcp: optionsOf()({ ...PROVIDER_COMMON, ...keys("surface") }).shape,
+}, "mcp");
 /** A maintained Notion connection using the selected provider interface. */
-export function notion(id, options) {
+export const notion = defineProvider({
+    name: "notion",
+    title: "Notion",
+    kind: "composed",
+    readme: "Notion",
+    bundle: { "baselineGzip": 145300, "maxGzip": 205300 },
+    skill,
+    options: NOTION_OPTIONS,
+    classify: NOTION_MCP_CLASSIFICATION,
+    create: notionConnector,
+});
+function notionConnector(id, options, provider) {
     const purpose = options.purpose.trim();
-    if (!purpose) {
-        throw new Error("notion() requires a non-empty workspace purpose.");
-    }
-    return options.surface === "mcp"
-        ? notionMcp(id, purpose, options)
-        : notionApi(id, purpose, options);
+    return options.surface === "api" ? notionApi(id, purpose, options) : notionMcp(id, purpose, options, provider);
 }
+/** @deprecated Read `notion.definition.classify` instead. Kept for existing imports. */
+export const NOTION_MCP_VETTED_CATALOG = reviewedCatalog(notion.definition.classify, 'defineProvider("notion")');