@zackbart/connecta 0.29.0 → 0.31.0

package/dist/providers/stripe/rest.d.ts

@@ -0,0 +1,14 @@
+import type { ApiTool } from "../../connectors/api-connector.js";
+import type { ConnectorContext, CredentialTestResult } from "../../types.js";
+import { type RestVendor } from "../_shared/rest/tools.js";
+/** Which Stripe environment a key reaches. */
+export type StripeMode = "production" | "sandbox";
+/** Stripe's REST origin. */
+export declare const STRIPE_API_BASE_URL = "https://api.stripe.com";
+export interface StripeRest {
+    vendor: RestVendor;
+    tools: ApiTool[];
+    testCredential(value: string, ctx: ConnectorContext): Promise<CredentialTestResult>;
+}
+/** Stripe's REST vendor, its named tools, and its credential test, for one mode. */
+export declare function stripeRest(mode: StripeMode, connectedAccount: string | undefined): StripeRest;

package/dist/providers/stripe/rest.js

@@ -0,0 +1,395 @@
+import { retryAfterMs } from "../../connectors/guarded-fetch.js";
+import { ConnectorCallError } from "../../errors.js";
+import { OperationIndex } from "../_shared/rest/operation-index.js";
+import { callRest, restCall, restTransport, } from "../_shared/rest/tools.js";
+import { valueSafety } from "../_shared/rest/value-safety.js";
+import { openapi } from "./openapi.generated.js";
+import { STRIPE_VALUE_SAFETY } from "./value-safety.js";
+/** Stripe's REST origin. */
+export const STRIPE_API_BASE_URL = "https://api.stripe.com";
+const FILES_ORIGIN = "https://files.stripe.com";
+const METER_EVENTS_ORIGIN = "https://meter-events.stripe.com";
+const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
+const READ_CAP_MS = 60_000;
+/**
+ * POSTs that only read, admitted by `stripe_api_read`. `POST
+ * /v1/tax/calculations` is deliberately absent: it persists a Calculation
+ * object a later Tax Transaction can reference, and Stripe bills each call.
+ */
+const READ_POSTS = [
+    ["POST", "/v1/invoices/create_preview", "Computes an upcoming invoice; Stripe persists nothing."],
+];
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+}
+function text(value) {
+    return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+function invalid(message) {
+    throw new ConnectorCallError("invalid_args", message);
+}
+/**
+ * Why this key cannot serve a connector declared for `mode`, or undefined.
+ * The key's own prefix carries its mode, so a live key in a sandbox
+ * connector (or the reverse) is refused before any request leaves.
+ */
+function stripeKeyProblem(key, mode) {
+    if (/^(?:sk|rk)_org_/.test(key)) {
+        return "This is a Stripe organization key, which needs a Stripe-Context header this connector does not send. Use one account's secret or restricted key.";
+    }
+    if (key.startsWith("pk_")) {
+        return "This is a publishable key; the Stripe API needs a secret (sk_) or restricted (rk_) key.";
+    }
+    const prefix = /^(?:sk|rk)_(live|test)_\S+$/.exec(key);
+    if (!prefix)
+        return "This is not a Stripe secret (sk_…) or restricted (rk_…) key.";
+    const keyMode = prefix[1] === "live" ? "production" : "sandbox";
+    if (keyMode !== mode) {
+        return `This connector is declared ${mode}, but the configured key is a ${prefix[1]}-mode key.`;
+    }
+    return undefined;
+}
+/** Flatten one value Stripe's way: `a[b]=`, indexed arrays, `""` to unset. */
+function flatten(key, value, emit, emptyArrays) {
+    if (value === undefined)
+        return;
+    if (value === null || value === "")
+        return emit(key, "");
+    if (Array.isArray(value)) {
+        if (value.length === 0) {
+            if (emptyArrays)
+                emit(key, "");
+            return;
+        }
+        value.forEach((item, index) => flatten(`${key}[${index}]`, item, emit, emptyArrays));
+        return;
+    }
+    if (typeof value === "object") {
+        for (const [name, item] of Object.entries(value))
+            flatten(`${key}[${name}]`, item, emit, emptyArrays);
+        return;
+    }
+    if (typeof value === "boolean")
+        return emit(key, value ? "true" : "false");
+    if (typeof value === "number" && Number.isFinite(value))
+        return emit(key, String(value));
+    if (typeof value === "string")
+        return emit(key, value);
+    invalid(`Stripe parameter ${key} must be a string, number, boolean, object, list, or null.`);
+}
+/**
+ * A v1 form body: nested objects as `a[b]`, arrays indexed `a[0]`, booleans
+ * as `true`/`false`, and `null`, `""`, or `[]` as an empty value, which is
+ * how Stripe unsets a field.
+ */
+function stripeForm(body) {
+    const form = new URLSearchParams();
+    for (const [key, value] of Object.entries(body))
+        flatten(key, value, (name, item) => form.append(name, item), true);
+    return form.toString();
+}
+/**
+ * Query parameters. v1 indexes arrays (`expand[0]=…`) like its bodies; v2
+ * repeats the key for a list of scalars (`include=a&include=b`), as Stripe's
+ * own libraries do. Objects use brackets in both.
+ */
+function stripeQuery(query, v2) {
+    const out = {};
+    for (const [key, value] of Object.entries(query)) {
+        const scalars = Array.isArray(value) && value.every((item) => ["string", "number", "boolean"].includes(typeof item));
+        if (v2 && scalars && value.length > 0) {
+            out[key] = value.map((item) => (typeof item === "boolean" ? (item ? "true" : "false") : String(item)));
+            continue;
+        }
+        flatten(key, value, (name, item) => (out[name] = item), false);
+    }
+    return out;
+}
+function expansions(call) {
+    const read = (value) => typeof value === "string"
+        ? [value]
+        : Array.isArray(value)
+            ? value.filter((item) => typeof item === "string")
+            : [];
+    return [...read(call.query["expand"]), ...read(record(call.body)["expand"])];
+}
+/**
+ * Reviewed refusals that depend on arguments; the value-safety table
+ * (`value-safety.ts`) refuses whole operations. Each expansion returns a
+ * secret the caller could not otherwise read through Connecta: a Stripe Apps
+ * secret's value, or a full Issuing card number or CVC, which an Issuing
+ * authorization, transaction, or token can embed as well as the card itself.
+ */
+function refuse(call) {
+    const expanded = expansions(call);
+    if (/^\/v1\/apps\/secrets(?:\/|$)/.test(call.path) && expanded.some((path) => /(?:^|\.)payload$/.test(path))) {
+        return "Stripe Apps secret values are not returned through Connecta. Read the secret's metadata without expanding payload.";
+    }
+    if (/^\/v1\/(?:test_helpers\/)?issuing\//.test(call.path) &&
+        expanded.some((path) => /(?:^|\.)(?:number|cvc)$/.test(path))) {
+        return "Issuing card numbers and CVCs are not expanded through Connecta. Use the card id and last4, or the Stripe Dashboard.";
+    }
+    return undefined;
+}
+/**
+ * Map a Stripe failure by the caller's next move (H11). For an operation the
+ * value-safety review withholds (`withheld`), Stripe's message is replaced:
+ * the type, code, decline code, and param still route.
+ */
+function stripeFailure(status, headers, body, withheld = false) {
+    const error = record(record(body)["error"]);
+    const code = text(error["code"]);
+    const kind = [text(error["type"]), code, text(error["decline_code"])].filter(Boolean).join(" ");
+    const param = text(error["param"]);
+    const requestId = headers.get("request-id");
+    const message = withheld
+        ? "Stripe's message is withheld because this operation handles credentials."
+        : (text(error["message"]) ?? `Stripe returned HTTP ${status}.`);
+    const detail = `Stripe ${kind || `HTTP ${status}`}${param ? ` (param ${param})` : ""}: ` +
+        `${message}${requestId ? ` Request ${requestId}.` : ""}`;
+    if (status === 429) {
+        if (code === "lock_timeout") {
+            // Stripe did not process the request (docs.stripe.com/rate-limits#object-lock-timeouts):
+            // a definite conflict, safe to retry once the other request finishes.
+            return new ConnectorCallError("conflict", `${detail} Another request is changing this object and Stripe did not process this one; retry after it finishes. This is a lock conflict, not a rate limit.`, { retryable: true, retryAfterMs: 1_000 });
+        }
+        const reason = headers.get("stripe-rate-limited-reason");
+        return new ConnectorCallError("rate_limited", `${detail}${reason ? ` Limited by ${reason}.` : ""} Back off before retrying.`, { retryAfterMs: retryAfterMs(headers) ?? 1_000 });
+    }
+    if (status === 401) {
+        return new ConnectorCallError("auth_required", `${detail} The configured Stripe key was rejected; an operator must replace it in this connection.`);
+    }
+    if (status === 403) {
+        return new ConnectorCallError("provider_permission_denied", `${detail} A restricted key lacks this permission; an operator must grant it on the key or use another key.`);
+    }
+    if (status === 404)
+        return new ConnectorCallError("not_found", `${detail} Resolve the id with a list or search read.`);
+    if (status === 400 || status === 409 || status === 422)
+        return new ConnectorCallError("invalid_args", detail);
+    if (status === 402)
+        return new ConnectorCallError("connector_call_failed", detail, { retryable: false });
+    if (status === 424 || status >= 500)
+        return new ConnectorCallError("unavailable", detail);
+    return new ConnectorCallError("connector_call_failed", detail, { retryable: false });
+}
+/** Cursors: v1 lists, search results, and v2 lists each spell the next page differently. */
+function page(data, call) {
+    const body = record(data);
+    if (body["object"] === "list" && Array.isArray(body["data"])) {
+        const backward = call.query["ending_before"] !== undefined;
+        const items = body["data"];
+        const edge = record(backward ? items[0] : items[items.length - 1])["id"];
+        const hasMore = body["has_more"] === true;
+        return {
+            hasMore,
+            ...(hasMore && typeof edge === "string"
+                ? { next: edge, param: backward ? "ending_before" : "starting_after" }
+                : {}),
+        };
+    }
+    if (body["object"] === "search_result") {
+        const next = text(body["next_page"]);
+        return { hasMore: body["has_more"] === true, ...(next ? { next, param: "page" } : {}) };
+    }
+    if (Array.isArray(body["data"]) && "next_page_url" in body) {
+        const url = text(body["next_page_url"]);
+        let next = null;
+        try {
+            next = url ? new URL(url, STRIPE_API_BASE_URL).searchParams.get("page") : null;
+        }
+        catch {
+            next = null;
+        }
+        return { hasMore: url !== undefined, ...(next ? { next, param: "page" } : {}) };
+    }
+    return undefined;
+}
+/** The pinned index, shared by every Stripe REST connector in the deployment. */
+let index;
+function stripeIndex() {
+    index ??= new OperationIndex(openapi, { vendor: "stripe", title: "Stripe" });
+    return index;
+}
+/** The reviewed value-safety table over the pinned index. */
+const SAFETY = valueSafety(STRIPE_VALUE_SAFETY, () => stripeIndex());
+/** Stripe's REST vendor, its named tools, and its credential test, for one mode. */
+export function stripeRest(mode, connectedAccount) {
+    const operations = stripeIndex();
+    const transports = new Map();
+    const transport = (origin) => {
+        let send = transports.get(origin);
+        if (!send) {
+            send = restTransport({
+                provider: "Stripe",
+                baseUrl: origin,
+                maxResponseBytes: MAX_RESPONSE_BYTES,
+                timeoutMs: READ_CAP_MS,
+                authenticate: async (ctx) => {
+                    const key = (await ctx.credential?.get())?.trim();
+                    if (!key) {
+                        throw new ConnectorCallError("auth_required", "No Stripe key is configured for this connector. An operator must add one in this connection in the operator UI.");
+                    }
+                    const problem = stripeKeyProblem(key, mode);
+                    if (problem) {
+                        throw new ConnectorCallError("auth_required", `${problem} An operator must replace this connector's key.`);
+                    }
+                    return { Authorization: `Bearer ${key}` };
+                },
+            });
+            transports.set(origin, send);
+        }
+        return send;
+    };
+    const encode = (call) => {
+        const v2 = call.path.startsWith("/v2/");
+        const headers = { "Stripe-Version": operations.version };
+        // v2 names the acting account with Stripe-Context; v1 with Stripe-Account.
+        if (connectedAccount)
+            headers[v2 ? "Stripe-Context" : "Stripe-Account"] = connectedAccount;
+        const query = stripeQuery(call.query, v2);
+        if (call.body === undefined)
+            return { query, headers };
+        if (v2)
+            return { query, headers, body: call.body };
+        if (typeof call.body !== "object" || call.body === null || Array.isArray(call.body)) {
+            invalid("A Stripe v1 body is an object of parameters.");
+        }
+        return {
+            query,
+            headers: { ...headers, "Content-Type": "application/x-www-form-urlencoded" },
+            rawBody: stripeForm(call.body),
+        };
+    };
+    const vendor = {
+        vendor: "stripe",
+        title: "Stripe",
+        index: operations,
+        transport(server) {
+            if (server === undefined)
+                return transport(STRIPE_API_BASE_URL);
+            if (server === FILES_ORIGIN)
+                return transport(FILES_ORIGIN);
+            if (server === METER_EVENTS_ORIGIN) {
+                return "The meter event stream takes a short-lived meter event session token, not an API key. Send single events with POST /v2/billing/meter_events.";
+            }
+            return `This operation is served from ${server}, which this connector does not reach.`;
+        },
+        failure: (status, headers, body, call) => stripeFailure(status, headers, body, call ? SAFETY.withholdsErrors(call.op) : false),
+        readPosts: READ_POSTS,
+        valueSafety: SAFETY,
+        refuse,
+        encode,
+        page,
+        idempotencyHeader: "Idempotency-Key",
+        upload: "Upload files in the Stripe Dashboard; this connector sends no multipart bodies.",
+        bodyHint: "v1 bodies are form-encoded for you, v2 bodies sent as JSON",
+    };
+    const livemode = mode === "production";
+    const tools = [
+        {
+            name: "get_stripe_account_info",
+            description: "Read the Stripe account this key reaches: id, name, country, default currency, mode, and connected account. Use it to confirm scope first.",
+            annotations: { readOnlyHint: true },
+            inputSchema: { type: "object", properties: {}, required: [], additionalProperties: false },
+            outputSchema: {
+                type: "object",
+                properties: {
+                    accountId: { type: "string" },
+                    name: { type: ["string", "null"] },
+                    country: { type: ["string", "null"] },
+                    defaultCurrency: { type: ["string", "null"] },
+                    mode: { type: "string", enum: ["production", "sandbox"] },
+                    livemode: { type: "boolean" },
+                    connectedAccount: { type: ["string", "null"], description: "Set when every call acts as this account." },
+                    chargesEnabled: { type: ["boolean", "null"] },
+                    payoutsEnabled: { type: ["boolean", "null"] },
+                },
+                required: ["accountId", "mode", "livemode", "connectedAccount"],
+            },
+            handler: async (_args, ctx) => {
+                const { data } = await callRest(vendor, restCall(vendor, "GET", "/v1/account"), ctx);
+                const account = record(data);
+                const profile = record(account["business_profile"]);
+                const dashboard = record(record(account["settings"])["dashboard"]);
+                return {
+                    accountId: String(account["id"] ?? ""),
+                    name: text(profile["name"]) ?? text(dashboard["display_name"]) ?? null,
+                    country: text(account["country"]) ?? null,
+                    defaultCurrency: text(account["default_currency"]) ?? null,
+                    mode,
+                    livemode,
+                    connectedAccount: connectedAccount ?? null,
+                    chargesEnabled: typeof account["charges_enabled"] === "boolean" ? account["charges_enabled"] : null,
+                    payoutsEnabled: typeof account["payouts_enabled"] === "boolean" ? account["payouts_enabled"] : null,
+                };
+            },
+        },
+        {
+            name: "get_balance_summary",
+            description: "Read the account's available and pending Stripe balance per currency, in minor units. Excludes balance transactions; list those with stripe_api_read.",
+            annotations: { readOnlyHint: true },
+            inputSchema: { type: "object", properties: {}, required: [], additionalProperties: false },
+            outputSchema: {
+                type: "object",
+                properties: {
+                    livemode: { type: "boolean" },
+                    available: { type: "array", description: "Funds available to pay out, per currency." },
+                    pending: { type: "array", description: "Funds not yet available, per currency." },
+                    instantAvailable: { type: "array" },
+                    connectReserved: { type: "array" },
+                },
+                required: ["livemode", "available", "pending"],
+            },
+            handler: async (_args, ctx) => {
+                const { data } = await callRest(vendor, restCall(vendor, "GET", "/v1/balance"), ctx);
+                const balance = record(data);
+                const amounts = (value) => Array.isArray(value)
+                    ? value.map((entry) => ({ amount: record(entry)["amount"], currency: record(entry)["currency"] }))
+                    : [];
+                return {
+                    livemode: balance["livemode"] === true,
+                    available: amounts(balance["available"]),
+                    pending: amounts(balance["pending"]),
+                    ...(Array.isArray(balance["instant_available"])
+                        ? { instantAvailable: amounts(balance["instant_available"]) }
+                        : {}),
+                    ...(Array.isArray(balance["connect_reserved"])
+                        ? { connectReserved: amounts(balance["connect_reserved"]) }
+                        : {}),
+                };
+            },
+        },
+    ];
+    return {
+        vendor,
+        tools,
+        async testCredential(value, ctx) {
+            const key = value.trim();
+            const problem = stripeKeyProblem(key, mode);
+            if (problem)
+                return { ok: false, message: problem };
+            try {
+                const { data } = await callRest(vendor, restCall(vendor, "GET", "/v1/account"), {
+                    ...ctx,
+                    credential: { get: async () => key, getAll: async () => ({ value: key }) },
+                });
+                const account = record(data);
+                const name = text(record(account["business_profile"])["name"]);
+                return {
+                    ok: true,
+                    message: `Authenticated to ${String(account["id"] ?? "the Stripe account")}${name ? ` (${name})` : ""} with a ${livemode ? "live" : "test"}-mode key.`,
+                };
+            }
+            catch (error) {
+                if (error instanceof ConnectorCallError && error.code === "provider_permission_denied") {
+                    // Stripe authenticated the key; only the account read is outside its permissions.
+                    return {
+                        ok: true,
+                        message: `Stripe accepted the ${livemode ? "live" : "test"}-mode key; it cannot read the account object, which only get_stripe_account_info needs.`,
+                    };
+                }
+                return { ok: false, message: error instanceof ConnectorCallError ? error.message : "Stripe rejected the key." };
+            }
+        },
+    };
+}

package/dist/providers/stripe/skill.generated.js

@@ -1,11 +1,13 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "\n\nThis OAuth session may expose both live and sandbox Stripe accounts. Discover the live account-selection tools, select the intended account and mode, then carry exact context fields such as `stripe_context` and `livemode` wherever the schema requires them. A live-mode write moves real money; a sandbox write changes test data. Never infer the account or mode from connector metadata.\n\n- Discover account and mode with the live account-selection tools before every account-scoped read or write. The published inventory has changed account-tool names; do not assume `list_available_accounts_or_orgs` is available. Select the intended result and carry the exact context fields required by the live schema unchanged. If the account, mode, or supported selector is ambiguous, stop and ask; never guess.\n- Organization accounts are not Stripe Connect connected accounts. A Connect call requires a separate connector with a deployment-configured restricted key plus Stripe's documented `Stripe-Account` header; OAuth does not support that path.\n\n\n- Organization accounts are not Stripe Connect connected accounts. A Connect call requires a deployment-configured restricted key plus Stripe's documented `Stripe-Account` header; OAuth does not support that path. Do not try to turn an organization-account call into a Connect call inside tool arguments.\n\n- 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.\n- Prefer a dedicated tool when one covers the task: `get_balance_summary` for balances and `stripe_analytics` for Sigma or Metrics reporting. Use `stripe_api_search` for everything else instead of assuming a retired dedicated tool still exists.\n- `stripe_implementation_planner` and the query-execution intents of `stripe_analytics` create provider-side planning or query-run state. Connecta therefore classifies both as writes and enforces the configured pool trust policy; their retrieval paths stay behind the same tool boundary.\n- `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; execution follows the configured pool trust policy.\n- 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`.\n- 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.\n- 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.\n- 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.\n- 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.\n- 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.\n- 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.\n- 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.\n- Send an `Idempotency-Key` on every write you might retry, if the tool accepts it, and reuse the same key for the retry. A retry with a fresh key is a second charge, not a second attempt.\n- Stripe answers a rate limit with `429` and a `Stripe-Rate-Limited-Reason` header; back off on that rather than retrying immediately. Stripe documents an account ceiling of , and any single endpoint is capped at 25 per second regardless of mode, so paging one list is the real constraint.\n- Use `search_stripe_documentation` when the shape of an object or a flow is unclear; it is a read and costs nothing but a call.\n- Treat every create, update, delete, refund, and report run as a write. For guest calls, classification, and routing, fetch `skills({ name: \"usage\" })`.\n- An `auth_required` failure means this connector's Stripe authorization is missing or expired: run `authorize_connector` for this connector id, then retry the same call unchanged. A rejected argument or a plan restriction comes back in Stripe's own words instead — read it rather than re-authorizing.\n",
+    "content": "- 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`.\n- 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.\n- 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.\n- 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.\n- 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.\n- 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.\n- Treat every create, update, delete, refund, and report run as a write. For guest calls, classification, and routing, fetch `skills({ name: \"usage\" })`.\n",
     "instructionsHeading": "Account instructions",
     "fragments": {
-        "guide_0": "\n\nThis OAuth session may expose both live and sandbox Stripe accounts. Discover the live account-selection tools, select the intended account and mode, then carry exact context fields such as `stripe_context` and `livemode` wherever the schema requires them. A live-mode write moves real money; a sandbox write changes test data. Never infer the account or mode from connector metadata.\n\n- Discover account and mode with the live account-selection tools before every account-scoped read or write. The published inventory has changed account-tool names; do not assume `list_available_accounts_or_orgs` is available. Select the intended result and carry the exact context fields required by the live schema unchanged. If the account, mode, or supported selector is ambiguous, stop and ask; never guess.\n- Organization accounts are not Stripe Connect connected accounts. A Connect call requires a separate connector with a deployment-configured restricted key plus Stripe's documented `Stripe-Account` header; OAuth does not support that path.\n",
-        "guide_1": "\n\n- Organization accounts are not Stripe Connect connected accounts. A Connect call requires a deployment-configured restricted key plus Stripe's documented `Stripe-Account` header; OAuth does not support that path. Do not try to turn an organization-account call into a Connect call inside tool arguments.\n",
-        "guide_2": "\n- 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.\n- Prefer a dedicated tool when one covers the task: `get_balance_summary` for balances and `stripe_analytics` for Sigma or Metrics reporting. Use `stripe_api_search` for everything else instead of assuming a retired dedicated tool still exists.\n- `stripe_implementation_planner` and the query-execution intents of `stripe_analytics` create provider-side planning or query-run state. Connecta therefore classifies both as writes and enforces the configured pool trust policy; their retrieval paths stay behind the same tool boundary.\n- `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; execution follows the configured pool trust policy.\n- 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`.\n- 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.\n- 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.\n- 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.\n- 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.\n- 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.\n- 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.\n- 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.\n- Send an `Idempotency-Key` on every write you might retry, if the tool accepts it, and reuse the same key for the retry. A retry with a fresh key is a second charge, not a second attempt.\n- Stripe answers a rate limit with `429` and a `Stripe-Rate-Limited-Reason` header; back off on that rather than retrying immediately. Stripe documents an account ceiling of ",
-        "guide_3": ", and any single endpoint is capped at 25 per second regardless of mode, so paging one list is the real constraint.\n- Use `search_stripe_documentation` when the shape of an object or a flow is unclear; it is a read and costs nothing but a call.\n- Treat every create, update, delete, refund, and report run as a write. For guest calls, classification, and routing, fetch `skills({ name: \"usage\" })`.\n- An `auth_required` failure means this connector's Stripe authorization is missing or expired: run `authorize_connector` for this connector id, then retry the same call unchanged. A rejected argument or a plan restriction comes back in Stripe's own words instead — read it rather than re-authorizing.\n"
+        "oauth": "\n\nThis OAuth session may expose both live and sandbox Stripe accounts. Discover the live account-selection tools, select the intended account and mode, then carry exact context fields such as `stripe_context` and `livemode` wherever the schema requires them. A live-mode write moves real money; a sandbox write changes test data. Never infer the account or mode from connector metadata.\n\n- Discover account and mode with the live account-selection tools before every account-scoped read or write. The published inventory has changed account-tool names; do not assume `list_available_accounts_or_orgs` is available. Select the intended result and carry the exact context fields required by the live schema unchanged. If the account, mode, or supported selector is ambiguous, stop and ask; never guess.\n- Organization accounts are not Stripe Connect connected accounts. A Connect call requires a separate API-key connector whose `connectedAccount` sends Stripe's documented `Stripe-Account` header; OAuth does not support that path.\n- 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.\n- Prefer a dedicated tool when one covers the task: `get_balance_summary` for balances and `stripe_analytics` for Sigma or Metrics reporting. Use `stripe_api_search` for everything else instead of assuming a retired dedicated tool still exists.\n- `stripe_implementation_planner` and the query-execution intents of `stripe_analytics` create provider-side planning or query-run state. Connecta therefore classifies both as writes and enforces the configured pool trust policy; their retrieval paths stay behind the same tool boundary.\n- `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; execution follows the configured pool trust policy.\n- 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.\n- Find an object with `stripe_api_search` (or a list endpoint through `stripe_api_read`) and carry the `id` it returned into the write.\n- 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.\n- Send an `Idempotency-Key` on every write you might retry, if the tool accepts it, and reuse the same key for the retry. A retry with a fresh key is a second charge, not a second attempt.\n",
+        "key": "\n\n- This is Connecta's REST connector to `api.stripe.com`, holding one operator-managed key. It reaches exactly one account in one mode, so there is no account selection and no `stripe_context` or `livemode` argument.\n- `stripe_api_search` finds API operations, not records: it searches the pinned API index and names the tool that calls each operation. `stripe_api_details` returns one operation's parameters with types, enums, and required names. Neither sends a request.\n- `stripe_api_read` calls GET operations, plus `POST /v1/invoices/create_preview`, which only previews. `stripe_api_write` calls every other POST and every DELETE, from a customer edit to a subscription cancellation, with `method` and `path` stated; execution follows the configured pool trust policy.\n- Paths are concrete: substitute ids into the template search returned (`/v1/payment_intents/pi_123`). Pass `query` and `body` as JSON objects named as `stripe_api_details` lists them. Connecta form-encodes v1 bodies and query lists (`expand: [\"latest_charge\"]`), sends v2 bodies as JSON, and pins `Stripe-Version` to the index's API version. Send `null` or `\"\"` to unset a field.\n- Every call is checked against the pinned index before it is sent. An unknown path returns the nearest operations; an unknown or missing parameter returns `validation.issues` with the accepted names. Nothing reached Stripe, so fix the call from that answer.\n- Results arrive as `{ status, data, page? }`. On a list, `page.next` is the cursor and `page.param` the query parameter to pass it as: `starting_after`, or `page` for search and v2 lists. Lists belong inside `execute_code`; pass `select` (dot paths such as `data.id` and `data.status`) to keep only the fields the question needs, which also keeps customer names, emails, and addresses out of the transcript.\n- `get_stripe_account_info` confirms the account, mode, and connected account; `get_balance_summary` returns available and pending balances. Use them when they answer the question.\n- Find records with list and search operations through `stripe_api_read` (`GET /v1/customers/search`, `GET /v1/charges` with `customer`) and carry the returned `id` into the write.\n- `stripe_api_write` sends an `Idempotency-Key` on every POST. Pass `idempotencyKey` for anything you might retry, or reuse the generated one the result returns. An ambiguous failure carries it in its message or as `uncertainCall.recovery.idempotencyKey`. Reuse it only with the exact original arguments and within Stripe's retention (v1 keys may be pruned after 24 hours); after that, look the object up before retrying. A retry with a fresh key is a second charge, not a second attempt.\n- Refused by design: operations that hand out a credential (ephemeral keys, Terminal connection tokens, account links (v1 and v2), Terminal onboarding links, Express login links, account sessions, customer sessions, billing portal sessions, file link creation, Financial Connections session creation, and the meter event session), Stripe Apps secret payloads (`expand` of `payload`), Issuing card `number` and `cvc` expansion on any Issuing path, multipart uploads such as `POST /v1/files` (use the Dashboard), and the meter event stream (send single events with `POST /v2/billing/meter_events`). Each refusal names its reason. Quote PDFs arrive from `files.stripe.com` as base64.\n- Secrets read as `\"[redacted]\"` in every result, expansions included: client secrets (PaymentIntents, SetupIntents, Checkout and Identity sessions, Sources, Financial Connections, invoice confirmation secrets), webhook and event destination signing secrets, Apps secret payloads, app-install authorization codes, Terminal Wi-Fi passwords, forwarded request header values, and Issuing card numbers and CVCs. Webhook and event destination URLs, file link URLs (in an expanded File, a list, or an event too), and pre-signed import URLs keep only their scheme and host. Identity verification `url`s come back whole. A Checkout Session's `url` comes back whole only for a guest payment session (`mode: \"payment\"`, no `customer` or `customer_account`, no customer creation, no saved payment method options); any other session returns only its scheme and host, because its page can show, reuse, or remove a customer's saved payment methods. Create those from your own server code, or send a payment link or the invoice's hosted page instead. These rules follow each object wherever it appears, expansions and events included. A `[redacted]` field is never the real value; do not send it back.\n- Failures of credential-bearing operations (webhook endpoints, Apps secrets, Terminal configurations, forwarding) carry Stripe's type, code, decline code, and param, not its message. Payment, billing, and account failures keep Stripe's message.\n- The hosted OAuth connection's natural-language Sigma, metrics, documentation search, implementation planner, and feedback tools do not exist with a key.\n",
+        "shared": "- 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`.\n- 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.\n- 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.\n- 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.\n- 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.\n- 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.\n- Treat every create, update, delete, refund, and report run as a write. For guest calls, classification, and routing, fetch `skills({ name: \"usage\" })`.\n",
+        "oauth_limits": "- Stripe answers a rate limit with `429` and a `Stripe-Rate-Limited-Reason` header; back off on that rather than retrying immediately. Stripe documents an account ceiling of 100 requests per second in live mode and 25 in sandbox mode, and any single endpoint is capped at 25 per second regardless of mode, so paging one list is the real constraint.\n- Use `search_stripe_documentation` when the shape of an object or a flow is unclear; it is a read and costs nothing but a call.\n- An `auth_required` failure means this connector's Stripe authorization is missing or expired: run `authorize_connector` for this connector id, then retry the same call unchanged. A rejected argument or a plan restriction comes back in Stripe's own words instead — read it rather than re-authorizing.\n",
+        "key_limits": "- Stripe answers a rate limit with `429` and a `Stripe-Rate-Limited-Reason` header; back off on that rather than retrying immediately. Stripe documents an account ceiling of ",
+        "key_tail": ", and any single endpoint is capped at 25 per second regardless of mode, so paging one list is the real constraint. A `429` with code `lock_timeout` is a lock conflict on one object, not a rate limit: Stripe did not process the request, so it fails as `conflict` and may be retried after the other request finishes.\n- An `auth_required` failure means the key is missing, revoked, or for the other mode: an operator must replace it in this connection in the operator UI, and `authorize_connector` returns that handoff. A restricted key without a permission fails as `provider_permission_denied` naming it; ask for the permission rather than retrying. A rejected argument comes back in Stripe's own words — read it rather than replacing the key.\n"
     }
 };