@zackbart/connecta 0.34.1 → 0.36.0

package/dist/providers/ccb/api.js

@@ -0,0 +1,496 @@
+import { CCB_MEDIA_TYPE, CCB_ENVIRONMENTS, CCB_READ_SCOPES, CCB_WRITE_SCOPES, CCB_SENSITIVE_FIELDS, } from "./lib/constants.js";
+// Pushpay ChMS v2 JSON contracts, OAuth, status meanings, admission and privacy.
+// The legacy per-church XML API is outside this provider's scope.
+import { Effect, Schema } from "effect";
+import { ConnectorCallError } from "../../errors.js";
+import { OperationIndex } from "../_shared/rest/operation-index.js";
+import { checked, indexedVendor } from "../_shared/rest/kit.js";
+import { valueSafety } from "../_shared/rest/value-safety.js";
+import { restSafety } from "../../http/safety.js";
+import { openapi } from "./openapi.generated.js";
+import { CCB_VALUE_SAFETY } from "./safety.js";
+import { CCB_VERDICTS } from "./lib/verdicts.js";
+export { CCB_VERDICTS };
+import { bearer } from "../../http/oauth.js";
+import { get } from "../../http/vendor.js";
+export const authenticate = bearer;
+const SCOPE_SHAPE = /^(read|write|delete):[a-z_]+$/;
+/** CCB's own minimum, which is also the cheapest honest first read. */
+export const DEFAULT_PER_PAGE = 25;
+/**
+ * A ceiling on absurdity rather than a budget: at 100 rows per page the
+ * fattest documented list (individuals with addresses) stays far below it.
+ */
+export const CCB_MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
+/**
+ * CCB meters the v2 API per endpoint and per API client: one request a second
+ * sustained with a burst of 60 (docs.pushpay.io/chms-v2/docs/general). Three
+ * endpoints are stricter and allow no burst — `/individuals/{id}` at one a
+ * second, `/scheduling/categories/{id}/schedules` at one per two seconds, and
+ * `/search/individuals/results` at one per five.
+ *
+ * What ships is one rolling window of 60 calls per 60 seconds, partitioned by
+ * endpoint (method plus path template), which is the documented default
+ * transcribed as faithfully as one rule can: it never admits more than the
+ * token bucket would in any minute, because a bucket of 60 refilling at one a
+ * second can pass up to 120 in a minute and the window passes 60. Partitioning
+ * matters — a single connector-wide window would throttle a healthy program
+ * that touches ten endpoints to a tenth of what CCB allows.
+ *
+ * What it cannot express is the three no-burst overrides: this release
+ * enforces one rule, and a rule has one budget for every partition. Those are
+ * left to CCB's own 429, which carries `retry-after` and maps to a
+ * `rate_limited` failure with that wait; the guide says to space those calls.
+ * No `maxConcurrency` is declared: per-endpoint concurrency would not keep a
+ * fast loop under one a second, and the window already bounds the burst.
+ *
+ * Per runtime, and per API client only as far as one runtime is the whole
+ * client: other deployments, isolates, or integrations using the same client
+ * spend from CCB's bucket without spending from this window.
+ */
+export const CCB_ADMISSION = {
+    rules: [
+        {
+            budget: { kind: "rolling-window", maxCalls: 60, windowMs: 60_000 },
+            partitionKey: ({ toolName, args }) => endpointPartition(toolName, args),
+        },
+    ],
+};
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+// ---------------------------------------------------------------------------
+// Admission partitions
+// ---------------------------------------------------------------------------
+/** The method and path template each named tool calls. */
+const NAMED_ENDPOINTS = {
+    get_me: "GET /me",
+    list_individuals: "GET /individuals",
+    get_individual: "GET /individuals/{id}",
+    list_families: "GET /families",
+    get_family: "GET /families/{id}",
+    list_groups: "GET /groups",
+    get_group: "GET /groups/{id}",
+    list_group_members: "GET /groups/{id}/members",
+    list_individual_groups: "GET /individuals/{id}/groups",
+    list_events: "GET /events",
+    get_event: "GET /events/{id}",
+    get_event_attendance: "GET /events/{id}/attendance/{occurrence}",
+    list_event_attendees: "GET /events/{id}/attendance/{occurrence}/attendees",
+    list_individual_notes: "GET /individuals/{id}/notes",
+    get_giving_metrics: (args) => args["familyId"] !== undefined ? "GET /families/{id}/metrics/giving" : "GET /individuals/{id}/metrics/giving",
+    search_records: (args) => `POST /search/${typeof args["domain"] === "string" ? args["domain"] : "?"}/results`,
+};
+/** `/individuals/123/notes` → `/individuals/{id}/notes`; the key never holds an id. */
+function pathTemplate(path) {
+    return path
+        .split("/")
+        .map((segment) => (/^\d+$/.test(segment) ? "{id}" : segment))
+        .join("/");
+}
+const MAX_PARTITION_KEY_CHARS = 120;
+/**
+ * The CCB endpoint one call will spend from, as a bounded, id-free key. Runs
+ * before argument validation, so it reads arguments defensively and never
+ * throws: a malformed hatch path falls into one shared partition and is then
+ * refused by the handler.
+ */
+function endpointPartition(toolName, raw) {
+    const args = asRecord(raw);
+    const named = NAMED_ENDPOINTS[toolName];
+    let key;
+    if (typeof named === "string")
+        key = named;
+    else if (named)
+        key = named(args);
+    else {
+        const method = toolName === "ccb_api_read"
+            ? typeof args["method"] === "string"
+                ? args["method"]
+                : "GET"
+            : typeof args["method"] === "string"
+                ? args["method"]
+                : "?";
+        const path = typeof args["path"] === "string" ? args["path"] : "";
+        key = `${method} ${pathTemplate(path)}`;
+    }
+    // ASCII-only after templating in every realistic case; the slice keeps an
+    // absurd path inside the admission controller's 128-byte key limit anyway.
+    return [...key]
+        .filter((c) => c.charCodeAt(0) < 128)
+        .join("")
+        .slice(0, MAX_PARTITION_KEY_CHARS);
+}
+export function resolveScopes(options) {
+    if (options.scopes !== undefined && options.access !== undefined) {
+        throw new Error("ccb() takes access or scopes, not both: scopes is the exact list and replaces access.");
+    }
+    if (options.scopes === undefined) {
+        const access = options.access ?? "read";
+        if (access !== "read" && access !== "read-write") {
+            throw new Error('ccb() access must be "read" or "read-write".');
+        }
+        return access === "read" ? CCB_READ_SCOPES : [...CCB_READ_SCOPES, ...CCB_WRITE_SCOPES];
+    }
+    if (!Array.isArray(options.scopes) || options.scopes.length === 0) {
+        throw new Error("ccb() scopes must be a non-empty list.");
+    }
+    const seen = new Set();
+    for (const scope of options.scopes) {
+        if (typeof scope !== "string" || !SCOPE_SHAPE.test(scope)) {
+            throw new Error(`ccb() scope "${String(scope)}" is not a CCB scope; CCB scopes look like read:individuals.`);
+        }
+        if (seen.has(scope))
+            throw new Error(`ccb() scope "${scope}" is listed twice.`);
+        seen.add(scope);
+    }
+    return [...options.scopes];
+}
+export const SEARCH_DOMAINS = [
+    "assignments",
+    "categories",
+    "department_detail",
+    "groups",
+    "individual_event_attendance",
+    "individual_groups",
+    "individuals",
+    "organizers",
+    "positions",
+    "schedules",
+    "schedules_totals",
+    "scheduling_files",
+    "scheduling_individuals",
+    "songs",
+    "volunteers",
+];
+const summaries = {
+    "GET /individuals": "List people (person profiles, individuals), search names, email and phone",
+    "GET /individuals/{id}": "Get a person profile (individual) for identity or update reconciliation",
+    "PUT /individuals/{id}": "Update or change a person's email, edit an individual profile, name or change phone number",
+    "POST /individuals": "Create or add a person profile, new individual",
+    "POST /individuals/{id}/notes": "Add or create a pastoral note for a person (individual)",
+    "GET /families": "List households and families",
+    "GET /groups/{id}/members": "List church group members and leaders, roster",
+    "POST /groups/{id}/members": "Add person to group, create group membership",
+    "PUT /groups/{group_id}/members/roles": "Change group role, update member or leader roles",
+    "POST /events/{id}/attendance/{occurrence}": "Record attendance, take attendance for an event occurrence",
+    "GET /individuals/{id}/metrics/giving": "Get individual giving metrics, donations and contributions counts",
+    "GET /families/{id}/metrics/giving": "Get family giving metrics, donations and contributions counts",
+    "POST /search/individuals/results": "Search people and individual profiles with advanced configuration and filters",
+    "GET /campuses": "List church campuses, timezone and public gift message",
+};
+const details = JSON.parse(openapi.details);
+// These thirteen wildcard-labelled schemas describe twelve JSON objects and
+// one JSON array. Their byte-pinned contracts were reviewed for JSON dispatch.
+const jsonBodies = new Set([
+    "POST /forms/{id}/responses",
+    "PUT /individuals/{id}/groups/{group_id}",
+    "PUT /individuals/{id}/privacy_settings",
+    "POST /church/privacy_defaults",
+    "PUT /messages/{id}",
+    "POST /messages/{id}/comments",
+    "PUT /messages/{id}/comments/{comment_id}",
+    "POST /scheduling/categories/{id}/notifications",
+    "PUT /individuals/{id}/assignments",
+    "PUT /scheduling/families/{id}/assignments",
+    "PUT /individuals/{id}/groups/bulk",
+    "POST /search/save",
+    "PUT /search/save/{id}",
+]);
+for (const [i, row] of details.o.entries()) {
+    const op = openapi.ops[i];
+    if (jsonBodies.has(`${op[0]} ${op[1]}`)) {
+        if (!row || !row[1] || row[1][0] !== "*/*")
+            throw new Error("CCB JSON request review is stale.");
+        row[1][0] = "application/json";
+    }
+}
+for (const row of details.o) {
+    if (row)
+        for (const parameter of row[0])
+            if (!parameter[4])
+                parameter[4] =
+                    {
+                        id: "Record id from a prior read; resolve the target before acting.",
+                        page: "Vendor page number restored from the signed continuation.",
+                        per_page: "Page size: 25, 50, 75 or 100; defaults to 25.",
+                        name: "Partial name search.",
+                    }[parameter[0]] ?? `${parameter[0].replaceAll("_", " ")} ${parameter[1]} parameter from the vendor contract.`;
+}
+export const CCB_INDEX = new OperationIndex({
+    ...openapi,
+    details: JSON.stringify(details),
+    // The public campus directory is church setup; retain both resource
+    // words so conversational searches distinguish it from campus subresources.
+    tags: [...openapi.tags, "church campuses"],
+    ops: openapi.ops.map((row) => {
+        const summary = summaries[`${row[0]} ${row[1]}`];
+        const label = summary ? `${summary}; ${row[3]}` : row[3];
+        const tag = row[0] === "GET" && row[1] === "/campuses" ? openapi.tags.length : row[4];
+        return row[5] === undefined
+            ? [row[0], row[1], row[2], label, tag]
+            : [row[0], row[1], row[2], label, tag, row[5]];
+    }),
+}, { vendor: "ccb", title: "CCB" });
+export const getMe = get("getMe", "/me", { success: Schema.Unknown });
+export const CcbApi = indexedVendor("CCB", CCB_INDEX, [getMe]);
+const safety = valueSafety(CCB_VALUE_SAFETY, () => CCB_INDEX);
+export const CCB_PAGE_HEADERS = ["x-page", "x-next-page", "x-total-pages", "x-total"];
+export function ccbPageInfo(headers, page, size, rows) {
+    const number = (name) => {
+        const raw = headers[name];
+        if (raw === undefined || raw === "")
+            return undefined;
+        if (!/^(0|[1-9]\d*)$/.test(raw) || !Number.isSafeInteger(Number(raw)))
+            throw new ConnectorCallError("connector_call_failed", "CCB returned invalid paging metadata.", {
+                retryable: false,
+            });
+        return Number(raw);
+    };
+    const current = number("x-page") ?? page;
+    if (current !== page)
+        throw new ConnectorCallError("connector_call_failed", "CCB returned a different page than requested.", {
+            retryable: false,
+        });
+    let next;
+    if (Object.hasOwn(headers, "x-next-page"))
+        next = number("x-next-page") ?? null;
+    else {
+        const pages = number("x-total-pages");
+        next = pages === undefined ? (rows >= size ? page + 1 : null) : page < pages ? page + 1 : null;
+    }
+    if (next !== null && (!rows || next <= page))
+        throw new ConnectorCallError("connector_call_failed", "CCB returned a nonadvancing or empty continuing page.", {
+            retryable: false,
+        });
+    return next;
+}
+const pageAdapter = {
+    param: "page",
+    in: "query",
+    headers: CCB_PAGE_HEADERS,
+    decode: (cursor) => {
+        const value = Number(cursor);
+        if (!/^[1-9]\d*$/.test(String(cursor)) || !Number.isSafeInteger(value))
+            throw new ConnectorCallError("invalid_args", "This CCB cursor contains no valid page number.");
+        return value;
+    },
+    next: (data, call) => {
+        const rows = Array.isArray(data)
+            ? data
+            : Array.isArray(asRecord(data)["items"])
+                ? asRecord(data)["items"]
+                : undefined;
+        if (!rows && !Object.hasOwn(call.headers, "x-next-page") && !Object.hasOwn(call.headers, "x-total-pages"))
+            return undefined;
+        return ccbPageInfo(call.headers, Number(call.query["page"] ?? 1), Number(call.query["per_page"] ?? 25), rows?.length ?? 1);
+    },
+};
+export const CCB_PAGES = Object.fromEntries(CCB_INDEX.ops
+    .filter((op) => CCB_VERDICTS[`${op.method} ${op.path}`] === "read" &&
+    op.path !== "/search/schedules_totals/results" &&
+    CCB_INDEX.contract(op).parameters.some((p) => p.in === "query" && p.name === "page"))
+    .map((op) => [`${op.method} ${op.path}`, pageAdapter]));
+export const CCB_NAMED = {
+    "GET /me": "get_me",
+    "GET /individuals": "list_individuals",
+    "GET /individuals/{id}": "get_individual",
+    "GET /families": "list_families",
+    "GET /families/{id}": "get_family",
+    "GET /groups": "list_groups",
+    "GET /groups/{id}": "get_group",
+    "GET /groups/{id}/members": "list_group_members",
+    "GET /individuals/{id}/groups": "list_individual_groups",
+    "GET /events": "list_events",
+    "GET /events/{id}": "get_event",
+    "GET /events/{id}/attendance/{occurrence}": "get_event_attendance",
+    "GET /events/{id}/attendance/{occurrence}/attendees": "list_event_attendees",
+    "GET /individuals/{id}/notes": "list_individual_notes",
+    "GET /individuals/{id}/metrics/giving": "get_giving_metrics",
+    "GET /families/{id}/metrics/giving": "get_giving_metrics",
+    ...Object.fromEntries(SEARCH_DOMAINS.map((domain) => [`POST /search/${domain}/results`, "search_records"])),
+};
+function pathProblem(path) {
+    return !path.startsWith("/") ||
+        path.startsWith("//") ||
+        /[%;\\?#]/.test(path) ||
+        path.split("/").some((p) => p === "." || p === "..") ||
+        /^\/oauth(?:\/|$)/i.test(path)
+        ? "CCB paths must be canonical indexed API paths; OAuth and encoded or traversal paths are refused."
+        : undefined;
+}
+function bodyRefusal(op) {
+    const content = CCB_INDEX.bodyType(op);
+    return content && !/^application\/(?:[^/]+\+)?json$/.test(content)
+        ? `CCB's JSON hatch cannot send ${content} request bodies; use the vendor application for this operation.`
+        : undefined;
+}
+export const ccbBinding = ({ connection, options, }) => ({
+    review: "CCB v2 uses JSON bodies, repeated form-array query parameters and deep-object bracket keys on its fixed environment origin. The index, safety and OAuth grant own admission and dispatch.",
+    refusal: (op) => safety.refusal(op.method, op.path) ?? bodyRefusal(op),
+    refuse: (call) => {
+        const denied = safety.refusal(call.method, call.op.path);
+        if (denied)
+            return denied;
+        const path = pathProblem(call.path);
+        if (path)
+            return path;
+        if (CCB_VERDICTS[`${call.method} ${call.op.path}`] !== "read" &&
+            !resolveScopes(options).some((scope) => !scope.startsWith("read:")))
+            return "This CCB connection has only read scopes; writes are refused.";
+        const size = call.query["per_page"];
+        if (size !== undefined && !/^(25|50|75|100)$/.test(String(size)))
+            return "CCB per_page must be one of 25, 50, 75, 100.";
+        const page = call.query["page"];
+        if (page !== undefined && (!/^[1-9]\d*$/.test(String(page)) || !Number.isSafeInteger(Number(page))))
+            return "CCB page must be a positive whole number.";
+        return bodyRefusal(call.op);
+    },
+    send: (call, settings) => connection.sendPath({
+        method: call.method,
+        path: call.path,
+        template: call.op.path,
+        query: queryPairs(call.query),
+        ...(call.body === undefined ? {} : { json: JSON.stringify(call.body) }),
+    }, settings),
+});
+function queryPairs(query) {
+    const out = [];
+    const add = (name, value) => {
+        if (Array.isArray(value))
+            for (const item of value)
+                add(name, item);
+        else if (value !== null && typeof value === "object")
+            for (const [key, item] of Object.entries(value))
+                add(`${name}[${key}]`, item);
+        else if (value !== undefined)
+            out.push([name, String(value ?? "")]);
+    };
+    for (const [name, value] of Object.entries(query))
+        add(name, value);
+    return out;
+}
+/** Uniform v2 privacy review, including the legacy hatches' unindexed paths. */
+export function ccbSafety(options) {
+    return {
+        reviewed: restSafety(safety, CCB_INDEX),
+        sensitiveFields: { names: CCB_SENSITIVE_FIELDS, choice: options.sensitiveFields ?? "drop" },
+    };
+}
+export function callCcb(connection, request) {
+    return Effect.gen(function* () {
+        const query = Object.fromEntries(Object.entries(request.query ?? {}).filter(([, value]) => value !== undefined));
+        const op = yield* checked(() => {
+            const problem = pathProblem(request.path);
+            if (problem)
+                throw new ConnectorCallError("invalid_args", problem);
+            const { op } = CCB_INDEX.resolve(request.method, request.path);
+            CCB_INDEX.check(op, query, request.body);
+            return op;
+        });
+        const answer = yield* connection.sendPath({
+            method: request.method,
+            path: request.path,
+            template: op.path,
+            query: queryPairs(query),
+            ...(request.body === undefined ? {} : { json: JSON.stringify(request.body) }),
+        }, { responseHeaders: CCB_PAGE_HEADERS });
+        return { body: answer.data, headers: new Headers(answer.headers) };
+    });
+}
+export function oauth(options) {
+    const endpoints = CCB_ENVIRONMENTS[options.environment];
+    return {
+        authorizationEndpoint: endpoints.authorizationEndpoint,
+        tokenEndpoint: `${endpoints.apiOrigin}/oauth/token`,
+        clientId: options.clientId,
+        clientSecret: options.clientSecret,
+        scope: resolveScopes(options).join(" "),
+        authorizationParams: {
+            ...(options.mode === "identity" ? { resource_owner_auth: "true" } : {}),
+            ...(options.subdomain?.trim() ? { subdomain: options.subdomain.trim() } : {}),
+        },
+        tokenRequestHeaders: { Accept: CCB_MEDIA_TYPE },
+        apiOrigins: [endpoints.apiOrigin],
+    };
+}
+function errorDetail(payload, status) {
+    const root = asRecord(payload);
+    const parts = [];
+    for (const key of ["message", "error_description", "error"]) {
+        const value = root[key];
+        if (typeof value === "string" && value.trim()) {
+            parts.push(value.trim());
+            break;
+        }
+    }
+    for (const item of asArray(root["errors"]).slice(0, 5)) {
+        if (typeof item === "string" && item.trim())
+            parts.push(item.trim());
+        else {
+            const message = asRecord(item)["message"];
+            if (typeof message === "string" && message.trim())
+                parts.push(message.trim());
+        }
+    }
+    const detail = parts.join("; ").slice(0, 500);
+    return detail ? `CCB HTTP ${status}: ${detail}${/[.!?]$/.test(detail) ? "" : "."}` : `CCB returned HTTP ${status}.`;
+}
+export const errors = {
+    meanings: { unknownId: "not_found", provesAbsence: true, conflicts: [] },
+    bodyFailures: {
+        statusOnly: [],
+        review: "An incomplete response body does not establish malformed JSON. Preserve CCB OAuth and write settlement semantics.",
+        readFailed: "CCB's response body could not be read completely.",
+    },
+    numericFacts: {
+        retryAfterMs: {
+            header: "retry-after",
+            format: "retry-after",
+            review: "HTTP Retry-After delay for failure recovery.",
+        },
+        resetAfterMs: {
+            header: "x-ratelimit-reset",
+            format: "epoch-seconds",
+            review: "CCB endpoint rate-limit reset time in epoch seconds.",
+        },
+        bodyRetryAfterMs: {
+            path: ["retry_after"],
+            format: "seconds",
+            review: "CCB rate-limit response body delay in seconds.",
+        },
+    },
+    provider: "CCB",
+    facts: () => ({}),
+    detail: ({ body, status }) => errorDetail(body, status),
+    unreadable: "CCB returned a successful response that is not JSON.",
+    statuses: {
+        401: () => ({
+            code: "auth_required",
+            words: (detail) => `${detail} CCB rejected the connection's access token. Call authorize_connector for this connector.`,
+            advice: ", then retry",
+        }),
+        403: () => ({
+            code: "provider_permission_denied",
+            retryable: false,
+            words: (detail) => `${detail} The grant lacks this endpoint's scope, or (Identity Auth) the signed-in person lacks the permission in CCB. Ask the CCB administrator to grant this endpoint's scope or the signed-in person's permission. Re-authorizing alone will not fix it.`,
+        }),
+        404: () => ({
+            code: "not_found",
+            words: (detail) => `${detail} Re-read the id from its list tool; CCB reports a permission gap as 403, so this record does not exist.`,
+        }),
+        412: () => ({ code: "invalid_args" }),
+        429: ({ retryAfterMs, numbers }) => {
+            const wait = retryAfterMs ?? numbers["resetAfterMs"] ?? numbers["bodyRetryAfterMs"];
+            return {
+                code: "rate_limited",
+                retryAfterMs: wait,
+                words: (detail) => `${detail} CCB limits each endpoint per API client.`,
+                advice: "; wait before calling this endpoint again",
+            };
+        },
+    },
+};

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

@@ -1,37 +1,6 @@
+import { CCB_ENVIRONMENTS } from "./lib/constants.js";
 import type { ConnectorCallAdmissionPolicy } from "../../types.js";
-/** CCB's v2 media type. The API and its token endpoint both require it. */
-export declare const CCB_MEDIA_TYPE = "application/vnd.ccbchurch.v2+json";
-/**
- * The two published environments. Credentials do not cross: sandbox clients
- * work only against the sandbox hosts and production clients only against
- * production, so the environment is part of the client, not a preference.
- */
-export declare const CCB_ENVIRONMENTS: {
-    readonly production: {
-        readonly apiOrigin: "https://api.ccbchurch.com";
-        readonly authorizationEndpoint: "https://oauth.ccbchurch.com/oauth/authorize";
-    };
-    readonly sandbox: {
-        readonly apiOrigin: "https://api-beta.ccbchurch.com";
-        readonly authorizationEndpoint: "https://beta-oauth.ccbchurch.com/oauth/authorize";
-    };
-};
-/**
- * The read scopes the named tools and the search hatch need, from the
- * `security` requirements of the operations they call (spec revision recorded
- * in the drift manifest). `read:campuses` and `read:church` are there so the
- * ids every projection carries — campus, membership type — can be resolved
- * through `ccb_api_get`. Request these on Pushpay's API access form.
- */
-export declare const CCB_READ_SCOPES: readonly string[];
-/**
- * What `access: "read-write"` adds: the writes of the everyday staff jobs —
- * profiles, groups, events and attendance, form responses, notes, process
- * queues, scheduling. No `delete:` scope, nothing financial, no background
- * checks, and no privacy settings: those are deliberate, so they are only
- * ever requested through an explicit `scopes` list.
- */
-export declare const CCB_WRITE_SCOPES: readonly string[];
+export { CCB_ENVIRONMENTS, CCB_MEDIA_TYPE, CCB_READ_SCOPES, CCB_WRITE_SCOPES, CCB_SENSITIVE_FIELDS, } from "./lib/constants.js";
 /** How the grant acts: for the whole church, or as one signed-in person. */
 export type CcbMode = "system" | "identity";
 /** Which Pushpay environment the client was issued for. */
@@ -73,15 +42,15 @@ export interface CcbOptions {
     clientSecret: string;
     /**
      * `"read"` (default) requests {@link CCB_READ_SCOPES} and ships no write
-     * tool; `"read-write"` adds {@link CCB_WRITE_SCOPES} and the approval-gated
-     * `ccb_api_mutate`. Exclusive with `scopes`.
+     * tool; `"read-write"` adds {@link CCB_WRITE_SCOPES} and `ccb_api_write`.
+     * The host may ask the user to confirm a write. Exclusive with `scopes`.
      */
     access?: "read" | "read-write";
     /**
      * The exact scope list to request, replacing `access`: narrower (drop
      * `read:individual_notes`) or wider (add `read:background_checks` for the
      * hatch). Must be a subset of what Pushpay granted the client. Any `write:`
-     * or `delete:` scope ships `ccb_api_mutate`.
+     * or `delete:` scope ships `ccb_api_write`.
      */
     scopes?: readonly string[];
     /**
@@ -100,6 +69,15 @@ export interface CcbOptions {
     maxResultBytes?: number;
     /** Serve only read-classified tools on every endpoint. Defaults to false. */
     readOnly?: boolean;
+    /**
+     * Whether results may carry {@link CCB_SENSITIVE_FIELDS}: allergies,
+     * giving numbers and dates, envelope ids, statement dates, attendance
+     * prayer requests and meeting notes, and form payment details. `"drop"`
+     * (default) removes them wherever they appear in every result: the named
+     * tools, the named reads, `search_records`, `ccb_api_read`, and `ccb_api_write`
+     * replies. `"return"` lets the hatches return those allowed fields; named projections stay narrow. Credentials and private file destinations are always withheld. Only deployment code decides; no tool argument can.
+     */
+    sensitiveFields?: "drop" | "return";
 }
-/** A maintained Church Community Builder (Pushpay ChMS) v2 connection. */
+/** A maintained Church Community Builder (Pushpay ChMS) v2 connection on the provider kit. */
 export declare const ccb: import("../../provider.js").ProviderFactory<CcbOptions>;