@zackbart/connecta 0.18.0 → 0.18.1

package/dist/providers/revenuecat.js

@@ -0,0 +1,314 @@
+import { remoteMcp, } from "../connectors/remote-mcp.js";
+import { vettedCatalog, withVettedCatalog } from "../catalog-drift.js";
+/** RevenueCat publishes one hosted MCP endpoint, streamable HTTP. */
+export const REVENUECAT_MCP_ENDPOINT = "https://mcp.revenuecat.ai/mcp";
+/**
+ * Tools whose official contract is observational rather than mutating.
+ *
+ * Every name here carries `Read` in RevenueCat's own tool reference
+ * (https://www.revenuecat.com/docs/tools/mcp/tools-reference, read
+ * 2026-08-18). The list is a superset by design (P5): a name a project never
+ * serves costs nothing, while an unclassified new one fails closed onto
+ * `call_destructive_tool`.
+ */
+const READ_ONLY_TOOLS = new Set([
+    // Projects and apps
+    "get-account-billing",
+    "get-app",
+    "get-project-ui-config",
+    "list-account-billing-invoices",
+    "list-app-public-api-keys",
+    "list-apps",
+    "list-audit-logs",
+    "list-collaborators",
+    "list-projects",
+    // Products and prices
+    "get-product",
+    "get-product-store-state",
+    "get-product-store-state-operation",
+    "list-products",
+    // Entitlements
+    "get-entitlement",
+    "get-products-from-entitlement",
+    "list-entitlements",
+    // Offerings and packages
+    "get-offering",
+    "get-offering-prices",
+    "list-offerings",
+    "list-packages",
+    // Targeting and audiences
+    "get-audience",
+    "get-audience-filter-options",
+    "get-targeting-rule",
+    "list-audiences",
+    "list-targeting-rules",
+    // Paywalls
+    "get-paywall",
+    "list-paywalls",
+    // Customers and subscriptions
+    "get-customer",
+    "get-customer-center-config",
+    "get-subscription",
+    "list-customer-events",
+    "list-customers",
+    "list-purchases",
+    "list-subscriptions",
+    "list-virtual-currencies-balances",
+    // Virtual currencies
+    "get-virtual-currency",
+    "list-virtual-currencies",
+    // Charts, metrics, and experiments
+    "get-benchmarks",
+    "get-chart-data",
+    "get-chart-options-schema",
+    "get-experiment",
+    "get-experiment-results",
+    "get-overview-metrics",
+    "get-revenue-metric",
+    "list-experiments",
+    // Integrations and webhooks
+    "get-webhook-integration",
+    "list-webhook-integrations",
+    // SDK compatibility
+    "list-sdk-feature-gates",
+    "list-sdk-versions",
+    // Paywall editing. Polling an async task is a read; the two tools that
+    // *start* one are writes and sit below.
+    "get-paywall-ai-task",
+]);
+/**
+ * The maintained write catalog. `"destructive"` tools modify or remove state
+ * that already exists; `"additive"` ones only bring something new into being.
+ * Both leave the read-only path — the distinction only decides whether the
+ * connection asserts `destructiveHint`, which shapes the host's approval copy.
+ *
+ * Every name here carries `Write` in RevenueCat's tool reference. The mass
+ * verdicts follow the verb: `archive-*` and `unarchive-*` flip an existing
+ * object's active state, `update-*` and `delete-*` and `publish-*` and
+ * `unpublish-*` and `detach-*` change or remove something that already exists,
+ * and a plain `create-*` brings a new object into being beside the old ones.
+ *
+ * Nine verdicts are not decided by the verb, and each is argued where it sits:
+ * `create-product-prices`, `equalize-subscription-prices`,
+ * `validate-app-credentials`, `upload-product-store-state-screenshot`,
+ * `attach-products-to-entitlement`, `attach-products-to-package`,
+ * `duplicate-paywall`, `create-paywall-ai`, and `edit-paywall-ai`.
+ *
+ * `render-paywall-screenshot` is deliberately on neither list. RevenueCat's
+ * reference gives it no access column at all, and a tool nobody has classified
+ * fails closed (P5) rather than being guessed into the read path because its
+ * name sounds harmless.
+ */
+const WRITE_TOOLS = new Map([
+    // Projects and apps
+    ["create-app", "additive"],
+    ["create-project", "additive"],
+    ["update-app", "destructive"],
+    ["update-project-ui-config", "destructive"],
+    // "Checks one saved App Store or Google Play credential set." RevenueCat
+    // files it Write, so it does not reach the read path — but it leaves the
+    // credentials themselves alone and only records the outcome of a check.
+    // Additive: a verdict comes into being, nothing existing is overwritten.
+    ["validate-app-credentials", "additive"],
+    // Products and prices
+    ["archive-product", "destructive"],
+    ["create-product", "additive"],
+    // Named `create-`, described "Configure prices for a product". A product's
+    // price set already exists, and configuring it replaces what is there
+    // rather than adding a second price beside the first. Money-facing and
+    // overwriting, so: destructive, whatever the verb says.
+    ["create-product-prices", "destructive"],
+    // "Fills missing App Store subscription territory prices." By RevenueCat's
+    // own word it only writes where a price is absent, so nothing already set
+    // is changed. Additive.
+    ["equalize-subscription-prices", "additive"],
+    ["set-product-store-state", "destructive"],
+    ["submit-products-to-store", "destructive"],
+    ["unarchive-product", "destructive"],
+    ["update-product", "destructive"],
+    // "Reserves an App Store Connect review screenshot slot." A new slot comes
+    // into being; no existing screenshot is replaced by the reservation.
+    ["upload-product-store-state-screenshot", "additive"],
+    // Entitlements
+    ["archive-entitlement", "destructive"],
+    // Attach adds a product to a membership set and removes nothing;
+    // `detach-products-from-entitlement` is its destructive counterpart. Filing
+    // both destructive would make the pair read identically in the approval copy
+    // a human is shown, which is exactly the inflation P5 warns about.
+    ["attach-products-to-entitlement", "additive"],
+    ["create-entitlement", "additive"],
+    ["detach-products-from-entitlement", "destructive"],
+    ["unarchive-entitlement", "destructive"],
+    ["update-entitlement", "destructive"],
+    // Offerings and packages
+    ["archive-offering", "destructive"],
+    // The same attach/detach argument one level down.
+    ["attach-products-to-package", "additive"],
+    ["create-offering", "additive"],
+    ["create-packages", "additive"],
+    ["delete-package-from-offering", "destructive"],
+    ["detach-products-from-package", "destructive"],
+    ["unarchive-offering", "destructive"],
+    ["update-offering", "destructive"],
+    // Targeting and audiences
+    ["create-audience", "additive"],
+    ["update-audience", "destructive"],
+    // Paywalls
+    // "Duplicates an existing paywall's current draft." The original is
+    // untouched and a new paywall appears beside it. Additive.
+    ["duplicate-paywall", "additive"],
+    ["publish-paywall", "destructive"],
+    ["unpublish-paywall", "destructive"],
+    // Customers and subscriptions. Neither verb is in the mass rule and neither
+    // removes anything, so the file's own criterion would read them additive.
+    // They are destructive on consequence, the way `create_refund` is in
+    // `stripe.ts`: `assign-customer-offering` overrides which offering a live
+    // customer's app serves, and `grant-customer-entitlement` opens paid access
+    // to a real person without a store purchase (the promotional subscription it
+    // creates is the mechanism, not the point). Both change what a customer
+    // gets today, and both deserve the destructive approval copy.
+    ["assign-customer-offering", "destructive"],
+    ["grant-customer-entitlement", "destructive"],
+    // Virtual currencies
+    ["archive-virtual-currency", "destructive"],
+    ["create-virtual-currency", "additive"],
+    ["unarchive-virtual-currency", "destructive"],
+    ["update-virtual-currency", "destructive"],
+    // Integrations and webhooks
+    // A new integration is a new object, but one that "starts delivering
+    // RevenueCat events to the given url" — with filters omitted, every customer
+    // event in the project, to a URL the caller typed. That is customer data
+    // leaving the account on consequence, which is the `create_refund` argument
+    // again: the verb says additive, the effect says destructive, and the
+    // approval copy should say the latter.
+    ["create-webhook-integration", "destructive"],
+    ["delete-webhook-integration", "destructive"],
+    ["update-webhook-integration", "destructive"],
+    // Paywall editing. Both start an async task; what the task does decides the
+    // verdict. Creating a paywall leaves every existing one alone (additive);
+    // editing one rewrites a draft that already exists (destructive).
+    ["create-paywall-ai", "additive"],
+    ["edit-paywall-ai", "destructive"],
+]);
+/**
+ * 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 const REVENUECAT_VETTED_CATALOG = vettedCatalog({
+    reads: READ_ONLY_TOOLS,
+    writes: WRITE_TOOLS,
+});
+/** The catalog's summary bound; a longer declared value throws (`src/registry.ts`). */
+const SUMMARY_BUDGET = 120;
+/**
+ * Fit a purpose-bearing summary inside the catalog's bound.
+ *
+ * Stripe and Mixpanel declare static summaries because their routing fact is
+ * an enumerable variant. RevenueCat's is not: two `sk_` connectors have the
+ * same title, the same endpoint, and the same catalog, and differ only by the
+ * project the operator says each key reaches. So the summary carries that, and
+ * clipping is this function's job rather than the operator's.
+ */
+function boundedSummary(prefix, purpose) {
+    const full = `${prefix}${purpose}`;
+    if (full.length <= SUMMARY_BUDGET)
+        return full;
+    return `${full.slice(0, SUMMARY_BUDGET - 1).trimEnd()}…`;
+}
+function sharedUsageGuide() {
+    return `
+- Resolve ids before acting; never guess one. \`list-projects\` yields the \`project_id\` every project-scoped call takes. \`list-apps\`, \`list-products\`, \`list-entitlements\`, \`list-offerings\`, \`list-paywalls\`, \`list-audiences\`, and \`list-customers\` yield the ids their \`get-\`, \`update-\`, \`archive-\`, and \`delete-\` counterparts expect. A plausible-looking id belongs to another project or to nobody.
+- Customers are addressed by the app user id your SDK set, not by an internal key. Find one with \`list-customers\` before \`get-customer\`, and carry the id it returned unchanged.
+- Customer and subscription objects are large, and a customer's history is larger. Page with the cursor the list returned rather than raising the page size, and reduce inside \`execute_code\` — select the fields the question needs and return those, not the whole object.
+- Whether a customer should have access is \`gives_access\` on each subscription from \`list-subscriptions\`, which RevenueCat calls the authoritative flag. \`status\` and \`expires_date\` describe the store-side state and disagree with it during grace periods, billing retries, and promotional grants — answer access questions from \`gives_access\` and say which subscription it came from.
+- \`get-chart-data\` is the metrics path: read \`get-chart-options-schema\` for the chart you want before calling it, rather than guessing an option name. \`get-overview-metrics\` and \`get-revenue-metric\` answer the summary questions in one call.
+- \`create-paywall-ai\`, \`edit-paywall-ai\`, and \`set-product-store-state\` are asynchronous. They return a task or operation id; poll it with \`get-paywall-ai-task\` or \`get-product-store-state-operation\` rather than assuming the work finished when the call returned.
+- This connection's tool list is not a fixed set. RevenueCat gates parts of its MCP catalog by plan, platform, and beta enrollment — paywall AI editing, benchmarks, experiments, virtual currencies, and the account-billing tools are the usual absentees — so search this connector for what it actually exposes rather than assuming a documented tool is here.
+- \`render-paywall-screenshot\` is unclassified on purpose: RevenueCat's reference gives it no access column, so it fails closed onto \`call_destructive_tool\` until a release reviews it.
+- RevenueCat meters API v2 per minute and per domain, and the domains differ: 480 requests per minute for customer information and virtual currencies, 60 for project configuration and audiences, 25 for charts and metrics. It answers a breach with \`429\`, a \`Retry-After\` header, and a \`backoff_ms\` field. Back off on that rather than retrying immediately, and expect chart sweeps to hit the ceiling long before customer reads do.
+- Treat every create, update, archive, unarchive, attach, detach, delete, publish, unpublish, grant, assign, and submit operation as a write. Connecta routes the maintained write catalog through \`call_destructive_tool\`; newly added tools also fail closed until a release classifies them.
+- An \`auth_required\` failure means this connector's RevenueCat authorization is missing or expired: run \`authorize_connector\` for this connector id, then retry the same call unchanged. A rejected argument, a permission gap, or a plan restriction comes back in RevenueCat's own words instead — read it rather than re-authorizing.
+`;
+}
+function oauthUsageGuide(purpose, instructions) {
+    const projectInstructions = instructions?.trim();
+    return `# RevenueCat usage
+
+Account-scoped connection: this OAuth session reaches every RevenueCat project the account can see. Connector purpose: ${purpose}
+
+Call \`list-projects\` first and carry the exact \`project_id\` it returned into every project-scoped call. Connecta does not pick a project, and the connector id, title, and purpose are routing hints rather than proof of which project a call will land in. If more than one project fits the request, stop and ask; never guess a \`project_id\`.
+${sharedUsageGuide()}${projectInstructions
+        ? `\n## Project instructions\n\n${projectInstructions}\n`
+        : ""}`;
+}
+function keyUsageGuide(purpose, instructions) {
+    const projectInstructions = instructions?.trim();
+    return `# RevenueCat usage
+
+Single-project connection: ${purpose}. RevenueCat secret API keys are project-wide, so this key reaches exactly one project and nothing outside it. A second project is a second connector with its own key and its own id — never a \`project_id\` argument pointed somewhere else.
+
+Confirm the project on first use: \`list-projects\` returns the one project this key can see, and its \`project_id\` is the one every project-scoped call takes. An empty or unexpected result means wrong connector, not missing data.
+
+A RevenueCat secret key is issued read-only or write-enabled, and connecta cannot tell which this one is. It does not filter writes for a read-only key: every write is offered, reaches RevenueCat, and fails there in RevenueCat's own words. Read that refusal as "this key cannot write" rather than as a bad argument, and route the write to a connector configured with a write-enabled key.
+${sharedUsageGuide()}${projectInstructions
+        ? `\n## Project instructions\n\n${projectInstructions}\n`
+        : ""}`;
+}
+/** A maintained RevenueCat hosted-MCP connection. */
+export function revenuecat(id, options) {
+    const purpose = options.purpose.trim();
+    if (!purpose) {
+        throw new Error("revenuecat() requires a non-empty project purpose.");
+    }
+    const auth = options.auth ?? { type: "oauth" };
+    const scoped = auth.type === "headers";
+    const connector = remoteMcp(id, {
+        url: REVENUECAT_MCP_ENDPOINT,
+        // The scope shape rides the title because browse-time discovery renders
+        // the title and the guide summary and nothing else, and reaching one
+        // project versus every project the account has is the fact an agent must
+        // not get wrong between two RevenueCat connections.
+        title: options.title ?? (scoped ? "RevenueCat (single project)" : "RevenueCat"),
+        description: scoped
+            ? `RevenueCat subscriptions and revenue (one project, static key) — ${purpose}`
+            : `RevenueCat subscriptions and revenue (every project the account can reach) — ${purpose}`,
+        auth,
+        requireHttps: true,
+        usageGuide: {
+            content: scoped
+                ? keyUsageGuide(purpose, options.instructions)
+                : oauthUsageGuide(purpose, options.instructions),
+            // Explicit rather than derived, and purpose-bearing rather than static:
+            // the derived summary would cut the scoping sentence mid-clause at 120
+            // characters, and two static summaries would leave two `sk_` connectors
+            // indistinguishable in the one field search returns (P3).
+            summary: scoped
+                ? boundedSummary("One project only: ", purpose)
+                : boundedSummary("All account projects; list-projects first: ", purpose),
+            // Not `required`. RevenueCat's own schemas describe each call; the guide
+            // carries the project-resolution sequence, which is worth reading before
+            // a run rather than before every call.
+        },
+        ...(options.callAdmission !== undefined
+            ? { callAdmission: options.callAdmission }
+            : {}),
+        ...(options.maxResultBytes !== undefined
+            ? { maxResultBytes: options.maxResultBytes }
+            : {}),
+    });
+    return withVettedCatalog(connector, REVENUECAT_VETTED_CATALOG);
+}

package/dist/providers/stripe.js

@@ -173,7 +173,11 @@ function sharedUsageGuide(rate) {
 - Four generic tools reach any Stripe API method. Find the method with \`stripe_api_search\`, read its parameters with \`stripe_api_details\`, then call \`stripe_api_read\` (GET) or \`stripe_api_write\` (POST/PATCH/PUT/DELETE). Never guess a path or a parameter name — \`stripe_api_details\` is cheaper than a rejected write.
 - Prefer a dedicated tool when one covers the task: \`get_stripe_account_info\` for account information, \`get_balance_summary\` for balances, \`create_refund\` for refunds, \`stripe_report\` for reports. One call instead of three, and a refund named \`create_refund\` reads far more clearly in the approval a human sees than the same refund buried in \`stripe_api_write\` arguments.
 - \`stripe_api_write\` carries the blast radius of the entire write API — every POST, PATCH, PUT, and DELETE, from a customer edit to a subscription cancellation. State the method and path explicitly; expect approval on every call.
-- Lists are cursor-paginated: \`limit\` defaults to 10 and caps at 100, \`starting_after\` and \`ending_before\` take an object id and are mutually exclusive, and \`has_more\` says whether to continue. Page inside \`execute_code\` and reduce before returning.
+- Lists are cursor-paginated: \`limit\` defaults to 10 and caps at 100, \`starting_after\` and \`ending_before\` take an object id and are mutually exclusive, and \`has_more\` says whether to continue. Page inside \`execute_code\`.
+- Any \`stripe_api_read\` list or \`stripe_api_search\` that returns full objects belongs inside \`execute_code\`, projected to the fields the question needs before \`return\`. Neither \`limit\` nor \`expand\` substitutes for that: an unprojected list of customers or invoices truncates long before it answers, and a projected one keeps the customer's name, email, and address out of the transcript.
+- Search filters on a documented per-resource field set, not on arbitrary attributes. Charges search takes \`amount\`, \`created\`, \`currency\`, \`customer\`, \`status\`, \`refunded\`, \`disputed\`, \`metadata\`, \`billing_details.address.postal_code\`, and \`payment_method_details.<source>.*\` card fields — there is no \`payment_intent\` field. When the field you want is not searchable, retrieve the parent object and follow its reference (the PaymentIntent's \`latest_charge\`) instead of retrying the search with another spelling.
+- The account → \`stripe_api_search\` → \`stripe_api_details\` → \`stripe_api_read\` sequence is one program, not four turns: resolve the method once, then call that method as many times as the investigation needs in the same run.
+- Decline outcomes live on the charge — \`outcome\`, \`failure_code\`, \`failure_message\` — reached from the PaymentIntent's \`latest_charge\`, so "why did this payment fail" is a PaymentIntent read followed by one charge read.
 - Resolve ids before acting; never guess one. Stripe ids are typed prefixes — \`cus_\` customer, \`sub_\` subscription, \`ch_\` charge, \`pi_\` payment intent, \`in_\` invoice, \`acct_\` account — and a plausible-looking id belongs to a different object or to nobody. Find the object with \`stripe_api_search\` (or a list endpoint through \`stripe_api_read\`) and carry the \`id\` it returned into the write.
 - This connection's tool list is not a fixed set. Stripe gates parts of its MCP catalog by account, integration, and beta enrollment, so search this connector for what it actually exposes rather than assuming a documented tool is here.
 - Amounts are integers in the currency's minor unit: \`1099\` is 10.99 USD, and zero-decimal currencies like JPY take \`10\` for 10 JPY. Never send a decimal.

package/dist/version.d.ts

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export declare const CONNECTA_VERSION = "0.18.0";
+export declare const CONNECTA_VERSION = "0.18.1";

package/dist/version.js

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.18.0";
+export const CONNECTA_VERSION = "0.18.1";

package/documentation/connectors.md

@@ -122,6 +122,7 @@ Maintained provider guides:
 - [Linear](./linear.md)
 - [Mixpanel](./mixpanel.md)
 - [Notion](./notion.md)
+- [RevenueCat](./revenuecat.md)
 - [Stripe](./stripe.md)
 
 ## The `api()` construction contract

package/documentation/operations.md

@@ -249,6 +249,7 @@ in.
 | `remote-mcp.test.ts` | `remoteMcp()` against an in-process server through the `_transportFactory` seam: passthrough, downstream `isError`, Workers-safe output-schema validation, request-scoped client reuse and at-most-once scope close; plus the real transport's manual redirect policy, destination guard, credential containment, and downstream session termination |
 | `remote-mcp-pagination.test.ts` | the `tools/list` cursor chain in both directions — exact cursor handoff, first-wins dedup, a failed later page rejecting rather than returning its prefix, the runaway backstops, the tool-metadata re-prime across pages, and paginated catalogs reaching the discovery path |
 | `request-admission.test.ts` | `/mcp` bounded before auth, the stable 503 and `Retry-After`, health and operator responsiveness under saturation, payload-free counters, queued cancellation, shutdown rejection while active work drains, and the separate fallback code pool |
+| `revenuecat-provider.test.ts` / `revenuecat-registry.test.ts` | the RevenueCat proxy's per-project key scoping and account-wide OAuth guides, its purpose-bearing summary, the argued borderline verdicts in its digest-free manifest, and the deliberately unclassified `render-paywall-screenshot`; then two project-scoped keys as two connectors in a real deployment |
 | `server.test.ts` | end-to-end `/mcp` (401 → compact initialize instructions → seven compact definitions with bounded connector inventory → complete usage skill → `call_tool`), conditional guide pointers, open routes, Clerk `.well-known` metadata without network, code mode, and deferred catalog reads through both discovery surfaces |
 | `server-route-contracts.test.ts` | the route contracts `server.ts` must keep byte-identical: every built-in answered ahead of connector routes inside the security wrapper, open data-free shells with framing denied, per-route auth and same-origin requirements with exact 401/403/405 bodies, and OAuth `verifyState`-before-`finishAuth` ordering |
 | `startup-warnings.test.ts` | every construction-time `logger.warn` and, as importantly, the conditions that must *not* trigger one: open mode with a credential or OAuth connector, `publicUrl` unset beside OAuth, dropped branding and `uiAuth` URLs, a missing `verifyState`, a credential test-hook mismatch, and an unusable `calls.maxResultBytes` |

package/documentation/provider-audit.md

@@ -1,7 +1,7 @@
 # Provider audit
 
 [`provider-conventions.md`](./provider-conventions.md) wrote the bar down. This
-document runs it against the five maintained prebuilt connections and returns a
+document runs it against the six maintained prebuilt connections and returns a
 verdict for every applicable convention: **meets**, **misses** (with the fix),
 or **n/a** (with the reason). A convention is never quietly skipped, and an
 accepted miss is recorded as a provider-specific exception with its argument
@@ -147,6 +147,28 @@ Linear's reasoning.
 | P12 admission budget | **missed → fixed** | the connection hardcoded a 600-call hourly budget transcribed from a limit Mixpanel meters **per user**. P12 names this case exactly: a per-runtime counter cannot approximate a per-user quota in either direction — one runtime serving several users under-counts, several isolates sharing one credential each admit a full budget. The default is removed; `callAdmission` is now an operator option with a documented example, matching Linear |
 | P13 drift visible | meets | both lists are module-level constants in one file, and are the manifest the refresh-time drift check compares against ([#343](https://github.com/zackbart/connecta/issues/343)) |
 
+## RevenueCat — hosted-MCP proxy
+
+Written after the conventions existed, so it has no misses to record — only two
+places where the honest answer departs from the obvious one, both argued below.
+Ninety-five documented tools, ninety-four classified, one deliberately not.
+
+| Convention | Verdict | Notes |
+| --- | --- | --- |
+| P1 add, never rewrite | meets | `listTools` maps annotations and returns every other field untouched |
+| P2 identity | meets | required `purpose` (blank throws), `instructions` appended under `## Project instructions`, and appended text cannot reach the classification |
+| P3 routing fact | meets, with the fact split in two | the routing fact is scope, and it has two halves. The *shape* — one project versus every project the account can reach — is knowable at construction and rides the default title (`RevenueCat (single project)` versus `RevenueCat`). *Which* project a key opens is not knowable without calling something, which P10 forbids, so it rides the guide's first line and the declared summary, built from the operator's `purpose`. That makes this the one maintained proxy with a purpose-bearing summary rather than a static one, and the reason is P3's own cost: two `sk_` connectors share a title, an endpoint, and a catalog, so a static summary would leave them indistinguishable in the only field search returns |
+| P4 endpoint default | n/a — one endpoint, and the scope rides the credential | RevenueCat publishes a single MCP endpoint, so there is nothing to select between. The scope difference comes from the credential shape itself, which the constructor reads rather than asks for: `auth.type === "headers"` *is* the single-project declaration. There is no mode to default and no mode to contradict, so the P4 machinery Stripe needs has nothing to do here |
+| P5 classification | meets | 50 reads, 15 additive writes, 29 destructive writes named; `render-paywall-screenshot` is on neither list because RevenueCat's reference gives it no access column, and it fails closed. Nine borderline verdicts are argued beside the rows they decide, and asserted in the suite so a silent flip fails |
+| P6 catalog varies | meets | the guide names paywall AI editing, benchmarks, experiments, virtual currencies, and account billing as the plan-, platform-, and beta-gated areas where absence is expected, and separately names the unclassified tool so its approval prompt does not read as a bug |
+| P7 reduction advice | meets | structured guide, declared summary, cursor-then-reduce advice aimed at the two objects that are actually large here (customers and their event history). `required` stays unset: the project-resolution sequence is worth reading before a run, not before every call |
+| P8 identity resolution | meets | the guide names the whole chain — `list-projects` for the `project_id` every project-scoped call takes, then `list-apps`, `list-products`, `list-entitlements`, `list-offerings`, `list-paywalls`, `list-audiences`, and `list-customers` for the ids their `get-`, `update-`, `archive-`, and `delete-` counterparts expect — and says a plausible-looking id belongs to another project or to nobody. For OAuth it also says to stop and ask when more than one project fits |
+| P9 authentication | meets | OAuth default, `requireHttps`, the API v2 secret key documented as a secret and paired with the narrowest scope RevenueCat offers (one project). The guide names the `auth_required` → `authorize_connector` route, and separately says that a read-only key's refusal is RevenueCat's own words rather than an authorization gap connecta can repair |
+| P10 no credential test | meets | no `credential`, `testCredential`, or `testCredentials`. This is also where the constructor's most tempting option was refused: a `project?: string` checked against `list-projects` at construction is a credential test wearing a configuration hat, so the operator's stated purpose carries the claim and the agent confirms it on first use. There is no recognizable-credential contradiction to throw on either — an `sk_` key encodes no project — so the construction-time half of P10 has nothing to check here, exactly as it has nothing to check for Mixpanel's region |
+| P11 transport vs tool error | meets | inherited whole from `remoteMcp()`; the wrapper adds no error handling and reads no downstream prose. The guide says a rejected argument, a permission gap, and a plan restriction all arrive in RevenueCat's own words |
+| P12 admission budget | meets, by declining a number that exists | RevenueCat does publish limits, which is why this row needed an argument rather than a shrug. It meters per domain — 480/min for customer information, virtual currencies, and refunds; 60 for project configuration and audiences; 25 for charts and metrics — and a `ConnectorCallAdmissionPolicy` carries exactly one rule. Picking 25 throttles a customer read loop to a nineteenth of its allowance; picking 480 leaves a chart sweep unprotected; neither is the provider's limit. The metering scope repeats the point: developer-level keys are metered per developer, which a per-runtime counter cannot approximate. So the guide states RevenueCat's own numbers and the `429` / `Retry-After` / `backoff_ms` signals, and `callAdmission` stays an operator option with a documented example |
+| P13 drift visible | meets | both lists are module-level constants in one file and *are* the manifest the wrapper classifies from, compared against the live catalog on every refresh ([#343](https://github.com/zackbart/connecta/issues/343)). The maintainer-run check accepts `revenuecat` with `CONNECTA_DRIFT_REVENUECAT_KEY`. No schema digests are recorded, and the manifest says so rather than shipping invented ones |
+
 ## Scoreboard
 
 | Provider | Meets | Missed and fixed | Recorded exception | Open |
@@ -156,8 +178,9 @@ Linear's reasoning.
 | Linear | 11 | 2 | P4 departs from the letter | — |
 | Stripe | 10 | 3 | — | — |
 | Mixpanel | 7 | 5 | P10 half n/a | — |
+| RevenueCat | 12 | 0 | P4 n/a (one endpoint); P3 met with a purpose-bearing summary | — |
 
-Nineteen misses, nineteen fixes, four recorded exceptions, one judgment left to
+Nineteen misses, nineteen fixes, six recorded exceptions, one judgment left to
 the issue that owns it. The pattern in the misses is worth naming: sixteen of
 the nineteen are a guide, a title, or a schema description failing to *say*
 something the implementation already did correctly. Only three changed what a
@@ -166,3 +189,10 @@ access declaration, Mixpanel dropping a budget it could not honestly compute.
 The conventions are mostly not asking for different behavior. They are asking
 for the behavior to reach the agent, which is a different problem and, on this
 evidence, the one the providers were losing.
+
+RevenueCat is the first connection written *after* the conventions and adds no
+misses to those nineteen, which is the least interesting thing about its row.
+The interesting part is that two conventions came out somewhere other than
+their obvious reading — P4 has no endpoint to select and P12 declines a number
+the provider actually publishes — and both had to be argued rather than
+skipped. A convention that only ever returns "meets" is not being applied.

package/documentation/provider-conventions.md

@@ -1,6 +1,6 @@
 # Provider conventions
 
-The five maintained prebuilt connections grew one at a time, and until now
+The six maintained prebuilt connections grew one at a time, and until now
 "excellent provider" meant whatever the last author thought. This document
 writes the judgment down so it can be argued with, audited, and reused.
 
@@ -11,7 +11,7 @@ cannot honestly cover both:
   tool name, schema, projection, and error. Today: Cloudflare, Notion.
 - **Hosted-MCP proxies** — `remoteMcp()` wrappers around a server somebody else
   operates, where the names, schemas, results, and error prose arrive as they
-  are. Today: Linear, Stripe, Mixpanel.
+  are. Today: Linear, Stripe, Mixpanel, RevenueCat.
 
 The governing principle for every convention below is the same: **keep the
 model that interacts with connecta as efficient as possible.** A convention
@@ -386,11 +386,18 @@ complete spends calls proving it is not. *Cost:* wrong-tool selection.
 
 A proxy cannot project a downstream result, so the guide tells the agent to
 page with the cursor rather than raising the page size, and to reduce inside
-`execute_code` before returning anything. Structured form, explicit `summary`,
-`required: true` only for a genuine cross-tool sequence or a generic wrapper.
-
-*Why:* the only projection available is the one the program writes. *Cost:*
-result size.
+`execute_code` before returning anything — and, where a value's rendering is
+the provider's rule rather than the schema's, what that value means: Mixpanel
+renders an absent boolean property as `false` in a breakdown, so the guide
+says to confirm presence before reading `false` as a signal
+([#430](https://github.com/zackbart/connecta/issues/430)). Structured form,
+explicit `summary`, `required: true` only for a genuine cross-tool sequence or
+a generic wrapper.
+
+*Why:* the only projection available is the one the program writes, and a
+value the schema types correctly can still mislead without the provider's
+rendering rule beside it — the agent then re-queries to explain a signal that
+was never there. *Cost:* result size.
 
 ### P8 — Identity resolution comes before action
 
@@ -494,8 +501,8 @@ is the shape that does not become it.
 **What a manifest holds.** Every tool name a release reviewed, the verdict it
 reviewed it as (`read-only`, `additive`, `destructive`), and — where a release
 actually read them — a digest of that tool's input and output schemas. Today
-the three proxies ship names and verdicts and no digests, because no release
-has read a live schema and written it down, and an invented digest reports a
+three of the four proxies ship names and verdicts and no digests, because no
+release has read a live schema and written it down, and an invented digest reports a
 change that never happened. `npm run drift:check -- --record` reads them from a
 live catalog and prints the block a release pastes in; until a release does,
 a manifest without digests counts no schema changes, which is the honest answer
@@ -567,9 +574,10 @@ compares its own totals against `detectCatalogDrift()`: two readings of one
 manifest that disagree mean one of them is lying, which is worth failing over.
 One credential per provider comes from the environment —
 `CONNECTA_DRIFT_LINEAR_KEY`, `CONNECTA_DRIFT_STRIPE_KEY`,
-`CONNECTA_DRIFT_MIXPANEL_KEY` — and a missing or dead one stops the run with a
-message naming it rather than reporting an empty catalog as mass removal.
-Linear and bare Stripe values use their documented bearer or Basic framing.
+`CONNECTA_DRIFT_MIXPANEL_KEY`, `CONNECTA_DRIFT_REVENUECAT_KEY` — and a missing
+or dead one stops the run with a message naming it rather than reporting an
+empty catalog as mass removal. Linear, bare Stripe, and RevenueCat `sk_` values
+use their documented bearer or Basic framing.
 Mixpanel's beta service-account form is provider-specific:
 `user:secret` becomes `Bearer Basic <base64(user:secret)>`, exactly as its MCP
 documentation requires. A value that already includes whitespace is treated
@@ -623,11 +631,11 @@ evidence and nothing else: no tool is generated from one, which is the
 ## What the audit checks
 
 The provider audit ([#342](https://github.com/zackbart/connecta/issues/342))
-runs this document against each of the five providers and returns a verdict per
+runs this document against each of the six providers and returns a verdict per
 convention: **meets**, **misses** (with the fix), or **not applicable** (with
 the reason). A convention is never quietly skipped, and an accepted miss is
 recorded as a provider-specific exception with its argument, not left blank.
-Its five reports live in [provider-audit.md](./provider-audit.md), and the
+Its six reports live in [provider-audit.md](./provider-audit.md), and the
 mechanically checkable half of the hand-written bar runs on every test run in
 [`test/provider-conventions.test.ts`](https://github.com/zackbart/connecta/blob/main/test/provider-conventions.test.ts) —
 so a convention that was met once stays met, or fails loudly.
@@ -675,6 +683,7 @@ their place, so they are this audit's work, not a second removal argument.
 
 Each provider's own guide ([Cloudflare](./cloudflare.md),
 [Linear](./linear.md), [Mixpanel](./mixpanel.md), [Notion](./notion.md),
-[Stripe](./stripe.md)) is part of the audited surface: documentation moves with
+[RevenueCat](./revenuecat.md), [Stripe](./stripe.md)) is part of the audited
+surface: documentation moves with
 the work, and a guide describing a surface that shipped differently is itself a
 miss.