# AI Church SDK

Official client libraries for the **AI Church** platform API — build on top of your church's
data in PHP, JavaScript, or any language that can make an HTTP request.

> Free for churches. Intellectual property of **Boreon Industries, LLC** (Boreon™, USA), a
> **[KWAM.CH](https://kwam.ch)** platform, operated on sovereign infrastructure at Infomaniak, Geneva.
> Reproduction by any company is pursued under our international license. *Soli Deo Gloria.*

---

## 1. Get your credentials

In the app go to **Settings → Automation / API & SDK** and copy:

- **API base URL** — `https://your-domain/app.php?action=api`
- **API key** — `sk_church_…` (send it as `Authorization: Bearer <key>`; keep it secret)

Auth is by API key only — these calls do **not** need a login session or CSRF token. Keep the key
server-side; don't ship it in public client code.

---

## 2. Quick start

### JavaScript (browser or Node 18+)

```js
import AIChurch from './aichurch.js';
const ac = new AIChurch('https://aichurch.boreon.com', 'sk_church_xxx');

const { data } = await ac.members({ q: 'smith', limit: 50 });
const stats   = await ac.stats();
await ac.recordGift({ member_id: 12, amount: 100, method: 'card' });
const risk    = await ac.atRisk();              // who needs follow-up
const verse   = await ac.verse('Psalm 23');
```

### PHP 7.4+

```php
require 'aichurch.php';
$ac = new AIChurch('https://aichurch.boreon.com', 'sk_church_xxx');

$members = $ac->members(['q' => 'smith', 'limit' => 50]);
$ac->recordGift(['member_id' => 12, 'amount' => 100, 'method' => 'card']);
$metrics = $ac->metrics();                       // deterministic church-health formulas
```

### curl

```bash
curl -H "Authorization: Bearer sk_church_xxx" \
  "https://aichurch.boreon.com/app.php?action=api&resource=stats"

curl -X POST -H "Authorization: Bearer sk_church_xxx" -H "Content-Type: application/json" \
  -d '{"member_id":12,"amount":100,"method":"card"}' \
  "https://aichurch.boreon.com/app.php?action=api&resource=giving"
```

---

## 3. Endpoints

Base: `GET|POST {baseUrl}/app.php?action=api&resource=<resource>` · auth `Authorization: Bearer <api_key>`

| Method | resource | Params / body | Returns |
|--------|----------|---------------|---------|
| GET  | `stats` | — | dashboard stats (members, YTD giving, at-risk…) |
| GET  | `members` | `q`, `limit`, or `id` | member list (or one) |
| GET  | `member` | `id` | a single member |
| POST | `members` | `first_name, last_name, email, phone, status, external_id, source` | upsert (matches by external_id/email) |
| GET  | `giving` | `limit` | recent gifts |
| POST | `giving` | `member_id, amount, fund_id, date, method` | record a gift |
| GET  | `metrics` | — | deterministic analytics formula groups |
| GET  | `at_risk` | — | members in at-risk / critical tiers |
| GET  | `segments` | — | donor-intelligence segments |
| GET  | `events` | — | events |
| POST | `events` | `name, start_date, end_date, location, capacity, type` | create event |
| POST | `engagement_recompute` | — | recompute all engagement scores |
| POST | `workflow_run` | `id` | run a workflow now |
| GET  | `verse` | `ref` | scripture lookup (bible-api) |

**Responses** are JSON. Lists come back as `{ "data": [...] }`. Errors return a non-2xx status with
`{ "error": "message" }` (the SDKs throw on these).

---

## 4. Notes

- **Auth transport:** the key is accepted **only** in the `Authorization: Bearer <key>` header (the old
  `?api_key=` query-string method was removed so keys never leak via logs, Referer, or browser history).
- **Read-only mode:** an admin can set the API to read-only (Settings → Config & Flags → Security & Access);
  while on, all `POST` writes return `403`. **Rotate** the key anytime in Settings → API & SDK (the old key
  is revoked immediately — update your integrations).
- **Privacy:** member responses return a fixed field allowlist and **exclude the pastoral `notes` field**.
- **CORS** is enabled (`Access-Control-Allow-Origin: *`) so the JS SDK works from any origin — but the
  key is the gate, so only use it where you can keep the key secret (server-to-server, or a trusted backend).
- **Webhooks:** `members` and `giving` writes fire your configured outbound webhook (`member.created`,
  `giving.recorded`) — wire AI Church into Zapier / Make / n8n. Configure under Settings → Integrations.
- **Rate / abuse:** the API is throttled per IP (240 req/min, plus a bad-key lockout) — be considerate
  with bulk writes and add a small delay if you hit `429`.
- **Versioning:** this is v1 of the API. New resources are additive; existing shapes won't break.

Questions? Use the in-app **Office Helper** or the **Knowledge Base** at `/kb/`.