@zackbart/connecta 0.31.0 → 0.32.0

package/dist/providers/planning-center/index.js

@@ -237,7 +237,7 @@ function isApp(value) {
  * normalization the guarded transport applies — so `..` cannot carry a request
  * from `/people/v2` to `/oauth` or anywhere else outside a product.
  */
-function appForPath(path) {
+function appForPath(path, apps) {
     let normalized;
     if (path.startsWith("/") && !path.startsWith("//")) {
         try {
@@ -249,10 +249,145 @@ function appForPath(path) {
     }
     const app = normalized === undefined ? undefined : APP_PATH.exec(normalized)?.[1];
     if (!app || !isApp(app)) {
-        throw new ConnectorCallError("invalid_args", `A Planning Center path begins with /<app>/v2, where app is one of ${PLANNING_CENTER_APPS.join(", ")} — for example /people/v2/people. No host, query string, or traversal.`);
+        throw new ConnectorCallError("invalid_args", `A Planning Center path begins with /<app>/v2, where app is one of ${apps.join(", ")} — for example /people/v2/people. No host, query string, or traversal.`);
     }
     return app;
 }
+/** Display names, in guide order. The guide never lists `api` as a product. */
+const APP_TITLES = {
+    people: "People",
+    services: "Services",
+    groups: "Groups",
+    "check-ins": "Check-Ins",
+    calendar: "Calendar",
+    registrations: "Registrations",
+    giving: "Giving",
+    publishing: "Publishing",
+    webhooks: "Webhooks",
+    api: "API",
+};
+/**
+ * A path's segments, each percent-decoded once, or a refusal when the path is
+ * not literal. While a product is excluded no path may lean on normalization:
+ * a dot segment, an empty segment, a backslash, whitespace, or an encoded
+ * `/`, `\`, `?`, `#`, or `%` could each mean one thing here and another to a
+ * server that decodes or resolves it, so none is admitted at all rather than
+ * reasoned about.
+ */
+function literalSegments(path) {
+    const ambiguous = () => new ConnectorCallError("invalid_args", "While this deployment excludes a Planning Center product, a path must be literal: no . or .. segments, empty segments, backslashes, whitespace, or percent-encoded /, \\, ?, #, or %.");
+    if (!path.startsWith("/"))
+        throw ambiguous();
+    const raw = path.slice(1).split("/");
+    return raw.map((segment, index) => {
+        if (segment === "" && index !== raw.length - 1)
+            throw ambiguous();
+        let decoded;
+        try {
+            decoded = decodeURIComponent(segment);
+        }
+        catch {
+            throw ambiguous();
+        }
+        const control = [...decoded].some((char) => char <= " " || char === "\x7f");
+        if (decoded === "." || decoded === ".." || control || /[/\\?#%]/.test(decoded))
+            throw ambiguous();
+        return decoded;
+    });
+}
+/**
+ * People resources a list is built from or answers with. A list's conditions
+ * can draw on any product — a Giving condition makes a donor list — and one
+ * list can be a condition of another, so while any product is excluded none
+ * of them is read, by path or by `include`.
+ */
+const LIST_RESOURCES = new Set(["lists", "list_results", "rules", "conditions"]);
+/** The People tools that read or refresh a list, removed with any exclusion. */
+const LIST_TOOLS = new Set(["list_lists", "list_list_people", "run_list"]);
+/** The webhook subscription collections, current and 2018-08-01. */
+const SUBSCRIPTION_COLLECTIONS = new Set(["webhook_subscriptions", "subscriptions"]);
+/**
+ * Refuse, before anything is sent, a request that would reach an excluded
+ * product. It reads literal segments, so it runs twice: on the path as given,
+ * and on the exact URL the transport is about to fetch (`admit`), which is the
+ * one that counts. Five doors lead to an excluded product:
+ *
+ * - its own paths, in any case or percent-encoding of a literal segment;
+ * - People lists, rules, conditions, and results, whose criteria can come from
+ *   the excluded product, by path or by `include`;
+ * - a new webhook subscription to its events, which delivers its records to
+ *   any URL — so a new subscription must name a reachable product's event;
+ * - an existing subscription, changed by id: a path names a subscription by
+ *   id, not by product, so no subscription is enabled, disabled, deleted, or
+ *   re-keyed while any product is excluded; and
+ * - webhook event and delivery payloads, which carry the record that fired
+ *   them, refused for every subscription for the same reason.
+ *
+ * People documents no other `include` or attribute that reaches another
+ * product's records.
+ */
+function refuseExcluded(segments, query, request, excluded) {
+    const disabled = (app, detail) => new ConnectorCallError("provider_permission_denied", `Planning Center ${APP_TITLES[app]} (/${app}/v2) is disabled in this deployment, so this connection ${detail}. Retrying will not help; only an operator can remove "${app}" from excludeApps.`, { retryable: false });
+    const because = (detail) => new ConnectorCallError("provider_permission_denied", `This deployment disables Planning Center ${series([...excluded].map((name) => APP_TITLES[name]))}, and ${detail} Retrying will not help.`, { retryable: false });
+    const lower = segments.map((segment) => segment.toLowerCase());
+    const app = lower[0] ?? "";
+    if (isApp(app) && excluded.has(app))
+        throw disabled(app, "does not reach its endpoints");
+    // Lists are refused and workflows are not. A list is a live query: reading
+    // it evaluates its conditions, Giving ones included, at read time, so it
+    // is the excluded product's API by another path. A workflow card is a
+    // stored People record. A Giving automation can create one, but so can
+    // staff, and once created it is People data, like a note or custom field
+    // value typed from a donor's details. Exclusion guards products' APIs,
+    // not provenance; refusing workflows would cost every exclusion a core
+    // People feature and argue equally for notes, fields, forms, and groups.
+    // The hard boundary is the token user's own per-product permissions.
+    const lists = "a People list's conditions can draw on a disabled product, so this connection reads no list, list result, rule, or condition.";
+    if (app === "people" && lower.some((segment) => LIST_RESOURCES.has(segment)))
+        throw because(lists);
+    for (const [key, value] of query) {
+        if (/include/i.test(key) &&
+            value
+                .toLowerCase()
+                .split(/[\s,.]+/)
+                .some((part) => LIST_RESOURCES.has(part))) {
+            throw because(lists);
+        }
+    }
+    if (app !== "webhooks")
+        return;
+    if (lower.some((segment) => /^(?:events|deliveries)\b/.test(segment))) {
+        throw because("a webhook event or delivery payload may carry any product's records, so this connection does not read them. Subscriptions themselves stay readable.");
+    }
+    if (request.method === "GET" || request.method === "HEAD")
+        return;
+    const resource = lower.slice(2).filter((segment) => segment !== "");
+    if (request.method !== "POST" || resource.length !== 1 || !SUBSCRIPTION_COLLECTIONS.has(resource[0])) {
+        throw because("a webhook subscription's id does not name its product, so this connection does not enable, disable, delete, or re-key an existing subscription.");
+    }
+    const data = asRecord(request.body)["data"];
+    const name = Array.isArray(data) ? undefined : asRecord(asRecord(data)["attributes"])["name"];
+    const event = typeof name === "string" ? /^([a-z-]+)\.v2\.events\./.exec(name.trim().toLowerCase())?.[1] : undefined;
+    if (event === undefined || !isApp(event)) {
+        throw because("a new webhook subscription must name one product's event, such as people.v2.events.person.created, in data.attributes.name.");
+    }
+    if (excluded.has(event))
+        throw disabled(event, "cannot subscribe to its webhook events");
+}
+/**
+ * The exclusion, enforced on the exact URL about to be fetched: after the
+ * transport has resolved and encoded it, so what is checked is what Planning
+ * Center routes. The origin and base path are asserted again here, not taken
+ * on trust from the confinement before it.
+ */
+function admit(baseUrl, url, request, excluded) {
+    const base = new URL(baseUrl);
+    const basePath = base.pathname.replace(/\/+$/, "");
+    if (url.origin !== base.origin || !url.pathname.startsWith(`${basePath}/`) || url.hash) {
+        throw new ConnectorCallError("invalid_args", "A Planning Center request left the Planning Center API origin.");
+    }
+    refuseExcluded(literalSegments(url.pathname.slice(basePath.length)), url.searchParams, request, excluded);
+}
 function errorDetail(payload, status) {
     const parts = [];
     for (const entry of asArray(asRecord(payload)["errors"])) {
@@ -309,9 +444,12 @@ function planningCenterFailure(status, headers, payload) {
         retryable: false,
     });
 }
-function planningCenterCall(send, versions) {
+function planningCenterCall(send, versions, excluded) {
+    const apps = PLANNING_CENTER_APPS.filter((app) => !excluded.has(app));
     return async (request, ctx) => {
-        const app = appForPath(request.path);
+        if (excluded.size > 0)
+            refuseExcluded(literalSegments(request.path), [], request, excluded);
+        const app = appForPath(request.path, apps);
         return await send(compact({
             method: request.method,
             path: request.path,
@@ -787,11 +925,11 @@ function personAttributes(args) {
     };
 }
 const WORKFLOW_CARD_ACTIONS = ["promote", "go_back", "skip_step", "snooze", "unsnooze", "remove", "restore"];
-function tools(call, defaultPageSize) {
+function tools(call, defaultPageSize, excluded) {
     const perPage = (args) => args["perPage"] ?? defaultPageSize;
     const list = (spec) => listTool(call, defaultPageSize, spec);
-    return [
-        // --- Hatches ------------------------------------------------------------
+    // --- Hatches --------------------------------------------------------------
+    const hatches = [
         {
             name: "pco_api_get",
             description: "Call any Planning Center GET endpoint in any product and return its untouched JSON:API body. Prefer a named read; this one does not flatten or resolve includes.",
@@ -813,7 +951,7 @@ function tools(call, defaultPageSize) {
         },
         {
             name: "pco_api_mutate",
-            description: "Call any Planning Center POST, PATCH, or DELETE endpoint with a JSON:API body. The approval-gated hatch for writes, actions, and money movement no named tool covers.",
+            description: `Call any Planning Center POST, PATCH, or DELETE endpoint with a JSON:API body. The approval-gated hatch for ${excluded.has("giving") ? "writes and actions" : "writes, actions, and money movement"} no named tool covers.`,
             annotations: DESTRUCTIVE,
             inputSchema: input({
                 method: {
@@ -844,7 +982,9 @@ function tools(call, defaultPageSize) {
                 }), ctx)) ?? null,
             }),
         },
-        // --- People -------------------------------------------------------------
+    ];
+    // --- People ---------------------------------------------------------------
+    const people = [
         {
             name: "get_me",
             description: "Get the Planning Center person this token acts as, with the organization's name and time zone. Supplies personId for my-schedule and assignee questions.",
@@ -1292,7 +1432,9 @@ function tools(call, defaultPageSize) {
                 };
             },
         }),
-        // --- Services -----------------------------------------------------------
+    ];
+    // --- Services -------------------------------------------------------------
+    const services = [
         list({
             name: "list_service_types",
             description: "List Services service types — the recurring services such as Sunday Morning. Supplies serviceTypeId for plans and teams.",
@@ -1596,7 +1738,9 @@ function tools(call, defaultPageSize) {
                 keys: relatedMany(row, "keys", index).map((key) => pick(key, ["name", "starting_key", "ending_key"])),
             }),
         }),
-        // --- Groups -------------------------------------------------------------
+    ];
+    // --- Groups ---------------------------------------------------------------
+    const groups = [
         list({
             name: "list_groups",
             description: "List Groups groups with type, schedule, and member count. Archived groups are excluded unless asked for; the API cannot create a group.",
@@ -1712,7 +1856,9 @@ function tools(call, defaultPageSize) {
                 group_id: relId(row, "group") ?? null,
             }),
         }),
-        // --- Check-Ins (read-only product) ---------------------------------------
+    ];
+    // --- Check-Ins (read-only product) -----------------------------------------
+    const checkIns = [
         list({
             name: "list_check_in_events",
             description: "List Check-Ins events, the recurring things people check in to. Supplies eventId for event periods and check-ins.",
@@ -1806,7 +1952,9 @@ function tools(call, defaultPageSize) {
                 event_period_id: relId(row, "event_period") ?? null,
             }),
         }),
-        // --- Calendar (events read-only) ----------------------------------------
+    ];
+    // --- Calendar (events read-only) ------------------------------------------
+    const calendar = [
         list({
             name: "list_calendar_event_instances",
             description: "List what is on the Calendar in a date range: each occurrence with times and location, recurrence expanded. Events cannot be written through the API.",
@@ -1848,7 +1996,9 @@ function tools(call, defaultPageSize) {
                 event_id: relId(row, "event") ?? null,
             }),
         }),
-        // --- Registrations (read-only product) ----------------------------------
+    ];
+    // --- Registrations (read-only product) ------------------------------------
+    const registrations = [
         list({
             name: "list_signups",
             description: "List Registrations signups (registration events) with open, close, and capacity state. Read-only: the API cannot register anyone.",
@@ -1917,7 +2067,9 @@ function tools(call, defaultPageSize) {
                 person_id: relId(row, "person") ?? null,
             }),
         }),
-        // --- Giving (reads; money moves only through pco_api_mutate) -------------
+    ];
+    // --- Giving (reads; money moves only through pco_api_mutate) ---------------
+    const giving = [
         list({
             name: "list_donations",
             description: "List Giving donations with their fund designations, newest first, by date, fund, or donor. Amounts are integer cents. Read-only.",
@@ -2075,7 +2227,9 @@ function tools(call, defaultPageSize) {
                 designations: designations(row, index),
             }),
         }),
-        // --- Webhooks -----------------------------------------------------------
+    ];
+    // --- Webhooks -------------------------------------------------------------
+    const webhooks = [
         {
             name: "list_webhook_subscriptions",
             description: "List the organization's webhook subscriptions: event name, URL, and active state. Never returns the signing secret; that needs pco_api_get.",
@@ -2104,18 +2258,117 @@ function tools(call, defaultPageSize) {
             },
         },
     ];
+    return {
+        hatches,
+        apps: {
+            people,
+            services,
+            groups,
+            "check-ins": checkIns,
+            calendar,
+            registrations,
+            giving,
+            publishing: [],
+            webhooks,
+            api: [],
+        },
+    };
 }
 // ---------------------------------------------------------------------------
 // Guide and construction
 // ---------------------------------------------------------------------------
-function usageGuide(purpose, instructions) {
+/** `a, b, and c`, the way the guide and description list products. */
+function series(items) {
+    return items.length < 3 ? items.join(" and ") : `${items.slice(0, -1).join(", ")}, and ${items.at(-1)}`;
+}
+/** The products the description names: those with named tools for staff work. */
+const DESCRIBED_APPS = [
+    "people",
+    "services",
+    "groups",
+    "check-ins",
+    "calendar",
+    "registrations",
+    "giving",
+];
+/** What a person id joins in each other product, for the guide's identity rule. */
+const PERSON_JOINS = [
+    ["services", "Services schedules"],
+    ["groups", "Groups memberships"],
+    ["giving", "Giving donations"],
+    ["check-ins", "Check-Ins"],
+];
+/**
+ * The maintained guide for the products this connection reaches. Every
+ * product-specific line is its own fragment, so an excluded product is
+ * neither described, pinned, nor named by a tool the guide points to, and an
+ * exclusion adds the line stating what the hatches refuse. With nothing
+ * excluded, the text is the whole guide as before; the `published` fragment
+ * is that same text without a purpose.
+ */
+function usageGuide(purpose, instructions, excluded) {
+    const fragments = skill.fragments;
+    const has = (app) => !excluded.has(app);
+    const pair = (a, b, both, onlyA, onlyB) => has(a) && has(b) ? both : has(a) ? onlyA : has(b) ? onlyB : "";
+    const apps = PLANNING_CENTER_APPS.filter(has);
+    const joins = PERSON_JOINS.filter(([app]) => has(app)).map(([, label]) => label);
     const organizationInstructions = instructions?.trim();
-    return `${skill.fragments.guide_0}${purpose}${skill.fragments.guide_1}${PLANNING_CENTER_APPS.map((app) => `${app} ${PLANNING_CENTER_API_VERSIONS[app]}`).join(", ")}${skill.fragments.guide_2}${organizationInstructions ? `\n## ${skill.instructionsHeading}\n\n${organizationInstructions}\n` : ""}`;
+    return [
+        fragments.heading,
+        apps
+            .filter((app) => app !== "api")
+            .map((app) => APP_TITLES[app])
+            .join(", "),
+        fragments.purpose,
+        purpose,
+        fragments.identity,
+        joins.length > 0 ? series(joins) : "every People record",
+        fragments.conventions,
+        has("services") ? fragments.plans : "",
+        fragments.writes,
+        excluded.size === 0 ? fragments.people : fragments.people_without_lists,
+        has("services") ? fragments.services : "",
+        has("groups") ? fragments.groups : "",
+        pair("check-ins", "registrations", fragments.check_ins_registrations, fragments.check_ins, fragments.registrations),
+        has("calendar") ? fragments.calendar : "",
+        has("giving") ? fragments.giving : "",
+        pair("publishing", "api", fragments.publishing_api, fragments.publishing, fragments.api),
+        fragments.hatches,
+        apps.map((app) => `${app} ${PLANNING_CENTER_API_VERSIONS[app]}`).join(", "),
+        fragments.pins,
+        excluded.size === 0 ? "" : fragments.disabled,
+        fragments.limits,
+        organizationInstructions ? `\n## ${skill.instructionsHeading}\n\n${organizationInstructions}\n` : "",
+    ].join("");
+}
+/**
+ * `excludeApps` as a set, refusing at construction what cannot be meant
+ * (INV-11): a product Planning Center does not have, a misspelling, or People.
+ */
+function excludedApps(value) {
+    const excluded = new Set();
+    if (value === undefined)
+        return excluded;
+    const excludable = PLANNING_CENTER_APPS.filter((app) => app !== "people").join(", ");
+    if (!Array.isArray(value)) {
+        throw new Error(`planningCenter() excludeApps must be an array of app names from: ${excludable}.`);
+    }
+    for (const entry of value) {
+        if (entry === "people") {
+            throw new Error('planningCenter() excludeApps cannot exclude "people": every product joins through People person ids, and the credential test reads /people/v2/me.');
+        }
+        if (typeof entry !== "string" || !isApp(entry)) {
+            const lower = typeof entry === "string" ? entry.trim().toLowerCase() : "";
+            throw new Error(`planningCenter() excludeApps has unknown app ${JSON.stringify(entry)}; expected any of ${excludable}.${isApp(lower) && lower !== "people" ? ` App names are lowercase path segments: "${lower}".` : ""}`);
+        }
+        excluded.add(entry);
+    }
+    return excluded;
 }
 /** The closed options planningCenter() accepts; see `assertKnownOptions`. */
 const PLANNING_CENTER_OPTIONS = optionsOf()({
     ...PROVIDER_COMMON,
-    ...keys("userAgent", "defaultPageSize", "baseUrl"),
+    ...keys("userAgent", "defaultPageSize", "excludeApps", "baseUrl"),
 });
 /** A maintained Planning Center Online connection over the REST API. */
 export const planningCenter = asProviderFactory({
@@ -2145,19 +2398,25 @@ function planningCenterConnector(id, options) {
     if (!userAgent || /[\r\n]/.test(userAgent)) {
         throw new Error("planningCenter() userAgent must be a non-empty single line.");
     }
+    const excluded = excludedApps(options.excludeApps);
     const auth = PERSONAL_ACCESS_TOKEN;
+    const baseUrl = options.baseUrl?.trim() || PLANNING_CENTER_API_BASE_URL;
     const send = guardedFetch({
         provider: "Planning Center",
-        baseUrl: options.baseUrl?.trim() || PLANNING_CENTER_API_BASE_URL,
+        baseUrl,
         headers: { Accept: "application/json", "User-Agent": userAgent },
         maxResponseBytes: PLANNING_CENTER_MAX_RESPONSE_BYTES,
         authenticate: (ctx) => auth.headers(ctx),
+        ...(excluded.size > 0
+            ? { admit: (url, request) => admit(baseUrl, url, request, excluded) }
+            : {}),
     });
-    const call = planningCenterCall(send, PLANNING_CENTER_API_VERSIONS);
+    const call = planningCenterCall(send, PLANNING_CENTER_API_VERSIONS, excluded);
+    const surface = tools(call, defaultPageSize, excluded);
     return api(id, {
         ...(options.authScope ? { authScope: options.authScope } : {}),
         title: options.title ?? "Planning Center",
-        description: `Planning Center church management — People, Services, Groups, Check-Ins, Calendar, Registrations, and Giving: ${purpose}`,
+        description: `Planning Center church management — ${series(DESCRIBED_APPS.filter((app) => !excluded.has(app)).map((app) => APP_TITLES[app]))}: ${purpose}`,
         credential: auth.credential,
         async testCredentials(values, ctx) {
             try {
@@ -2186,7 +2445,7 @@ function planningCenterConnector(id, options) {
         },
         callAdmission: options.callAdmission ?? PLANNING_CENTER_ADMISSION,
         usageGuide: {
-            content: usageGuide(purpose, options.instructions),
+            content: usageGuide(purpose, options.instructions, excluded),
             summary: "Person ids join every product, offset paging, per-product write limits, JSON:API hatches, pinned versions.",
             // Deliberately not `required`. Every named tool's schema is complete
             // enough to call it on its own; the guide carries the cross-product
@@ -2194,6 +2453,9 @@ function planningCenterConnector(id, options) {
             // it leaves the named surface or hits one of them.
         },
         ...(options.maxResultBytes !== undefined ? { maxResultBytes: options.maxResultBytes } : {}),
-        tools: tools(call, defaultPageSize),
+        tools: [
+            ...surface.hatches,
+            ...PLANNING_CENTER_APPS.flatMap((app) => (excluded.has(app) ? [] : surface.apps[app])).filter((tool) => excluded.size === 0 || !LIST_TOOLS.has(tool.name)),
+        ],
     });
 }

package/dist/providers/planning-center/skill.generated.js

@@ -1,10 +1,30 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "# Planning Center usage\n\nPlanning Center Online church management — People, Services, Groups, Check-Ins, Calendar, Registrations, Giving, Publishing, Webhooks — for: \n\n## Identity first\n\n- A person id is the join key across every product: the id `search_people` returns is the `personId` for Services schedules, Groups memberships, Giving donations, and Check-Ins. Resolve ids with list tools; never guess one.\n- A person id that used to resolve and now answers `not_found` was most likely merged. Read `/people/v2/person_mergers` with `where[person_to_remove_id]` and follow `person_to_keep_id`.\n- `get_me` names the user this token acts as. Every read and write runs with that user's permissions, product by product; a `provider_permission_denied` means an administrator must grant that user access to the product or record.\n\n## Results and paging\n\n- Records keep Planning Center's own snake_case attribute names; a relationship appears as `<relationship>_id`. Pass `raw: true` for the untouched JSON:API resources and `included`.\n- Lists page by offset: `perPage` up to 100, then pass `page.nextOffset` back as `offset` while `page.hasMore` is true. `page.totalCount` answers \"how many\" without paging — request `perPage: 1`.\n- A bare date in a date filter is the organization's local day; pass a full timestamp for exact bounds. Name filters are exact; end one with `%` for a prefix match.\n- `get_plan` fetches the plan, its items, and its team in one call and sets `itemsTruncated`/`teamMembersTruncated` past 100 rows; page the rest with `pco_api_get`.\n\n## What each product lets the API write\n\n- People: full read/write. `update_person` with `status: inactive` archives reversibly; a DELETE is permanent and only reachable through `pco_api_mutate`. `run_list` can fire list automations.\n- Services: full read/write. A plan's dates come from its plan times. Scheduling needs a team.\n- Groups: memberships and group settings are writable; groups cannot be created, and events and attendance are read-only.\n- Check-Ins and Registrations: read-only. Nobody can be checked in or registered through the API.\n- Calendar: events, instances, and times are read-only; tags, resources, rooms, and folders are writable through `pco_api_mutate`.\n- Giving: the named tools only read, amounts in integer cents. Creating or editing donations, refunds, and committing a batch move money and go through `pco_api_mutate`.\n- Publishing and the `api` product (organization, OAuth applications, personal access tokens) have no named tools; use the hatches.\n\n## The hatches\n\n- `pco_api_get` reaches any GET; `pco_api_mutate` any POST, PATCH, or DELETE, always approval-gated. Paths start `/<app>/v2`, exactly as Planning Center documents them; the connector owns host, auth, content type, and the `X-PCO-API-Version` header.\n- Bodies are JSON:API documents: `{\"data\":{\"type\":\"Email\",\"attributes\":{...}}}`. `null` clears an attribute; an omitted key is left alone.\n- Each product is pinned to a reviewed API version: . Pass `version` only for an endpoint those versions lack.\n- Query parameters are name/value pairs with literal brackets: `where[status]`, `include`, `order`, `filter`, `fields[Person]`. Every list response's `meta` names the `can_query_by`, `can_order_by`, and `can_include` values for that endpoint; an unknown `where` key is ignored rather than refused.\n- File uploads go to a separate host (upload.planningcenteronline.com), which this connection does not reach.\n\n## Rate limits\n\nPlanning Center allows 100 requests per 20 seconds per user, shared by every integration running as that user. This connection admits 100 calls per 20 seconds, five at a time, per runtime — an approximation, not a guarantee. A `rate_limited` failure carries Planning Center's wait. Filter server-side and use `totalCount` rather than paging to count.\n",
+    "content": "# Planning Center usage\n\nPlanning Center Online church management — People, Services, Groups, Check-Ins, Calendar, Registrations, Giving, Publishing, Webhooks.\n\n## Identity first\n\n- A person id is the join key across every product: the id `search_people` returns is the `personId` for Services schedules, Groups memberships, Giving donations, and Check-Ins. Resolve ids with list tools; never guess one.\n- A person id that used to resolve and now answers `not_found` was most likely merged. Read `/people/v2/person_mergers` with `where[person_to_remove_id]` and follow `person_to_keep_id`.\n- `get_me` names the user this token acts as. Every read and write runs with that user's permissions, product by product; a `provider_permission_denied` means an administrator must grant that user access to the product or record.\n\n## Results and paging\n\n- Records keep Planning Center's own snake_case attribute names; a relationship appears as `<relationship>_id`. Pass `raw: true` for the untouched JSON:API resources and `included`.\n- Lists page by offset: `perPage` up to 100, then pass `page.nextOffset` back as `offset` while `page.hasMore` is true. `page.totalCount` answers \"how many\" without paging — request `perPage: 1`.\n- A bare date in a date filter is the organization's local day; pass a full timestamp for exact bounds. Name filters are exact; end one with `%` for a prefix match.\n- `get_plan` fetches the plan, its items, and its team in one call and sets `itemsTruncated`/`teamMembersTruncated` past 100 rows; page the rest with `pco_api_get`.\n\n## What each product lets the API write\n\n- People: full read/write. `update_person` with `status: inactive` archives reversibly; a DELETE is permanent and only reachable through `pco_api_mutate`. `run_list` can fire list automations.\n- Services: full read/write. A plan's dates come from its plan times. Scheduling needs a team.\n- Groups: memberships and group settings are writable; groups cannot be created, and events and attendance are read-only.\n- Check-Ins and Registrations: read-only. Nobody can be checked in or registered through the API.\n- Calendar: events, instances, and times are read-only; tags, resources, rooms, and folders are writable through `pco_api_mutate`.\n- Giving: the named tools only read, amounts in integer cents. Creating or editing donations, refunds, and committing a batch move money and go through `pco_api_mutate`.\n- Publishing and the `api` product (organization, OAuth applications, personal access tokens) have no named tools; use the hatches.\n\n## The hatches\n\n- `pco_api_get` reaches any GET; `pco_api_mutate` any POST, PATCH, or DELETE, always approval-gated. Paths start `/<app>/v2`, exactly as Planning Center documents them; the connector owns host, auth, content type, and the `X-PCO-API-Version` header.\n- Bodies are JSON:API documents: `{\"data\":{\"type\":\"Email\",\"attributes\":{...}}}`. `null` clears an attribute; an omitted key is left alone.\n- Each product is pinned to a reviewed API version: people 2026-06-04, services 2018-11-01, groups 2023-07-10, check-ins 2025-05-28, calendar 2026-06-22, registrations 2025-05-01, giving 2019-10-18, publishing 2024-03-25, webhooks 2022-10-20, api 2026-09-24. Pass `version` only for an endpoint those versions lack.\n- Query parameters are name/value pairs with literal brackets: `where[status]`, `include`, `order`, `filter`, `fields[Person]`. Every list response's `meta` names the `can_query_by`, `can_order_by`, and `can_include` values for that endpoint; an unknown `where` key is ignored rather than refused.\n- File uploads go to a separate host (upload.planningcenteronline.com), which this connection does not reach.\n\n## Rate limits\n\nPlanning Center allows 100 requests per 20 seconds per user, shared by every integration running as that user. This connection admits 100 calls per 20 seconds, five at a time, per runtime — an approximation, not a guarantee. A `rate_limited` failure carries Planning Center's wait. Filter server-side and use `totalCount` rather than paging to count.\n",
     "instructionsHeading": "Organization instructions",
     "fragments": {
-        "guide_0": "# Planning Center usage\n\nPlanning Center Online church management — People, Services, Groups, Check-Ins, Calendar, Registrations, Giving, Publishing, Webhooks — for: ",
-        "guide_1": "\n\n## Identity first\n\n- A person id is the join key across every product: the id `search_people` returns is the `personId` for Services schedules, Groups memberships, Giving donations, and Check-Ins. Resolve ids with list tools; never guess one.\n- A person id that used to resolve and now answers `not_found` was most likely merged. Read `/people/v2/person_mergers` with `where[person_to_remove_id]` and follow `person_to_keep_id`.\n- `get_me` names the user this token acts as. Every read and write runs with that user's permissions, product by product; a `provider_permission_denied` means an administrator must grant that user access to the product or record.\n\n## Results and paging\n\n- Records keep Planning Center's own snake_case attribute names; a relationship appears as `<relationship>_id`. Pass `raw: true` for the untouched JSON:API resources and `included`.\n- Lists page by offset: `perPage` up to 100, then pass `page.nextOffset` back as `offset` while `page.hasMore` is true. `page.totalCount` answers \"how many\" without paging — request `perPage: 1`.\n- A bare date in a date filter is the organization's local day; pass a full timestamp for exact bounds. Name filters are exact; end one with `%` for a prefix match.\n- `get_plan` fetches the plan, its items, and its team in one call and sets `itemsTruncated`/`teamMembersTruncated` past 100 rows; page the rest with `pco_api_get`.\n\n## What each product lets the API write\n\n- People: full read/write. `update_person` with `status: inactive` archives reversibly; a DELETE is permanent and only reachable through `pco_api_mutate`. `run_list` can fire list automations.\n- Services: full read/write. A plan's dates come from its plan times. Scheduling needs a team.\n- Groups: memberships and group settings are writable; groups cannot be created, and events and attendance are read-only.\n- Check-Ins and Registrations: read-only. Nobody can be checked in or registered through the API.\n- Calendar: events, instances, and times are read-only; tags, resources, rooms, and folders are writable through `pco_api_mutate`.\n- Giving: the named tools only read, amounts in integer cents. Creating or editing donations, refunds, and committing a batch move money and go through `pco_api_mutate`.\n- Publishing and the `api` product (organization, OAuth applications, personal access tokens) have no named tools; use the hatches.\n\n## The hatches\n\n- `pco_api_get` reaches any GET; `pco_api_mutate` any POST, PATCH, or DELETE, always approval-gated. Paths start `/<app>/v2`, exactly as Planning Center documents them; the connector owns host, auth, content type, and the `X-PCO-API-Version` header.\n- Bodies are JSON:API documents: `{\"data\":{\"type\":\"Email\",\"attributes\":{...}}}`. `null` clears an attribute; an omitted key is left alone.\n- Each product is pinned to a reviewed API version: ",
-        "guide_2": ". Pass `version` only for an endpoint those versions lack.\n- Query parameters are name/value pairs with literal brackets: `where[status]`, `include`, `order`, `filter`, `fields[Person]`. Every list response's `meta` names the `can_query_by`, `can_order_by`, and `can_include` values for that endpoint; an unknown `where` key is ignored rather than refused.\n- File uploads go to a separate host (upload.planningcenteronline.com), which this connection does not reach.\n\n## Rate limits\n\nPlanning Center allows 100 requests per 20 seconds per user, shared by every integration running as that user. This connection admits 100 calls per 20 seconds, five at a time, per runtime — an approximation, not a guarantee. A `rate_limited` failure carries Planning Center's wait. Filter server-side and use `totalCount` rather than paging to count.\n"
+        "heading": "# Planning Center usage\n\nPlanning Center Online church management — ",
+        "purpose": " — for: ",
+        "identity": "\n\n## Identity first\n\n- A person id is the join key across every product: the id `search_people` returns is the `personId` for ",
+        "conventions": ". Resolve ids with list tools; never guess one.\n- A person id that used to resolve and now answers `not_found` was most likely merged. Read `/people/v2/person_mergers` with `where[person_to_remove_id]` and follow `person_to_keep_id`.\n- `get_me` names the user this token acts as. Every read and write runs with that user's permissions, product by product; a `provider_permission_denied` means an administrator must grant that user access to the product or record.\n\n## Results and paging\n\n- Records keep Planning Center's own snake_case attribute names; a relationship appears as `<relationship>_id`. Pass `raw: true` for the untouched JSON:API resources and `included`.\n- Lists page by offset: `perPage` up to 100, then pass `page.nextOffset` back as `offset` while `page.hasMore` is true. `page.totalCount` answers \"how many\" without paging — request `perPage: 1`.\n- A bare date in a date filter is the organization's local day; pass a full timestamp for exact bounds. Name filters are exact; end one with `%` for a prefix match.\n",
+        "plans": "- `get_plan` fetches the plan, its items, and its team in one call and sets `itemsTruncated`/`teamMembersTruncated` past 100 rows; page the rest with `pco_api_get`.\n",
+        "writes": "\n## What each product lets the API write\n\n",
+        "people": "- People: full read/write. `update_person` with `status: inactive` archives reversibly; a DELETE is permanent and only reachable through `pco_api_mutate`. `run_list` can fire list automations.\n",
+        "people_without_lists": "- People: full read/write, except lists. `update_person` with `status: inactive` archives reversibly; a DELETE is permanent and only reachable through `pco_api_mutate`.\n",
+        "services": "- Services: full read/write. A plan's dates come from its plan times. Scheduling needs a team.\n",
+        "groups": "- Groups: memberships and group settings are writable; groups cannot be created, and events and attendance are read-only.\n",
+        "check_ins_registrations": "- Check-Ins and Registrations: read-only. Nobody can be checked in or registered through the API.\n",
+        "check_ins": "- Check-Ins: read-only. Nobody can be checked in through the API.\n",
+        "registrations": "- Registrations: read-only. Nobody can be registered through the API.\n",
+        "calendar": "- Calendar: events, instances, and times are read-only; tags, resources, rooms, and folders are writable through `pco_api_mutate`.\n",
+        "giving": "- Giving: the named tools only read, amounts in integer cents. Creating or editing donations, refunds, and committing a batch move money and go through `pco_api_mutate`.\n",
+        "publishing_api": "- Publishing and the `api` product (organization, OAuth applications, personal access tokens) have no named tools; use the hatches.\n",
+        "publishing": "- Publishing has no named tools; use the hatches.\n",
+        "api": "- The `api` product (organization, OAuth applications, personal access tokens) has no named tools; use the hatches.\n",
+        "hatches": "\n## The hatches\n\n- `pco_api_get` reaches any GET; `pco_api_mutate` any POST, PATCH, or DELETE, always approval-gated. Paths start `/<app>/v2`, exactly as Planning Center documents them; the connector owns host, auth, content type, and the `X-PCO-API-Version` header.\n- Bodies are JSON:API documents: `{\"data\":{\"type\":\"Email\",\"attributes\":{...}}}`. `null` clears an attribute; an omitted key is left alone.\n- Each product is pinned to a reviewed API version: ",
+        "pins": ". Pass `version` only for an endpoint those versions lack.\n- Query parameters are name/value pairs with literal brackets: `where[status]`, `include`, `order`, `filter`, `fields[Person]`. Every list response's `meta` names the `can_query_by`, `can_order_by`, and `can_include` values for that endpoint; an unknown `where` key is ignored rather than refused.\n- File uploads go to a separate host (upload.planningcenteronline.com), which this connection does not reach.\n",
+        "disabled": "- This deployment disables some products, and the hatches refuse their paths before sending. While any product is disabled they also refuse People lists, list results, rules, and conditions, by path or `include`, because a list's conditions can draw on any product; webhook event and delivery payloads; and any change to an existing webhook subscription, whose id does not name its product. A new subscription must name a reachable product's event.\n",
+        "limits": "\n## Rate limits\n\nPlanning Center allows 100 requests per 20 seconds per user, shared by every integration running as that user. This connection admits 100 calls per 20 seconds, five at a time, per runtime — an approximation, not a guarantee. A `rate_limited` failure carries Planning Center's wait. Filter server-side and use `totalCount` rather than paging to count.\n",
+        "published": "# Planning Center usage\n\nPlanning Center Online church management — People, Services, Groups, Check-Ins, Calendar, Registrations, Giving, Publishing, Webhooks.\n\n## Identity first\n\n- A person id is the join key across every product: the id `search_people` returns is the `personId` for Services schedules, Groups memberships, Giving donations, and Check-Ins. Resolve ids with list tools; never guess one.\n- A person id that used to resolve and now answers `not_found` was most likely merged. Read `/people/v2/person_mergers` with `where[person_to_remove_id]` and follow `person_to_keep_id`.\n- `get_me` names the user this token acts as. Every read and write runs with that user's permissions, product by product; a `provider_permission_denied` means an administrator must grant that user access to the product or record.\n\n## Results and paging\n\n- Records keep Planning Center's own snake_case attribute names; a relationship appears as `<relationship>_id`. Pass `raw: true` for the untouched JSON:API resources and `included`.\n- Lists page by offset: `perPage` up to 100, then pass `page.nextOffset` back as `offset` while `page.hasMore` is true. `page.totalCount` answers \"how many\" without paging — request `perPage: 1`.\n- A bare date in a date filter is the organization's local day; pass a full timestamp for exact bounds. Name filters are exact; end one with `%` for a prefix match.\n- `get_plan` fetches the plan, its items, and its team in one call and sets `itemsTruncated`/`teamMembersTruncated` past 100 rows; page the rest with `pco_api_get`.\n\n## What each product lets the API write\n\n- People: full read/write. `update_person` with `status: inactive` archives reversibly; a DELETE is permanent and only reachable through `pco_api_mutate`. `run_list` can fire list automations.\n- Services: full read/write. A plan's dates come from its plan times. Scheduling needs a team.\n- Groups: memberships and group settings are writable; groups cannot be created, and events and attendance are read-only.\n- Check-Ins and Registrations: read-only. Nobody can be checked in or registered through the API.\n- Calendar: events, instances, and times are read-only; tags, resources, rooms, and folders are writable through `pco_api_mutate`.\n- Giving: the named tools only read, amounts in integer cents. Creating or editing donations, refunds, and committing a batch move money and go through `pco_api_mutate`.\n- Publishing and the `api` product (organization, OAuth applications, personal access tokens) have no named tools; use the hatches.\n\n## The hatches\n\n- `pco_api_get` reaches any GET; `pco_api_mutate` any POST, PATCH, or DELETE, always approval-gated. Paths start `/<app>/v2`, exactly as Planning Center documents them; the connector owns host, auth, content type, and the `X-PCO-API-Version` header.\n- Bodies are JSON:API documents: `{\"data\":{\"type\":\"Email\",\"attributes\":{...}}}`. `null` clears an attribute; an omitted key is left alone.\n- Each product is pinned to a reviewed API version: people 2026-06-04, services 2018-11-01, groups 2023-07-10, check-ins 2025-05-28, calendar 2026-06-22, registrations 2025-05-01, giving 2019-10-18, publishing 2024-03-25, webhooks 2022-10-20, api 2026-09-24. Pass `version` only for an endpoint those versions lack.\n- Query parameters are name/value pairs with literal brackets: `where[status]`, `include`, `order`, `filter`, `fields[Person]`. Every list response's `meta` names the `can_query_by`, `can_order_by`, and `can_include` values for that endpoint; an unknown `where` key is ignored rather than refused.\n- File uploads go to a separate host (upload.planningcenteronline.com), which this connection does not reach.\n\n## Rate limits\n\nPlanning Center allows 100 requests per 20 seconds per user, shared by every integration running as that user. This connection admits 100 calls per 20 seconds, five at a time, per runtime — an approximation, not a guarantee. A `rate_limited` failure carries Planning Center's wait. Filter server-side and use `totalCount` rather than paging to count.\n"
     }
 };

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

@@ -48,7 +48,7 @@ export type SheetsOptions = GoogleWorkspaceOptions;
  *
  * Reads are read-only. `create_spreadsheet`, `add_sheet`, and `append_values`
  * are additive writes the host approves through call_destructive_tool or a
- * trusted program; the value writes, `clear_values`, and the raw
+ * program on a writable endpoint; the value writes, `clear_values`, and the raw
  * `batch_update_spreadsheet` are destructive.
  */
 export declare const sheets: import("../../provider.js").ProviderFactory<GoogleWorkspaceOptions>;

package/dist/providers/sheets/index.js

@@ -550,8 +550,8 @@ const SPREADSHEET_FIELDS = [
 // --- Tools ------------------------------------------------------------------------
 function tools(client) {
     const readOnly = { readOnlyHint: true };
-    // Additive: nothing that existed is lost. Program writes require a trusted
-    // pool; other writes use call_destructive_tool. The host controls approval.
+    // Additive: nothing that existed is lost. Writes require a writable
+    // endpoint: call_destructive_tool or a program. The host controls approval.
     const additive = { readOnlyHint: false, destructiveHint: false };
     const destructive = { readOnlyHint: false, destructiveHint: true };
     const spreadsheetPath = (args) => `/spreadsheets/${encodeURIComponent(String(args["spreadsheetId"]))}`;
@@ -1188,7 +1188,7 @@ function usageGuide(purpose, instructions) {
  *
  * Reads are read-only. `create_spreadsheet`, `add_sheet`, and `append_values`
  * are additive writes the host approves through call_destructive_tool or a
- * trusted program; the value writes, `clear_values`, and the raw
+ * program on a writable endpoint; the value writes, `clear_values`, and the raw
  * `batch_update_spreadsheet` are destructive.
  */
 export const sheets = asProviderFactory({

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

@@ -45,7 +45,7 @@ export type SlidesOptions = GoogleWorkspaceOptions;
  *
  * Reads run in programs. `create_presentation`, `create_slide`,
  * `create_comment`, and `create_comment_reply` are additive writes the host
- * approves through call_destructive_tool or a trusted program;
+ * approves through call_destructive_tool or a program on a writable endpoint;
  * `replace_all_text`, `update_comment_thread`, `update_comment_post`,
  * `delete_comment`, `delete_comment_reply`, and `batch_update_presentation`
  * are destructive.

package/dist/providers/slides/index.js

@@ -2051,7 +2051,7 @@ function tools(client) {
             name: "create_presentation",
             description: "Create an empty Google Slides deck with one title slide in the user's My Drive root. It cannot place the deck in a folder or copy a template.",
             // Additive: a new file changes nothing that existed. Not read-only, so
-            // program calls require a trusted pool; other writes use
+            // program calls require a writable endpoint; other writes use
             // call_destructive_tool. The host controls approval.
             annotations: { readOnlyHint: false, destructiveHint: false },
             inputSchema: input({
@@ -2239,7 +2239,7 @@ function tools(client) {
             name: "create_comment",
             description: "Comment on a slide, a notes page, an element, a range of its text, or a table cell, optionally assigning it. Adds a thread; Slides notifies as in the editor.",
             // Additive: a new thread changes nothing that existed. Not read-only,
-            // so program calls require a trusted pool; other writes use
+            // so program calls require a writable endpoint; other writes use
             // call_destructive_tool. The host controls approval.
             annotations: { readOnlyHint: false, destructiveHint: false },
             inputSchema: input({
@@ -2594,7 +2594,7 @@ function usageGuide(purpose, instructions) {
  *
  * Reads run in programs. `create_presentation`, `create_slide`,
  * `create_comment`, and `create_comment_reply` are additive writes the host
- * approves through call_destructive_tool or a trusted program;
+ * approves through call_destructive_tool or a program on a writable endpoint;
  * `replace_all_text`, `update_comment_thread`, `update_comment_post`,
  * `delete_comment`, `delete_comment_reply`, and `batch_update_presentation`
  * are destructive.