@zackbart/connecta 0.34.1 → 0.35.0

package/dist/providers/planning-center/lib/constants.d.ts

@@ -0,0 +1,58 @@
+import type { ConnectorCallAdmissionPolicy } from "../../../types.js";
+/** Planning Center's REST origin. Override only for a proxy or test double. */
+export declare const PLANNING_CENTER_API_BASE_URL = "https://api.planningcenteronline.com";
+/** The products behind `/<app>/v2`, in the order their guides list them. */
+export declare const PLANNING_CENTER_APPS: readonly ["people", "services", "groups", "check-ins", "calendar", "registrations", "giving", "publishing", "webhooks", "api"];
+export type PlanningCenterApp = (typeof PLANNING_CENTER_APPS)[number];
+/**
+ * A product a deployment may remove from this connection. People is the one
+ * it may not: every product joins through its person ids, and the credential
+ * test reads `/people/v2/me`.
+ */
+export type PlanningCenterExcludableApp = Exclude<PlanningCenterApp, "people">;
+/**
+ * One reviewed `X-PCO-API-Version` per product, sent on every request.
+ *
+ * The header is optional, and omitting it is the trap: Planning Center then
+ * applies a per-application default chosen in a web dashboard, so behavior
+ * would follow whoever last clicked there rather than this file. Each date is
+ * the newest non-beta version in the product's documentation graph on
+ * 2026-10-05, and every projection below is written against it. A breaking
+ * change arrives as a new dated version, never inside this one, so moving a
+ * pin is a reviewed change to this table, its drift manifest, and whatever
+ * projection the version's change list touches. Notes worth keeping:
+ *
+ * - groups `2023-07-10` removed every person attribute from `Membership`, so a
+ *   membership is nameless without `include=person`.
+ * - calendar `2026-06-22` may return `BookedEvent*` stubs in place of events on
+ *   booking and conflict traversals for users without access to the event.
+ * - webhooks `2022-10-20` renamed `Subscription` to `WebhookSubscription`.
+ * - services `2018-11-01` and giving `2019-10-18` are simply the newest there is.
+ *
+ * Every request uses the pin for its product; another version requires a
+ * reviewed pin and regenerated operation index.
+ */
+export declare const PLANNING_CENTER_API_VERSIONS: Readonly<Record<PlanningCenterApp, string>>;
+/** Planning Center's own cap on `per_page`; its default is 25. */
+export declare const MAX_PAGE_SIZE = 100;
+export declare const DEFAULT_PAGE_SIZE = 25;
+/**
+ * A ceiling on absurdity, not a budget. `per_page` tops out at 100, and the
+ * heaviest projection here — 100 people with emails and phone numbers
+ * included — is a few hundred kilobytes.
+ */
+export declare const PLANNING_CENTER_MAX_RESPONSE_BYTES: number;
+/**
+ * Planning Center documents 100 requests per 20 seconds per authenticated user
+ * (429 with `Retry-After` in seconds past it, and `X-PCO-API-Request-Rate-*`
+ * headers on every response). The rolling window transcribes that number, as
+ * Cloudflare's per-user limit is transcribed: a per-runtime approximation, not
+ * an enforcement, because N isolates each keep their own counter and every
+ * other integration the token's user runs draws on the same bucket.
+ * `maxConcurrency: 5` is connecta's choice, not Planning Center's — the bound
+ * that stops one `execute_code` fan-out from spending the window in a tick.
+ * Admission meters tool calls, not requests: `get_plan` spends three.
+ */
+export declare const PLANNING_CENTER_ADMISSION: ConnectorCallAdmissionPolicy;
+/** Planning Center refuses a request without a descriptive one (HTTP 403). */
+export declare const DEFAULT_USER_AGENT = "connecta/0.35.0 (+https://github.com/zackbart/connecta)";

package/dist/providers/planning-center/lib/constants.js

@@ -0,0 +1,83 @@
+import { CONNECTA_VERSION } from "../../../version.js";
+/** Planning Center's REST origin. Override only for a proxy or test double. */
+export const PLANNING_CENTER_API_BASE_URL = "https://api.planningcenteronline.com";
+/** The products behind `/<app>/v2`, in the order their guides list them. */
+export const PLANNING_CENTER_APPS = [
+    "people",
+    "services",
+    "groups",
+    "check-ins",
+    "calendar",
+    "registrations",
+    "giving",
+    "publishing",
+    "webhooks",
+    "api",
+];
+/**
+ * One reviewed `X-PCO-API-Version` per product, sent on every request.
+ *
+ * The header is optional, and omitting it is the trap: Planning Center then
+ * applies a per-application default chosen in a web dashboard, so behavior
+ * would follow whoever last clicked there rather than this file. Each date is
+ * the newest non-beta version in the product's documentation graph on
+ * 2026-10-05, and every projection below is written against it. A breaking
+ * change arrives as a new dated version, never inside this one, so moving a
+ * pin is a reviewed change to this table, its drift manifest, and whatever
+ * projection the version's change list touches. Notes worth keeping:
+ *
+ * - groups `2023-07-10` removed every person attribute from `Membership`, so a
+ *   membership is nameless without `include=person`.
+ * - calendar `2026-06-22` may return `BookedEvent*` stubs in place of events on
+ *   booking and conflict traversals for users without access to the event.
+ * - webhooks `2022-10-20` renamed `Subscription` to `WebhookSubscription`.
+ * - services `2018-11-01` and giving `2019-10-18` are simply the newest there is.
+ *
+ * Every request uses the pin for its product; another version requires a
+ * reviewed pin and regenerated operation index.
+ */
+export const PLANNING_CENTER_API_VERSIONS = {
+    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",
+};
+/** Planning Center's own cap on `per_page`; its default is 25. */
+export const MAX_PAGE_SIZE = 100;
+export const DEFAULT_PAGE_SIZE = 25;
+/**
+ * A ceiling on absurdity, not a budget. `per_page` tops out at 100, and the
+ * heaviest projection here — 100 people with emails and phone numbers
+ * included — is a few hundred kilobytes.
+ */
+export const PLANNING_CENTER_MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
+/**
+ * Planning Center documents 100 requests per 20 seconds per authenticated user
+ * (429 with `Retry-After` in seconds past it, and `X-PCO-API-Request-Rate-*`
+ * headers on every response). The rolling window transcribes that number, as
+ * Cloudflare's per-user limit is transcribed: a per-runtime approximation, not
+ * an enforcement, because N isolates each keep their own counter and every
+ * other integration the token's user runs draws on the same bucket.
+ * `maxConcurrency: 5` is connecta's choice, not Planning Center's — the bound
+ * that stops one `execute_code` fan-out from spending the window in a tick.
+ * Admission meters tool calls, not requests: `get_plan` spends three.
+ */
+export const PLANNING_CENTER_ADMISSION = {
+    rules: [
+        {
+            maxConcurrency: 5,
+            budget: { kind: "rolling-window", maxCalls: 100, windowMs: 20_000 },
+            maxQueueSize: 32,
+            queueTimeoutMs: 5_000,
+            retryAfterMs: 1_000,
+        },
+    ],
+};
+/** Planning Center refuses a request without a descriptive one (HTTP 403). */
+export const DEFAULT_USER_AGENT = `connecta/${CONNECTA_VERSION} (+https://github.com/zackbart/connecta)`;

package/dist/providers/planning-center/lib/discovery.js

@@ -0,0 +1,40 @@
+import { OperationIndex } from "../../_shared/rest/operation-index.js";
+/** Reviewed workflow vocabulary over the unchanged vendor paths and contracts. */
+const summaries = {
+    "GET /people/v2/people": "Find and search People profiles: a person, contact details, active or inactive members, name, email or phone.",
+    "GET /people/v2/people/{person_id}": "Get one person's People profile and contact details; include emails, phone numbers, addresses and household.",
+    "PATCH /people/v2/people/{person_id}": "Update or archive a person: inactive archives the People profile; active restores it without deleting history.",
+    "GET /people/v2/person_mergers": "Find merged person history and the surviving People id for a removed duplicate profile.",
+    "POST /people/v2/people/{person_id}/emails": "Add an email address to a person as a separate People Email record.",
+    "POST /people/v2/people/{person_id}/phone_numbers": "Add a phone number to a person as a separate People PhoneNumber record.",
+    "GET /people/v2/field_definitions": "List custom field definitions, names and data types for People profiles.",
+    "GET /people/v2/people/{person_id}/field_data": "List a person's custom field values; join field definitions for their names and data types.",
+    "GET /people/v2/people/{person_id}/notes": "List a person's profile note records and their categories.",
+    "GET /services/v2/people": "List Services volunteers and person identities for a volunteer roster; use plans for who is serving on a date.",
+    "GET /services/v2/teams": "List volunteer teams and roster roles across Services service types.",
+    "GET /services/v2/service_types": "List service types to resolve the worship service before finding its dated plan and order of service.",
+    "GET /services/v2/service_types/{service_type_id}/plans": "List dated Services plans for an order of service; choose the plan before reading items or the volunteer roster.",
+    "GET /services/v2/service_types/{service_type_id}/plans/{plan_id}/items": "Read the order of service: ordered plan items, songs, durations and worship-service positions.",
+    "GET /services/v2/service_types/{service_type_id}/plans/{plan_id}/team_members": "List a plan's volunteer roster and serving team members, with person, team and position identities.",
+    "POST /services/v2/service_types/{service_type_id}/plans/{plan_id}/team_members": "Schedule a volunteer into one plan's serving roster with the person's team and position.",
+    "GET /groups/v2/groups": "Find church groups, then resolve group leaders and members through their memberships.",
+    "GET /groups/v2/groups/{group_id}/memberships": "List church group leaders and members; each group membership joins a person and their leader role.",
+    "GET /giving/v2/donations": "List donations by person, date or fund; include designations for fund identities.",
+};
+/** Reviewed vocabulary; shared hatch ranking keeps the full index reachable. */
+export class PlanningCenterIndex extends OperationIndex {
+    constructor(data) {
+        super({
+            ...data,
+            ops: data.ops.map(([method, path, id, summary, tag, server]) => {
+                const reviewed = summaries[`${method} ${path}`];
+                // PCO omits operation ids: preserve the generated CRUD/resource words
+                // alongside workflow synonyms so verb-led queries remain discoverable.
+                const combined = reviewed ? `${reviewed} (${summary.replace(/ — Planning Center \w[\w-]*$/, "")})` : summary;
+                return server === undefined
+                    ? [method, path, id, combined, tag]
+                    : [method, path, id, combined, tag, server];
+            }),
+        }, { vendor: "pco", title: "Planning Center" });
+    }
+}

package/dist/providers/planning-center/lib/guide.js

@@ -0,0 +1,39 @@
+import { PLANNING_CENTER_APPS, isApp } from "../api.js";
+/** `a, b, and c`, the way the guide and description list products. */
+export 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. */
+export const DESCRIBED_APPS = [
+    "people",
+    "services",
+    "groups",
+    "check-ins",
+    "calendar",
+    "registrations",
+    "giving",
+];
+/**
+ * `excludeApps` as a set, refusing at construction what cannot be meant
+ * (INV-11): a product Planning Center does not have, a misspelling, or People.
+ */
+export 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;
+}

package/dist/providers/planning-center/lib/json-api.js

@@ -0,0 +1,83 @@
+import { ConnectorCallError } from "../../../errors.js";
+export function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+export function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+export function compact(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+export function isResource(value) {
+    const record = asRecord(value);
+    return typeof record["id"] === "string" && typeof record["type"] === "string";
+}
+export function resources(value) {
+    return (Array.isArray(value) ? value : value ? [value] : []).filter(isResource);
+}
+export function indexIncluded(document) {
+    const index = new Map();
+    for (const resource of resources(document["included"])) {
+        index.set(`${resource.type}:${resource.id}`, resource);
+    }
+    return index;
+}
+export function relationshipData(resource, name) {
+    return resource.relationships?.[name]?.data;
+}
+/** The related id, `null` when Planning Center says there is none. */
+export function relId(resource, name) {
+    const data = relationshipData(resource, name);
+    if (data === null)
+        return null;
+    const id = asRecord(data)["id"];
+    return typeof id === "string" ? id : undefined;
+}
+export function related(resource, name, index) {
+    const data = asRecord(relationshipData(resource, name));
+    return typeof data["type"] === "string" && typeof data["id"] === "string"
+        ? index.get(`${data["type"]}:${data["id"]}`)
+        : undefined;
+}
+export function relatedMany(resource, name, index) {
+    return asArray(relationshipData(resource, name))
+        .map((entry) => {
+        const ref = asRecord(entry);
+        return index.get(`${String(ref["type"])}:${String(ref["id"])}`);
+    })
+        .filter((item) => item !== undefined);
+}
+/** `{ id, ...the named attributes }`, keeping Planning Center's own names. */
+export function pick(resource, names) {
+    const attributes = resource.attributes ?? {};
+    const out = { id: resource.id };
+    for (const name of names) {
+        if (attributes[name] !== undefined)
+            out[name] = attributes[name];
+    }
+    return out;
+}
+export function attribute(resource, name) {
+    return resource?.attributes?.[name];
+}
+/** A JSON:API write document. `undefined` drops a key; `null` clears a field. */
+export function writeDocument(type, attributes) {
+    return { data: { type, attributes: compact(attributes) } };
+}
+/** One branchable signal: `meta.next.offset`, Planning Center's own cursor. */
+export function pageOf(document, offset = 0) {
+    const meta = asRecord(document["meta"]);
+    const next = asRecord(meta["next"])["offset"];
+    const total = meta["total_count"];
+    if (meta["next"] != null && (next === undefined || !Number.isSafeInteger(next) || next <= offset)) {
+        throw new ConnectorCallError("connector_call_failed", "Planning Center returned invalid paging metadata.", {
+            retryable: false,
+        });
+    }
+    const nextOffset = next === undefined ? null : next;
+    return {
+        hasMore: nextOffset !== null,
+        nextOffset,
+        totalCount: typeof total === "number" && Number.isSafeInteger(total) && total >= 0 ? total : null,
+    };
+}