@churchify/sdk

Typed TypeScript client for the Churchify church-retention REST API. Works in Node and the browser.

npm install @churchify/sdk

Usage

import { createChurchifyClient, ChurchifyApiError } from '@churchify/sdk';

const churchify = createChurchifyClient({
  baseUrl: 'https://api.churchify.app', // or http://localhost:9010 in dev
  apiKey: process.env.CHURCHIFY_API_KEY!,
});

// The pastor retention briefing for the church
const briefing = await churchify.retention.briefing();

// Who is drifting / which guests have gone cold?
const atRisk = await churchify.retention.atRisk({ limit: 20 });

// One person's full retention picture (score, reasons, next actions, timeline)
const brief = await churchify.retention.personBrief(personId);

// Create a task for a person, then complete it
const action = await churchify.retention.createNextAction({
  personId,
  type: 'invite_to_group',
  reason: 'Returned for a 3rd visit — ready to connect',
  priority: 'high',
});
await churchify.retention.completeNextAction(action._id, { outcome: 'Joined Tuesday group' });

Authentication & tenancy

The API key encodes both the church (tenant) and the scopes it may use, so the SDK never takes a churchId. Create keys in Churchify under Admin → Settings → API Keys. Pass actorPersonId to attribute mutations to a person for audit purposes (it does not grant access).

Errors

Non-success responses throw ChurchifyApiError with status, code, and (for validation failures) issues.

try {
  await churchify.retention.createNextAction({ /* … */ } as any);
} catch (e) {
  if (e instanceof ChurchifyApiError) console.error(e.status, e.code, e.issues);
}

API

| Method | Endpoint | |---|---| | retention.briefing() | GET /v1/retention/briefing | | retention.atRisk({ limit }) | GET /v1/retention/at-risk | | retention.personBrief(id) | GET /v1/people/:id/retention-brief | | retention.personEvents(id, opts) | GET /v1/people/:id/events | | retention.nextActions(opts) | GET /v1/next-actions | | retention.personNextActions(id, opts) | GET /v1/people/:id/next-actions | | retention.createNextAction(body) | POST /v1/next-actions | | retention.completeNextAction(id, body) | POST /v1/next-actions/:id/complete |

License

MIT © Moloks Technologies