@zackbart/connecta 0.28.0 → 0.29.0

package/dist/providers/breeze/skill.generated.js

@@ -0,0 +1,9 @@
+// Generated by scripts/generate-providers.mjs; do not edit.
+export const skill = {
+    "content": ".breezechms.com (Breeze ChMS, now Tithely Church Management): people, tags, events, attendance, forms, volunteers, and giving.\n\nChurch purpose: \n\n## Sensitive data: reduce in code\n\nPeople records carry home addresses, phones, birthdates, and family ties, and\ngiving records reveal who gives and how much — religious affiliation by proxy.\nRead them inside `execute_code` and return only the counts, totals, or the\nfew fields the task needs. Never echo whole profiles or donor lists.\n\n## Ids and profile fields\n\n- Ids are numeric strings. Read them from a list tool; never guess one.\n- Events have two ids: an instance id (`list_events` `id`) for one\n  occurrence, and a series `eventId`. Attendance, volunteers, and\n  check-in take the instance id.\n- Person `details` are keyed by profile `fieldId`, not by name. Call\n  `list_profile_fields` once and map ids to names in code. Multiple-choice\n  values and `list_people` filters use option ids from the same call;\n  join several with `-`.\n- `list_people` has no name search. List without details and match names\n  in code, then `get_person` the hits.\n- Projections rename Breeze's snake_case fields to camelCase and drop photo\n  paths and internal columns; `raw: true` returns Breeze's rows.\n\n## Pagination\n\n`list_people` pages by `cursor`: continue while `page.hasMore`. Breeze\nreports no total, so a full page sets `hasMore` and the next may be empty.\n`list_events` and `list_account_log` do not page: `truncated: true`\nmeans narrow the date range. Other lists return everything.\n\n## Giving\n\n`list_contributions` and `list_funds` call endpoints Breeze removed from\nits public reference in 2023 but still serves. They may change or vanish\nwithout notice; a failure there is not your argument's fault. Amounts are\ndecimal strings; `totalAmount` is an exact sum. Online gifts processed by\nTithe.ly arrive through its sync, batched per deposit, so the latest days\nmay be missing. Read the currency from `get_account_summary`.\n\n## Writes and the hatches\n\n- Every write, `add_person`, `assign_tag`, and `record_check_in`\n  included, follows the routing in the `usage` skill. Fetch it with\n  `skills({ name: \"usage\" })` for guest API and trust rules.\n  Those three only add, and `add_person` never deduplicates.\n- `update_person` field values: text, date (M/D/YYYY), or option id in\n  `response`; email, phone, address, and family_role values in `details`.\n- Every Breeze call is a GET, writes included, so the hatches split by\n  endpoint. `breeze_api_get` admits only reviewed read endpoints and their\n  documented parameters, such as `/tags/list_folders`,\n  `/events/list_event`, `/events/attendance/eligible`, `/giving/view`,\n  and `/pledges/list_campaigns`; it refuses anything else. Everything else\n  — event, family, volunteer, and form writes, giving writes, check-out,\n  undocumented parameters — is `breeze_api_mutate`. Paths are below\n  `/api`; `*_json` values may be passed as objects.\n- `list_account_log` actions include person_created, person_updated,\n  person_deleted, tag_assign, tag_unassign, event_created,\n  attendance_deleted, form_entry_updated, contribution_added,\n  contribution_updated, contribution_deleted, and batch_updated.\n\n## Rate limits\n\nBreeze publishes no limit and sends no rate headers; a third party reports\nabout 20 requests per minute. Keep loops sequential and prefer one list call\nover many single reads.\n",
+    "instructionsHeading": "Church instructions",
+    "fragments": {
+        "guide_0": ".breezechms.com (Breeze ChMS, now Tithely Church Management): people, tags, events, attendance, forms, volunteers, and giving.\n\nChurch purpose: ",
+        "guide_1": "\n\n## Sensitive data: reduce in code\n\nPeople records carry home addresses, phones, birthdates, and family ties, and\ngiving records reveal who gives and how much — religious affiliation by proxy.\nRead them inside `execute_code` and return only the counts, totals, or the\nfew fields the task needs. Never echo whole profiles or donor lists.\n\n## Ids and profile fields\n\n- Ids are numeric strings. Read them from a list tool; never guess one.\n- Events have two ids: an instance id (`list_events` `id`) for one\n  occurrence, and a series `eventId`. Attendance, volunteers, and\n  check-in take the instance id.\n- Person `details` are keyed by profile `fieldId`, not by name. Call\n  `list_profile_fields` once and map ids to names in code. Multiple-choice\n  values and `list_people` filters use option ids from the same call;\n  join several with `-`.\n- `list_people` has no name search. List without details and match names\n  in code, then `get_person` the hits.\n- Projections rename Breeze's snake_case fields to camelCase and drop photo\n  paths and internal columns; `raw: true` returns Breeze's rows.\n\n## Pagination\n\n`list_people` pages by `cursor`: continue while `page.hasMore`. Breeze\nreports no total, so a full page sets `hasMore` and the next may be empty.\n`list_events` and `list_account_log` do not page: `truncated: true`\nmeans narrow the date range. Other lists return everything.\n\n## Giving\n\n`list_contributions` and `list_funds` call endpoints Breeze removed from\nits public reference in 2023 but still serves. They may change or vanish\nwithout notice; a failure there is not your argument's fault. Amounts are\ndecimal strings; `totalAmount` is an exact sum. Online gifts processed by\nTithe.ly arrive through its sync, batched per deposit, so the latest days\nmay be missing. Read the currency from `get_account_summary`.\n\n## Writes and the hatches\n\n- Every write, `add_person`, `assign_tag`, and `record_check_in`\n  included, follows the routing in the `usage` skill. Fetch it with\n  `skills({ name: \"usage\" })` for guest API and trust rules.\n  Those three only add, and `add_person` never deduplicates.\n- `update_person` field values: text, date (M/D/YYYY), or option id in\n  `response`; email, phone, address, and family_role values in `details`.\n- Every Breeze call is a GET, writes included, so the hatches split by\n  endpoint. `breeze_api_get` admits only reviewed read endpoints and their\n  documented parameters, such as `/tags/list_folders`,\n  `/events/list_event`, `/events/attendance/eligible`, `/giving/view`,\n  and `/pledges/list_campaigns`; it refuses anything else. Everything else\n  — event, family, volunteer, and form writes, giving writes, check-out,\n  undocumented parameters — is `breeze_api_mutate`. Paths are below\n  `/api`; `*_json` values may be passed as objects.\n- `list_account_log` actions include person_created, person_updated,\n  person_deleted, tag_assign, tag_unassign, event_created,\n  attendance_deleted, form_entry_updated, contribution_added,\n  contribution_updated, contribution_deleted, and batch_updated.\n\n## Rate limits\n\nBreeze publishes no limit and sends no rate headers; a third party reports\nabout 20 requests per minute. Keep loops sequential and prefer one list call\nover many single reads.\n"
+    }
+};

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

@@ -0,0 +1,103 @@
+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[];
+/** 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. */
+export type CcbEnvironment = keyof typeof CCB_ENVIRONMENTS;
+export interface CcbOptions {
+    /** Which church this connection reaches and what it is for. Required. */
+    purpose: string;
+    /** Human-readable display name; the default names environment, mode, and access. */
+    title?: string;
+    /** Church-specific conventions appended to the maintained guide. */
+    instructions?: string;
+    /**
+     * The environment the OAuth client was issued for. Required, with no
+     * default: sandbox credentials work only against the sandbox hosts and
+     * production credentials only against production, and nothing in a client
+     * id says which it is. A wrong guess fails at consent with CCB's opaque
+     * "Error accessing page".
+     */
+    environment: CcbEnvironment;
+    /**
+     * `"system"` (System Auth): a Master Administrator, or someone who can edit
+     * system-wide settings, approves the connection once for the whole church,
+     * and every caller shares that one grant. `"identity"` (Identity Auth,
+     * `resource_owner_auth=true`): each person signs in as themselves, CCB
+     * applies that person's own permissions, and every grant is personal. Identity
+     * Auth works only after the church has completed System Auth for the same
+     * client. Required: the two modes reach different data for different people.
+     */
+    mode: CcbMode;
+    /**
+     * The OAuth client id Pushpay issued. Clients are issued by hand through
+     * Pushpay's API access request form
+     * (https://vendor.ccbchurch.com/goto/forms/15/responses/new), which also
+     * fixes the scopes and the redirect URI — register
+     * `<publicUrl>/oauth/callback/<id>` there, character for character.
+     */
+    clientId: string;
+    /** The client secret, from deployment configuration. Never stored. */
+    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`.
+     */
+    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`.
+     */
+    scopes?: readonly string[];
+    /**
+     * The church's CCB subdomain (`mychurch` for mychurch.ccbchurch.com). Sent
+     * at consent so the approver skips typing it. Optional.
+     */
+    subdomain?: string;
+    /** Default rows per page for list tools: 25 (default), 50, 75, or 100. */
+    defaultPerPage?: 25 | 50 | 75 | 100;
+    /**
+     * Replaces the per-endpoint default admission policy. Pass your own to
+     * account for other integrations spending from the same API client.
+     */
+    callAdmission?: ConnectorCallAdmissionPolicy;
+    /** Connector-specific inline result limit; omit to inherit the deployment. */
+    maxResultBytes?: number;
+}
+/** A maintained Church Community Builder (Pushpay ChMS) v2 connection. */
+export declare const ccb: import("../../provider.js").ProviderFactory<CcbOptions>;