@zackbart/connecta 0.24.2 → 0.24.4

package/documentation/mixpanel.md

@@ -1,160 +0,0 @@
-# Mixpanel prebuilt connection
-
-Import `mixpanel()` independently from
-`@zackbart/connecta/providers/mixpanel`. It wraps Mixpanel's hosted MCP server
-with regional endpoint selection, OAuth by default, a task-oriented usage
-guide, and a vetted safety classification. It adds no provider dependency and
-is not reachable from Connecta's root entry.
-
-```ts
-import { mixpanel } from "@zackbart/connecta/providers/mixpanel";
-
-const analytics = mixpanel("product_analytics", {
-  title: "Production product analytics",
-  purpose: "Product and growth decisions for the production app",
-  region: "us",
-  instructions: "Use the Core Product project unless the request says otherwise.",
-});
-```
-
-The `id` owns the ordinary connector namespaces; use a different id for every
-Mixpanel account. `purpose` is required because an agent choosing between two
-instances needs to know which account answers the question. Account
-`instructions` are appended to the maintained guide and cannot change the
-connector's safety classification.
-
-`region` accepts `"us"` (the default), `"eu"`, or `"in"` and selects the
-corresponding [official hosted endpoint](https://docs.mixpanel.com/docs/mcp#mcp-server-urls).
-A project lives in exactly one residency, so the region also decides what this
-connection can see at all: a question pointed at the wrong one comes back empty
-rather than wrong, which reads as the project having no data. That makes it a
-routing fact, so it rides the default `title` (`Mixpanel (us)`, `Mixpanel
-(eu)`, `Mixpanel (in)`) and opens the usage guide — `search_tools` renders a
-connector's title and guide summary and never its description.
-OAuth is the recommended default and keeps each connector instance's flow and
-tokens in its connector-scoped storage. Mixpanel service accounts are also
-supported with an explicit header override:
-
-```ts
-mixpanel("automation_analytics", {
-  purpose: "Headless release-health reporting",
-  auth: {
-    type: "headers",
-    headers: { Authorization: `Bearer Basic ${env.MIXPANEL_SA_TOKEN}` },
-  },
-});
-```
-
-Keep that encoded service-account value in the runtime's secret store; it is a
-password, not ordinary configuration. Mixpanel currently labels service-account
-MCP authentication beta. Prefer OAuth unless the deployment is intentionally
-headless.
-
-The same service account can arrive from the connection UI at `/` instead, and there the
-operator pastes the readable pair rather than an encoded blob:
-
-```ts
-mixpanel("automation_analytics", {
-  purpose: "Headless release-health reporting",
-  auth: { type: "credential" },
-});
-```
-
-The slot renders as "Service account" and takes `username:secret`. Connecta
-base64-encodes it and sends Mixpanel's documented `Bearer Basic` framing, so the
-operator never has to encode anything by hand. **The two paths take different
-strings:** the `headers` example above wants the already-encoded blob
-(`echo -n "username:secret" | base64`), and this one wants the plaintext pair.
-Migrating from one to the other means decoding, not copying. Until a value is
-saved the connector is present and reports `auth_required`. See
-[storage and credentials](./storage-and-credentials.md#a-remote-mcp-connectors-static-credential).
-
-## Conditional input contracts
-
-Mixpanel's hosted descriptions enforce three cross-field conditions that its
-input schemas do not encode. Connecta preserves those schemas unchanged under
-[P1](./provider-conventions.md#p1--normalize-by-adding-never-by-rewriting), so
-the maintained guide carries the missing call guidance:
-
-- `Get-Business-Context` requires `project_id` or `organization_id`.
-- `Get-Property-Values` requires `properties` or the deprecated `property`
-  alias. Event property values also require `event`.
-- `List-Properties` accepts `names` or `query`, never both.
-
-A read-only live audit on 2026-08-13 confirmed all three refusals against the
-US hosted endpoint. They are reported upstream as
-[`mixpanel/mixpanel-headless#202`](https://github.com/mixpanel/mixpanel-headless/issues/202).
-The vetted catalog records current schema digests for all 64 tools,
-so a later schema correction or regression increments runtime drift when an
-ordinary catalog refresh observes it. The live definition is still served
-unchanged. The credential-free provider check does not depend on those digests.
-The guide can shrink when the downstream schema becomes complete; Connecta does
-not absorb the defect permanently.
-
-The wrapper classifies the documented observational tools as reads and the
-documented create, update, edit, merge, dismiss, duplicate, and delete tools as
-writes. An unfamiliar tool the downstream leaves unannotated fails closed onto
-`call_destructive_tool` until a Connecta release reviews it.
-
-That classification fills in downstream silence and otherwise preserves
-explicit annotations. A tool on the read allowlist arriving with
-`destructiveHint: true` or `readOnlyHint: false` keeps exactly what the
-downstream said and stays behind `call_destructive_tool`. A tool on neither
-maintained list arriving with `readOnlyHint: true` keeps that too, and stays
-callable from `execute_code`. Both are the downstream telling you this
-release's allowlist is stale, and on a name no release has reviewed its word is
-the only evidence there is. One narrow fail-closed exception applies to a name
-this release reviewed and filed destructive: a `Delete-Dashboard` claiming
-`readOnlyHint: true` is a downstream bug rather than news, and stays on the
-approval path. Maintained writes that only create
-something new (`Create-Dashboard`, `Create-Cohort`, `Create-Metric`, and the
-rest) leave `destructiveHint` unset; `readOnlyHint: false` already routes them
-through the destructive path, and asserting destruction only inflates the
-approval copy the host shows a human.
-
-Experiments and Feature Flags are Mixpanel beta surfaces. Their three changed
-schemas were reviewed again on 2026-08-30. The same review added
-`Fill-Event-Metadata` as a destructive write because it applies generated names
-and descriptions to existing Lexicon events.
-
-## Rate limits
-
-Mixpanel meters its MCP server **per user per hour**, shared with everything
-else that credential does. Connecta's counter is per runtime, not per user, and
-the two cannot be reconciled in either direction: one runtime serving several
-users under-counts, and several Worker isolates or Node processes sharing one
-credential each admit a full budget. A hardcoded ceiling would therefore either
-throttle a healthy deployment or fail to protect a busy one, so this connection
-declares **no call-admission budget by default**. An operator who knows the
-account can supply one explicitly:
-
-```ts
-mixpanel("product_analytics", {
-  purpose: "Product and growth decisions for the production app",
-  callAdmission: {
-    rules: [
-      { budget: { kind: "rolling-window", maxCalls: 300, windowMs: 3_600_000 } },
-    ],
-  },
-});
-```
-
-A budget-only rule needs no queue. If you add `maxConcurrency` you are asking
-for a queue, and the admission controller then requires the rest of the queue
-settings at construction. Discovery traffic is outside connector call admission
-either way and still needs restrained use.
-
-## Public contract check
-
-`npm run drift:check -- --docs --provider mixpanel` compares Mixpanel's
-official Available Tools table with the vetted manifest and checks all three
-regional endpoints plus OAuth support. The current table lists 63 tools. It
-omits `Fill-Event-Metadata`, which remains classified from the last
-authenticated review and is reported as `not documented`, not silently removed.
-
-## Conventions
-
-This connection is audited against
-[the provider conventions](./provider-conventions.md). Its verdict per
-convention, including every recorded exception, is the Mixpanel section of
-[the provider audit](https://github.com/zackbart/connecta/blob/main/records/provider-audit.md).

package/documentation/notion.md

@@ -1,308 +0,0 @@
-# Notion prebuilt connection
-
-Import `notion()` independently from `@zackbart/connecta/providers/notion`. It
-offers two deployment-time interfaces. The default is a hand-written `api()`
-surface over Notion's public REST API: fifteen deliberate tools, lean
-projections of Notion's famously bloated payloads, typed failures, a rate
-budget matched to the documented limit, and a required usage guide. The other
-choice is Notion's official hosted MCP with live provider-owned schemas and a
-broader workspace, files, views, agents, and sessions catalog. Neither is
-reachable from Connecta's root entry.
-
-```ts
-import { notion } from "@zackbart/connecta/providers/notion";
-
-const wiki = notion("engineering_wiki", {
-  surface: "api", // optional; this is the backward-compatible default
-  title: "Engineering wiki",
-  purpose: "Runbooks, specs, and on-call notes for the platform team",
-  instructions: "Prefer the Runbooks database; specs live under Projects.",
-});
-```
-
-Use Notion's hosted MCP instead:
-
-```ts
-const workspace = notion("notion_mcp", {
-  surface: "mcp",
-  purpose: "Workspace search, files, views, and asynchronous agent sessions",
-});
-```
-
-The `id` owns the ordinary connector namespaces; use a different id for every
-Notion workspace. `purpose` is required because an agent choosing between two
-instances needs to know which workspace answers the question. Workspace
-`instructions` are appended to the maintained guide and cannot change the
-connector's safety classification.
-
-## Choosing an interface
-
-Use the API interface for its compact, stable projections. A single Notion
-page returns every property as a
-discriminated wrapper object, every string as an array of rich-text runs each
-carrying its own annotations block, and every user reference as a nested
-object. A twenty-five row database query is tens of kilobytes of structure
-around a few hundred bytes of meaning. Hand-writing the surface is what makes
-the projections possible, and the projections are the point.
-
-Use `surface: "mcp"` for Notion's wider official capabilities, including
-connected-source search, attachments, saved views, Notion Skills, agents, and
-asynchronous sessions. Tool names and schemas come from the live server.
-Connecta preserves them and only fills in release-reviewed safety annotations
-when Notion is silent. OAuth is the hosted server's authentication contract.
-Do not apply the hand-written REST schemas to similarly named MCP tools. The
-MCP interface accepts `callAdmission` for an operator-supplied runtime policy;
-it does not assume the REST interface's endpoint budget describes MCP traffic.
-
-## API authentication
-
-One operator-managed credential: an internal integration token from
-[notion.so/profile/integrations](https://www.notion.so/profile/integrations).
-The deployment needs `vault: encryptedCredentialVault(storage, encryptionKey)` configured, or the token
-cannot be stored and every call fails `auth_required` at use.
-
-Two Notion-specific facts decide whether a working token is enough:
-
-- **Sharing is per object.** A token reaches only what has been explicitly
-  shared with its integration. An unshared page returns 404, not 403.
-- **Capabilities are per integration**, and the comment capabilities are off by
-  default. `list_comments` and `add_comment` fail with 403 until an operator
-  turns them on in Notion.
-
-The connection UI at `/` offers a Test action, which calls `GET /v1/users/me` — the
-cheapest call that proves a token is live — and reports the workspace it
-authenticated into.
-
-The MCP interface uses Notion OAuth instead of the integration-token form. An
-`auth_required` failure means the grant is absent or expired and must be
-completed again through `authorize_connector`.
-
-## The pinned API version
-
-The connection pins `Notion-Version: 2026-03-11` and offers no override. That
-is deliberate rather than lazy. Notion's versions are date-named and old ones
-keep working indefinitely, so an override would look harmless; it is not.
-`2026-03-11` is the version in which databases split into data sources,
-`archived` became `in_trash`, and block append took a `position` object instead
-of an `after` string. Every projection and write body here assumes those
-shapes, so a deployment that pinned an older version would get quietly wrong
-results instead of a loud failure.
-
-Notion also ships *additive* changes to every version simultaneously, which is
-why the property and block projections fall back to unwrapping an unknown
-type's payload rather than switching exhaustively. A property type that ships
-after this release degrades to its raw value, and a block type that does keeps
-its payload under `raw`; neither vanishes.
-
-The remaining sections document the hand-written API interface. MCP tool
-arguments and results are intentionally read from the live server instead.
-
-## API tools
-
-Ten reads, all annotated `readOnlyHint: true`:
-
-| Tool | What it is for |
-| --- | --- |
-| `search` | Find pages and data sources by **title**. Never searches content. |
-| `get_page` | One page's metadata and flattened property values. |
-| `get_page_content` | A page's body as flat blocks reduced to plain text. |
-| `get_page_property` | One property in full, past the 25-entry truncation. |
-| `get_database` | A database container and the data sources inside it. |
-| `get_data_source_schema` | Property ids, types, and select/status options. |
-| `query_data_source` | Filtered, sorted rows with properties already flattened. |
-| `list_users` | Workspace users and bots with their ids. |
-| `get_self` | Which integration and workspace this connector authenticates as. |
-| `list_comments` | Unresolved comments as plain text with discussion ids. |
-
-Five writes, none read-only, so all of them route through
-`call_destructive_tool`:
-
-| Tool | Classification |
-| --- | --- |
-| `create_page` | additive |
-| `append_blocks` | additive |
-| `add_comment` | additive |
-| `update_page_properties` | `destructiveHint: true` — replaces existing values |
-| `trash_page` | `destructiveHint: true` — removes a page from reads |
-
-The additive three leave `destructiveHint` unset: `readOnlyHint: false` already
-routes them through the approval path, and claiming a create destroys something
-only inflates the copy a host shows a human. `update_page_properties`
-deliberately has no `in_trash` argument, so an update can never trash a page by
-accident; trashing is its own named, reversible tool.
-
-## Lean projections, and the raw escape hatch
-
-Every read projects. A page becomes ids, plain text, and flattened values:
-`title` and `rich_text` collapse to strings, `select` and `status` to their
-option name, `multi_select` to an array of names, `relation` to an array of
-page ids, `people` to `{ id, name }`, `unique_id` to `"RL-12"`, and
-`formula`/`rollup` to their computed value. No `plain_text` runs, no
-`annotations` blocks, no property wrappers survive.
-
-Two projections are opinionated enough to call out:
-
-- **`search` returns identity fields only** — no properties at all. A
-  twenty-five result search across a populated database would otherwise drag
-  back several hundred flattened values for results the agent is about to
-  discard. `get_page` fetches properties for the one that matched.
-- **`get_page` reports what Notion hid.** Notion paginates four property types
-  — `title`, `rich_text`, `relation`, and `people` — cutting each off at 25
-  entries and signalling it only with a `has_more` flag on the property itself.
-  The projection surfaces those in `truncated_properties` as `{ name, id }`,
-  which is what stops an agent from confidently reasoning about 25 of 300
-  relations. The `id` is there because the handoff needs it: `get_page_property`
-  addresses a property by id, not by name.
-
-Where the dropped detail can matter — `search`, `get_page`, `get_page_content`,
-`get_page_property`, `get_data_source_schema`, `query_data_source`,
-`list_comments` — `raw: true` returns Notion's untouched response instead. It is
-much larger; it exists so a missing field is never a dead end. When the goal is
-*fewer* fields rather than more, `get_page` and `query_data_source` also take a
-`properties` array to project only the named ones.
-
-One caveat with `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, not three.
-Unmodelled *block* types are covered without it — a block whose type this
-projection does not know, and whose payload is not plain rich text, keeps that
-payload verbatim under `raw` on the block, so nothing collapses to an empty
-string.
-
-## Databases contain data sources
-
-This is the trap the guide is marked `required` for. A Notion database is a
-container; the rows and the schema live in a *data source* inside it, and the
-two ids are not interchangeable. The id in a database's URL is a **database
-id**, and passing it to `query_data_source` fails. The sequence is
-`get_database` → `get_data_source_schema` → `query_data_source`; `search`
-returns data sources directly and skips the first step.
-
-`create_page` needs the same distinction: a row is created under
-`parent_data_source_id`, never a database id. Its title also needs
-`title_property` from the schema, because a database's title column is rarely
-called "title".
-
-## Typed failures
-
-The mapping is deliberately not one-to-one with Notion's error codes. Notion's
-`code` says what its API thinks happened; Connecta's says what the caller
-should do next, and two of Notion's are easy to mistranslate.
-
-| Notion | Connecta | Why |
-| --- | --- | --- |
-| 400 (`validation_error`, `invalid_json`, `invalid_request`, `missing_version`, …) | `invalid_args` | every documented 400 is a malformed request |
-| 401 `unauthorized` | `auth_required` | the token is missing or invalid |
-| 403 `restricted_resource` | `connector_call_failed`, non-retryable | **not** `auth_required` |
-| 404 `object_not_found` | `connector_call_failed`, non-retryable | overloaded — deliberately **not** `not_found`; see below |
-| 409 `conflict_error` | `unavailable`, retryable | Notion says to retry |
-| 429 `rate_limited` | `rate_limited` + `retryAfterMs` | `Retry-After` seconds → ms |
-| 529 `service_overload` | `unavailable` + `retryAfterMs` | back off like a 429 |
-| 5xx | `unavailable`, retryable | upstream failure |
-
-The two that matter:
-
-**403 is not an authentication failure.** The token is fine; the integration
-lacks a capability or was never shared the object. Routing it to
-`auth_required` would send an agent to `authorize_connector`, which cannot
-grant a Notion capability or share a page. It is a non-retryable call failure
-whose message says an operator must change it in Notion.
-
-**404 does not prove absence.** Notion returns `object_not_found` both for an
-object that does not exist and for one that exists but has not been shared with
-the integration, and it will not say which. The message says both, because
-treating it as deletion is exactly how an agent concludes a page is gone when
-it was simply never shared. This is why the row above does not use `not_found`,
-which exists precisely to say "it is not there": the qualifier on that code
-([H11](./provider-conventions.md#h11--errors-are-mapped-to-what-the-caller-does-next))
-is that the provider must tell absence apart from a permission gap, and Notion
-does not. A program that skipped this id as missing would be right about half
-the time, which is the half that matters.
-
-## Rate limiting
-
-Notion documents "an average of three requests per second, with some bursts
-beyond the average allowed" per connection, plus a separate per-workspace limit
-scaled to the plan. The connection declares a rolling budget of 180 calls per
-minute — the same average expressed over a window short bursts pass and a
-sustained loop does not — **paired with `maxConcurrency: 3`**.
-
-The concurrency cap is the load-bearing half. A budget alone is an average, and
-an averaged budget cannot stop a program from firing forty calls in the same
-tick; the cap keeps a burst shaped roughly like the one Notion documents.
-Neither half is a guarantee, because admission meters *tool calls* rather than
-requests — a single admitted `get_page_content` can spend twenty fetches, so
-180 calls per minute is a floor on the real request rate, not a ceiling.
-Declaring the cap is also what makes the queue settings legal — the admission
-controller refuses queue settings without a queue at construction.
-
-Like every connector budget this is per-runtime: N Worker isolates or Node
-processes serving one deployment each keep their own counter. It approximates
-the provider's limit; it does not enforce it.
-
-One tool can turn a single agent call into several downstream requests:
-`get_page_content` with `depth > 0` walks nested blocks, and call admission
-meters tool calls, not the fetches inside them. That walk stops at an internal
-ceiling of twenty requests and reports `truncated: true` rather than spending
-the whole budget invisibly.
-
-## Pagination
-
-List-shaped tools take `page_size` (1–100) and `start_cursor`, and return
-`has_more` with `next_cursor`. The default page size is 25 rather than Notion's
-100, because a first read should be cheap; `defaultPageSize` raises it for a
-deployment that pages a lot.
-
-Cursors are opaque. Notion's own versioning page is explicit that they may
-change in length, format, and structure at any time and must be passed back
-verbatim — never parsed, validated, or constructed.
-
-## What the API interface does not do
-
-No file uploads, no database or data-source creation, no schema editing, no
-block updates or deletes, no page moves. Those are all real Notion endpoints
-and all deliberately absent: this is a deliberate tool surface, not a mirror of
-the API. Some are present on Notion's hosted MCP interface. Anything still
-missing is reachable through a custom `api()` connector beside this one, which
-remains a first-class path.
-
-The 2026-03-11 contract also offers more fields on create and update. They were
-reviewed after the 0.17.0 drift check and remain deliberately absent:
-
-- `create_page` does not create workspace-private pages, apply templates,
-  choose page placement, or accept expanded icon and cover forms. Those change
-  ownership, start asynchronous content work, control ordering, or depend on
-  file surfaces. They are not extensions of the maintained page/row authoring
-  contract (#408).
-- `update_page_properties` does not lock pages, apply templates, or erase page
-  content. Locking is coordination state, templates finish asynchronously, and
-  `erase_content` permanently deletes every child block through the API. None
-  belongs under an approval named for property replacement (#409).
-
-`trash_page` stays separate and reversible. The current `create_page`,
-`update_page_properties`, and `trash_page` request subsets remain valid against
-the expanded published contract.
-
-There is also **no guarded raw-REST escape hatch** — no `notion_api_get`, no
-`notion_api_mutate`. The convention that permits one
-([H14](./provider-conventions.md#h14--a-named-tool-must-beat-the-escape-hatch-and-the-escape-hatch-splits-by-safety))
-also permits a small provider to have none, provided it says so, and Notion's
-public API is finite and slow-moving enough that a named surface can cover it.
-The usage guide says it too, because an agent that assumes a hatch exists
-spends a search proving it does not: absent from the tool list means absent
-from this connection, not hidden behind a generic call.
-
-## Contract checks
-
-`npm run providers:check` compares the 14 fixed REST endpoints with Notion's
-published OpenAPI document and the 34 MCP names, endpoint, and OAuth support
-with Notion's official pages. It needs no Notion credential. The MCP schemas
-are not vendored or reconstructed: the live `tools/list` response remains the
-contract agents receive.
-
-## Conventions
-
-This connection is audited against
-[the provider conventions](./provider-conventions.md). Its verdict per
-convention, including every recorded exception, is the Notion section of
-[the provider audit](https://github.com/zackbart/connecta/blob/main/records/provider-audit.md).