@zackbart/connecta 0.24.3 → 0.24.4

package/dist/providers/revenuecat.js

@@ -3,7 +3,12 @@ import { vettedCatalog, withVettedCatalog } from "../catalog-drift.js";
 import { defined } from "../connectors/api.js";
 /** RevenueCat publishes one hosted MCP endpoint, streamable HTTP. */
 export const REVENUECAT_MCP_ENDPOINT = "https://mcp.revenuecat.ai/mcp";
-/** Reviewed reads; see `documentation/revenuecat.md` and convention P5. */
+/**
+ * Reviewed reads, every `Read` row of RevenueCat's tool reference as read on
+ * 2026-08-30 (P5). The list is a superset: plan, platform, and beta enrollment
+ * gate parts of the catalog, so a name this account never returns costs
+ * nothing while an unlisted new one fails closed.
+ */
 const READ_ONLY_TOOLS = new Set([
     // Projects and apps
     "get-account-billing",
@@ -70,26 +75,48 @@ const READ_ONLY_TOOLS = new Set([
     // *start* one are writes and sit below.
     "get-paywall-ai-task",
 ]);
-/** Reviewed writes and verb exceptions: `documentation/revenuecat.md`. */
+/**
+ * Reviewed writes with their destructive verdict. Most follow the verb, and
+ * additive writes stay additive because `readOnlyHint: false` already routes
+ * them through the approval path — asserting a destruction that does not happen
+ * only inflates the copy a human reads. The verdicts the verb does not decide
+ * carry their reason on the row.
+ *
+ * `render-paywall-screenshot` is deliberately in neither map: RevenueCat's
+ * reference gives it no access column, so the live annotation stands and a
+ * catalog that omits one fails closed. Guessing from a harmless-sounding name
+ * is what P5 exists to prevent.
+ */
 const WRITE_TOOLS = new Map([
     // Projects and apps
     ["create-app", "additive"],
     ["create-project", "additive"],
     ["update-app", "destructive"],
     ["update-project-ui-config", "destructive"],
+    // Filed `Write` by RevenueCat, so it cannot take the read path, but it leaves
+    // the saved credentials alone and only records a check's outcome.
     ["validate-app-credentials", "additive"],
     // Products and prices
     ["archive-product", "destructive"],
     ["create-product", "additive"],
+    // Named `create-`, but "Configure prices for a product": the price set
+    // already exists, so this overwrites it, and it is money-facing.
     ["create-product-prices", "destructive"],
+    // "Fills *missing* App Store subscription territory prices" — by
+    // RevenueCat's own word it writes only where nothing is set.
     ["equalize-subscription-prices", "additive"],
+    // An upsert.
     ["set-product-store-state", "destructive"],
+    // Sends products to Apple for review.
     ["submit-products-to-store", "destructive"],
     ["unarchive-product", "destructive"],
     ["update-product", "destructive"],
+    // Reserves a new App Store Connect review screenshot slot; replaces nothing.
     ["upload-product-store-state-screenshot", "additive"],
     // Entitlements
     ["archive-entitlement", "destructive"],
+    // Attach adds membership and removes nothing; detach is the destructive half.
+    // Filing both destructive would make the pair read identically to a human.
     ["attach-products-to-entitlement", "additive"],
     ["create-entitlement", "additive"],
     ["detach-products-from-entitlement", "destructive"],
@@ -97,6 +124,7 @@ const WRITE_TOOLS = new Map([
     ["update-entitlement", "destructive"],
     // Offerings and packages
     ["archive-offering", "destructive"],
+    // The attach/detach argument again, one level down.
     ["attach-products-to-package", "additive"],
     ["create-offering", "additive"],
     ["create-packages", "additive"],
@@ -110,6 +138,7 @@ const WRITE_TOOLS = new Map([
     // Paywalls
     ["attach-offering-to-paywall", "destructive"],
     ["detach-offering-from-paywall", "destructive"],
+    // Copies an existing paywall's current draft; the original is untouched.
     ["duplicate-paywall", "additive"],
     ["publish-paywall", "destructive"],
     ["unpublish-paywall", "destructive"],
@@ -130,14 +159,23 @@ const WRITE_TOOLS = new Map([
     ["unarchive-virtual-currency", "destructive"],
     ["update-virtual-currency", "destructive"],
     // Integrations and webhooks
+    // Destructive on consequence, not on the verb: no existing integration
+    // changes, but with filters omitted the new one starts delivering every
+    // customer event in the project to a URL the caller typed.
     ["create-webhook-integration", "destructive"],
     ["delete-webhook-integration", "destructive"],
     ["update-webhook-integration", "destructive"],
-    // Paywall editing
+    // Paywall editing. Both start an async task; the difference is what the task
+    // touches — a new paywall, or a draft that already exists.
     ["create-paywall-ai", "additive"],
     ["edit-paywall-ai", "destructive"],
 ]);
-/** Release-reviewed manifest; see provider conventions P5 and P13. */
+/**
+ * One release-reviewed manifest, used both to classify a live tool and as the
+ * baseline the drift check compares against, so the annotation a caller gets
+ * and the verdict a check reads can never disagree. Names and verdicts only —
+ * no schemas are vendored; the live `tools/list` response stays authoritative.
+ */
 export const REVENUECAT_VETTED_CATALOG = vettedCatalog({
     reads: READ_ONLY_TOOLS,
     writes: WRITE_TOOLS,

package/dist/providers/stripe.d.ts

@@ -40,7 +40,13 @@ export interface StripeHeaderOptions extends StripeCommonOptions {
     connectedAccount?: string;
 }
 export type StripeOptions = StripeOAuthOptions | StripeHeaderOptions;
-/** Release-reviewed manifest; see provider conventions P5 and P13. */
+/**
+ * One release-reviewed manifest, used both to classify a live tool and as the
+ * baseline the drift check compares against, so the annotation a caller gets and
+ * the verdict a check reads can never disagree. Stripe publishes no stability or
+ * deprecation policy for this tool set, so treat it as unversioned: an
+ * unclassified, unannotated name fails closed onto the approval path (P5).
+ */
 export declare const STRIPE_VETTED_CATALOG: import("../catalog-drift.js").VettedCatalog;
 /** A maintained Stripe hosted-MCP connection. */
 export declare function stripe(id: string, options: StripeOptions): Connector;

package/dist/providers/stripe.js

@@ -3,7 +3,14 @@ import { vettedCatalog, withVettedCatalog } from "../catalog-drift.js";
 import { defined } from "../connectors/api.js";
 /** Stripe publishes one hosted MCP endpoint for every account and mode. */
 export const STRIPE_MCP_ENDPOINT = "https://mcp.stripe.com/";
-/** Account limits and local concurrency rationale: `documentation/stripe.md`. */
+/**
+ * Stripe documents no MCP-specific limit, so these transcribe the account limit
+ * MCP traffic spends: 100 requests per second live, 25 in a sandbox. OAuth takes
+ * the sandbox rule (`mode ?? "sandbox"` below) because one session can reach
+ * either mode and the policy is fixed before the account-scoped call begins.
+ * The `maxConcurrency` figures are Connecta's own choice — Stripe says
+ * per-account and per-endpoint concurrency limits exist but publishes no number.
+ */
 const STRIPE_ADMISSION = {
     production: {
         rules: [
@@ -47,16 +54,30 @@ const READ_ONLY_TOOLS = new Set([
     "manage_stripe_accounts",
     "search_stripe_documentation",
 ]);
-/** Reviewed writes, including mixed read/create tools: `documentation/stripe.md`. */
+/**
+ * Reviewed writes with their destructive verdict. `stripe_api_write` is the
+ * sibling of `stripe_api_read` and carries every `POST`, `PATCH`, `PUT`, and
+ * `DELETE`. Additive writes leave `destructiveHint` unset: `readOnlyHint: false`
+ * already routes them through the approval path, and asserting destruction they
+ * do not perform would misstate their effect.
+ */
 const WRITE_TOOLS = new Map([
     ["stripe_api_write", "destructive"],
     ["create_refund", "destructive"],
+    // Creates and continues provider-side guide state; destroys nothing.
     ["stripe_implementation_planner", "additive"],
+    // Retrieval mixed with query-run creation behind one tool.
     ["stripe_analytics", "additive"],
     ["stripe_report", "additive"],
     ["send_stripe_mcp_feedback", "additive"],
 ]);
-/** Release-reviewed manifest; see provider conventions P5 and P13. */
+/**
+ * One release-reviewed manifest, used both to classify a live tool and as the
+ * baseline the drift check compares against, so the annotation a caller gets and
+ * the verdict a check reads can never disagree. Stripe publishes no stability or
+ * deprecation policy for this tool set, so treat it as unversioned: an
+ * unclassified, unannotated name fails closed onto the approval path (P5).
+ */
 export const STRIPE_VETTED_CATALOG = vettedCatalog({
     reads: READ_ONLY_TOOLS,
     writes: WRITE_TOOLS,
@@ -64,7 +85,12 @@ export const STRIPE_VETTED_CATALOG = vettedCatalog({
 /** Stripe key prefixes carry their own mode; only a clear reading counts. */
 const LIVE_KEY = /\b(?:sk|rk|pk)_live_/;
 const TEST_KEY = /\b(?:sk|rk|pk)_test_/;
-/** Refuse a recognizable key/mode mismatch; see `documentation/stripe.md`. */
+/**
+ * Refuse a recognizable key/mode mismatch. This is the only mode guard Connecta
+ * can offer, and it needs the key as a literal header to read the prefix: an
+ * operator-managed key is not in the deployment file, so its declared mode
+ * stands alone and a key pointed at the other environment fails at Stripe.
+ */
 function assertModeMatchesKey(id, mode, auth) {
     if (auth.type !== "headers")
         return;

package/dist/providers/vercel.js

@@ -1,4 +1,14 @@
-/** See documentation/vercel.md#no-sdk-on-purpose. */
+/**
+ * No `@vercel/sdk` on purpose — not a dependency and not an optional peer.
+ * Direct fetch keeps the root Workers-safe, avoids shipping the SDK's generated
+ * model graph, and lets the reviewed named operations and the REST hatches share
+ * one guarded transport. The trade is API drift, handled explicitly rather than
+ * by the SDK's version bumps: `scripts/drift/vercel-endpoints.json` records the
+ * method, versioned path, spec revision, and request/response digest for every
+ * fixed endpoint, and `npm run providers:check -- --provider vercel` compares
+ * those rows with Vercel's published OpenAPI document at
+ * https://openapi.vercel.sh/ without needing a credential.
+ */
 import { api, defined } from "../connectors/api.js";
 import { remoteMcp } from "../connectors/remote-mcp.js";
 import { vettedCatalog, withVettedCatalog } from "../catalog-drift.js";

package/dist/registry.d.ts

@@ -107,8 +107,8 @@ export interface RegistryView {
         signal?: AbortSignal;
     }): Promise<CallAdmissionPermit>;
     resultsStorage(): KVStorage;
-    /** Reserve runtime-wide capacity before writing a paging envelope. */
-    stashResult(key: string, value: string, ttlSeconds: number): Promise<boolean>;
+    /** Reserve runtime-wide capacity before writing a paging envelope's chunks. */
+    stashResult(key: string, chunks: readonly string[], ttlSeconds: number): Promise<boolean>;
     /** Local declared-vs-stored credential mismatch, with no downstream I/O. */
     credentialDriftFor(id: string): Promise<string | undefined>;
     /** Value-free shape learned from successful calls, never a provider declaration. */
@@ -240,8 +240,16 @@ export declare class Registry implements RegistryView {
     private observeCatalogDrift;
     /** Reject queued/future downstream admission; active permits release safely. */
     closeCallAdmission(): void;
-    /** Reserve capacity and write one ASCII paging envelope in this runtime. */
-    stashResult(key: string, value: string, ttlSeconds: number, prefix?: string): Promise<boolean>;
+    /**
+     * Reserve capacity and write one ASCII paging envelope in this runtime.
+     *
+     * `chunks[0]` lands on `<prefix><key>` and `chunks[n]` on `<prefix><key>#<n>`
+     * — the layout get_result reads back, so a page fetches only the chunks it
+     * covers instead of the whole stored result (issue #540). Chunking is a
+     * read-cost decision, not a capacity one: however many keys an envelope
+     * occupies, it is one stash entry charged its total ASCII length.
+     */
+    stashResult(key: string, chunks: readonly string[], ttlSeconds: number, prefix?: string): Promise<boolean>;
     /**
      * Storage namespaced to the meta-tool result store (`results:` prefix), kept
      * separate from any connector's `conn:<id>:` namespace. Backs get_result.

package/dist/registry.js

@@ -446,12 +446,20 @@ export class Registry {
         for (const registry of this.personalRegistries.values())
             registry.closeCallAdmission();
     }
-    /** Reserve capacity and write one ASCII paging envelope in this runtime. */
-    async stashResult(key, value, ttlSeconds, prefix = "results:") {
+    /**
+     * Reserve capacity and write one ASCII paging envelope in this runtime.
+     *
+     * `chunks[0]` lands on `<prefix><key>` and `chunks[n]` on `<prefix><key>#<n>`
+     * — the layout get_result reads back, so a page fetches only the chunks it
+     * covers instead of the whole stored result (issue #540). Chunking is a
+     * read-cost decision, not a capacity one: however many keys an envelope
+     * occupies, it is one stash entry charged its total ASCII length.
+     */
+    async stashResult(key, chunks, ttlSeconds, prefix = "results:") {
         const maxBytes = this.opts.results?.maxStashBytes ?? 8 * 1024 * 1024;
         const maxEntries = this.opts.results?.maxStashEntries ?? 64;
         // The paging envelope is ASCII, so its string length is its stored byte count.
-        const bytes = value.length;
+        const bytes = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
         if (bytes > maxBytes || maxEntries === 0)
             return false;
         const now = Date.now();
@@ -462,7 +470,8 @@ export class Registry {
             try {
                 // TTL alone cannot reclaim a lazy backend. Keep the charge until deletion
                 // succeeds, including writes which persisted before throwing.
-                await this.opts.storage.delete(oldKey);
+                for (const staleKey of entry.keys)
+                    await this.opts.storage.delete(staleKey);
                 this.resultStash.delete(oldKey);
                 this.resultStashBytes -= entry.bytes;
             }
@@ -473,11 +482,16 @@ export class Registry {
         if (this.resultStash.size >= maxEntries || this.resultStashBytes + bytes > maxBytes)
             return false;
         const fullKey = prefix + key;
-        const entry = { bytes, expiresAt: Infinity, busy: true };
+        const keys = chunks.map((_, index) => index === 0 ? fullKey : `${fullKey}#${index}`);
+        const entry = { keys, bytes, expiresAt: Infinity, busy: true };
         this.resultStash.set(fullKey, entry);
         this.resultStashBytes += bytes;
         try {
-            await this.opts.storage.set(fullKey, value, { ttlSeconds });
+            // Trailing chunks first: the header chunk is what makes an id readable, so
+            // a write that fails midway leaves no envelope pointing at absent chunks.
+            for (let index = keys.length - 1; index >= 0; index--) {
+                await this.opts.storage.set(keys[index], chunks[index], { ttlSeconds });
+            }
             entry.expiresAt = Date.now() + ttlSeconds * 1000;
             return true;
         }
@@ -1201,8 +1215,8 @@ class ScopedRegistryView {
         }
         return registry.admitCall(...args);
     }
-    stashResult(key, value, ttlSeconds) {
-        return this.root.stashResult(key, value, ttlSeconds, this.scope.subjectKey ? `subject:${this.scope.subjectKey}:` : "results:");
+    stashResult(key, chunks, ttlSeconds) {
+        return this.root.stashResult(key, chunks, ttlSeconds, this.scope.subjectKey ? `subject:${this.scope.subjectKey}:` : "results:");
     }
     resultsStorage() {
         return this.scope.subjectKey

package/dist/types.d.ts

@@ -519,6 +519,43 @@ export interface ConnectaBranding {
     };
     /** `theme-color` meta value. Defaults to "#ffffff". */
     themeColor?: string;
+    /**
+     * Operator-page appearance. Every field is optional, and a rejected value
+     * takes its default rather than failing the page, so `createConnecta` warns
+     * at startup about anything it dropped.
+     *
+     * Five knobs, not a palette. Surfaces, borders, muted text, and the status
+     * colors all derive from these, so a deployment sets an accent and gets a
+     * readable page instead of thirty chances to break one.
+     */
+    theme?: ConnectaTheme;
+}
+/**
+ * The operator UI's themeable tokens. These land in a `:root` block on the
+ * page, so each is gated by a narrow syntactic check: an unvalidated value
+ * here would let deployment config write arbitrary CSS.
+ */
+export interface ConnectaTheme {
+    /**
+     * The brand color: links, focus rings, primary actions, the active nav item.
+     * Hex only (`#rgb`, `#rrggbb`, or `#rrggbbaa`). Defaults to `#2f5fe0`.
+     */
+    accent?: string;
+    /**
+     * Corner rounding for cards, inputs, and buttons. A CSS length (`10px`,
+     * `0.5rem`) or a bare number read as pixels. `0` restores square corners.
+     * Defaults to `10px`.
+     */
+    radius?: string | number;
+    /** Body font stack. A plain CSS font-family list. Defaults to a system stack. */
+    fontFamily?: string;
+    /** Monospace font stack for addresses, ids, and the endpoint URL. */
+    monoFamily?: string;
+    /**
+     * `"system"` (the default) follows the operator's OS setting; `"light"` and
+     * `"dark"` pin the page to one palette.
+     */
+    colorScheme?: "system" | "light" | "dark";
 }
 /** An inbound authentication provider (bearer token, interactive identity, ...). */
 export interface InboundAuth {

package/dist/ui.js

@@ -8,7 +8,7 @@ import { mapSettledWithConcurrency, resolveDiscoveryConcurrency, } from "./concu
 import { OPERATOR_UI_CSS, OPERATOR_UI_SCRIPT, } from "./operator-ui/generated.js";
 import { CONNECTA_VERSION } from "./version.js";
 export { filterUiConnectors, } from "./operator-ui/model.js";
-import { resolveBranding, isSafeHttpsUrl } from "./branding.js";
+import { resolveBranding, isSafeHttpsUrl, themeCss } from "./branding.js";
 export { CONNECTA_FAVICON_SVG, resolveBranding, isSafeHttpUrl, isSafeHttpsUrl, isSafeIconHref } from "./branding.js";
 /**
  * A JS string literal safe to inline in a script element. Escaping `/` keeps
@@ -281,8 +281,14 @@ export function renderUiHtml(uiAuth, mcpUrl = "/mcp", branding, nonce, page = "c
     const clerkScript = clerk && clerkScriptOrigin
         ? `<script${nonceAttr} crossorigin="anonymous" data-clerk-publishable-key="${escapeHtmlAttr(clerk.publishableKey)}" src="${escapeHtmlAttr(clerkScriptOrigin)}/npm/@clerk/clerk-js@6/dist/clerk.browser.js"></script>`
         : "";
+    // A pinned scheme is an attribute, not a stylesheet edit: the dark palette
+    // keys off `html[data-scheme]`, so "system" leaves the attribute off and the
+    // media query decides.
+    const schemeAttr = brand.theme.colorScheme === "system"
+        ? ""
+        : ` data-scheme="${brand.theme.colorScheme}"`;
     return `<!doctype html>
-<html lang="en">
+<html lang="en"${schemeAttr}>
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
@@ -292,22 +298,24 @@ export function renderUiHtml(uiAuth, mcpUrl = "/mcp", branding, nonce, page = "c
 <link rel="shortcut icon" href="/favicon.ico">
 <title>${escapeHtmlAttr(title)}</title>
 ${clerkScript}
-<style>${OPERATOR_UI_CSS}</style>
+<style>${OPERATOR_UI_CSS}${themeCss(brand.theme)}</style>
 </head>
 <body>
 <a class="skip-link" href="#operatorContent">Skip to operator page</a>
-<header class="masthead shell pgrid">
-  ${owner}
-  <div class="mast-nav">
-    ${product}
+<header class="masthead shell">
+  <div class="masthead-inner">
+    <div class="mast-nav">
+      ${owner}
+      ${product}
+    </div>
     <div id="operatorNav"></div>
   </div>
 </header>
 
 <main id="operatorContent" class="page shell" tabindex="-1">
-  <div class="lead pgrid">
-    <h1 class="pcap">${OPERATOR_PAGE_LABELS[page]}</h1>
-    <div class="pbody lead-copy">
+  <div class="lead">
+    <h1>${OPERATOR_PAGE_LABELS[page]}</h1>
+    <div class="lead-copy">
       <p>${escapeHtmlAttr(brand.description)}</p>
       <noscript><p class="msg">The operator pages need JavaScript. Nothing else here
       does — agents reach this deployment through <span class="mono">/mcp</span>.</p></noscript>

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.24.3";
+export declare const CONNECTA_VERSION = "0.24.4";

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.24.3";
+export const CONNECTA_VERSION = "0.24.4";