@zackbart/connecta 0.34.0 → 0.35.0

package/dist/providers/overflow/index.js

@@ -1,39 +1,9 @@
 import { skill } from "./skill.generated.js";
-/**
- * Overflow (overflow.co) — church and nonprofit giving: cash, stock, crypto,
- * and donor-advised-fund gifts, the deposits that settle them, the donors who
- * gave them, and the recurring gifts that will.
- *
- * No SDK on purpose, and Overflow publishes none for this API anyway: v3 is
- * header-authenticated JSON over thirty-eight operations, so `fetch` through
- * the shared guarded transport keeps this subpath Workers-clean and adds
- * nothing to install. Every tool below is hand-written. Overflow's OpenAPI
- * document is drift evidence only — `src/providers/overflow/drift.json`
- * records the operations the named tools touch, and
- * `pnpm run providers:check --provider overflow` compares them with the
- * published document without a credential. That document is served only by
- * staging (`server.stage.overflow.co/api/docs/openapi.json`; production's
- * equivalent answers 404), so the check reads staging's contract and assumes
- * production runs the same v3 surface — Overflow documents one API at two
- * base URLs, not two APIs.
- *
- * The surface is small enough to cover whole: named reads for the jobs a
- * finance or ministry team actually asks about — what was given, what settled
- * into the bank, who gave, what recurs, which campaign, and why a webhook
- * missed — and two guarded hatches so every other operation stays reachable.
- * Every write Overflow offers either moves money (charges, payment
- * authorization, refunds, recurring-gift changes) or edits a donor's record,
- * so none gets a named tool: each crosses `overflow_api_mutate`, which is
- * destructive by declaration and lands on the host's approval prompt with the
- * exact method, path, and body a human is being asked to allow. Overflow has
- * no upload endpoint, so there is no upload hatch.
- */
-import { apiConnector as api, defined } from "../../connectors/api-connector.js";
-import { guardedFetch, retryAfterMs, } from "../../connectors/guarded-fetch.js";
-import { ConnectorCallError } from "../../errors.js";
 import { keys, optionsOf } from "../../config-schema.js";
 import { PROVIDER_COMMON } from "../../connectors/option-shapes.js";
-import { asProviderFactory } from "../../provider.js";
+import { defineApiProvider } from "../../http/provider.js";
+import { authenticate, API_KEY_CREDENTIAL, DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE, OVERFLOW_MAX_RESPONSE_BYTES, OverflowApi, errors, safety, result, probe, admit, OVERFLOW_INDEX, OVERFLOW_VERDICTS, OVERFLOW_NAMED, OVERFLOW_PAGES, } from "./api.js";
+import { overflowTools } from "./tools.js";
 /**
  * Overflow's two published environments. They are separate deployments with
  * separate credentials: a staging key works only against staging and a
@@ -43,22 +13,6 @@ export const OVERFLOW_API_BASE_URLS = {
     production: "https://server.overflow.co",
     staging: "https://server.stage.overflow.co",
 };
-/** Every v3 operation lives below this path on either origin. */
-const API_PATH = "/api/v3";
-/** Overflow's cap on `limit` for every page-numbered collection. */
-const MAX_PAGE_SIZE = 100;
-/** Overflow's own default; already a quarter of the cap, so a first read is cheap. */
-const DEFAULT_PAGE_SIZE = 25;
-/** Webhook event logs page by cursor and cap `limit` lower, at 50. */
-const MAX_EVENT_LOG_PAGE_SIZE = 50;
-const DEFAULT_EVENT_LOG_PAGE_SIZE = 25;
-/**
- * A ceiling on absurdity, not a budget. A full page of 100 contributions with
- * their embedded donor blocks is a few hundred kilobytes; anything near four
- * mebibytes is a proxy misbehaving.
- */
-const OVERFLOW_MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
-/** Overflow's documented fixed window: 120 requests per 60 seconds per client. */
 const RATE_LIMIT_WINDOW_MS = 60_000;
 /**
  * Overflow documents 120 requests per minute per API client, metered in a
@@ -84,1452 +38,70 @@ const OVERFLOW_ADMISSION = {
         },
     ],
 };
-function asRecord(value) {
-    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
-}
-function asArray(value) {
-    return Array.isArray(value) ? value : [];
-}
-function compact(value) {
-    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
-}
-/** A `{ id, name }` reference, or undefined when Overflow sent none. */
-function reference(value) {
-    const record = asRecord(value);
-    return Object.keys(record).length === 0 ? undefined : compact({ id: record["id"], name: record["name"] });
-}
-// --- Credentials and transport ----------------------------------------------
-const API_KEY_CREDENTIAL = {
-    label: "Overflow API credentials",
-    description: "The client id and API key Overflow issued for this environment (Overflow dashboard, or Overflow's developer team). Staging and production credentials are separate and not interchangeable. Server-side only: connecta sends them to Overflow's API and nowhere else.",
-    fields: [
-        {
-            name: "clientId",
-            label: "Client ID",
-            description: "Overflow's public client identifier, sent as x-client-id.",
-            placeholder: "c77c8d57-7e1c-4a7e-ad46-e756e5f8dabd",
-            inputType: "text",
-        },
-        {
-            name: "apiKey",
-            label: "API key",
-            description: "The secret key paired with that client id, sent as x-api-key.",
-            placeholder: "Paste Overflow API key",
-            inputType: "password",
-        },
-    ],
-};
-/**
- * One credential source today: the operator's client id and API key. This is
- * the only place that knows what proves identity to Overflow, so an OAuth
- * bearer source — if Overflow ever offers one and `api()` grows the slot — is
- * a second function selected at construction, not a change to any tool.
- */
-async function apiKeyHeaders(ctx) {
-    const values = await ctx.credential?.getAll();
-    const clientId = values?.["clientId"]?.trim();
-    const apiKey = values?.["apiKey"]?.trim();
-    if (!clientId || !apiKey) {
-        throw new ConnectorCallError("auth_required", "No Overflow client id and API key are configured for this connector. Call authorize_connector for recovery options; an operator adds both fields in this connection in the operator UI.");
-    }
-    return { "x-client-id": clientId, "x-api-key": apiKey };
-}
-function overflowTransport(origin) {
-    return guardedFetch({
-        provider: "Overflow",
-        baseUrl: `${origin.replace(/\/+$/, "")}${API_PATH}`,
-        headers: { Accept: "application/json" },
-        maxResponseBytes: OVERFLOW_MAX_RESPONSE_BYTES,
-        authenticate: apiKeyHeaders,
-    });
-}
-// --- Failures ----------------------------------------------------------------
-/** NestJS framing: `{ statusCode, message: string | string[], error }`, or `{ error }`. */
-function detailFor(payload, status) {
-    const root = asRecord(payload);
-    const message = root["message"];
-    if (typeof message === "string" && message.trim())
-        return message.trim();
-    if (Array.isArray(message)) {
-        const lines = message.filter((line) => typeof line === "string" && line.trim() !== "");
-        if (lines.length > 0)
-            return lines.join("; ");
-    }
-    if (typeof root["error"] === "string" && root["error"].trim()) {
-        return root["error"].trim();
-    }
-    if (typeof payload === "string" && payload.trim()) {
-        return payload.trim().slice(0, 300);
-    }
-    return `Overflow returned HTTP ${status}.`;
-}
-/**
- * Overflow's own wait: `Retry-After` if a proxy supplies one, otherwise
- * `x-ratelimit-reset`, which Overflow documents as the seconds left in the
- * current window (a delta, not an epoch).
- */
-function windowResetMs(headers) {
-    const retryAfter = retryAfterMs(headers);
-    if (retryAfter !== undefined)
-        return retryAfter;
-    const raw = headers.get("x-ratelimit-reset");
-    if (!raw)
-        return undefined;
-    const seconds = Number(raw.trim());
-    return Number.isFinite(seconds) && seconds >= 0 ? Math.trunc(seconds * 1_000) : undefined;
-}
-/**
- * Map an Overflow failure by what the caller does next (H11).
- *
- * Three readings here are Overflow-specific. A bad client id or key answers
- * 403 "Forbidden resource" (observed against staging; the docs table says
- * 401), and so does an attempt to edit a donor profile that a donor account
- * owns — the status cannot tell those apart, so a write's message says so.
- * A 404 is an absence: credentials are per nonprofit and Overflow scopes every
- * read to it, so a missing id is missing from this nonprofit's view and the
- * next move is to re-resolve it. And a 5xx on a write is never retryable from
- * here: Overflow's own contract returns 500 from `POST /contributions` after
- * work has started, so the charge may exist, and a blind retry could charge a
- * donor twice.
- */
-function overflowFailure(status, headers, payload, method) {
-    const detail = detailFor(payload, status);
-    if (status === 429) {
-        return new ConnectorCallError("rate_limited", `Overflow rate limit reached (HTTP 429): ${detail} Overflow allows 120 requests per minute per API client in a fixed 60-second window, shared by every integration using this client id.`, { retryAfterMs: windowResetMs(headers) ?? RATE_LIMIT_WINDOW_MS });
-    }
-    if (status === 401 || status === 403) {
-        const ambiguity = method !== "GET" && status === 403
-            ? " Overflow also answers 403 when a donor profile owned by a donor account cannot be edited through the API; if reads succeed with this credential, that refusal is the cause and no credential change will fix it."
-            : "";
-        return new ConnectorCallError(status === 403 ? "provider_permission_denied" : "auth_required", `Overflow rejected the request (HTTP ${status}): ${detail} The client id and API key may be wrong, revoked, or issued for the other environment (staging and production credentials are not interchangeable); an operator must check them and ask the account administrator to grant resource access if they are valid.${ambiguity}`);
-    }
-    if (status === 404) {
-        return new ConnectorCallError("not_found", `Overflow found no such resource for this nonprofit (HTTP 404): ${detail} Re-resolve the id with its list tool; for a raw call, confirm the path below /api/v3.`);
-    }
-    if (status === 400) {
-        return new ConnectorCallError("invalid_args", `Overflow rejected the request (HTTP 400): ${detail}`);
-    }
-    if (status === 409 || status === 422) {
-        return new ConnectorCallError("connector_call_failed", `Overflow refused the operation (HTTP ${status}): ${detail} Repeating the same call will not change the outcome.`, { retryable: false });
-    }
-    if (status >= 500) {
-        if (method !== "GET") {
-            return new ConnectorCallError("connector_call_failed", `Overflow failed while processing a write (HTTP ${status}): ${detail} The write may or may not have taken effect. Read the affected contribution, donor, or recurring gift before retrying; repeating a charge, refund, or subscription change can apply it twice.`, { retryable: false });
-        }
-        const wait = windowResetMs(headers);
-        return new ConnectorCallError("unavailable", `Overflow is failing upstream (HTTP ${status}): ${detail}`, wait === undefined ? {} : { retryAfterMs: wait });
-    }
-    return new ConnectorCallError("connector_call_failed", `Overflow request failed (HTTP ${status}): ${detail}`, {
-        retryable: false,
-    });
-}
-function parseBody(text) {
-    if (!text.trim())
-        return undefined;
-    try {
-        return JSON.parse(text);
-    }
-    catch {
-        return text;
-    }
-}
-/**
- * Send one request. Named tools read strictly — a successful response that is
- * not JSON is a malformed answer — while the hatches return Overflow's body
- * as it arrived, text included (`/health` answers `ok`).
- */
-async function callOverflow(send, request, ctx, mode = "strict") {
-    return await send(request, ctx, async (response) => {
-        const text = await response.text();
-        if (!response.ok) {
-            throw overflowFailure(response.status, response.headers, parseBody(text), request.method);
-        }
-        const body = parseBody(text);
-        if (mode === "strict" && typeof body === "string") {
-            throw new ConnectorCallError("connector_call_failed", "Overflow returned a non-JSON body for a successful read.", { retryable: false });
-        }
-        return body;
-    });
-}
-function segment(value) {
-    return encodeURIComponent(String(value));
-}
-/**
- * Overflow pages by number and reports `totalCount`, so "is there another
- * page?" is arithmetic over what was asked for. A response with no usable
- * count reports `hasMore` from whether the page came back full — honest in
- * the common case, and never a confident `false` on a page that was full.
- */
-function pageInfo(payload, page, limit, rows) {
-    const total = asRecord(payload)["totalCount"];
-    if (typeof total === "number" && Number.isFinite(total)) {
-        return { page, limit, totalCount: total, hasMore: page * limit < total };
-    }
-    return { page, limit, totalCount: (page - 1) * limit + rows, hasMore: rows >= limit };
-}
-// --- Projections -------------------------------------------------------------
-/**
- * The donor as it rides inside a contribution: identity only. Overflow embeds
- * the whole profile — email, phone, mailing address, giving aggregates — in
- * every contribution row; `get_donor` is where that belongs.
- */
-function projectDonorReference(value) {
-    const donor = asRecord(value);
-    if (Object.keys(donor).length === 0)
-        return undefined;
-    return compact({
-        id: donor["id"],
-        firstName: donor["firstName"],
-        lastName: donor["lastName"],
-    });
-}
-function projectContribution(value) {
-    const contribution = asRecord(value);
-    const paymentMethod = asRecord(contribution["paymentMethod"]);
-    const stocks = asRecord(contribution["stocks"]);
-    const crypto = asRecord(contribution["crypto"]);
-    return compact({
-        id: contribution["id"],
-        type: contribution["type"],
-        status: contribution["status"],
-        amount: contribution["amount"],
-        frequency: contribution["frequency"] ?? undefined,
-        contributionDate: contribution["contributionDate"],
-        donor: projectDonorReference(contribution["donor"]),
-        anonymous: contribution["anonymous"],
-        donorCoveredFees: contribution["donorCoveredFees"],
-        campaign: reference(contribution["campaign"]),
-        subcampaign: reference(contribution["subcampaign"]),
-        locationId: contribution["locationId"],
-        depositId: contribution["depositId"] ?? undefined,
-        subscriptionId: contribution["subscriptionId"],
-        givingLinkId: contribution["givingLinkId"] ?? undefined,
-        pledgeId: contribution["pledgeId"] ?? undefined,
-        paymentMethod: Object.keys(paymentMethod).length === 0
-            ? undefined
-            : compact({ type: paymentMethod["type"], last4: paymentMethod["last4"] }),
-        stocks: Object.keys(stocks).length === 0
-            ? undefined
-            : compact({ quantity: stocks["quantity"], tickers: stocks["tickers"] }),
-        crypto: Object.keys(crypto).length === 0 ? undefined : compact({ quantity: crypto["quantity"], token: crypto["token"] }),
-        dedication: contribution["dedication"] ?? undefined,
-        donorNotes: contribution["donorNotes"] ?? undefined,
-        metadata: contribution["metadata"] ?? undefined,
-        createdAt: contribution["createdAt"],
-        updatedAt: contribution["updatedAt"],
-    });
-}
-function projectDonor(value, full) {
-    const donor = asRecord(value);
-    return compact({
-        id: donor["id"],
-        firstName: donor["firstName"],
-        lastName: donor["lastName"],
-        email: donor["email"],
-        phone: full ? donor["phone"] : undefined,
-        address: full ? (donor["address"] ?? undefined) : undefined,
-        locationIds: donor["locationIds"],
-        totalContributionsCount: donor["totalContributionsCount"],
-        activeRecurringCount: donor["activeRecurringCount"],
-        latestContributionDate: donor["latestContributionDate"],
-        createdAt: donor["createdAt"],
-        updatedAt: donor["updatedAt"],
-    });
-}
-function projectDeposit(value, withLineItems) {
-    const deposit = asRecord(value);
-    return compact({
-        id: deposit["id"],
-        status: deposit["status"],
-        type: deposit["type"],
-        amountInCents: deposit["amountInCents"],
-        arrivalAt: deposit["arrivalAt"],
-        name: deposit["name"] ?? undefined,
-        bankName: deposit["bankName"] ?? undefined,
-        bankLast4: deposit["bankLast4"] ?? undefined,
-        statementDescriptor: deposit["statementDescriptor"] ?? undefined,
-        paymentMethodTypes: deposit["paymentMethodType"],
-        startingBalanceInCents: deposit["startingBalanceInCents"] ?? undefined,
-        endingBalanceInCents: deposit["endingBalanceInCents"] ?? undefined,
-        reconciledAt: deposit["reconciledAt"] ?? null,
-        createdAt: deposit["createdAt"],
-        updatedAt: deposit["updatedAt"],
-        lineItems: withLineItems
-            ? asArray(deposit["lineItems"]).map((row) => {
-                const item = asRecord(row);
-                return compact({
-                    type: item["type"],
-                    grossValueInCents: item["grossValueInCents"],
-                    grossFeeValueInCents: item["grossFeeValueInCents"],
-                    referenceId: item["referenceId"],
-                    description: item["description"],
-                });
-            })
-            : undefined,
-    });
-}
-function projectRefund(value) {
-    const refund = asRecord(value);
-    return compact({
-        id: refund["id"],
-        contributionId: refund["contributionId"],
-        status: refund["status"],
-        reason: refund["reason"] ?? undefined,
-        amountInCents: refund["amountInCents"],
-        netValueInCents: refund["netValueInCents"],
-        feeValueInCents: refund["feeValueInCents"] ?? undefined,
-        depositId: refund["depositId"] ?? undefined,
-        createdAt: refund["createdAt"],
-        updatedAt: refund["updatedAt"],
-    });
-}
-function projectChargeback(value) {
-    const chargeback = asRecord(value);
-    return compact({
-        id: chargeback["id"],
-        contributionId: chargeback["contributionId"],
-        status: chargeback["status"],
-        type: chargeback["type"],
-        reason: chargeback["reason"] ?? undefined,
-        amountInCents: chargeback["amountInCents"],
-        netValueInCents: chargeback["netValueInCents"] ?? undefined,
-        feeValueInCents: chargeback["feeValueInCents"] ?? undefined,
-        depositId: chargeback["depositId"] ?? undefined,
-        createdAt: chargeback["createdAt"],
-        updatedAt: chargeback["updatedAt"],
-    });
-}
-function projectSubscription(value) {
-    const subscription = asRecord(value);
-    const paymentMethod = asRecord(subscription["paymentMethod"]);
-    return compact({
-        id: subscription["id"],
-        donorId: subscription["donorId"],
-        status: subscription["status"],
-        amount: subscription["amount"],
-        frequency: subscription["frequency"],
-        startDate: subscription["startDate"],
-        nextPaymentDate: subscription["nextPaymentDate"] ?? null,
-        anonymous: subscription["anonymous"],
-        donorCoveredFees: subscription["donorCoveredFees"],
-        campaign: reference(subscription["campaign"]),
-        subcampaign: reference(subscription["subcampaign"]),
-        locationId: subscription["locationId"] ?? undefined,
-        paymentMethod: Object.keys(paymentMethod).length === 0
-            ? undefined
-            : compact({
-                id: paymentMethod["id"],
-                type: paymentMethod["type"],
-                last4: paymentMethod["last4"],
-                expiration: paymentMethod["expiration"],
-            }),
-        metadata: subscription["metadata"] ?? undefined,
-        createdAt: subscription["createdAt"],
-        updatedAt: subscription["updatedAt"],
-    });
-}
-function projectPaymentMethod(value) {
-    const method = asRecord(value);
-    return compact({
-        id: method["id"],
-        type: method["type"],
-        last4: method["last4"],
-        expirationDate: method["expirationDate"],
-        isExpired: method["isExpired"],
-        updatedAt: method["updatedAt"],
-    });
-}
-function projectCampaign(value) {
-    const campaign = asRecord(value);
-    const refs = (list) => {
-        const rows = asArray(list)
-            .map(reference)
-            .filter((row) => row !== undefined);
-        return rows.length === 0 ? undefined : rows;
-    };
-    return compact({
-        id: campaign["id"],
-        name: campaign["name"],
-        status: campaign["status"],
-        isSubcampaign: campaign["isSubcampaign"],
-        isActive: campaign["isActive"],
-        startDate: campaign["startDate"],
-        endDate: campaign["endDate"] ?? null,
-        hideFromDonors: campaign["hideFromDonors"],
-        archivedAt: campaign["archivedAt"] ?? undefined,
-        locationIds: campaign["locationIds"],
-        parentCampaigns: refs(campaign["parentCampaigns"]),
-        subcampaigns: refs(campaign["subcampaigns"]),
-        totalContributionCount: campaign["totalContributionCount"],
-        totalContributionValue: campaign["totalContributionValue"],
-        uniqueDonorCount: campaign["uniqueDonorCount"],
-    });
-}
-function projectLocation(value) {
-    const location = asRecord(value);
-    return compact({
-        id: location["id"],
-        name: location["name"],
-        isDefaultLocation: location["isDefaultLocation"],
-        hideFromDonors: location["hideFromDonors"],
-        archivedAt: location["archivedAt"] ?? null,
-        createdAt: location["createdAt"],
-        updatedAt: location["updatedAt"],
-    });
-}
-function projectTapEvent(value) {
-    const event = asRecord(value);
-    const device = asRecord(event["device"]);
-    const group = asRecord(event["group"]);
-    const destination = asRecord(event["destination"]);
-    return compact({
-        id: event["id"],
-        createdAt: event["createdAt"],
-        deviceId: event["deviceId"],
-        deviceSerialNumber: device["serialNumber"],
-        groupId: event["groupId"],
-        groupName: group["name"],
-        destinationId: event["destinationId"],
-        destinationName: destination["name"],
-        destinationType: destination["type"] ?? undefined,
-    });
-}
-function projectWebhook(value) {
-    const webhook = asRecord(value);
-    return compact({
-        id: webhook["id"],
-        name: webhook["name"],
-        description: webhook["description"] ?? undefined,
-        destinationUrl: webhook["destinationUrl"],
-        enabledEvents: webhook["enabledEvents"],
-        status: webhook["status"],
-        createdAt: webhook["createdAt"],
-        updatedAt: webhook["updatedAt"],
-    });
-}
-/**
- * Deliberately drops `request.body` and `response.body`. The request body is
- * the event payload Overflow delivered — donor names, emails, and amounts —
- * and the response body is whatever the receiving server echoed. Diagnosing a
- * missed delivery needs the status, the code, and the error, not the payload.
- */
-function projectEventLog(value) {
-    const log = asRecord(value);
-    const request = asRecord(log["request"]);
-    const response = asRecord(log["response"]);
-    return compact({
-        id: log["id"],
-        eventId: log["eventId"],
-        webhookEventName: log["webhookEventName"],
-        status: log["status"],
-        attemptNumber: log["attemptNumber"],
-        deliverySource: log["deliverySource"],
-        originatedAt: log["originatedAt"],
-        attemptedAt: log["attemptedAt"],
-        url: request["url"],
-        responseCode: response["code"],
-        responseDurationMs: response["durationMs"],
-        errorMessage: response["errorMessage"],
-    });
-}
-// --- Schema fragments --------------------------------------------------------
-function namedInput(properties, required = []) {
-    return { type: "object", properties, required, additionalProperties: false };
-}
-const RAW_PROPERTY = {
-    type: "boolean",
-    description: "Return Overflow's untouched rows instead of the lean projection.",
-};
-const OBJECT_ID = "^[0-9a-fA-F]{24}$";
-function idProperty(source) {
-    return {
-        type: "string",
-        pattern: OBJECT_ID,
-        description: `24-hex id from ${source}.`,
-    };
-}
-const DATE_PROPERTY = (meaning) => ({
-    type: "string",
-    pattern: "^\\d{4}-\\d{2}-\\d{2}",
-    description: `${meaning}; ISO date or date-time.`,
-});
-const SORT_DIRECTION = {
-    type: "string",
-    enum: ["ASC", "DESC"],
-    description: "Sort direction.",
-};
-const ID_LIST = (source) => ({
-    type: "array",
-    minItems: 1,
-    items: { type: "string", pattern: OBJECT_ID, description: `Id from ${source}.` },
-    description: `Ids from ${source}; matches any.`,
-});
-const PAGE_PROPERTY = {
-    type: "integer",
-    minimum: 1,
-    description: "1-based page number. Defaults to 1.",
-};
-function limitProperty(defaultPageSize) {
-    return {
-        type: "integer",
-        minimum: 1,
-        maximum: MAX_PAGE_SIZE,
-        description: `Rows per page, up to Overflow's cap of ${MAX_PAGE_SIZE}. Defaults to ${defaultPageSize}.`,
-    };
-}
-const PAGE_OUTPUT = {
-    type: "object",
-    properties: {
-        page: { type: "integer" },
-        limit: { type: "integer" },
-        totalCount: { type: "integer" },
-        hasMore: { type: "boolean", description: "True when page + 1 exists." },
-    },
-    required: ["page", "limit", "totalCount", "hasMore"],
-};
-function listOutput(key, item) {
-    return {
-        type: "object",
-        properties: { [key]: { type: "array", items: item }, page: PAGE_OUTPUT },
-        required: [key, "page"],
-    };
-}
-const REFERENCE = {
-    type: "object",
-    properties: { id: { type: "string" }, name: { type: "string" } },
-};
-const CONTRIBUTION_SCHEMA = {
-    type: "object",
-    properties: {
-        id: { type: "string" },
-        type: { type: "string" },
-        status: { type: "string" },
-        amount: { type: "number" },
-        frequency: { type: "string" },
-        contributionDate: { type: "string" },
-        donor: { type: "object" },
-        campaign: REFERENCE,
-        subcampaign: REFERENCE,
-        locationId: { type: "string" },
-        depositId: { type: "string" },
-        subscriptionId: { type: "string" },
-        paymentMethod: { type: "object" },
-        stocks: { type: "object" },
-        crypto: { type: "object" },
-        metadata: { type: "object" },
-        createdAt: { type: "string" },
-        updatedAt: { type: "string" },
-    },
-    required: ["id", "type", "status", "amount"],
-};
-const DONOR_SCHEMA = {
-    type: "object",
-    properties: {
-        id: { type: "string" },
-        firstName: { type: "string" },
-        lastName: { type: "string" },
-        email: { type: "string" },
-        phone: { type: "string" },
-        address: { type: "object" },
-        locationIds: { type: "array", items: { type: "string" } },
-        totalContributionsCount: { type: "number" },
-        activeRecurringCount: { type: "number" },
-        latestContributionDate: { type: "string" },
-        createdAt: { type: "string" },
-        updatedAt: { type: "string" },
-    },
-    required: ["id"],
-};
-const DEPOSIT_SCHEMA = {
-    type: "object",
-    properties: {
-        id: { type: "string" },
-        status: { type: "string" },
-        type: { type: "string" },
-        amountInCents: { type: "number" },
-        arrivalAt: { type: "string" },
-        name: { type: "string" },
-        bankName: { type: "string" },
-        bankLast4: { type: "string" },
-        paymentMethodTypes: { type: "array", items: { type: "string" } },
-        reconciledAt: { type: ["string", "null"] },
-        lineItems: { type: "array", items: { type: "object" } },
-        createdAt: { type: "string" },
-        updatedAt: { type: "string" },
-    },
-    required: ["id", "status", "amountInCents"],
-};
-const MONEY_ROLLUP = {
-    type: "object",
-    properties: {
-        count: { type: "number" },
-        grossInCents: { type: "number" },
-        feesInCents: { type: "number" },
-        totalInCents: { type: "number" },
-    },
-};
-const REFUND_SCHEMA = {
-    type: "object",
-    properties: {
-        id: { type: "string" },
-        contributionId: { type: "string" },
-        status: { type: "string" },
-        reason: { type: "string" },
-        amountInCents: { type: "number" },
-        netValueInCents: { type: "number" },
-        feeValueInCents: { type: "number" },
-        depositId: { type: "string" },
-        createdAt: { type: "string" },
-        updatedAt: { type: "string" },
-    },
-    required: ["id", "contributionId", "status", "amountInCents"],
-};
-const CHARGEBACK_SCHEMA = {
-    type: "object",
-    properties: {
-        id: { type: "string" },
-        contributionId: { type: "string" },
-        status: { type: "string" },
-        type: { type: "string" },
-        reason: { type: "string" },
-        amountInCents: { type: "number" },
-        netValueInCents: { type: "number" },
-        depositId: { type: "string" },
-        createdAt: { type: "string" },
-        updatedAt: { type: "string" },
-    },
-    required: ["id", "contributionId", "status", "amountInCents"],
-};
-const SUBSCRIPTION_SCHEMA = {
-    type: "object",
-    properties: {
-        id: { type: "string" },
-        donorId: { type: "string" },
-        status: { type: "string" },
-        amount: { type: "number" },
-        frequency: { type: "string" },
-        startDate: { type: "string" },
-        nextPaymentDate: { type: ["string", "null"] },
-        campaign: REFERENCE,
-        subcampaign: REFERENCE,
-        locationId: { type: "string" },
-        paymentMethod: { type: "object" },
-        createdAt: { type: "string" },
-        updatedAt: { type: "string" },
-    },
-    required: ["id", "donorId", "status", "amount", "frequency"],
-};
-const PAYMENT_METHOD_SCHEMA = {
-    type: "object",
-    properties: {
-        id: { type: "string" },
-        type: { type: "string" },
-        last4: { type: "string" },
-        expirationDate: { type: "string" },
-        isExpired: { type: "boolean" },
-        updatedAt: { type: "string" },
-    },
-    required: ["id", "type", "last4"],
-};
-const CAMPAIGN_SCHEMA = {
-    type: "object",
-    properties: {
-        id: { type: "string" },
-        name: { type: "string" },
-        status: { type: "string" },
-        isSubcampaign: { type: "boolean" },
-        isActive: { type: "boolean" },
-        startDate: { type: "string" },
-        endDate: { type: ["string", "null"] },
-        locationIds: { type: "array", items: { type: "string" } },
-        parentCampaigns: { type: "array", items: REFERENCE },
-        subcampaigns: { type: "array", items: REFERENCE },
-        totalContributionCount: { type: "number" },
-        totalContributionValue: { type: "number" },
-        uniqueDonorCount: { type: "number" },
-    },
-    required: ["id", "name", "status"],
-};
-const LOCATION_SCHEMA = {
-    type: "object",
-    properties: {
-        id: { type: "string" },
-        name: { type: "string" },
-        isDefaultLocation: { type: "boolean" },
-        hideFromDonors: { type: "boolean" },
-        archivedAt: { type: ["string", "null"] },
-        createdAt: { type: "string" },
-    },
-    required: ["id", "name"],
-};
-const TAP_EVENT_SCHEMA = {
-    type: "object",
-    properties: {
-        id: { type: "string" },
-        createdAt: { type: "string" },
-        deviceId: { type: "string" },
-        deviceSerialNumber: { type: "number" },
-        groupId: { type: "string" },
-        groupName: { type: "string" },
-        destinationId: { type: "string" },
-        destinationName: { type: "string" },
-        destinationType: { type: "string" },
-    },
-    required: ["id", "createdAt"],
-};
-const WEBHOOK_SCHEMA = {
-    type: "object",
-    properties: {
-        id: { type: "string" },
-        name: { type: "string" },
-        destinationUrl: { type: "string" },
-        enabledEvents: { type: "array", items: { type: "string" } },
-        status: { type: "string" },
-        createdAt: { type: "string" },
-    },
-    required: ["id", "name", "status"],
-};
-const EVENT_LOG_SCHEMA = {
-    type: "object",
-    properties: {
-        id: { type: "string" },
-        eventId: { type: "string" },
-        webhookEventName: { type: "string" },
-        status: { type: "string" },
-        attemptNumber: { type: "number" },
-        attemptedAt: { type: "string" },
-        url: { type: "string" },
-        responseCode: { type: "number" },
-        errorMessage: { type: "string" },
-    },
-    required: ["id", "status"],
-};
-// --- Raw hatches ---------------------------------------------------------------
-const RAW_PATH_PROPERTY = {
-    type: "string",
-    minLength: 1,
-    description: "Path below /api/v3 beginning with '/', e.g. /refunds/<id>. No query string.",
-};
-const RAW_QUERY_PROPERTY = {
-    type: "array",
-    maxItems: 50,
-    description: "Query parameters as name/value pairs; repeat a name to send several values.",
-    items: {
-        type: "object",
-        properties: {
-            name: { type: "string", minLength: 1, description: "Parameter name, e.g. statusBucket[]." },
-            value: {
-                type: ["string", "number", "boolean"],
-                description: "Parameter value.",
-            },
-        },
-        required: ["name", "value"],
-        additionalProperties: false,
-    },
-};
-/** Name/value pairs to a query, repeated names becoming repeated keys. */
-function rawQuery(value) {
-    const query = {};
-    for (const row of asArray(value)) {
-        const pair = asRecord(row);
-        const name = pair["name"];
-        const item = pair["value"];
-        if (typeof name !== "string")
-            continue;
-        if (typeof item === "string" || typeof item === "number" || typeof item === "boolean") {
-            (query[name] ??= []).push(item);
-        }
-    }
-    return Object.fromEntries(Object.entries(query).map(([name, values]) => [name, values.length === 1 ? values[0] : values]));
-}
-function tools(send, defaultPageSize) {
-    const readOnly = { readOnlyHint: true };
-    const LIMIT = limitProperty(defaultPageSize);
-    /** One page-numbered collection read: `{ data, totalCount }` in, `{ <key>, page }` out. */
-    async function list(spec, ctx) {
-        const page = spec.args["page"] ?? 1;
-        const limit = spec.args["limit"] ?? defaultPageSize;
-        const payload = await callOverflow(send, { method: "GET", path: spec.path, query: { ...spec.query, page, limit } }, ctx);
-        const rows = asArray(asRecord(payload)["data"]);
-        return {
-            [spec.key]: spec.args["raw"] === true ? rows : rows.map(spec.project),
-            page: pageInfo(payload, page, limit, rows.length),
-        };
-    }
-    /** One single-resource read: Overflow wraps it as `{ data }`. */
-    async function one(path, ctx) {
-        const payload = await callOverflow(send, { method: "GET", path }, ctx);
-        const record = asRecord(payload)["data"];
-        if (record === undefined || record === null) {
-            throw new ConnectorCallError("connector_call_failed", "Overflow answered without the requested record.", {
-                retryable: false,
-            });
-        }
-        return asRecord(record);
-    }
-    return [
-        {
-            name: "overflow_api_get",
-            description: "Call any Overflow v3 GET endpoint and return its untouched body. Prefer a named read; this covers single refunds, chargebacks, campaigns, and Tap devices.",
-            annotations: readOnly,
-            inputSchema: namedInput({ path: RAW_PATH_PROPERTY, query: RAW_QUERY_PROPERTY }, ["path"]),
-            outputSchema: {
-                type: "object",
-                properties: { result: { description: "Overflow's untouched response body." } },
-                required: ["result"],
-            },
-            handler: async (args, ctx) => ({
-                result: (await callOverflow(send, { method: "GET", path: String(args["path"]), query: rawQuery(args["query"]) }, ctx, "raw")) ?? null,
-            }),
-        },
-        {
-            name: "overflow_api_mutate",
-            description: "Send a JSON POST, PATCH, or DELETE to Overflow v3. Every Overflow write — charges, refunds, recurring gifts, donor edits — goes here, behind approval.",
-            annotations: { readOnlyHint: false, destructiveHint: true },
-            inputSchema: namedInput({
-                method: {
-                    type: "string",
-                    enum: ["POST", "PATCH", "DELETE"],
-                    description: "Mutation method the Overflow endpoint requires.",
-                },
-                path: RAW_PATH_PROPERTY,
-                query: RAW_QUERY_PROPERTY,
-                body: {
-                    type: ["object", "array"],
-                    description: "JSON body exactly as Overflow documents it. Units differ: subscription `amount` is dollars, " +
-                        "/payments/authorize takes `amountInCents`, /contributions `amount` states none. Omit when the endpoint takes none.",
-                },
-            }, ["method", "path"]),
-            outputSchema: {
-                type: "object",
-                properties: {
-                    result: { description: "Overflow's untouched response body, or null when it sent none." },
-                },
-                required: ["result"],
-            },
-            handler: async (args, ctx) => ({
-                result: (await callOverflow(send, {
-                    method: args["method"],
-                    path: String(args["path"]),
-                    query: rawQuery(args["query"]),
-                    ...(args["body"] !== undefined ? { body: args["body"] } : {}),
-                }, ctx, "raw")) ?? null,
-            }),
-        },
-        {
-            name: "list_contributions",
-            description: "List gifts (cash, stock, crypto, DAF, manual) with status, amount, campaign, deposit, and donor name. Donor contact details stay in get_donor.",
-            annotations: readOnly,
-            inputSchema: namedInput({
-                minimumUpdatedDate: DATE_PROPERTY("Updated on or after"),
-                maximumUpdatedDate: DATE_PROPERTY("Updated on or before"),
-                minimumInitiatedDate: DATE_PROPERTY("Initiated on or after"),
-                maximumInitiatedDate: DATE_PROPERTY("Initiated on or before"),
-                statusBucket: {
-                    type: "array",
-                    minItems: 1,
-                    uniqueItems: true,
-                    items: {
-                        type: "string",
-                        enum: ["PENDING", "CONFIRMED", "FAILED", "CANCELED"],
-                        description: "Status bucket.",
-                    },
-                    description: "Overflow's coarse status buckets; matches any.",
-                },
-                campaignId: idProperty("list_campaigns"),
-                subcampaignId: idProperty("list_campaigns with isSubcampaign"),
-                locationIds: ID_LIST("list_locations"),
-                givingLinkId: { type: "string", minLength: 1, description: "Giving link id." },
-                pledgeId: { type: "string", minLength: 1, description: "Pledge id." },
-                page: PAGE_PROPERTY,
-                limit: LIMIT,
-                raw: RAW_PROPERTY,
-            }),
-            outputSchema: listOutput("contributions", CONTRIBUTION_SCHEMA),
-            handler: (args, ctx) => list({
-                args,
-                path: "/contributions",
-                key: "contributions",
-                project: projectContribution,
-                query: {
-                    minimumUpdatedDate: args["minimumUpdatedDate"],
-                    maximumUpdatedDate: args["maximumUpdatedDate"],
-                    minimumInitiatedDate: args["minimumInitiatedDate"],
-                    maximumInitiatedDate: args["maximumInitiatedDate"],
-                    "statusBucket[]": args["statusBucket"],
-                    campaignId: args["campaignId"],
-                    subcampaignId: args["subcampaignId"],
-                    "locationIds[]": args["locationIds"],
-                    givingLinkId: args["givingLinkId"],
-                    pledgeId: args["pledgeId"],
-                },
-            }, ctx),
-        },
-        {
-            name: "get_contribution",
-            description: "Get one contribution by id with its status, amount, campaign, deposit, and donor name. Refunds and chargebacks are separate lists.",
-            annotations: readOnly,
-            inputSchema: namedInput({ contributionId: idProperty("list_contributions"), raw: RAW_PROPERTY }, [
-                "contributionId",
-            ]),
-            outputSchema: CONTRIBUTION_SCHEMA,
-            handler: async (args, ctx) => {
-                const record = await one(`/contributions/${segment(args["contributionId"])}`, ctx);
-                return args["raw"] === true ? record : projectContribution(record);
-            },
-        },
-        {
-            name: "list_deposits",
-            description: "List deposits (payouts from Overflow to the nonprofit's bank) with status, net amount in cents, arrival date, and reconciliation state.",
-            annotations: readOnly,
-            inputSchema: namedInput({
-                startDate: DATE_PROPERTY("Arrived on or after"),
-                endDate: DATE_PROPERTY("Arrived on or before"),
-                types: {
-                    type: "array",
-                    minItems: 1,
-                    uniqueItems: true,
-                    items: { type: "string", enum: ["AUTOMATED", "MANUAL", "IMPORT"], description: "Deposit type." },
-                    description: "Deposit types; matches any.",
-                },
-                reconciled: { type: "boolean", description: "Filter by reconciliation state." },
-                minimumAmountInCents: { type: "integer", minimum: 0, description: "Net amount at least this, in cents." },
-                maximumAmountInCents: { type: "integer", minimum: 0, description: "Net amount at most this, in cents." },
-                search: { type: "string", minLength: 1, description: "Overflow's free-text search across deposit fields." },
-                sortDirection: { ...SORT_DIRECTION, description: "Arrival-date order. Defaults to DESC." },
-                page: PAGE_PROPERTY,
-                limit: LIMIT,
-                raw: RAW_PROPERTY,
-            }),
-            outputSchema: listOutput("deposits", DEPOSIT_SCHEMA),
-            handler: (args, ctx) => list({
-                args,
-                path: "/deposits",
-                key: "deposits",
-                project: (row) => projectDeposit(row, false),
-                query: {
-                    startDate: args["startDate"],
-                    endDate: args["endDate"],
-                    "types[]": args["types"],
-                    reconciled: args["reconciled"],
-                    minimumEstimatedValueInCents: args["minimumAmountInCents"],
-                    maximumEstimatedValueInCents: args["maximumAmountInCents"],
-                    search: args["search"],
-                    sortDirection: args["sortDirection"],
-                },
-            }, ctx),
-        },
-        {
-            name: "get_deposit",
-            description: "Get one deposit with its line items: each payment, refund, chargeback, adjustment, or transfer it settled, in cents. Totals are get_deposit_summary.",
-            annotations: readOnly,
-            inputSchema: namedInput({ depositId: idProperty("list_deposits"), raw: RAW_PROPERTY }, ["depositId"]),
-            outputSchema: DEPOSIT_SCHEMA,
-            handler: async (args, ctx) => {
-                const record = await one(`/deposits/${segment(args["depositId"])}`, ctx);
-                return args["raw"] === true ? record : projectDeposit(record, true);
-            },
-        },
-        {
-            name: "get_deposit_summary",
-            description: "Get one deposit's totals by kind — contributions, refunds, chargebacks, adjustments — as count, gross, fees, and net in cents.",
-            annotations: readOnly,
-            inputSchema: namedInput({ depositId: idProperty("list_deposits") }, ["depositId"]),
-            outputSchema: {
-                type: "object",
-                properties: {
-                    depositId: { type: "string" },
-                    contributions: MONEY_ROLLUP,
-                    refunds: MONEY_ROLLUP,
-                    chargebacks: MONEY_ROLLUP,
-                    adjustments: MONEY_ROLLUP,
-                },
-                required: ["depositId", "contributions", "refunds", "chargebacks", "adjustments"],
-            },
-            handler: async (args, ctx) => {
-                const summary = await one(`/deposits/${segment(args["depositId"])}/summary`, ctx);
-                const rollup = (value) => {
-                    const row = asRecord(value);
-                    return compact({
-                        count: row["count"] ?? 0,
-                        grossInCents: row["grossInCents"] ?? 0,
-                        feesInCents: row["feesInCents"] ?? 0,
-                        totalInCents: row["totalInCents"] ?? 0,
-                    });
-                };
-                return {
-                    depositId: args["depositId"],
-                    contributions: rollup(summary["contributions"]),
-                    refunds: rollup(summary["refunds"]),
-                    chargebacks: rollup(summary["chargebacks"]),
-                    adjustments: rollup(summary["adjustments"]),
-                };
-            },
-        },
-        {
-            name: "list_refunds",
-            description: "List refunds with status, reason, amount, and net in cents, optionally for one contribution. Reads only; issuing a refund is a mutate call.",
-            annotations: readOnly,
-            inputSchema: namedInput({
-                contributionId: idProperty("list_contributions"),
-                minimumUpdatedDate: DATE_PROPERTY("Updated on or after"),
-                maximumUpdatedDate: DATE_PROPERTY("Updated on or before"),
-                sortDirection: { ...SORT_DIRECTION, description: "Created-date order. Defaults to DESC." },
-                page: PAGE_PROPERTY,
-                limit: LIMIT,
-                raw: RAW_PROPERTY,
-            }),
-            outputSchema: listOutput("refunds", REFUND_SCHEMA),
-            handler: (args, ctx) => list({
-                args,
-                path: "/refunds",
-                key: "refunds",
-                project: projectRefund,
-                query: {
-                    contributionId: args["contributionId"],
-                    minimumUpdatedDate: args["minimumUpdatedDate"],
-                    maximumUpdatedDate: args["maximumUpdatedDate"],
-                    sortDirection: args["sortDirection"],
-                },
-            }, ctx),
-        },
-        {
-            name: "list_chargebacks",
-            description: "List chargebacks (card disputes and ACH returns) with status — pending, won, lost — and amounts in cents, optionally for one contribution.",
-            annotations: readOnly,
-            inputSchema: namedInput({
-                contributionId: idProperty("list_contributions"),
-                minimumUpdatedDate: DATE_PROPERTY("Updated on or after"),
-                maximumUpdatedDate: DATE_PROPERTY("Updated on or before"),
-                sortDirection: { ...SORT_DIRECTION, description: "Created-date order. Defaults to DESC." },
-                page: PAGE_PROPERTY,
-                limit: LIMIT,
-                raw: RAW_PROPERTY,
-            }),
-            outputSchema: listOutput("chargebacks", CHARGEBACK_SCHEMA),
-            handler: (args, ctx) => list({
-                args,
-                path: "/chargebacks",
-                key: "chargebacks",
-                project: projectChargeback,
-                query: {
-                    contributionId: args["contributionId"],
-                    minimumUpdatedDate: args["minimumUpdatedDate"],
-                    maximumUpdatedDate: args["maximumUpdatedDate"],
-                    sortDirection: args["sortDirection"],
-                },
-            }, ctx),
-        },
-        {
-            name: "list_donors",
-            description: "List donors with name, email, gift count, and recurring count. Cannot search by name or email; omits phone and address, which get_donor returns.",
-            annotations: readOnly,
-            inputSchema: namedInput({
-                locationIds: ID_LIST("list_locations"),
-                minimumUpdatedDate: DATE_PROPERTY("Updated on or after"),
-                maximumUpdatedDate: DATE_PROPERTY("Updated on or before"),
-                sortBy: {
-                    type: "string",
-                    enum: ["updatedAt", "createdAt", "lastName", "firstName", "email", "totalContributionsCount"],
-                    description: "Sort field. Defaults to updatedAt.",
-                },
-                sortDirection: { ...SORT_DIRECTION, description: "Defaults to DESC." },
-                page: PAGE_PROPERTY,
-                limit: LIMIT,
-                raw: RAW_PROPERTY,
-            }),
-            outputSchema: listOutput("donors", DONOR_SCHEMA),
-            handler: (args, ctx) => list({
-                args,
-                path: "/donors",
-                key: "donors",
-                project: (row) => projectDonor(row, false),
-                query: {
-                    "locationIds[]": args["locationIds"],
-                    minimumUpdatedDate: args["minimumUpdatedDate"],
-                    maximumUpdatedDate: args["maximumUpdatedDate"],
-                    sortBy: args["sortBy"],
-                    sortDirection: args["sortDirection"],
-                },
-            }, ctx),
-        },
-        {
-            name: "get_donor",
-            description: "Get one donor's full profile: contact details, mailing address, locations, and giving counts. Their gifts are list_contributions rows.",
-            annotations: readOnly,
-            inputSchema: namedInput({ donorId: idProperty("list_donors or a contribution's donor.id") }, ["donorId"]),
-            outputSchema: DONOR_SCHEMA,
-            handler: async (args, ctx) => projectDonor(await one(`/donors/${segment(args["donorId"])}`, ctx), true),
-        },
-        {
-            name: "list_subscriptions",
-            description: "List recurring gifts with status, amount, frequency, next payment date, and campaign — for the nonprofit or, given donorId, one donor.",
-            annotations: readOnly,
-            inputSchema: namedInput({
-                donorId: idProperty("list_donors; omit for every donor"),
-                status: {
-                    type: "array",
-                    minItems: 1,
-                    uniqueItems: true,
-                    items: {
-                        type: "string",
-                        enum: ["active", "paused", "pending", "failed", "inactive", "recreated"],
-                        description: "Recurring-gift status.",
-                    },
-                    description: "Statuses; matches any.",
-                },
-                locationIds: ID_LIST("list_locations"),
-                minimumUpdatedDate: DATE_PROPERTY("Updated on or after"),
-                maximumUpdatedDate: DATE_PROPERTY("Updated on or before"),
-                sortBy: {
-                    type: "string",
-                    enum: ["createdAt", "amount", "frequency", "nextContributionAt"],
-                    description: "Sort field. Defaults to createdAt.",
-                },
-                sortDirection: { ...SORT_DIRECTION, description: "Defaults to DESC." },
-                page: PAGE_PROPERTY,
-                limit: LIMIT,
-                raw: RAW_PROPERTY,
-            }),
-            outputSchema: listOutput("subscriptions", SUBSCRIPTION_SCHEMA),
-            handler: (args, ctx) => list({
-                args,
-                path: args["donorId"] === undefined ? "/subscriptions" : `/subscriptions/${segment(args["donorId"])}`,
-                key: "subscriptions",
-                project: projectSubscription,
-                query: {
-                    "status[]": args["status"],
-                    "locationIds[]": args["locationIds"],
-                    minimumUpdatedDate: args["minimumUpdatedDate"],
-                    maximumUpdatedDate: args["maximumUpdatedDate"],
-                    sortBy: args["sortBy"],
-                    sortDirection: args["sortDirection"],
-                },
-            }, ctx),
-        },
-        {
-            name: "list_payment_methods",
-            description: "List one donor's saved payment methods (type, last 4, expiry) and their ids. Unpaginated. Never returns account or card numbers.",
-            annotations: readOnly,
-            inputSchema: namedInput({
-                donorId: idProperty("list_donors"),
-                showExpired: { type: "boolean", description: "Include expired methods. Defaults to false." },
-                raw: RAW_PROPERTY,
-            }, ["donorId"]),
-            outputSchema: {
-                type: "object",
-                properties: { paymentMethods: { type: "array", items: PAYMENT_METHOD_SCHEMA } },
-                required: ["paymentMethods"],
-            },
-            handler: async (args, ctx) => {
-                const payload = await callOverflow(send, {
-                    method: "GET",
-                    path: `/payment-methods/${segment(args["donorId"])}`,
-                    query: { showExpired: args["showExpired"] },
-                }, ctx);
-                const rows = asArray(asRecord(payload)["data"]);
-                return { paymentMethods: args["raw"] === true ? rows : rows.map(projectPaymentMethod) };
-            },
-        },
-        {
-            name: "list_campaigns",
-            description: "List campaigns or subcampaigns with status, dates, and giving totals. Ids feed the campaignId filters and gift bodies.",
-            annotations: readOnly,
-            inputSchema: namedInput({
-                isSubcampaign: { type: "boolean", description: "True lists subcampaigns instead. Defaults to false." },
-                parentCampaignId: idProperty("list_campaigns; lists its subcampaigns"),
-                search: { type: "string", minLength: 1, description: "Campaign-name search." },
-                includeArchived: { type: "boolean", description: "Include archived campaigns." },
-                excludeInactive: { type: "boolean", description: "Exclude campaigns that have ended." },
-                sortBy: {
-                    type: "string",
-                    enum: [
-                        "startDate",
-                        "endDate",
-                        "name",
-                        "displayOrder",
-                        "totalContributionCount",
-                        "totalContributionValue",
-                        "uniqueDonorCount",
-                    ],
-                    description: "Sort field. Defaults to startDate.",
-                },
-                sortDirection: { ...SORT_DIRECTION, description: "Defaults to DESC." },
-                page: PAGE_PROPERTY,
-                limit: LIMIT,
-                raw: RAW_PROPERTY,
-            }),
-            outputSchema: listOutput("campaigns", CAMPAIGN_SCHEMA),
-            handler: (args, ctx) => list({
-                args,
-                path: "/campaigns",
-                key: "campaigns",
-                project: projectCampaign,
-                query: {
-                    isSubcampaign: args["isSubcampaign"] === undefined
-                        ? args["parentCampaignId"] === undefined
-                            ? undefined
-                            : "true"
-                        : String(args["isSubcampaign"]),
-                    parentCampaignId: args["parentCampaignId"],
-                    search: args["search"],
-                    includeArchived: args["includeArchived"],
-                    excludeInactive: args["excludeInactive"],
-                    sortBy: args["sortBy"],
-                    sortDirection: args["sortDirection"],
-                },
-            }, ctx),
-        },
-        {
-            name: "list_locations",
-            description: "List the nonprofit's locations (campuses) with names and ids for the locationIds filters. The default location is flagged.",
-            annotations: readOnly,
-            inputSchema: namedInput({
-                includeArchived: { type: "boolean", description: "Include archived locations." },
-                sortBy: {
-                    type: "string",
-                    enum: ["displayOrder", "name", "createdAt"],
-                    description: "Sort field. Defaults to displayOrder.",
-                },
-                sortDirection: { ...SORT_DIRECTION, description: "Defaults to ASC." },
-                page: PAGE_PROPERTY,
-                limit: LIMIT,
-            }),
-            outputSchema: listOutput("locations", LOCATION_SCHEMA),
-            handler: (args, ctx) => list({
-                args,
-                path: "/locations",
-                key: "locations",
-                project: projectLocation,
-                query: {
-                    includeArchived: args["includeArchived"],
-                    sortBy: args["sortBy"],
-                    sortDirection: args["sortDirection"],
-                },
-            }, ctx),
-        },
-        {
-            name: "list_tap_events",
-            description: "List Tap-to-give taps with the device, group, and destination each hit. Taps are engagement, not gifts; giving is list_contributions.",
-            annotations: readOnly,
-            inputSchema: namedInput({
-                startDate: DATE_PROPERTY("On or after"),
-                endDate: DATE_PROPERTY("On or before"),
-                groupIds: ID_LIST("a tap event's groupId"),
-                destinationIds: ID_LIST("a tap event's destinationId"),
-                deviceIds: ID_LIST("a tap event's deviceId"),
-                sortDirection: { ...SORT_DIRECTION, description: "Time order. Defaults to DESC." },
-                page: PAGE_PROPERTY,
-                limit: LIMIT,
-                raw: RAW_PROPERTY,
-            }),
-            outputSchema: listOutput("events", TAP_EVENT_SCHEMA),
-            handler: (args, ctx) => list({
-                args,
-                path: "/tap/events",
-                key: "events",
-                project: projectTapEvent,
-                query: {
-                    startDate: args["startDate"],
-                    endDate: args["endDate"],
-                    "groupIds[]": args["groupIds"],
-                    "destinationIds[]": args["destinationIds"],
-                    "deviceIds[]": args["deviceIds"],
-                    sortDirection: args["sortDirection"],
-                },
-            }, ctx),
-        },
-        {
-            name: "list_webhooks",
-            description: "List the nonprofit's webhook subscriptions with destination URL, enabled events, and status. Delivery history is list_webhook_event_logs.",
-            annotations: readOnly,
-            inputSchema: namedInput({
-                status: { type: "string", enum: ["enabled", "disabled"], description: "Subscription status." },
-                sortDirection: { ...SORT_DIRECTION, description: "Created-date order. Defaults to DESC." },
-                page: PAGE_PROPERTY,
-                limit: LIMIT,
-            }),
-            outputSchema: listOutput("webhooks", WEBHOOK_SCHEMA),
-            handler: (args, ctx) => list({
-                args,
-                path: "/webhooks",
-                key: "webhooks",
-                project: projectWebhook,
-                query: { status: args["status"], sortDirection: args["sortDirection"] },
-            }, ctx),
-        },
-        {
-            name: "list_webhook_event_logs",
-            description: "List delivery attempts for one webhook with status, response code, and error. Omits event payloads unless raw. Pages by cursor, not page.",
-            annotations: readOnly,
-            inputSchema: namedInput({
-                webhookId: idProperty("list_webhooks"),
-                status: { type: "string", enum: ["delivered", "failed", "pending"], description: "Delivery status." },
-                webhookEventName: {
-                    type: "string",
-                    pattern: "^(\\*|[a-z_]+\\.[a-z_]+)$",
-                    description: "Event name, e.g. contribution.approved or donor.updated.",
-                },
-                sortDirection: { ...SORT_DIRECTION, description: "Attempt order. Defaults to DESC." },
-                cursor: {
-                    type: "string",
-                    minLength: 1,
-                    description: "This tool pages by cursor: pass nextCursor back unchanged.",
-                },
-                limit: {
-                    type: "integer",
-                    minimum: 1,
-                    maximum: MAX_EVENT_LOG_PAGE_SIZE,
-                    description: `Attempts per page, up to Overflow's cap of ${MAX_EVENT_LOG_PAGE_SIZE} for this endpoint. Defaults to ${DEFAULT_EVENT_LOG_PAGE_SIZE}.`,
-                },
-                raw: RAW_PROPERTY,
-            }, ["webhookId"]),
-            outputSchema: {
-                type: "object",
-                properties: {
-                    attempts: { type: "array", items: EVENT_LOG_SCHEMA },
-                    nextCursor: {
-                        type: "string",
-                        description: "Present only when more attempts exist; no page object.",
-                    },
-                },
-                required: ["attempts"],
-            },
-            handler: async (args, ctx) => {
-                const payload = asRecord(await callOverflow(send, {
-                    method: "GET",
-                    path: `/webhooks/${segment(args["webhookId"])}/event-logs`,
-                    query: {
-                        status: args["status"],
-                        webhookEventName: args["webhookEventName"],
-                        sortDirection: args["sortDirection"],
-                        cursor: args["cursor"],
-                        limit: args["limit"] ?? DEFAULT_EVENT_LOG_PAGE_SIZE,
-                    },
-                }, ctx));
-                const rows = asArray(payload["data"]);
-                const info = asRecord(payload["pageInfo"]);
-                const next = info["nextCursor"];
-                return compact({
-                    attempts: args["raw"] === true ? rows : rows.map(projectEventLog),
-                    nextCursor: info["hasNextPage"] === true && typeof next === "string" && next !== "" ? next : undefined,
-                });
-            },
-        },
-    ];
-}
-// --- Guide ---------------------------------------------------------------------
-function usageGuide(purpose, environment, instructions) {
-    const accountInstructions = instructions?.trim();
-    const environmentLine = environment === "production"
-        ? "Overflow **production**: live nonprofit giving data, real donors, and real money."
-        : "Overflow **staging**: Overflow's sandbox, isolated from production donors and money.";
-    return `# Overflow usage
-
-${environmentLine}
-
-Nonprofit purpose: ${purpose}${skill.fragments.guide_0}${accountInstructions ? `\n## ${skill.instructionsHeading}\n\n${accountInstructions}\n` : ""}`;
-}
-// --- Construction --------------------------------------------------------------
-/** The closed options overflow() accepts; see `assertKnownOptions`. */
 const OVERFLOW_OPTIONS = optionsOf()({
     ...PROVIDER_COMMON,
     ...keys("environment", "defaultPageSize", "baseUrl"),
 });
-/**
- * A maintained Overflow connection.
- *
- * `environment` is required with no default, and the argument runs the other
- * way from a provider whose environment rides the credential. Overflow
- * publishes two base URLs and issues separate credentials for each, so a
- * mismatch fails loudly with a 403 rather than reaching the wrong data — but
- * that is exactly why a default buys nothing. Defaulting to staging, the
- * "safe" side, sends every real deployment to a sandbox where its production
- * key is refused with a generic "Forbidden resource" and no hint that the base
- * URL is the problem. Defaulting to production makes a test deployment that
- * forgot the option one pasted key away from charging real donors through the
- * mutate hatch. The environment is a fact the operator knows and connecta
- * cannot infer — Overflow's keys carry no recognizable environment marker — so
- * the operator states it, and the title and the guide's first line repeat it.
- */
-export const overflow = asProviderFactory({
+function environmentOf(options) {
+    const environment = options.environment;
+    if (environment !== "production" && environment !== "staging")
+        throw new Error('overflow() requires environment: "production" or "staging". Overflow issues separate credentials for each, and connecta will not guess which one a deployment means.');
+    return environment;
+}
+export const overflow = defineApiProvider({
     name: "overflow",
     title: "Overflow",
-    kind: "api",
     readme: "Overflow",
-    bundle: {
-        "baselineGzip": 20410,
-        "maxGzip": 80410,
-        "note": "./providers/overflow starts at 20,410 B gzip: a hand-written api() surface over the guarded transport with no hosted-MCP interface, so it pulls in neither remoteMcp nor the Effect core the other providers carry. The cap uses the existing baseline + 60,000 B policy.",
-    },
     skill,
     options: OVERFLOW_OPTIONS,
-    create: overflowConnector,
+    bundle: {
+        baselineGzip: 352543,
+        note: "./providers/overflow measures 352,543 B gzip standalone at 88c918ed (0011 step 2), versus 341,849 B on main 8e92eed9 (+10,694 B), Node 26.12.0 with zlib-ng 1.3.1. This includes the shared Effect kit, paid once per deployment; provider entries are reported, not capped, and their sizes are not additive (#899).",
+    },
+    displayTitle: (options) => `Overflow (${environmentOf(options)})`,
+    description: (options) => `Overflow nonprofit giving, ${environmentOf(options)}: ${options.purpose}`,
+    vendor: OverflowApi,
+    baseUrl: (options) => `${(options.baseUrl?.trim() || OVERFLOW_API_BASE_URLS[environmentOf(options)]).replace(/\/+$/, "")}/api/v3`,
+    maxResponseBytes: OVERFLOW_MAX_RESPONSE_BYTES,
+    headers: { Accept: "application/json" },
+    pageSize: { default: DEFAULT_PAGE_SIZE, max: MAX_PAGE_SIZE },
+    credential: API_KEY_CREDENTIAL,
+    authenticate,
+    admit,
+    errors,
+    idempotencyKey: false,
+    safety: () => safety,
+    result,
+    probe,
+    guide: (options) => ({
+        heading: "Overflow usage",
+        context: [
+            environmentOf(options) === "production"
+                ? "Overflow production: live nonprofit giving, donors and money."
+                : "Overflow staging: a sandbox with separate credentials and data.",
+            `Nonprofit purpose: ${options.purpose}`,
+            "Named reads minimize contact data; get_donor is the full-contact lookup. Webhook signing secrets are always removed.",
+            ...(options.readOnly ? ["This connection is read-only: every write is refused."] : []),
+            ...(options.defaultPageSize !== undefined
+                ? [`Paged lists return ${options.defaultPageSize} items by default on this connection.`]
+                : []),
+        ],
+        summary: "Giving records: asset-specific status, per-field money units, donor joins and deposit reconciliation.",
+        required: true,
+    }),
+    hatch: {
+        name: "overflow",
+        title: "Overflow",
+        index: OVERFLOW_INDEX,
+        verdicts: OVERFLOW_VERDICTS,
+        named: OVERFLOW_NAMED,
+        pages: OVERFLOW_PAGES,
+        pathExample: "/donors/6710f34fd5061afeec3eab50",
+        notes: () => ({
+            read: "Paths are relative to /api/v3. Array query filters use bracketed names and repeated values; GET /health returns text.",
+            write: "Refund acknowledgements can be JSON strings or plain text; empty write acknowledgements are valid. Resolve donor and payment-method ids first; money units differ by field.",
+        }),
+    },
+    defaultCallAdmission: OVERFLOW_ADMISSION,
+    tools: overflowTools,
 });
-function overflowConnector(id, options) {
-    const purpose = options.purpose?.trim();
-    if (!purpose) {
-        throw new Error("overflow() requires a non-empty nonprofit purpose.");
-    }
-    const environment = options.environment;
-    if (environment !== "production" && environment !== "staging") {
-        throw new Error('overflow() requires environment: "production" or "staging". Overflow issues separate credentials for each, and connecta will not guess which one a deployment means.');
-    }
-    const defaultPageSize = options.defaultPageSize ?? DEFAULT_PAGE_SIZE;
-    if (!Number.isInteger(defaultPageSize) || defaultPageSize < 1 || defaultPageSize > MAX_PAGE_SIZE) {
-        throw new Error(`overflow() defaultPageSize must be a whole number between 1 and ${MAX_PAGE_SIZE}.`);
-    }
-    const send = overflowTransport(options.baseUrl?.trim() || OVERFLOW_API_BASE_URLS[environment]);
-    const label = environment === "production" ? "production" : "staging";
-    return api(id, {
-        ...defined({ authScope: options.authScope, maxResultBytes: options.maxResultBytes }),
-        title: options.title ?? `Overflow (${label})`,
-        description: `Overflow nonprofit giving, ${label}: ${purpose}`,
-        credential: API_KEY_CREDENTIAL,
-        async testCredentials(values, ctx) {
-            // Overflow has no identity endpoint, and /health answers without a
-            // credential, so it proves nothing. One location is the cheapest
-            // authenticated read: every nonprofit has at least its default one, and
-            // its name is the closest thing to "which organization is this?" the
-            // API will say.
-            try {
-                const payload = asRecord(await callOverflow(send, { method: "GET", path: "/locations", query: { limit: 1, sortBy: "displayOrder" } }, {
-                    ...ctx,
-                    credential: {
-                        get: async (field) => (field ? (values[field] ?? null) : null),
-                        getAll: async () => values,
-                    },
-                }));
-                const first = asRecord(asArray(payload["data"])[0]);
-                const total = payload["totalCount"];
-                const where = typeof first["name"] === "string"
-                    ? ` The nonprofit's first location is "${first["name"]}"${typeof total === "number" ? ` of ${total}` : ""}.`
-                    : "";
-                return {
-                    ok: true,
-                    message: `Overflow ${label} accepted the client id and API key.${where}`,
-                };
-            }
-            catch (error) {
-                return {
-                    ok: false,
-                    message: error instanceof ConnectorCallError
-                        ? error.message
-                        : `Overflow ${label} rejected the client id and API key.`,
-                };
-            }
-        },
-        callAdmission: options.callAdmission === undefined ? OVERFLOW_ADMISSION : options.callAdmission,
-        usageGuide: {
-            content: usageGuide(purpose, environment, options.instructions),
-            summary: `Overflow ${label}: money units per field, final statuses, deposits, donor-PII care, and writes via mutate.`,
-            // Required because correct use depends on facts no schema carries:
-            // which statuses are final per asset type, which money unit each field
-            // and write body uses (cents, dollars, or unstated), and
-            // that every write is a mutate-hatch call whose body comes from
-            // Overflow's reference.
-            required: true,
-        },
-        tools: tools(send, defaultPageSize),
-    });
-}