ab-ecosystem-cpass 0.1.0 → 1.0.0

package/docs/audience/webhooks.md

@@ -0,0 +1,167 @@
+# Audience webhooks
+
+`crm.webhooks` — `/v1/audience/webhooks`
+
+HTTPS endpoints the platform POSTs contact events to.
+
+Three things in this SDK are called a webhook; they are not the same thing:
+
+| | Carries | Signed |
+| --- | --- | --- |
+| `crm.webhooks` | Contact events: created, updated, deleted | **yes** |
+| [`crm.crmTriggers`](crm-triggers.md) | One configured request per rule, when a contact matches | no |
+| [`crm.channelWebhooks`](../channels/webhooks.md) | A channel's message traffic | n/a |
+
+**Scoping** — unlike the rest of the audience module, these rows are scoped by
+**tenant** rather than by the calling user.
+
+| Action | Route | Scope |
+| --- | --- | --- |
+| [`list`](#list) | `GET /v1/audience/webhooks` | `webhooks:read` |
+| [`get`](#get) | `GET /v1/audience/webhooks/:id` | `webhooks:read` |
+| [`create`](#create) | `POST /v1/audience/webhooks` | `webhooks:write` |
+| [`update`](#update) | `PATCH /v1/audience/webhooks/:id` | `webhooks:write` |
+| [`delete`](#delete) | `DELETE /v1/audience/webhooks/:id` | `webhooks:write` |
+
+## The webhook object
+
+```ts
+interface Webhook {
+  id: string;
+  url: string;
+  events: ('contact.created' | 'contact.updated' | 'contact.deleted')[];
+  enabled: boolean;
+  failureCount: number;     // consecutive delivery failures
+  lastDeliveredAt?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+```
+
+## The delivery
+
+Your endpoint receives:
+
+```ts
+interface WebhookEnvelope {
+  id: string;         // delivery id, stable across retries of the same event
+  type: string;       // e.g. 'contact.created'
+  tenantId: string;
+  createdAt: string;
+  data: unknown;      // the contact, or { id } for a deletion
+}
+```
+
+with two headers:
+
+```
+x-crm-timestamp: 1774512000
+x-crm-signature: v1=<hex>
+```
+
+where the digest is `HMAC-SHA256(secret, "<timestamp>.<raw body>")`. Verify
+against the **raw bytes**, before any JSON parsing:
+
+```ts
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+const verify = (secret: string, timestamp: string, rawBody: string, header: string) => {
+  const digest = createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
+  const expected = Buffer.from(`v1=${digest}`);
+  const actual = Buffer.from(header);
+  return expected.length === actual.length && timingSafeEqual(expected, actual);
+};
+```
+
+Reject a timestamp too far from now to stop replays.
+
+---
+
+## list
+
+```ts
+crm.webhooks.list(query?: Partial<ListWebhooksQuery>): Promise<Page<Webhook>>
+```
+
+`GET /v1/audience/webhooks` · `webhooks:read` · **200**
+
+**Cursor paginated**, not offset.
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `limit` | number | `50` | 1–100. |
+| `cursor` | string | — | From the previous response's `nextCursor`. |
+| `enabled` | boolean | — | Accepted by the contract, but **not yet applied** by the service — the list comes back unfiltered. Filter client-side until that lands. |
+
+---
+
+## get
+
+```ts
+crm.webhooks.get(id: string): Promise<Webhook>
+```
+
+`GET /v1/audience/webhooks/:id` · `webhooks:read` · **200**
+
+The signing secret is **never** returned here. It is shown once, by `create`.
+
+---
+
+## create
+
+```ts
+crm.webhooks.create(input: CreateWebhookInput): Promise<Webhook & { secret: string }>
+```
+
+`POST /v1/audience/webhooks` · `webhooks:write` · **201**
+
+### Body
+
+| Field | Type | Required | Default | Notes |
+| --- | --- | --- | --- | --- |
+| `url` | string | yes | — | Must be a valid absolute URL. |
+| `events` | `WebhookEventType[]` | yes | — | At least one of `contact.created`, `contact.updated`, `contact.deleted`. |
+| `enabled` | boolean | no | `true` | |
+
+The URL has to be **public https**. A non-https URL, or a hostname resolving to
+a loopback, link-local or private address, is rejected with
+`422 invalid_webhook_url` — the DNS lookup happens at write time, so a name that
+resolves privately is caught here rather than at delivery.
+
+```ts
+const hook = await crm.webhooks.create({
+  url: 'https://ops.example.com/hooks/crm',
+  events: ['contact.created', 'contact.updated'],
+});
+
+await vault.store(hook.secret);  // the only response that carries it
+```
+
+---
+
+## update
+
+```ts
+crm.webhooks.update(id: string, input: UpdateWebhookInput): Promise<Webhook>
+```
+
+`PATCH /v1/audience/webhooks/:id` · `webhooks:write` · **200**
+
+Same fields as `create`, all optional. A new `url` is checked the same way.
+`events` **replaces** the subscription list rather than adding to it.
+
+The secret does not change and cannot be rotated through this route — create a
+second webhook, move over, and delete the first.
+
+---
+
+## delete
+
+```ts
+crm.webhooks.delete(id: string): Promise<void>
+```
+
+`DELETE /v1/audience/webhooks/:id` · `webhooks:write` · **204**, no body.
+
+Delivery stops immediately; queued attempts are dropped. To pause instead, send
+`update(id, { enabled: false })`.

package/docs/channels/activity.md

@@ -0,0 +1,68 @@
+# Activity log
+
+`crm.activity` — `/v1/channels/:channelId/logs`
+
+What happened to a channel, and who did it — the owner, the agency, or the
+platform itself.
+
+**Read-only**, and written by the services as they work. Wallet movements share
+the feed with ordinary activity, so `type: 'activity'` is the filter for
+"everything except money"; for the money itself with its running balance, read
+the [wallet ledger](wallet.md) instead.
+
+| Action | Route | Scope |
+| --- | --- | --- |
+| [`list`](#list) | `GET /v1/channels/:channelId/logs` | `channels:read` |
+
+## The activity log object
+
+```ts
+interface ActivityLog {
+  id: string;
+  source: {
+    type?: 'user' | 'agency' | 'system';
+    id?: string;
+  };
+  log: {
+    type?: 'wallet' | 'activity';
+    event: string;     // machine name, e.g. 'template.approved'
+    message: string;   // human-readable line for the feed
+  };
+  createdAt: string;
+  updatedAt: string;
+}
+```
+
+---
+
+## list
+
+```ts
+crm.activity.list(channelId: string, query?: Partial<ListActivityLogsQuery>): Promise<Paginated<ActivityLog>>
+```
+
+`GET /v1/channels/:channelId/logs` · `channels:read` · **200**
+
+Newest first.
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `page` | number | `1` | 1-based. |
+| `rows` | number | `25` | 1–100. |
+| `search` | string | — | 1–120 chars. Matches the **event name and the message**. |
+| `type` | `'wallet' \| 'activity'` | — | Quick filter. |
+| `source` | `'user' \| 'agency' \| 'system'` | — | Quick filter: who caused the entry. |
+| `event` | string | — | Quick filter: one exact event name, 1–120 chars. |
+| `range` | `{ start, end }` | — | Unix seconds. `0` on either end means no bound. Serialised to JSON by the SDK. |
+
+```ts
+// Everything the platform did to this channel this week
+const feed = await crm.activity.list(channelId, {
+  source: 'system',
+  type: 'activity',
+  range: { start: weekStart, end: 0 },
+});
+
+// One event's history
+const approvals = await crm.activity.list(channelId, { event: 'template.approved' });
+```

package/docs/channels/billing.md

@@ -0,0 +1,112 @@
+# Conversation billing
+
+`crm.billing` — `/v1/channels/:channelId/conversations`
+
+What each conversation on a channel cost.
+
+One route answers in two shapes. Without `stat` it pages through individual
+charges; with `stat` it returns aggregates instead — which is why this SDK
+splits it into two methods.
+
+**`channelId` may be `'all'`** to read across every channel the caller owns.
+That also changes what `summary` groups by: currency across all channels,
+message category on a single one.
+
+| Action | Route | Scope |
+| --- | --- | --- |
+| [`list`](#list) | `GET /v1/channels/:channelId/conversations` | `channels:read` |
+| [`stats`](#stats) | `GET /v1/channels/:channelId/conversations?stat=…` | `channels:read` |
+
+Read-only: charges are written by the platform as conversations happen.
+
+## The billing log object
+
+```ts
+interface BillingLog {
+  id: string;
+  chatId?: string;             // the conversation the charge belongs to
+  identifier: string;          // the recipient, as the channel addresses them
+  deduction: {
+    billable: boolean;         // false for free-tier conversations — logged, not charged
+    amount: number;
+    currency: string;
+  };
+  meta?: Record<string, unknown>;  // recipient country, category, template, campaign, message id
+  createdAt: string;
+  updatedAt: string;
+}
+```
+
+---
+
+## list
+
+```ts
+crm.billing.list(channelId: string, query?): Promise<Paginated<BillingLog>>
+```
+
+`GET /v1/channels/:channelId/conversations` · `channels:read` · **200**
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `page` | number | `1` | 1-based. |
+| `rows` | number | `25` | 1–100. |
+| `search` | string | — | 1–120 chars. Matches the recipient `identifier` and the `meta` fields: recipient, category, country and message id. |
+| `range` | `{ start, end }` | — | Unix seconds. `0` on either end means **no bound**. Serialised to JSON by the SDK. |
+| `template` | string[] | — | Quick filter: templates the conversation was billed against. |
+| `country` | string[] | — | Quick filter: recipient country codes. |
+| `campaign` | string[] | — | Quick filter: campaigns that produced the conversation. |
+
+The three array filters are sent as JSON; the server also accepts a
+comma-separated string if you build the query yourself.
+
+```ts
+const charges = await crm.billing.list('all', {
+  range: { start: 1767225600, end: 1769817600 },
+  country: ['IN', 'US'],
+  rows: 100,
+});
+```
+
+---
+
+## stats
+
+```ts
+crm.billing.stats(channelId: string, stat?: BillingStat, query?): Promise<BillingStats>
+```
+
+`GET /v1/channels/:channelId/conversations?stat=…` · `channels:read` · **200**
+
+The same filters, aggregated instead of paged. `stat` defaults to `'summary'`.
+
+```ts
+interface BillingStats {
+  data: { group: string; totalRecords: number; totalDeductionAmount: number }[];
+  stat: 'summary' | 'day_wise';
+}
+```
+
+`group` is what the totals are cut by:
+
+| `stat` | `channelId` | `group` is |
+| --- | --- | --- |
+| `summary` | `'all'` | the currency |
+| `summary` | one channel | the message category |
+| `day_wise` | either | the calendar date |
+
+**Pagination does not apply** — every group is returned, and `page`/`rows` are
+ignored.
+
+```ts
+const monthly = await crm.billing.stats('all', 'summary', {
+  range: { start: 1767225600, end: 1769817600 },
+});
+
+for (const row of monthly.data) {
+  console.log(row.group, row.totalDeductionAmount, `(${row.totalRecords} conversations)`);
+}
+
+// Per day, one channel
+const daily = await crm.billing.stats(channelId, 'day_wise', { range: { start: 0, end: 0 } });
+```

package/docs/channels/channel-props.md

@@ -0,0 +1,290 @@
+# Channel properties
+
+`crm.channels.getProp` / `crm.channels.setProp` — `/v1/channels/:id/:prop`
+
+Everything about a channel that lives with the **provider** rather than on the
+channel document: the business profile, QR codes, media uploads, number
+registration, the message queue.
+
+```ts
+crm.channels.getProp<T>(id, prop, query?): Promise<ChannelPropResponse<T>>
+crm.channels.setProp<T>(id, prop, options?): Promise<ChannelPropResponse<T>>
+```
+
+Both answer the same envelope:
+
+```ts
+interface ChannelPropResponse<T> {
+  data: T;         // whatever the provider returned — shape follows `prop`
+  prop: string;    // echo
+  channel: string; // echo
+}
+```
+
+`data` is deliberately untyped: each property returns whatever Meta (or the
+local config) hands back. Pass a type argument when you know the shape.
+
+## Which channels support which properties
+
+| Category | Readable | Writable |
+| --- | --- | --- |
+| `whatsapp` | all | all |
+| `rcs` | `fetch_channel_queue` `recharge_url` `token` | `test_message` |
+| anything else | none | none |
+
+Asking for an unsupported property is `400 unsupported_channel_prop`, with the
+supported list in `details`.
+
+## `setProp` options
+
+```ts
+interface SetPropOptions {
+  body?: Record<string, unknown>;  // JSON body — ignored when `raw` is set
+  query?: Record<string, unknown>; // query string parameters
+  raw?: BodyInit;                  // file bytes, for the three binary properties
+  contentType?: string;            // required whenever `raw` is set
+}
+```
+
+**Three properties take file bytes instead of JSON**: `profile_pic`,
+`resumable_upload` and `upload_media`. Pass them as `raw` with a `contentType`.
+
+Several write properties wrap their payload in an `update` key — that is Meta's
+own envelope, passed straight through. The table below says which.
+
+---
+
+## Readable properties
+
+### `general`
+
+Meta's general details for the phone number: verified name, quality rating,
+display number status.
+
+```ts
+const { data } = await crm.channels.getProp(id, 'general');
+```
+
+### `business_profile`
+
+The WhatsApp business profile: about text, address, description, email,
+websites, vertical, profile picture URL.
+
+### `business_compliance`
+
+Compliance information registered for the business (India's customer-care
+details, and similar).
+
+### `business_commerce`
+
+Commerce settings: whether the catalog and cart are on.
+
+### `conversation_automation`
+
+The configured welcome message, ice-breaker prompts and commands.
+
+### `qr_code`
+
+The channel's WhatsApp QR codes and their short links.
+
+### `message_analytics`
+
+Meta's message analytics for the number.
+
+| Query | Required | Default | Notes |
+| --- | --- | --- | --- |
+| `start` | yes | — | Unix seconds. |
+| `end` | yes | — | Unix seconds. |
+| `breakdown` | no | `'DAY'` | Meta's breakdown granularity. |
+| `number` | no | the channel's own identity | Phone number to report on. |
+
+```ts
+const { data } = await crm.channels.getProp(id, 'message_analytics', {
+  start: 1767225600,
+  end: 1769817600,
+  breakdown: 'DAY',
+});
+```
+
+A missing `start` or `end` is a `422`.
+
+### `redirect_url`
+
+A deep link into Meta Business Suite, prefilled for this channel.
+
+| Query | Required | Values |
+| --- | --- | --- |
+| `target` | yes | `meta_catalog_manager` · `link_whatsApp_catalog` · `wa_manager` · `business` |
+
+An unknown target is a `422` listing the valid ones. `data` is the URL string.
+
+### `token`
+
+The channel's inbound API token, followed by an encrypted copy: the prefix
+identifies the channel, the remainder proves the platform issued it. `data` is
+the concatenated string. This is how you read a token back after
+[`rotateToken`](channels.md#rotatetoken).
+
+### `channel_config`
+
+What the agency permits on this channel. Agencies that have never saved a config
+get permissive defaults.
+
+```ts
+{ about: boolean }   // may the about text be edited
+```
+
+### `fetch_channel_queue`
+
+How many messages are waiting in the channel's outbound queue.
+
+### `recharge_url`
+
+The agency's hosted top-up page for the channel's currency, prefilled with the
+caller's details. `404 recharge_link_unavailable` when no link is configured for
+that currency.
+
+---
+
+## Writable properties
+
+### Profile and compliance
+
+| `prop` | Body | Notes |
+| --- | --- | --- |
+| `business_profile` | `{ update: {...} }` | Meta's business profile fields. |
+| `business_compliance` | `{ update: {...} }` | Compliance details. |
+| `business_commerce` | `{ update: {...} }` | Catalog and cart settings. |
+
+`update` is required on all three; leaving it out is a `422`.
+
+```ts
+await crm.channels.setProp(id, 'business_profile', {
+  body: { update: { about: 'We reply in minutes', email: 'hi@example.com' } },
+});
+```
+
+### `qr_code`
+
+`{ update: {...} }`. Pass `update.edit: true` to change an existing code;
+otherwise a new one is created.
+
+### `conversation_automation`
+
+Reads the current automation, changes one part of it, and writes it back — so
+the rest survives.
+
+| Body key | Effect |
+| --- | --- |
+| `welcome_message` | Sets `enable_welcome_message`. |
+| `prop: 'prompts'` + `prompts` | Replaces the ice-breaker prompts. |
+| `prop: 'commands'` + `commands` | Replaces the commands. |
+
+```ts
+await crm.channels.setProp(id, 'conversation_automation', {
+  body: { prop: 'prompts', prompts: [{ prompt_text: 'Track my order' }] },
+});
+```
+
+### `conversation_analytics`
+
+| Body | Required | Default |
+| --- | --- | --- |
+| `range` | yes | — |
+| `granularity` | no | `'DAILY'` |
+| `breakdown` | no | `''` |
+
+Meta's conversation statistics for the channel's own number.
+
+### `whatsapp_business_encryption`
+
+`{ business_public_key }` — required. Registers the key used for encrypted flow
+responses.
+
+### Number registration and migration
+
+| `prop` | Body | What it does |
+| --- | --- | --- |
+| `wa_request_otp` | `{ method?: 'SMS' \| 'VOICE' }` | Asks Meta to send a verification code. Anything but `'VOICE'` is treated as `'SMS'`. |
+| `wa_submit_otp` | `{ code }` | Verifies the code. Required. |
+| `wa_pin_update` | `{ pin, localization? }` | Registers the number with Meta, which is what enables messaging on it. Runs the credit-line handshake and provisions the BSP account first. Already registered? The call is a no-op returning `{ pin: 'unchanged' }`. |
+| `wa_biz_update` | — | For WA Biz numbers, already registered with Meta: does the billing handshake and activates the channel. `400 not_biz_app_channel` on any other channel. |
+| `wa_deregister` | — | Deregisters the number at Meta. |
+| `migrate_number` | `{ cc, phone_number }` | Both required. Moves the channel to a new number and rewrites its `phone_number_id` and identity. |
+
+`wa_pin_update` and `wa_biz_update` both clear the channel's cache: registration
+changes how the number behaves, and anything cached describes the state before
+it.
+
+### File uploads — **binary body**
+
+| `prop` | Sends | Returns |
+| --- | --- | --- |
+| `profile_pic` | The image bytes | Uploads to Meta, then sets it as the profile picture. |
+| `resumable_upload` | The file bytes | `{ h: '<handle>' }` — Meta's upload handle, for use in a template. |
+| `upload_media` | The file bytes | Meta's media id, for sending. |
+
+```ts
+await crm.channels.setProp(id, 'profile_pic', {
+  raw: await file.arrayBuffer(),
+  contentType: 'image/jpeg',
+});
+
+const { data } = await crm.channels.setProp<{ h: string }>(id, 'resumable_upload', {
+  raw: bytes,
+  contentType: 'image/png',
+});
+data.h; // pass this handle to a template component
+```
+
+Up to 25 MB per request. A missing `contentType` will not be inferred.
+
+### `test_message`
+
+Sends one message on the channel, to check it end to end.
+
+`409 channel_inactive` if the channel is not active.
+
+For WhatsApp the body is an outbound message. `{ type: 'flow', flow_id, to, ... }`
+sends a flow instead, and the flow must belong to this channel and be sendable.
+`wait_for_flow_response` waits for the reply.
+
+RCS speaks its own content schema: the whole body is passed through as the
+message, with `queue_id` read off it.
+
+```ts
+await crm.channels.setProp(id, 'test_message', {
+  body: { to: '919876543210', type: 'text', text: { body: 'ping' } },
+});
+```
+
+### `webhook_listener_update`
+
+Points both Meta subscriptions — the WABA (account-level events) and the phone
+number (messages) — at the platform's listener, and marks the channel as
+upgraded. Both have to point there for the listener to be whole.
+
+Returns `{ webhook: '<listener url>' }`.
+
+### `delete_channel_queue`
+
+Purges the channel's outbound queue. Returns `{ deleted: true }`. Anything
+waiting is dropped, not sent.
+
+### `enable_whatsapp_direct` / `disable_whatsapp_direct`
+
+Flips `whatsapp_direct_enabled` on the channel. Takes no body; returns
+`{ whatsapp_direct_enabled: boolean }`.
+
+---
+
+## Errors
+
+| Status | Code | When |
+| --- | --- | --- |
+| 400 | `unsupported_channel_prop` | The channel's category does not support this property. `details.supported` lists what it does. |
+| 400 | `provider_request_failed` | Meta rejected the call (a 4xx from them). `details` carries their reason. |
+| 502 | `provider_request_failed` | Meta failed or was unreachable (a 5xx). |
+| 502 | `partner_request_failed` | The BSP partner call failed. |
+| 422 | — | A required body or query key was missing. |
+| 404 | `not_found` | No such channel for this caller. |