@zackbart/connecta 0.28.0 → 0.28.1

package/dist/providers/ccb.d.ts

@@ -0,0 +1,103 @@
+import type { Connector, 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 function ccb(id: string, options: CcbOptions): Connector;