@zackbart/connecta 0.34.1 → 0.35.0

package/dist/providers/stripe/api.js

@@ -0,0 +1,401 @@
+// Stripe's pinned contract, auth, error mapping and framing on the provider kit.
+import { Effect, Schema } from "effect";
+import { ConnectorCallError } from "../../errors.js";
+import { Refusal } from "../../http/errors.js";
+import { restSafety, resultSafety } from "../../http/safety.js";
+import { guardedClient } from "../../http/client.js";
+import { Credentials } from "../../http/services.js";
+import { connect, get } from "../../http/vendor.js";
+import { stripePage, stripeBackwardPage, stripeSearchPage, stripeV2Page } from "../../http/hatch-paging.js";
+import { responseMedia } from "../_shared/rest/response-media.js";
+import { OperationIndex } from "../_shared/rest/operation-index.js";
+import { checked, indexedVendor } from "../_shared/rest/kit.js";
+import { valueSafety, refuseWithheldLinks } from "../_shared/rest/value-safety.js";
+import { openapi } from "./openapi.generated.js";
+import { STRIPE_VALUE_SAFETY } from "./safety.js";
+import { STRIPE_API_BASE_URL } from "./lib/config.js";
+import { withholdEmbeddedUrlsIn } from "../_shared/rest/value-safety.js";
+export function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+}
+export function text(value) {
+    return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+const LOCK_TIMEOUT = "lock_timeout";
+export const stripeErrors = {
+    meanings: {
+        unknownId: "not_found",
+        provesAbsence: true,
+        conflicts: [
+            "HTTP 409 when the request conflicts with another request, including a concurrent use of the same idempotency key",
+            "HTTP 429 with code lock_timeout when another request holds the object's lock",
+        ],
+    },
+    numericFacts: {
+        retryAfterMs: {
+            header: "retry-after",
+            format: "retry-after",
+            review: "HTTP Retry-After delay for failure recovery.",
+        },
+    },
+    authBeforeExecution: {
+        evidence: "https://docs.stripe.com/error-low-level#content-errors: invalid API keys are refused before execution on API v1; API replies carry Request-Id.",
+        matches: ({ operation, headers }) => operation.template.startsWith("/v1/") && !!headers["request-id"],
+    },
+    provider: "Stripe",
+    factVocabulary: { code: [LOCK_TIMEOUT] },
+    facts: (body) => {
+        const error = record(record(body)["error"]);
+        return {
+            type: text(error["type"]),
+            code: text(error["code"]),
+            declineCode: text(error["decline_code"]),
+            param: text(error["param"]),
+        };
+    },
+    headers: ["request-id", "stripe-rate-limited-reason"],
+    detail: ({ status, facts, headers, withheld, body }) => {
+        const kind = [facts.type, facts.code, facts.declineCode].filter(Boolean).join(" ");
+        const message = withheld
+            ? "Stripe's message is withheld because this operation handles credentials."
+            : (text(record(record(withholdEmbeddedUrlsIn(body))["error"])["message"]) ?? `Stripe returned HTTP ${status}.`);
+        const requestId = headers["request-id"];
+        return (`Stripe ${kind || `HTTP ${status}`}${facts.param ? ` (param ${facts.param})` : ""}: ` +
+            `${message}${requestId ? ` Request ${requestId}.` : ""}`);
+    },
+    classify: [
+        // 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.
+        ({ status, facts }) => status === 429 && facts.code === LOCK_TIMEOUT
+            ? {
+                code: "conflict",
+                retryable: true,
+                retryAfterMs: 1_000,
+                words: (detail) => `${detail} Another request is changing this object and Stripe did not process this one. This is a lock conflict, not a rate limit.`,
+                advice: " Retry after it finishes.",
+            }
+            : undefined,
+    ],
+    statuses: {
+        429: ({ headers, retryAfterMs }) => {
+            const reason = headers["stripe-rate-limited-reason"];
+            return {
+                code: "rate_limited",
+                retryAfterMs: retryAfterMs ?? 1_000,
+                words: (detail) => `${detail}${reason ? ` Limited by ${reason}.` : ""}`,
+                advice: " Back off before retrying.",
+            };
+        },
+        401: () => ({
+            code: "auth_required",
+            words: (detail) => `${detail} The configured Stripe key was rejected; an operator must replace it in this connection.`,
+        }),
+        403: () => ({
+            code: "provider_permission_denied",
+            words: (detail) => `${detail} A restricted key lacks this permission; an operator must grant it on the key or use another key.`,
+        }),
+        404: () => ({ code: "not_found", words: (detail) => `${detail} Resolve the id with a list or search read.` }),
+        409: () => ({ code: "conflict" }),
+        402: () => ({ code: "connector_call_failed", retryable: false }),
+        424: () => ({ code: "unavailable" }),
+    },
+    unreadable: "Stripe returned malformed JSON.",
+    bodyFailures: {
+        review: "Stripe HTTP 424 is an external dependency failure, including when its body exceeds the byte ceiling (https://docs.stripe.com/api/errors). A failed body read does not establish malformed JSON; preserve the bounded read phase only.",
+        statusOnly: [424],
+        readFailed: "Stripe's response body could not be read completely.",
+    },
+};
+const FILES_ORIGIN = "https://files.stripe.com";
+const METER_EVENTS_ORIGIN = "https://meter-events.stripe.com";
+export const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
+export 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.
+ */
+export const READ_POSTS = [
+    ["POST", "/v1/invoices/create_preview", "Computes an upcoming invoice; Stripe persists nothing."],
+];
+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.
+ */
+export 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.
+ */
+export 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;
+}
+export const stripeIndex = new OperationIndex(openapi, { vendor: "stripe", title: "Stripe" });
+export const stripeSafety = valueSafety(STRIPE_VALUE_SAFETY, () => stripeIndex);
+function operationRefusal(op) {
+    return (checkServer(op.server) ??
+        stripeSafety.refusal(op.method, op.path) ??
+        (/^multipart\/|octet-stream/.test(stripeIndex.bodyType(op) ?? "")
+            ? `${op.method} ${op.path} takes an upload. Upload files in the Stripe Dashboard; this connector sends no multipart bodies.`
+            : undefined));
+}
+export const STRIPE_VERDICTS = Object.fromEntries(stripeIndex.ops.map((op) => [
+    `${op.method} ${op.path}`,
+    operationRefusal(op)
+        ? "refuse"
+        : op.method === "GET" || READ_POSTS.some(([method, path]) => method === op.method && path === op.path)
+            ? "read"
+            : "destructive",
+]));
+export const STRIPE_PAGES = Object.fromEntries(stripeIndex.ops.flatMap((op) => {
+    if (op.method !== "GET" || STRIPE_VERDICTS[`GET ${op.path}`] !== "read")
+        return [];
+    const parameters = stripeIndex
+        .contract(op)
+        .parameters.filter((p) => p.in === "query")
+        .map((p) => p.name);
+    return parameters.includes("starting_after")
+        ? [[`GET ${op.path}`, parameters.includes("ending_before") ? [stripePage, stripeBackwardPage] : stripePage]]
+        : parameters.includes("page")
+            ? [[`GET ${op.path}`, op.path.startsWith("/v2/") ? stripeV2Page : stripeSearchPage]]
+            : [];
+}));
+export function stripeBinding({ connection, options, }) {
+    const files = stripeConnection(options, "files");
+    return {
+        review: "Stripe v1 nested form and v2 JSON framing, connected-account headers, confined quote PDF origin, and existing argument-dependent safety refusals; every dispatch uses Connection.sendPath.",
+        allowOtherServers: true,
+        refusal: operationRefusal,
+        refuse: (call) => operationRefusal(call.op) ?? refuse(call),
+        send: (call, sendOptions) => sendStripe(connection, options, call, files, sendOptions),
+    };
+}
+export const safety = () => ({
+    reviewed: restSafety(stripeSafety, stripeIndex),
+    sensitiveFields: { names: [], choice: "drop" },
+});
+export const getAccount = get("getAccount", "/v1/account", {
+    headers: Schema.Struct({ "Stripe-Account": Schema.optionalKey(Schema.String) }),
+    success: Schema.Unknown,
+});
+export const getBalance = get("getBalance", "/v1/balance", { success: Schema.Unknown });
+const RESPONSE_MEDIA = { "GET /v1/quotes/{quote}/pdf": ["application/pdf"] };
+export const StripeApi = {
+    ...indexedVendor("stripe", stripeIndex, [getAccount, getBalance]),
+    binaryBodies: {
+        review: "The exact Stripe pin declares one non-JSON success: GET /v1/quotes/{quote}/pdf, application/pdf. JSON operations never accept text/HTML or arbitrary binary acknowledgements (#1000).",
+        forResponse: (status, operation, type) => responseMedia(RESPONSE_MEDIA, status, operation, type) === "binary",
+    },
+};
+export function stripeConnection(options, origin = "api") {
+    return connect(StripeApi, guardedClient({
+        provider: "Stripe",
+        baseUrl: origin === "files" ? FILES_ORIGIN : STRIPE_API_BASE_URL,
+        maxResponseBytes: MAX_RESPONSE_BYTES,
+        timeoutMs: READ_CAP_MS,
+        headers: { "Stripe-Version": stripeIndex.version },
+        authenticate: authenticate(options),
+    }), { errors: stripeErrors, safety: resultSafety(safety()) });
+}
+export const authenticate = (options) => Effect.gen(function* () {
+    const values = yield* (yield* Credentials).values.pipe(Effect.mapError((error) => new Refusal({ error })));
+    const key = typeof values?.value === "string" ? values.value.trim() : undefined;
+    if (!key)
+        return yield* Effect.fail(new Refusal({
+            error: 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, options.mode);
+    if (problem)
+        return yield* Effect.fail(new Refusal({
+            error: new ConnectorCallError("auth_required", `${problem} An operator must replace this connector's key.`),
+        }));
+    return { Authorization: `Bearer ${key}` };
+});
+export function connectedAccount(options) {
+    if (options.auth.type !== "apiKey")
+        throw new Error("remoteMcp() with ConnectaConfig.classification for hosted MCP connections; use a distinct id beside the API connector.");
+    if (options.mode !== "production" && options.mode !== "sandbox")
+        throw new Error('stripe() requires mode "production" or "sandbox" with apiKey auth.');
+    if (options.connectedAccount === undefined)
+        return undefined;
+    const account = typeof options.connectedAccount === "string" ? options.connectedAccount.trim() : "";
+    if (!/^acct_[A-Za-z0-9]+$/.test(account))
+        throw new Error('stripe() connectedAccount must be a Stripe account id ("acct_...").');
+    return account;
+}
+export function checkServer(server) {
+    if (server === undefined || server === FILES_ORIGIN)
+        return undefined;
+    return server === METER_EVENTS_ORIGIN
+        ? "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."
+        : `This operation is served from ${server}, which this connector does not reach.`;
+}
+export function sendStripe(connection, options, call, files, sendOptions) {
+    return checked(() => {
+        const server = checkServer(call.op.server);
+        if (server)
+            invalid(server);
+        const refusal = stripeSafety.refusal(call.method, call.op.path) ?? refuse(call);
+        if (refusal)
+            invalid(refusal);
+        const reading = call.method === "GET" ||
+            call.method === "HEAD" ||
+            READ_POSTS.some(([method, path]) => method === call.method && path === call.op.path);
+        if (!reading)
+            refuseWithheldLinks([call.body, call.query, call.path], "Stripe");
+        const v2 = call.path.startsWith("/v2/");
+        const headers = {};
+        const account = connectedAccount(options);
+        if (account)
+            headers[v2 ? "Stripe-Context" : "Stripe-Account"] = account;
+        const query = Object.entries(stripeQuery(call.query, v2)).flatMap(([key, value]) => (Array.isArray(value) ? value : [value]).map((value) => [key, value]));
+        if (call.body === undefined)
+            return { method: call.method, path: call.path, template: call.op.path, query, headers };
+        if (v2)
+            return {
+                method: call.method,
+                path: call.path,
+                template: call.op.path,
+                query,
+                headers,
+                json: JSON.stringify(call.body),
+            };
+        if (!call.body || typeof call.body !== "object" || Array.isArray(call.body))
+            invalid("A Stripe v1 body is an object of parameters.");
+        return {
+            method: call.method,
+            path: call.path,
+            template: call.op.path,
+            query,
+            headers,
+            form: [...new URLSearchParams(stripeForm(call.body))],
+            emptyForm: true,
+        };
+    }).pipe(Effect.flatMap((request) => (call.op.server === FILES_ORIGIN ? files : connection).sendPath(request, sendOptions)));
+}
+export const probe = {
+    operation: getAccount,
+    request: (options) => ({
+        headers: connectedAccount(options) ? { "Stripe-Account": connectedAccount(options) } : {},
+    }),
+    check: (values, options) => stripeKeyProblem((values.value ?? "").trim(), options.mode),
+    describe: (data, options) => {
+        const account = record(data);
+        const name = text(record(account["business_profile"])["name"]);
+        return `Authenticated to ${String(account["id"] ?? "the Stripe account")}${name ? ` (${name})` : ""} with a ${options.mode === "production" ? "live" : "test"}-mode key.`;
+    },
+    failure: (error, options) => error.code === "provider_permission_denied"
+        ? {
+            ok: true,
+            message: `Stripe accepted the ${options.mode === "production" ? "live" : "test"}-mode key; it cannot read the account object, which only get_stripe_account_info needs.`,
+        }
+        : undefined,
+};
+export const MODE_COPY = {
+    production: {
+        title: "Stripe (production)",
+        blurb: "production — live money and real customers",
+        warning: "This is a PRODUCTION Stripe connection. Every write moves real money against real customers, and a refund cannot be undone. If a request could plausibly be a rehearsal, route it to a sandbox connector instead.",
+        rate: "100 requests per second",
+    },
+    sandbox: {
+        title: "Stripe (sandbox)",
+        blurb: "sandbox — test data, no real money",
+        warning: "This is a SANDBOX Stripe connection. Nothing here is real money and none of these objects exist in production, so never answer a question about live revenue, payouts, or a named customer from this connector.",
+        rate: "25 requests per second",
+    },
+};

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

@@ -1,8 +1,6 @@
-import { type StripeMode } from "./rest.js";
-export type { StripeMode } from "./rest.js";
-export { STRIPE_API_BASE_URL } from "./rest.js";
-/** Stripe publishes one hosted MCP endpoint for every account and mode. */
-export declare const STRIPE_MCP_ENDPOINT = "https://mcp.stripe.com/";
+import { type StripeMode } from "./lib/config.js";
+export { STRIPE_API_BASE_URL } from "./lib/config.js";
+export type { StripeMode } from "./lib/config.js";
 interface StripeCommonOptions {
     /** Human-readable display name; defaults to "Stripe" for OAuth and the mode for a key. */
     title?: string;
@@ -17,19 +15,6 @@ interface StripeCommonOptions {
     /** Serve only read-classified tools on every endpoint. Defaults to false. */
     readOnly?: boolean;
 }
-/**
- * Stripe's hosted MCP server over OAuth. One session can reach live and
- * sandbox accounts; Stripe returns the mode with each account.
- */
-export interface StripeOAuthOptions extends StripeCommonOptions {
-    auth: {
-        type: "oauth";
-    };
-    /** Refused: OAuth reaches live and sandbox accounts, and Stripe returns mode with each. */
-    mode?: never;
-    /** Refused: a Connect account needs an API-key connector. */
-    connectedAccount?: never;
-}
 /**
  * Connecta's REST connector to `api.stripe.com` with one operator-managed
  * secret or restricted key, pasted into the connection in the operator UI.
@@ -44,12 +29,5 @@ export interface StripeApiKeyOptions extends StripeCommonOptions {
     /** Act as one Connect account: `Stripe-Account` on v1, `Stripe-Context` on v2. */
     connectedAccount?: string;
 }
-export type StripeOptions = StripeOAuthOptions | StripeApiKeyOptions;
-/**
- * A maintained Stripe connection. `auth` selects the implementation: OAuth
- * reaches Stripe's hosted MCP server; an API key reaches Connecta's REST
- * connector to `api.stripe.com`.
- */
-export declare const stripe: import("../../provider.js").ProviderFactory<StripeOptions>;
-/** @deprecated Read `stripe.definition.classify` instead. Kept for existing imports. */
-export declare const STRIPE_VETTED_CATALOG: import("../../catalog-drift.js").VettedCatalog;
+export type StripeOptions = StripeApiKeyOptions;
+export declare const stripe: import("../../provider.js").ProviderFactory<StripeApiKeyOptions>;