@churchapps/integration-sdk 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,366 @@
+import { Request, Response, RequestHandler } from 'express';
+
+/** Every webhook event B1 can emit. */
+type B1WebhookEventName = "person.created" | "person.updated" | "person.destroyed" | "group.created" | "group.updated" | "group.destroyed" | "group.member.added" | "group.member.removed" | "household.created" | "household.updated" | "household.destroyed" | "donation.created" | "donation.updated" | "attendance.recorded" | "session.created" | "form.submission.created" | "event.created" | "event.updated" | "event.destroyed";
+/** The HTTP headers B1 sends with every webhook delivery. */
+declare const WEBHOOK_HEADERS: {
+    readonly signature: "X-B1-Signature";
+    readonly event: "X-B1-Event";
+    readonly deliveryId: "X-B1-Delivery-Id";
+    readonly timestamp: "X-B1-Timestamp";
+};
+/** The JSON body B1 POSTs to a subscriber URL. */
+interface B1WebhookEnvelope<T = unknown> {
+    event: B1WebhookEventName;
+    churchId: string;
+    /** ISO 8601 timestamp. */
+    occurredAt: string;
+    data: T;
+}
+interface PersonWebhookData {
+    id: string;
+    churchId: string;
+    name?: {
+        display?: string;
+        first?: string;
+        last?: string;
+    };
+    contactInfo?: {
+        email?: string;
+    };
+}
+interface GroupWebhookData {
+    id: string;
+    churchId: string;
+    name?: string;
+    categoryName?: string;
+}
+interface GroupMemberWebhookData {
+    id: string;
+    churchId: string;
+    groupId: string;
+    personId: string;
+}
+interface HouseholdWebhookData {
+    id: string;
+    churchId: string;
+    name?: string;
+}
+interface DonationWebhookData {
+    id: string;
+    churchId: string;
+    personId?: string;
+    batchId?: string;
+    donationDate?: string;
+    amount?: number;
+    currency?: string;
+    method?: string;
+    status?: string;
+}
+interface AttendanceWebhookData {
+    id: string;
+    churchId: string;
+    personId?: string;
+    visitDate?: string;
+    checkinTime?: string;
+}
+interface SessionWebhookData {
+    id: string;
+    churchId: string;
+    groupId?: string;
+    serviceTimeId?: string;
+    sessionDate?: string;
+}
+interface FormSubmissionWebhookData {
+    id: string;
+    churchId: string;
+    formId?: string;
+    contentType?: string;
+    contentId?: string;
+}
+interface EventWebhookData {
+    id: string;
+    churchId: string;
+    groupId?: string;
+    title?: string;
+    start?: string;
+    end?: string;
+}
+/**
+ * Discriminated union of every webhook envelope — `switch (env.event)` narrows
+ * `data` to the matching shape.
+ */
+type B1Webhook = B1WebhookEnvelope<PersonWebhookData> & {
+    event: "person.created" | "person.updated" | "person.destroyed";
+} | B1WebhookEnvelope<GroupWebhookData> & {
+    event: "group.created" | "group.updated" | "group.destroyed";
+} | B1WebhookEnvelope<GroupMemberWebhookData> & {
+    event: "group.member.added" | "group.member.removed";
+} | B1WebhookEnvelope<HouseholdWebhookData> & {
+    event: "household.created" | "household.updated" | "household.destroyed";
+} | B1WebhookEnvelope<DonationWebhookData> & {
+    event: "donation.created" | "donation.updated";
+} | B1WebhookEnvelope<AttendanceWebhookData> & {
+    event: "attendance.recorded";
+} | B1WebhookEnvelope<SessionWebhookData> & {
+    event: "session.created";
+} | B1WebhookEnvelope<FormSubmissionWebhookData> & {
+    event: "form.submission.created";
+} | B1WebhookEnvelope<EventWebhookData> & {
+    event: "event.created" | "event.updated" | "event.destroyed";
+};
+
+/** A recognised OAuth / API-key scope. */
+type B1KnownScope = "people:read" | "people:write" | "groups:read" | "groups:write" | "donations:read" | "donations:write" | "attendance:read" | "attendance:write" | "forms:write" | "content:read" | "content:write" | "messaging:read" | "messaging:write" | "roles:read" | "roles:write" | "settings:read" | "settings:write" | "offline_access";
+/** Scope strings — known scopes get autocomplete, custom strings still allowed. */
+type B1Scope = B1KnownScope | (string & {});
+/** All scopes B1 recognises in its catalog (plus `offline_access`). */
+declare const B1_SCOPES: B1KnownScope[];
+type B1GrantType = "authorization_code" | "refresh_token" | "urn:ietf:params:oauth:grant-type:device_code";
+/** The token response from `POST /membership/oauth/token`. */
+interface B1TokenResponse {
+    access_token: string;
+    token_type: "Bearer";
+    /** Lifetime in seconds. */
+    expires_in: number;
+    /** Unix timestamp (seconds) the token was created. Absent on the device grant. */
+    created_at?: number;
+    refresh_token: string;
+    scope: string;
+}
+/** The response from `POST /membership/oauth/device/authorize` (RFC 8628). */
+interface B1DeviceAuthResponse {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete?: string;
+    /** Lifetime in seconds. */
+    expires_in: number;
+    /** Recommended poll interval in seconds. */
+    interval: number;
+}
+/** Outcome of a single device-token poll. */
+type B1DevicePollResult = {
+    status: "approved";
+    token: B1TokenResponse;
+} | {
+    status: "pending";
+} | {
+    status: "expired";
+} | {
+    status: "denied";
+};
+
+/** The B1 Api modules, each addressed by a `/<module>` path prefix. */
+type B1Module = "membership" | "giving" | "attendance" | "content" | "messaging" | "doing" | "reporting";
+/** Known B1 Api base URLs. */
+declare const B1_BASE_URLS: {
+    readonly prod: "https://api.b1.church";
+    readonly staging: "https://api.staging.b1.church";
+};
+interface B1RestClientOptions {
+    /** A raw `cak_<prefix>.<secret>` API key, sent verbatim as a bearer token. */
+    apiKey: string;
+    /** Base URL — defaults to production. */
+    baseUrl?: string;
+    /** Override `fetch` (for tests or non-global-fetch runtimes). */
+    fetch?: typeof fetch;
+}
+type B1QueryValue = string | number | boolean | undefined | null;
+interface B1RequestOptions {
+    method?: "GET" | "POST" | "PUT" | "DELETE";
+    body?: unknown;
+    query?: Record<string, B1QueryValue>;
+    headers?: Record<string, string>;
+}
+
+/** Thrown by `verifyAndParse` when a signature does not match. */
+declare class WebhookVerificationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Verifies and parses inbound B1 webhook deliveries.
+ *
+ * The signature is an HMAC-SHA256 over the **raw request body** — verify
+ * before any JSON parse/re-stringify, which would change byte order/whitespace.
+ * Byte-compatible with the B1 Api `shared/webhooks/WebhookSigner.ts`.
+ */
+declare class WebhookVerifier {
+    /** Computes the `X-B1-Signature` value for a raw body. */
+    static sign(secret: string, rawBody: string | Buffer): string;
+    /**
+     * Returns `true` when `signatureHeader` matches the body. Never throws —
+     * a missing, empty, or malformed header simply returns `false`.
+     */
+    static verify(secret: string, rawBody: string | Buffer, signatureHeader: string | null | undefined): boolean;
+    /** Parses a raw body into a typed envelope (no verification). */
+    static parseEnvelope<T = unknown>(rawBody: string | Buffer): B1WebhookEnvelope<T>;
+    /**
+     * Verifies the signature, then parses the body into a typed envelope.
+     * Throws `WebhookVerificationError` if the signature does not match.
+     */
+    static verifyAndParse<T = unknown>(secret: string, rawBody: string | Buffer, signatureHeader: string | null | undefined): B1WebhookEnvelope<T>;
+}
+
+declare global {
+    namespace Express {
+        interface Request {
+            /** The untouched request body — set by `express.json({ verify })`. */
+            rawBody?: Buffer | string;
+            /** The verified, parsed webhook envelope — set by `b1WebhookMiddleware`. */
+            b1Webhook?: B1WebhookEnvelope;
+        }
+    }
+}
+interface B1WebhookMiddlewareOptions {
+    /** The webhook secret, or a function resolving one per request. */
+    secret: string | ((req: Request) => string);
+    /** Called instead of the default 401 response when verification fails. */
+    onInvalid?: (req: Request, res: Response) => void;
+}
+/**
+ * Express middleware that verifies the `X-B1-Signature` header and attaches a
+ * typed `req.b1Webhook` envelope.
+ *
+ * The raw request body must be available — capture it before JSON parsing:
+ *
+ * ```ts
+ * app.use(express.json({ verify: (req, _res, buf) => { (req as any).rawBody = buf; } }));
+ * app.post("/webhooks/b1", b1WebhookMiddleware({ secret }), (req, res) => {
+ *   console.log(req.b1Webhook?.event);
+ *   res.sendStatus(200);
+ * });
+ * ```
+ *
+ * `express.raw({ type: "application/json" })` is also accepted — `req.body` is
+ * then a Buffer the middleware verifies and parses itself.
+ */
+declare function b1WebhookMiddleware(options: B1WebhookMiddlewareOptions): RequestHandler;
+
+/**
+ * A typed REST client for the B1 Api, authenticated with a `cak_` API key.
+ *
+ * The Api is a single host with per-module path prefixes — use `request()`
+ * with a full `/membership/...` path, or the module helpers which prefix it
+ * for you.
+ *
+ * ```ts
+ * const client = new B1RestClient({ apiKey: "cak_..." });
+ * const people = await client.membership<Person[]>("/people");
+ * ```
+ *
+ * Non-2xx responses throw `B1ApiError` (carrying status + parsed body) so a
+ * caller can distinguish 401/403/404/500.
+ */
+declare class B1RestClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options: B1RestClientOptions);
+    /** Issues a request against a full Api path (e.g. `/membership/people`). */
+    request<T = unknown>(path: string, options?: B1RequestOptions): Promise<T>;
+    /** Request against the `/membership` module. */
+    membership<T = unknown>(path: string, options?: B1RequestOptions): Promise<T>;
+    /** Request against the `/giving` module. */
+    giving<T = unknown>(path: string, options?: B1RequestOptions): Promise<T>;
+    /** Request against the `/attendance` module. */
+    attendance<T = unknown>(path: string, options?: B1RequestOptions): Promise<T>;
+    /** Request against the `/content` module. */
+    content<T = unknown>(path: string, options?: B1RequestOptions): Promise<T>;
+    /** Request against the `/messaging` module. */
+    messaging<T = unknown>(path: string, options?: B1RequestOptions): Promise<T>;
+    /** Request against the `/doing` module. */
+    doing<T = unknown>(path: string, options?: B1RequestOptions): Promise<T>;
+    /** Request against the `/reporting` module. */
+    reporting<T = unknown>(path: string, options?: B1RequestOptions): Promise<T>;
+    private module;
+    private buildUrl;
+}
+
+/** Thrown by `B1RestClient` when the Api returns a non-2xx response. */
+declare class B1ApiError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly body: unknown;
+    readonly method: string;
+    readonly url: string;
+    constructor(opts: {
+        status: number;
+        statusText: string;
+        body: unknown;
+        method: string;
+        url: string;
+    });
+}
+
+/** Thrown when a B1 OAuth endpoint returns an `error` response. */
+declare class B1OAuthError extends Error {
+    readonly error: string;
+    readonly errorDescription?: string;
+    readonly status: number;
+    constructor(error: string, errorDescription: string | undefined, status: number);
+}
+interface B1OAuthClientOptions {
+    clientId: string;
+    /** Required for confidential clients (authorization_code grant). */
+    clientSecret?: string;
+    /** Base URL — defaults to production. */
+    baseUrl?: string;
+    /** Override `fetch` (for tests or non-global-fetch runtimes). */
+    fetch?: typeof fetch;
+}
+interface AwaitDeviceTokenOptions {
+    deviceCode: string;
+    /** Poll interval in seconds (from `B1DeviceAuthResponse.interval`). */
+    interval: number;
+    /** Overall timeout in seconds (from `B1DeviceAuthResponse.expires_in`). */
+    expiresIn: number;
+    /** Optional abort signal to cancel polling. */
+    signal?: AbortSignal;
+}
+/**
+ * Helper for B1's OAuth flows — authorization-code, refresh-token, and the
+ * RFC 8628 device flow — against `/membership/oauth/*`.
+ */
+declare class B1OAuthClient {
+    private readonly clientId;
+    private readonly clientSecret?;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options: B1OAuthClientOptions);
+    /**
+     * Requests an authorization code. B1's `/authorize` endpoint is an
+     * authenticated POST, so this needs the *user's* access token (a JWT).
+     */
+    getAuthorizationCode(params: {
+        userAccessToken: string;
+        redirectUri: string;
+        scope: B1Scope[] | string;
+        state?: string;
+    }): Promise<{
+        code: string;
+        state: string | null;
+    }>;
+    /** Exchanges an authorization code for tokens. */
+    exchangeCode(params: {
+        code: string;
+        redirectUri?: string;
+    }): Promise<B1TokenResponse>;
+    /** Exchanges a refresh token for a fresh access token. */
+    refresh(refreshToken: string): Promise<B1TokenResponse>;
+    /** Starts the device flow — returns a user code + verification URI. */
+    startDeviceFlow(scope?: B1Scope[] | string): Promise<B1DeviceAuthResponse>;
+    /** Polls once for a device-flow token. Never throws on a pending/expired/denied state. */
+    pollDeviceToken(deviceCode: string): Promise<B1DevicePollResult>;
+    /** Polls until the device flow is approved, denied, or expires. */
+    awaitDeviceToken(options: AwaitDeviceTokenOptions): Promise<B1TokenResponse>;
+    /** Looks up a pending device authorization by its user code (for an approval UI). */
+    getPendingDevice(userCode: string): Promise<unknown>;
+    private post;
+    private rawPost;
+}
+
+/** `@churchapps/integration-sdk` — toolkit for building B1.church integrations. */
+declare const VERSION = "0.1.0";
+
+export { type AttendanceWebhookData, type AwaitDeviceTokenOptions, B1ApiError, type B1DeviceAuthResponse, type B1DevicePollResult, type B1GrantType, type B1KnownScope, type B1Module, B1OAuthClient, type B1OAuthClientOptions, B1OAuthError, type B1QueryValue, type B1RequestOptions, B1RestClient, type B1RestClientOptions, type B1Scope, type B1TokenResponse, type B1Webhook, type B1WebhookEnvelope, type B1WebhookEventName, type B1WebhookMiddlewareOptions, B1_BASE_URLS, B1_SCOPES, type DonationWebhookData, type EventWebhookData, type FormSubmissionWebhookData, type GroupMemberWebhookData, type GroupWebhookData, type HouseholdWebhookData, type PersonWebhookData, type SessionWebhookData, VERSION, WEBHOOK_HEADERS, WebhookVerificationError, WebhookVerifier, b1WebhookMiddleware };