@zackbart/connecta 0.28.0 → 0.29.0

package/dist/providers/notion/skill.generated.js

@@ -0,0 +1,10 @@
+// Generated by scripts/generate-providers.mjs; do not edit.
+export const skill = {
+    "content": "\n## Identity before routing\n\nThis explicit `surface: \"api\"` connection acts as an internal integration.\nIts `integration_*` tools are canonical for bot-scoped/headless operations.\nHosted MCP is the default and acts as its OAuth-authorized user. Authorization\nis not equivalent: an integration token cannot authorize hosted MCP, and user\nOAuth cannot reproduce the integration bot's ownership/sharing boundary.\nConfigure each under a separate connector id and authorize it independently.\nDo not switch to a user identity to recover a failed integration operation.\n\nUse the bot tools when the task requires that integration identity. Use hosted\n`notion-search`, `notion-fetch`, `notion-get-users`, `notion-get-comments`,\n`notion-create-pages`, `notion-update-page`, and `notion-create-comment` for\nuser-owned content work. Hosted MCP additionally covers sessions, agents,\nattachments and broader workspace operations. REST tool names are not MCP aliases.\n\n\n\n## Databases contain data sources\n\nA Notion database is a container; the rows and the schema live in a *data\nsource* inside it. The two ids are not interchangeable and Notion rejects the\nwrong one.\n\n- The id in a Notion database URL is a **database id**.\n- `integration_get_database` turns it into the `data_sources` list — usually one entry.\n- `integration_get_data_source_schema` and `integration_query_data_source` take that\n  **data_source_id**, and so does `integration_create_page` when adding a row.\n\nSo the sequence for \"find rows in this database\" is `integration_get_database` →\n`integration_get_data_source_schema` → `integration_query_data_source`. `integration_search` returns data\nsources directly and skips the first step.\n\n## Property quirks that break writes\n\n- Property names in filters, sorts, and writes must match the schema exactly,\n  including case. Read `integration_get_data_source_schema` before composing one.\n- `select` and `status` writes must use an existing option name; inventing\n  one fails. The schema lists the valid options.\n- Writes **replace** a property. Sending one item to a `multi_select` or\n  `relation` drops the others, so send the complete intended value.\n- `rollup`, `formula`, `unique_id`, and the created/edited fields are\n  computed. They cannot be written.\n- A page's title column is rarely called \"title\" — pass `title_property` from\n  the schema when creating or updating a row.\n- Notion truncates `title`, `rich_text`, `relation`, and `people` at 25\n  entries. `integration_get_page` reports each one in `truncated_properties` as\n  `{ name, id }`; pass that `id` as `property_id` to\n  `integration_get_page_property` for the complete value.\n\n## Reading page content\n\n`integration_get_page` returns properties. `integration_get_page_content` returns the body as flat\nblocks. Nested blocks (toggles, list children, table rows) need `depth`, and\neach level multiplies requests — a deep read stops at an internal ceiling and\nreports `truncated: true` rather than spending the whole rate-limit budget.\n\n## Appending is append-only\n\n`integration_append_blocks` adds children and nothing else. It cannot move, reorder, or\nreplace an existing block, and a block appended through the API can never be\nrelocated by it afterwards. Get the position right the first time with\n`position` and `after_block_id`. Notion caps one call at 100 blocks.\n\n## Lean by default, raw on request\n\nEvery read projects Notion's payload down to ids, plain text, and flattened\nproperty values. Where the dropped detail can matter — `integration_search`, `integration_get_page`,\n`integration_get_page_content`, `integration_get_page_property`, `integration_get_data_source_schema`,\n`integration_query_data_source`, `integration_list_comments` — pass `raw: true` to get Notion's\nuntouched response instead. It is much larger; reach for it only when a\nspecific field is missing. Narrow `integration_query_data_source` and `integration_get_page` with\n`properties` instead whenever the goal is fewer fields, not more.\n\n`integration_get_page_content` with `raw: true` returns one level exactly as Notion\nsent it and does not walk nested children, so `depth` is ignored alongside\nit. A block type this projection does not model keeps its payload under\n`raw` on the block itself, so nothing silently flattens to an empty string.\n\n## Failures worth reading carefully\n\n- **404** means \"no such object\" *or* \"not shared with this integration\", and\n  Notion will not say which. Never conclude a page was deleted from it; check\n  that the page is shared with the integration in Notion.\n- **403** is not an expired token. The integration is missing a capability\n  (comment capabilities are off by default) or the object was never shared.\n  Re-authorizing cannot fix it; an operator must change it in Notion.\n- **429** carries a retry window. Notion allows roughly three requests per\n  second per integration, so wait it out rather than retrying immediately.\n\n## No escape hatch\n\nThis connection has no guarded raw-REST tool, deliberately. Notion's public\nAPI is small and slow-moving enough for the named surface to cover it, so\nthere is no `notion_api_*` to reach for — an operation absent from the tool\nlist is absent from this connection, not hidden behind a generic call.\n\n## Writes and pagination\n\n- Notion has **no idempotency key**. A retried `integration_create_page` or\n  `integration_add_comment` creates a duplicate. Confirm with `integration_search` before repeating\n  a write that may have partially succeeded.\n- List tools take `page_size` (max 100) and return `has_more` with\n  `next_cursor`. Pass a cursor back verbatim — it is opaque and must never be\n  parsed or constructed. Follow pages inside `execute_code` and reduce there.\n# Notion MCP usage\n\nOfficial MCP interface: tool names, descriptions, argument schemas, and result\nschemas come from Notion's live server. Connecta preserves that catalog and\napplies release-reviewed classification. Reviewed writes stay writes even when Notion claims they only read.\n\nWorkspace purpose: \n\n- This connection acts as its OAuth-authorized user. The separately configured\n  `surface: \"api\"` connection retains required internal-integration operations\n  under `integration_*` names, including headless content writes, cursor-complete\n  queries, exact JSON blocks and property items. No identity fallback occurs.\n- Discover the live catalog before assuming a tool exists. Notion can gate\n  tools by workspace, account, client, and rollout independently of Connecta.\n- Start broad discovery with `notion-search`, then use `notion-fetch` on\n  the exact page, database, data source, or object before changing it.\n- Use the live input schema as the contract. Notion owns these MCP schemas;\n  the REST schemas in Connecta's API interface do not apply to MCP tools with\n  similar names.\n- Session and agent tools can launch asynchronous work. Read session state and\n  events before sending another message, waiting, or stopping a session.\n- File uploads and attachment tools create durable workspace state. Keep\n  downloads inside the requested task and do not expose signed attachment URLs.\n- An `auth_required` failure means this connector's OAuth grant is missing or\n  expired. Run `authorize_connector` for this connector id, then retry.\n",
+    "instructionsHeading": "Workspace instructions",
+    "fragments": {
+        "guide_0": "\n## Identity before routing\n\nThis explicit `surface: \"api\"` connection acts as an internal integration.\nIts `integration_*` tools are canonical for bot-scoped/headless operations.\nHosted MCP is the default and acts as its OAuth-authorized user. Authorization\nis not equivalent: an integration token cannot authorize hosted MCP, and user\nOAuth cannot reproduce the integration bot's ownership/sharing boundary.\nConfigure each under a separate connector id and authorize it independently.\nDo not switch to a user identity to recover a failed integration operation.\n\nUse the bot tools when the task requires that integration identity. Use hosted\n`notion-search`, `notion-fetch`, `notion-get-users`, `notion-get-comments`,\n`notion-create-pages`, `notion-update-page`, and `notion-create-comment` for\nuser-owned content work. Hosted MCP additionally covers sessions, agents,\nattachments and broader workspace operations. REST tool names are not MCP aliases.\n\n\n\n## Databases contain data sources\n\nA Notion database is a container; the rows and the schema live in a *data\nsource* inside it. The two ids are not interchangeable and Notion rejects the\nwrong one.\n\n- The id in a Notion database URL is a **database id**.\n- `integration_get_database` turns it into the `data_sources` list — usually one entry.\n- `integration_get_data_source_schema` and `integration_query_data_source` take that\n  **data_source_id**, and so does `integration_create_page` when adding a row.\n\nSo the sequence for \"find rows in this database\" is `integration_get_database` →\n`integration_get_data_source_schema` → `integration_query_data_source`. `integration_search` returns data\nsources directly and skips the first step.\n\n## Property quirks that break writes\n\n- Property names in filters, sorts, and writes must match the schema exactly,\n  including case. Read `integration_get_data_source_schema` before composing one.\n- `select` and `status` writes must use an existing option name; inventing\n  one fails. The schema lists the valid options.\n- Writes **replace** a property. Sending one item to a `multi_select` or\n  `relation` drops the others, so send the complete intended value.\n- `rollup`, `formula`, `unique_id`, and the created/edited fields are\n  computed. They cannot be written.\n- A page's title column is rarely called \"title\" — pass `title_property` from\n  the schema when creating or updating a row.\n- Notion truncates `title`, `rich_text`, `relation`, and `people` at 25\n  entries. `integration_get_page` reports each one in `truncated_properties` as\n  `{ name, id }`; pass that `id` as `property_id` to\n  `integration_get_page_property` for the complete value.\n\n## Reading page content\n\n`integration_get_page` returns properties. `integration_get_page_content` returns the body as flat\nblocks. Nested blocks (toggles, list children, table rows) need `depth`, and\neach level multiplies requests — a deep read stops at an internal ceiling and\nreports `truncated: true` rather than spending the whole rate-limit budget.\n\n## Appending is append-only\n\n`integration_append_blocks` adds children and nothing else. It cannot move, reorder, or\nreplace an existing block, and a block appended through the API can never be\nrelocated by it afterwards. Get the position right the first time with\n`position` and `after_block_id`. Notion caps one call at 100 blocks.\n\n## Lean by default, raw on request\n\nEvery read projects Notion's payload down to ids, plain text, and flattened\nproperty values. Where the dropped detail can matter — `integration_search`, `integration_get_page`,\n`integration_get_page_content`, `integration_get_page_property`, `integration_get_data_source_schema`,\n`integration_query_data_source`, `integration_list_comments` — pass `raw: true` to get Notion's\nuntouched response instead. It is much larger; reach for it only when a\nspecific field is missing. Narrow `integration_query_data_source` and `integration_get_page` with\n`properties` instead whenever the goal is fewer fields, not more.\n\n`integration_get_page_content` with `raw: true` returns one level exactly as Notion\nsent it and does not walk nested children, so `depth` is ignored alongside\nit. A block type this projection does not model keeps its payload under\n`raw` on the block itself, so nothing silently flattens to an empty string.\n\n## Failures worth reading carefully\n\n- **404** means \"no such object\" *or* \"not shared with this integration\", and\n  Notion will not say which. Never conclude a page was deleted from it; check\n  that the page is shared with the integration in Notion.\n- **403** is not an expired token. The integration is missing a capability\n  (comment capabilities are off by default) or the object was never shared.\n  Re-authorizing cannot fix it; an operator must change it in Notion.\n- **429** carries a retry window. Notion allows roughly three requests per\n  second per integration, so wait it out rather than retrying immediately.\n\n## No escape hatch\n\nThis connection has no guarded raw-REST tool, deliberately. Notion's public\nAPI is small and slow-moving enough for the named surface to cover it, so\nthere is no `notion_api_*` to reach for — an operation absent from the tool\nlist is absent from this connection, not hidden behind a generic call.\n\n## Writes and pagination\n\n- Notion has **no idempotency key**. A retried `integration_create_page` or\n  `integration_add_comment` creates a duplicate. Confirm with `integration_search` before repeating\n  a write that may have partially succeeded.\n- List tools take `page_size` (max 100) and return `has_more` with\n  `next_cursor`. Pass a cursor back verbatim — it is opaque and must never be\n  parsed or constructed. Follow pages inside `execute_code` and reduce there.\n",
+        "guide_1": "# Notion MCP usage\n\nOfficial MCP interface: tool names, descriptions, argument schemas, and result\nschemas come from Notion's live server. Connecta preserves that catalog and\napplies release-reviewed classification. Reviewed writes stay writes even when Notion claims they only read.\n\nWorkspace purpose: ",
+        "guide_2": "\n\n- This connection acts as its OAuth-authorized user. The separately configured\n  `surface: \"api\"` connection retains required internal-integration operations\n  under `integration_*` names, including headless content writes, cursor-complete\n  queries, exact JSON blocks and property items. No identity fallback occurs.\n- Discover the live catalog before assuming a tool exists. Notion can gate\n  tools by workspace, account, client, and rollout independently of Connecta.\n- Start broad discovery with `notion-search`, then use `notion-fetch` on\n  the exact page, database, data source, or object before changing it.\n- Use the live input schema as the contract. Notion owns these MCP schemas;\n  the REST schemas in Connecta's API interface do not apply to MCP tools with\n  similar names.\n- Session and agent tools can launch asynchronous work. Read session state and\n  events before sending another message, waiting, or stopping a session.\n- File uploads and attachment tools create durable workspace state. Keep\n  downloads inside the requested task and do not expose signed attachment URLs.\n- An `auth_required` failure means this connector's OAuth grant is missing or\n  expired. Run `authorize_connector` for this connector id, then retry.\n"
+    }
+};

package/dist/providers/overflow/index.d.ts

@@ -0,0 +1,60 @@
+import type { ConnectorCallAdmissionPolicy } from "../../types.js";
+/**
+ * Overflow's two published environments. They are separate deployments with
+ * separate credentials: a staging key works only against staging and a
+ * production key only against production.
+ */
+export declare const OVERFLOW_API_BASE_URLS: {
+    readonly production: "https://server.overflow.co";
+    readonly staging: "https://server.stage.overflow.co";
+};
+/** Which Overflow environment a connection talks to. */
+export type OverflowEnvironment = keyof typeof OVERFLOW_API_BASE_URLS;
+/** Options for the maintained Overflow connection. */
+export interface OverflowOptions {
+    /**
+     * Required, with no default. Production is live donor data and real money;
+     * staging is a separate sandbox with its own credentials. Neither is a safe
+     * thing to land on by omission — see the constructor for the argument.
+     */
+    environment: OverflowEnvironment;
+    /** Which nonprofit this connection reaches, and for whom. */
+    purpose: string;
+    /** Human-readable display name; defaults name the environment. */
+    title?: string;
+    /** Nonprofit-specific conventions appended to the maintained guide. */
+    instructions?: string;
+    /** Downstream auth ownership. Defaults to one shared deployment grant. */
+    authScope?: "shared" | "personal";
+    /**
+     * Replaces the default per-runtime admission policy, which transcribes
+     * Overflow's documented 120 requests per minute per client.
+     */
+    callAdmission?: ConnectorCallAdmissionPolicy;
+    /** Connector-specific inline result limit; omit to inherit the deployment. */
+    maxResultBytes?: number;
+    /** Default page size for page-numbered list tools. Defaults to 25; Overflow caps it at 100. */
+    defaultPageSize?: number;
+    /**
+     * API origin override for a proxy or test double. Connecta appends
+     * `/api/v3`. The declared `environment` still names what the proxy reaches.
+     */
+    baseUrl?: string;
+}
+/**
+ * A maintained Overflow connection.
+ *
+ * `environment` is required with no default, and the argument runs the other
+ * way from a provider whose environment rides the credential. Overflow
+ * publishes two base URLs and issues separate credentials for each, so a
+ * mismatch fails loudly with a 403 rather than reaching the wrong data — but
+ * that is exactly why a default buys nothing. Defaulting to staging, the
+ * "safe" side, sends every real deployment to a sandbox where its production
+ * key is refused with a generic "Forbidden resource" and no hint that the base
+ * URL is the problem. Defaulting to production makes a test deployment that
+ * forgot the option one pasted key away from charging real donors through the
+ * mutate hatch. The environment is a fact the operator knows and connecta
+ * cannot infer — Overflow's keys carry no recognizable environment marker — so
+ * the operator states it, and the title and the guide's first line repeat it.
+ */
+export declare const overflow: import("../../provider.js").ProviderFactory<OverflowOptions>;