@zackbart/connecta 0.18.0 → 0.18.2

package/dist/providers/revenuecat.js

@@ -0,0 +1,323 @@
+import { remoteMcp, withCredentialDefaults, } 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 = withCredentialDefaults(options.auth ?? { type: "oauth" }, {
+        credential: {
+            label: "API v2 secret key",
+            description: "A RevenueCat API v2 secret key. It reaches exactly one project, which is why two projects are two connectors; it is stored encrypted and never displayed.",
+            placeholder: "sk_…",
+        },
+    });
+    // Both static shapes reach one project. Where the key came from — the
+    // deployment file or the operator page — changes nothing an agent must know
+    // about scope, so the title, description, and guide follow the scope alone.
+    const scoped = auth.type !== "oauth";
+    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.d.ts

@@ -22,10 +22,16 @@ export interface StripeOAuthOptions extends StripeCommonOptions {
     mode?: never;
     connectedAccount?: never;
 }
-/** Static credentials have one fixed mode, including Stripe Connect calls. */
+/**
+ * Static credentials have one fixed mode, including Stripe Connect calls.
+ *
+ * Both static shapes belong here: a key the deployment supplies as a literal
+ * header, and one the operator pastes at `/credentials`. Neither can discover
+ * its own mode — a restricted key answers for exactly one — so both declare it.
+ */
 export interface StripeHeaderOptions extends StripeCommonOptions {
-    auth: Extract<RemoteMcpAuth, {
-        type: "headers";
+    auth: Exclude<RemoteMcpAuth, {
+        type: "oauth";
     }>;
     mode: StripeMode;
     /** Act as one Connect account by sending Stripe's `Stripe-Account` header. */

package/dist/providers/stripe.js

@@ -1,4 +1,4 @@
-import { remoteMcp, } from "../connectors/remote-mcp.js";
+import { remoteMcp, withCredentialDefaults, } from "../connectors/remote-mcp.js";
 import { vettedCatalog, withVettedCatalog } from "../catalog-drift.js";
 /** Stripe publishes one hosted MCP endpoint for every account and mode. */
 export const STRIPE_MCP_ENDPOINT = "https://mcp.stripe.com/";
@@ -109,17 +109,31 @@ function assertModeMatchesKey(id, mode, auth) {
     }
 }
 function resolveAuth(id, options) {
-    const auth = options.auth ?? { type: "oauth" };
+    const auth = withCredentialDefaults(options.auth ?? { type: "oauth" }, {
+        credential: {
+            label: "Secret or restricted API key",
+            description: "A Stripe secret or restricted API key for this connector's declared mode. Stripe sends it as a bearer token; it is stored encrypted and never displayed.",
+            placeholder: "sk_… or rk_…",
+        },
+    });
     const connectedAccount = options.connectedAccount?.trim();
     if (connectedAccount === undefined || connectedAccount === "")
         return auth;
     if (!connectedAccount.startsWith("acct_")) {
         throw new Error(`stripe("${id}") connectedAccount must be a Stripe account id ("acct_...").`);
     }
-    if (auth.type !== "headers") {
+    if (auth.type === "oauth") {
         throw new Error(`stripe("${id}") cannot reach a connected account over OAuth; Stripe ` +
             `requires a restricted API key for Stripe-Account calls.`);
     }
+    if (auth.type === "credential") {
+        // `Stripe-Account` is a second header beside the credential's own, and the
+        // credential shape assembles exactly one. A Connect connector therefore
+        // still takes its restricted key as a literal header.
+        throw new Error(`stripe("${id}") cannot reach a connected account with an ` +
+            `operator-managed credential; Stripe-Account is a second static ` +
+            `header, so declare auth: { type: "headers" } for this connector.`);
+    }
     return {
         type: "headers",
         headers: { ...auth.headers, "Stripe-Account": connectedAccount },
@@ -173,7 +187,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.
@@ -195,9 +213,14 @@ export function stripe(id, options) {
     if (auth.type === "oauth" && mode !== undefined) {
         throw new Error(`stripe("${id}") cannot declare a connector-wide mode for OAuth; Stripe returns mode with each account.`);
     }
-    if (auth.type === "headers" && mode !== "production" && mode !== "sandbox") {
-        throw new Error(`stripe("${id}") with headers auth requires mode "production" or "sandbox".`);
+    if (auth.type !== "oauth" && mode !== "production" && mode !== "sandbox") {
+        throw new Error(`stripe("${id}") with headers or credential auth requires mode ` +
+            `"production" or "sandbox".`);
     }
+    // Only a literal header can be inspected. An operator-managed credential is
+    // not readable at construction — there is nothing in the deployment file to
+    // read — so the declared mode stands alone, and a key pointed at the other
+    // one is Stripe's own refusal to report.
     if (auth.type === "headers") {
         assertModeMatchesKey(id, mode, auth);
     }

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.2";

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.2";

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
@@ -293,3 +294,28 @@ server issuer discovered and validated by the SDK; see
 [storage and credentials](./storage-and-credentials.md#downstream-oauth).
 The callback route validates `state` before passing the complete callback query
 to the SDK so RFC 9207 `iss` validation is not lost.
+
+A remote MCP connector that authenticates with a static key has two ways to
+receive one. `{ type: "headers", headers }` bakes the literal value into the
+deployment file, which suits a secret the runtime already holds.
+`{ type: "credential" }` declares the slot instead and lets an operator paste
+the key at `/credentials`, where it is encrypted at rest and rotatable without
+a redeploy:
+
+```ts
+remoteMcp("revenuecat_bepresent", {
+  url: "https://mcp.revenuecat.ai/mcp",
+  auth: {
+    type: "credential",
+    credential: { label: "API v2 secret key" },
+  },
+});
+```
+
+Header name and framing are configurable — `header` defaults to
+`Authorization`, `scheme` to `Bearer`, `scheme: null` sends the value bare, and
+a `Basic` framing base64-encodes a `user:secret` pair. Every maintained hosted
+connection takes the shape through its existing `auth` option and fills in its
+own label and framing. The full behavior, including rotation and the empty-slot
+state, is in
+[storage and credentials](./storage-and-credentials.md#a-remote-mcp-connectors-static-credential).

package/documentation/linear.md

@@ -65,9 +65,12 @@ connection; it now answers 404.
 ## Authentication
 
 OAuth 2.1 with dynamic client registration is the default and keeps each
-connector instance's flow and tokens in its connector-scoped storage. Linear
-also accepts a bearer token or a personal API key passed directly in the
-`Authorization` header, which suits a headless deployment:
+connector instance's flow and tokens in its connector-scoped storage. Linear's
+MCP server also "supports passing OAuth token and API keys directly in the
+`Authorization: Bearer <yourtoken>` header instead of using the interactive
+authentication flow" ([Linear MCP docs](https://linear.app/docs/mcp)), which
+suits a headless deployment. Note the framing: the bare-`Authorization`
+convention is Linear's *GraphQL* API, and this endpoint is not that.
 
 ```ts
 linear("automation_tracker", {
@@ -75,7 +78,7 @@ linear("automation_tracker", {
   access: "read-only",
   auth: {
     type: "headers",
-    headers: { Authorization: env.LINEAR_API_KEY },
+    headers: { Authorization: `Bearer ${env.LINEAR_API_KEY}` },
   },
 });
 ```
@@ -85,6 +88,24 @@ configuration. A personal API key carries the acting user's full workspace
 permissions, so pair it with `access: "read-only"` unless the deployment
 genuinely writes.
 
+The same key can arrive from `/credentials` instead, which is what a deployment
+with no secret store — or an operator who rotates keys without a redeploy —
+wants:
+
+```ts
+linear("automation_tracker", {
+  purpose: "Headless release reporting",
+  access: "read-only",
+  auth: { type: "credential" },
+});
+```
+
+The slot renders as "Personal API key" and Connecta sends the stored value as
+`Authorization: Bearer <key>`, the framing Linear's MCP page documents; pass
+`credential` or `scheme` to override either. Until the operator saves a value
+the connector is present and reports `auth_required`. See
+[storage and credentials](./storage-and-credentials.md#a-remote-mcp-connectors-static-credential).
+
 ## Safety classification
 
 The wrapper classifies Linear's documented `list_*`, `get_*`, and

package/documentation/meta-tools.md

@@ -310,6 +310,11 @@ handoff:
   declared credential label and field names/guidance; or
 - `unavailable`: an honest deployment/configuration message.
 
+The class follows what the connector declares, not how it was authored: a
+`remoteMcp()` connection using `auth: { type: "credential" }` declares a slot
+and no OAuth flow, so it lands in `operator_config` beside every `api()`
+credential.
+
 The tool accepts no secret. `force` applies only to OAuth and may discard its
 stored grant before restarting consent. Static credential values are written
 only through the same-origin, Clerk-operator credential route. After OAuth

package/documentation/mixpanel.md

@@ -50,6 +50,25 @@ 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 `/credentials` 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

package/documentation/operations.md

@@ -247,8 +247,10 @@ in.
 | `provider-conventions.test.ts` | the conventions a test can hold: hand-written providers refusing schemas they cannot enforce (H5), their compact discovery schemas staying complete (H7), Cloudflare stating its second pagination convention in the schema (H10), and Notion saying it has no escape hatch (H14) |
 | `registry.test.ts` | construction and id validation, startup warnings, address resolution, catalog TTL/persistence/completeness, agent-only stale-while-revalidate with cross-request single-flight shared with blocking reads in both start orders, owned teardown, invalidation/fingerprint guards, blocking diagnostics, and broken-connector isolation |
 | `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-credential.test.ts` | `remoteMcp()` drawing a static key from `/credentials`: the declared slot and its refusal of named fields and bad header names, header framing (bearer, bare, and the two `Basic` forms) observed on the wire, an empty slot failing as `auth_required` rather than reaching the downstream, a value carrying a control character refused before framing and absent from every surface — `call_tool`, `status`, the Test result, `lastError`, and the thrown error — rotation replacing the cached client and a connect already in flight while a wiped value fails the next call, the Test action's catalog probe and scope close, the cleartext-destination warning, and the vault and `authorize_connector` handoff end to end |
 | `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.