@zackbart/connecta 0.18.0 → 0.18.1

package/CHANGELOG.md

@@ -2,6 +2,61 @@
 
 All notable changes to this package are documented here.
 
+## 0.18.1 — 2026-08-18
+
+This patch is the response to one long investigation run against a live
+deployment: a Mixpanel-and-Stripe user-journey reconstruction that rated the
+connectors trustworthy and the ceremony too high. Nothing breaks and no
+constructor changes. The two maintained guides now say the things that
+investigation had to discover the hard way — which questions Insights cannot
+answer, when Mixpanel's `false` is an absent property, which Stripe reads must
+be projected inside the sandbox and why that is a privacy boundary as much as
+a size one, and which fields Stripe search will not filter on. Beside them, a
+new maintained RevenueCat connection lands, with the fact that decides its
+deployment shape stated up front: a RevenueCat secret key reaches exactly one
+project, so several projects are several connectors. A deployment that
+constructs none of the three connections can ignore this release entirely.
+
+### Added
+
+- **`revenuecat()` — a maintained RevenueCat hosted-MCP connection** at
+  `@zackbart/connecta/providers/revenuecat`. OAuth by default (account-scoped:
+  the guide requires `list-projects` first and carries `project_id` into every
+  project-scoped call, stopping on ambiguity); an API v2 secret key as the
+  headless alternative, which binds the connector to one project — the guide's
+  first line names it, and a second project is a second connector with its own
+  key. All 95 documented tools are classified from RevenueCat's tools reference
+  (50 read-only, 15 additive, 29 destructive); `render-paywall-screenshot`
+  carries no access column there and fails closed. Borderline verdicts are
+  argued beside the rows they decide: `create-webhook-integration`,
+  `grant-customer-entitlement`, and `assign-customer-offering` are destructive
+  on consequence, not on verb. RevenueCat publishes six per-domain rate limits
+  and one admission rule cannot honestly cover 95 tools, so `callAdmission`
+  stays with the operator and the guide states the numbers. The maintainer-run
+  drift check accepts `revenuecat` behind `CONNECTA_DRIFT_REVENUECAT_KEY`; no
+  schema digests are recorded until a maintainer runs `--record` against a live
+  project (#433).
+
+### Changed
+
+- **The Mixpanel guide says what Insights cannot answer.** One analysis is one
+  `execute_code` program with one `Get-Query-Schema` fetch; per-user event
+  timelines and sequence questions are out of reach through `Run-Query`
+  (`Get-User-Replays-Data` covers one user only where session replay is on);
+  `false` on a boolean property may be an absent one and must be confirmed with
+  `List-Properties` before it becomes a signal; breakdown responses are
+  flattened one row per combination inside the program with `$overall`
+  dropped. Convention P7 gains the rendering-rule clause this rests on (#430).
+
+- **The Stripe guide names the reads that must be projected and the fields
+  search cannot filter.** Any `stripe_api_read` list or `stripe_api_search`
+  that returns full objects belongs inside `execute_code`, projected before
+  `return` — the reduction keeps customer PII out of the transcript, not only
+  bytes. Charges search takes a documented field set with no `payment_intent`;
+  follow the PaymentIntent's `latest_charge` instead. The account → search →
+  details → read sequence is one program, and decline outcomes are `outcome`,
+  `failure_code`, `failure_message` on the charge (#431).
+
 ## 0.18.0 — 2026-08-13
 
 This minor release spends fewer tokens before the first call and answers

package/README.md

@@ -2,133 +2,94 @@
 
 ![A monochrome clay Connecta hub joining many tools](https://raw.githubusercontent.com/zackbart/connecta/main/assets/connecta-clay-hero.png)
 
-One place for AI agents to connect to the tools you choose.
+One MCP endpoint. The integrations you chose. Your agent reaches them by
+writing code instead of loading a thousand tool definitions.
 
-Connecta gives an agent a single MCP endpoint instead of making it connect to
-every service separately. You decide which integrations are available and
-Connecta holds their credentials, and the agent mostly works by writing
-ordinary JavaScript that Connecta runs in a sandbox next to them — with a few
-explicit tools for the jobs a program is the wrong shape for, destructive calls
-among them.
+## The mental model
 
-```mermaid
-flowchart LR
-    Agent["AI agent"]
-    Integrations["The integrations you chose"]
-
-    subgraph Connecta["Connecta: one MCP endpoint; credentials stay here"]
-        Sandbox["execute_code<br/>server-side sandbox"]
-        Explicit["Explicit tools<br/>destructive calls, search, auth"]
-    end
-
-    Agent -->|"writes a program"| Sandbox
-    Agent -->|"one deliberate call"| Explicit
-    Sandbox --> Integrations
-    Explicit --> Integrations
-```
+You ask your agent a question that touches a service — Linear, Stripe, an
+internal API, anything you have connected. Here is what happens:
 
-## Why Connecta
+1. The agent talks to one endpoint, yours, and sees seven tools. Always seven,
+   no matter how many services sit behind it.
+2. It writes a short JavaScript program. Connecta runs it in a sandbox next to
+   your integrations. The program can search for tools, call them, chain the
+   calls, and shape the result.
+3. Only the answer comes back into the agent's context — not raw pages of
+   API output.
+4. If the agent wants to change something — create, update, delete — it
+   cannot do that from a program. It makes one explicit call, and your MCP
+   client can put that call in front of you first.
 
-- **One connection.** Configure clients once, even as integrations change.
-- **Seven tools, not seven hundred.** A program can search the catalog, chain
-  calls, and trim the results before the agent ever sees them — so nothing has
-  to be loaded up front.
-- **Safer access.** Credentials stay server-side — the program never sees them
-  — and consequential actions remain explicit and individual.
-- **Named client access.** A Clerk operator can issue and revoke one-time,
-  hashed Bearer tokens for MCP clients that support header authentication.
-- **Your deployment.** Connecta runs on Node, Docker, or Cloudflare Workers,
-  with configuration you can review and version.
+Credentials never leave the server. The program never sees them, and neither
+does the agent.
 
-## Start here
+```mermaid
+flowchart TB
+    Client["Your MCP client<br/>Claude, Cursor, …"]
 
-Create the prescribed Node deployment:
+    subgraph Connecta["Connecta — one endpoint, seven tools, your credentials"]
+        Sandbox["execute_code<br/>the agent's program runs here<br/>read-only tools only"]
+        Explicit["call_destructive_tool<br/>one visible call per write<br/>your client can ask you first"]
+    end
 
-```sh
-npx @zackbart/connecta init my-connecta
-cd my-connecta
-npm install
-CONNECTA_TOKEN=dev-token npm start
-```
+    Integrations["The integrations you chose<br/>Linear · Stripe · Notion · your HTTP API · any MCP server"]
 
-Point an MCP client at `http://localhost:8787/mcp` with
-`Authorization: Bearer dev-token`. The generated project is deliberately small:
-
-```text
-my-connecta/
-├── src/index.ts       # connectors, auth, storage, public URL
-├── src/file-activity.ts # deployment-owned activity store, wired on request
-├── package.json       # exact Connecta and QuickJS versions
-├── tsconfig.json
-├── Dockerfile         # the same source, containerized
-├── docker-compose.yml # one service, state on a named volume
-├── .dockerignore
-├── .env.example
-├── .gitignore
-├── AGENTS.md
-├── CLAUDE.md -> AGENTS.md
-└── README.md
+    Client -->|"one connection"| Sandbox
+    Client --> Explicit
+    Sandbox -->|"reads"| Integrations
+    Explicit -->|"writes"| Integrations
 ```
 
-The same project runs as a long-lived container without changing a line of it:
-
-```sh
-cp .env.example .env    # set CONNECTA_TOKEN
-docker compose up -d --build
+This is the kind of thing the agent writes, not you:
+
+```js
+async () => {
+  const { nodes } = await tracker.list_issues({ state: "started" });
+  const byOwner = {};
+  for (const issue of nodes) {
+    (byOwner[issue.assignee?.name ?? "unassigned"] ??= []).push(issue.identifier);
+  }
+  return byOwner;
+}
 ```
 
-For an agent setting this up, the contract is:
-
-1. Edit `src/index.ts`; do not copy Connecta internals into the deployment.
-2. Keep the required `executor: quickJsExecutor()` configuration; without an
-   executor the deployment refuses to boot.
-3. Keep secrets in environment variables or a secret store, never source.
-4. Add connectors explicitly: import a maintained prebuilt provider
-   constructor when one exists, otherwise write a deliberate `remoteMcp()` or
-   `api()` connector. There is no registry to browse and nothing registers
-   itself.
-5. Run `npm run typecheck`, start the server, and run
-   `CONNECTA_TOKEN=... npm run doctor`. Doctor checks health, the executor, and
-   the exact seven-tool model-facing surface, then executes a harmless sandbox
-   program. The bearer stays in the environment rather than command history.
-
-The operator surface is the same in both shapes and off until you say so:
-Clerk sign-in, the credential vault, access-token issuance, and payload-free
-activity ship as commented configuration, each one a variable and an
-uncommented block away. The generated `README.md` walks through all four, and
-the [Worker example](./examples/worker/) does the same for KV and D1.
-
-Already have a deployment on an older version? `init` deliberately refuses to
-merge into it, so bringing one current is its own procedure:
-[Upgrading an existing deployment](./documentation/upgrading.md) is the
-runbook, written for the agent working inside that project.
-
-The template refuses to merge into an existing directory, so initialization
-cannot overwrite another project. Its generated programs have no filesystem,
-environment, arbitrary network, imports, or timers; only explicitly read-only
-connector tools are reachable. Unannotated or write-capable calls stay
-individual and cross `call_destructive_tool`, where the MCP host can ask the
-operator for approval.
-
-The Node template also pins its one approved dependency install script:
-esbuild, which `tsx` needs to run the deployment source. A dependency update
-that adds or changes an install script fails the package smoke until reviewed.
-
-There are two deployment shapes and no others:
-
-- [Node, local or Docker](./templates/node/) — what `init` copies
-- [Cloudflare Worker deployment](./examples/worker/)
-- [Subsystem documentation](./documentation/)
-
-Every deployment configures a sandbox: QuickJS on Node or a Dynamic Worker on
-Cloudflare. Construction fails with an actionable error when the executor is
-missing, so the model-facing interface is always the same seven tools.
-
-## Project status
-
-Connecta is built for its author's deployments first and is still evolving.
-Breaking changes are expected before 1.0.
-
-Read the [ethos](./ethos.md) for the product's principles, the
-[changelog](./CHANGELOG.md) for releases, and [security policy](./SECURITY.md)
-for vulnerability reporting.
+Fifty issues in, one small object out. Your context window notices.
+
+## What you can do with it
+
+- **Put every MCP server you use behind one connection.** Add or remove
+  services in a config file; your client never changes.
+- **Wrap any HTTP API by hand.** A few lines per tool. No OpenAPI conversion —
+  generated tool sprawl is the problem, not the fix.
+- **Use maintained connections** for Cloudflare, Linear, Mixpanel, Notion,
+  RevenueCat, and Stripe — known endpoints, auth defaults, and vetted read/write
+  classifications, imported one at a time.
+- **Let the agent work in code.** Search, chain, filter, join, and reduce
+  inside the sandbox instead of round-tripping every call through the model.
+- **Keep writes deliberate.** Only tools marked read-only run in a program.
+  Everything else is a separate, visible call your client can gate.
+- **Run it where you like.** Node, a Docker container, or a Cloudflare Worker,
+  from the same small deployment file.
+
+There is also an operator surface, off until you turn it on: sign-in, an
+encrypted credential vault with rotation, revocable per-client tokens, and a
+payload-free activity log.
+
+Connecta is not a platform, a marketplace, a policy engine, or a multi-tenant
+service. Those are decisions, and the [ethos](./ethos.md) records each one
+and why.
+
+## Getting started
+
+Setup is written for an agent. Point yours at [`AGENTS.md`](./AGENTS.md) and
+ask it to set up a Connecta deployment; the
+[documentation](./documentation/) covers every subsystem if you want to go
+deeper, and [upgrading](./documentation/upgrading.md) an existing deployment
+is its own runbook.
+
+## Status
+
+Built for its author's deployments first and published openly. Breaking
+changes are expected before 1.0. See the [changelog](./CHANGELOG.md) and
+[security policy](./SECURITY.md).

package/dist/providers/mixpanel.js

@@ -184,7 +184,10 @@ Account purpose: ${purpose}
 - \`Get-Business-Context\` requires either \`project_id\` or \`organization_id\`. Its schema marks both optional, but the hosted tool rejects a call with neither.
 - \`Get-Property-Values\` requires \`properties\` or the deprecated \`property\` alias. Event property values also require \`event\`; prefer \`properties\` and never send both property forms with conflicting values.
 - \`List-Properties\` accepts \`names\` or \`query\`, never both. Use exact \`names\` for known properties and \`query\` for substring discovery.
-- For a new analysis, fetch \`Get-Query-Schema\` before \`Run-Query\`. Reduce query results inside \`execute_code\` before returning them.
+- One analysis is one \`execute_code\` program: fetch \`Get-Query-Schema\` once, run every \`Run-Query\` of the analysis in that program, and return the reduced table. The schema is tens of kilobytes and the same for every report type, so re-fetching it per query buys nothing. Never return raw \`Run-Query\` output.
+- Insights, funnels, and retention answer aggregate questions. A per-user ordered event timeline, or a sequence question such as "event A with no later event B", is not answerable with \`Run-Query\` in a reasonable number of calls, and this hosted catalog has no per-\`distinct_id\` event timeline — \`Get-User-Replays-Data\` covers one user's replays with their events only where session replay is enabled and present. If the deployment exposes a Mixpanel export or activity-feed connector, use that; if it does not, tell the user the question is out of reach here rather than approximating it with hourly buckets and hundreds of empty rows.
+- \`false\` on a boolean property may be an absent property: Mixpanel renders a missing value as \`false\` in boolean breakdowns, and server-imported events often lack client-side properties entirely. Confirm the property is present with \`List-Properties\` or \`Get-Property-Values\` before treating \`false\` as a signal, and say when a conclusion rests on that ambiguity.
+- Breakdown responses nest \`$overall\` and per-segment series objects. Flatten to one row per complete breakdown combination inside \`execute_code\` before returning, and drop \`$overall\` unless the question asks for the total.
 - Use \`Get-Report\` when the request names an existing saved report. Use \`Run-Query\` for a new question.
 - This account's tool list is not a fixed set. Mixpanel gates parts of its MCP catalog by plan and beta enrollment — experiments, feature flags, session replay, and issue triage are the usual absentees — so search this connector for what it actually exposes rather than assuming a documented tool is here.
 - Mixpanel meters MCP traffic per user per hour, shared with everything else that credential does. Reuse discovery results within a run and avoid speculative fan-out.

package/dist/providers/revenuecat.d.ts

@@ -0,0 +1,77 @@
+import { type RemoteMcpAuth } from "../connectors/remote-mcp.js";
+import type { Connector, ConnectorCallAdmissionPolicy } from "../types.js";
+/** RevenueCat publishes one hosted MCP endpoint, streamable HTTP. */
+export declare const REVENUECAT_MCP_ENDPOINT = "https://mcp.revenuecat.ai/mcp";
+export interface RevenueCatOptions {
+    /**
+     * Human-readable display name; defaults to "RevenueCat" for OAuth and
+     * "RevenueCat (single project)" for a static API v2 secret key. The scope
+     * shape rides the title because it is the one routing fact connecta can
+     * know at construction: an `sk_` key reaches exactly one project, an OAuth
+     * session reaches every project the account can. *Which* project a key
+     * reaches is not knowable here (P10 — no credential test), so the guide's
+     * first line carries the operator's stated purpose instead.
+     */
+    title?: string;
+    /**
+     * Which project this connector is for and what decisions it answers. With
+     * headers auth this is the only place the project a key reaches is named,
+     * so it goes in the guide's first line and its summary.
+     */
+    purpose: string;
+    /**
+     * OAuth by default; static headers support a RevenueCat API v2 secret key
+     * as `Authorization: Bearer sk_…`.
+     */
+    auth?: RemoteMcpAuth;
+    /** Project-specific conventions appended to the maintained provider guide. */
+    instructions?: string;
+    /** Connector-specific inline result limit; omit to inherit the deployment. */
+    maxResultBytes?: number;
+    /**
+     * Optional per-runtime call-admission policy. Deliberately not defaulted,
+     * even though RevenueCat does publish numbers.
+     *
+     * API v2 meters per *domain*, and the domains disagree by a factor of
+     * nineteen: Customer Information 480/min, Virtual Currencies 480/min,
+     * Subscription Transactions Refunds 480/min, Audiences 60/min, Project
+     * Configuration 60/min, Charts & Metrics 25/min
+     * (https://www.revenuecat.com/docs/api-v2#tag/Rate-Limit, read 2026-08-18).
+     * A `ConnectorCallAdmissionPolicy` carries exactly one rule, so a
+     * connector-wide budget has to pick one of those six numbers for all ninety-
+     * five tools. Transcribing 25 would throttle a customer read loop to a
+     * nineteenth of its documented allowance; transcribing 480 would leave a
+     * chart sweep unprotected. Neither is the provider's limit, and both would
+     * look like RevenueCat being flaky.
+     *
+     * The metering scope says the same thing again: the limit applies per API
+     * key for app-level keys and per *developer* for developer-level keys, so
+     * an OAuth session shares one budget with everything else that developer
+     * does — which a per-runtime counter cannot approximate in either
+     * direction. So the number stays with the operator who knows the account,
+     * exactly as P12 prescribes; `documentation/revenuecat.md` shows how to
+     * supply one.
+     */
+    callAdmission?: ConnectorCallAdmissionPolicy;
+}
+/**
+ * The manifest this release reviewed: both lists in one place, which is what
+ * makes the classification the connector applies and the drift check that runs
+ * beside it the same fact (P13). Ninety-four of the ninety-five tools
+ * RevenueCat's reference lists on 2026-08-18 are classified; the ninety-fifth,
+ * `render-paywall-screenshot`, has no access column to classify from and fails
+ * closed.
+ *
+ * No schema digests. No release has read RevenueCat's live schemas and written
+ * them down — that needs a live project and a maintainer's own `sk_` key — and
+ * an invented digest would report a change that never happened.
+ * `npm run drift:check -- --record` reads them from a live catalog and prints
+ * the block to paste in
+ * ([#351](https://github.com/zackbart/connecta/issues/351)).
+ *
+ * Exported because the maintainer-run check compares against this manifest and
+ * *names* what moved, which the runtime check deliberately cannot.
+ */
+export declare const REVENUECAT_VETTED_CATALOG: import("../catalog-drift.js").VettedCatalog;
+/** A maintained RevenueCat hosted-MCP connection. */
+export declare function revenuecat(id: string, options: RevenueCatOptions): Connector;