ab-ecosystem-cpass 0.1.0 → 1.0.0

package/docs/channels/channels.md

@@ -0,0 +1,199 @@
+# Channels
+
+`crm.channels` — `/v1/channels`
+
+The connections an account sends and receives on: a WhatsApp number, an RCS
+agent, a webchat widget.
+
+A channel is **provisioned by onboarding, not by this API**. There is no
+`create` and no `delete`: `disable` retires one for good, keeping the row its
+billing, wallet and activity history hang off.
+
+Anything that lives with the provider rather than on the channel document — the
+business profile, the QR code, media uploads, number registration — moves
+through `getProp` and `setProp`, documented on their own page:
+**[channel properties](channel-props.md)**.
+
+| Action | Route | Scope |
+| --- | --- | --- |
+| [`list`](#list) | `GET /v1/channels` | `channels:read` |
+| [`get`](#get) | `GET /v1/channels/:id` | `channels:read` |
+| [`updateDetails`](#updatedetails) | `PUT /v1/channels/:id` | `channels:write` |
+| [`disable`](#disable) | `POST /v1/channels/:id/disable` | `channels:write` |
+| [`rotateToken`](#rotatetoken) | `DELETE /v1/channels/:id/token` | `channels:write` |
+| [`getProp`](channel-props.md) | `GET /v1/channels/:id/:prop` | `channels:read` |
+| [`setProp`](channel-props.md) | `POST /v1/channels/:id/:prop` | `channels:write` |
+
+## The channel object
+
+Credentials and the private auth block are stripped from every response; what
+remains is safe to hand a console.
+
+```ts
+interface Channel {
+  id: string;
+  active: boolean;                  // enabled by the owner — NOT the connection state
+  ecom?: { store_status: boolean; store?: string };
+  basic_details: { name: string; color_code: string; channel_identity: string };
+  meta: {
+    category: string;               // whatsapp | sms | email | rcs | webchat
+    provider: string;               // BSP or integration, e.g. EMBEDDED_PNCL_BILLING
+    support_template: boolean;
+    show_template: boolean;
+    bypass_webhook_verification: boolean;
+  };
+  wallet: { balance: number | 'NULL'; currency: string };
+  campaign_tps: number;             // messages/second the campaign runner may push; default 10
+  upgraded_webhook_listener: boolean;
+  cloud: ChannelCloud;              // provider identifiers, flattened
+  api_only: boolean;
+  crm_only: boolean;
+  mm_lite_enabled: boolean;
+  access_token: string;             // short-lived encrypted handle, minted per response
+  [key: string]: unknown;
+}
+
+interface ChannelCloud {
+  instagram_id: string;
+  is_instagram_business_login: boolean;
+  waba_id: string;
+  business: string;                 // Meta business id
+  phone_number_id: string;
+  is_on_biz_app: boolean;
+  version: string;                  // Graph API version
+  auto_read_receipt: number;
+  upgrade_eligibility: boolean;
+  wa_biz_registration: 'pending' | 'completed';
+}
+```
+
+`basic_details.channel_identity` is the channel's address: the phone number, the
+handle, the widget id.
+
+**Wallet balances are divided down for display.** They are stored as
+ten-thousandths; `channel.wallet.balance` is the value to four decimal places.
+`'NULL'` means the agency has hidden the wallet from this caller. The
+[wallet ledger](wallet.md) reports the raw stored values instead.
+
+---
+
+## list
+
+```ts
+crm.channels.list(query?: Partial<ListChannelsQuery>): Promise<Paginated<Channel>>
+```
+
+`GET /v1/channels` · `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 channel **name and identity**. |
+| `type` | `'whatsapp' \| 'sms' \| 'email' \| 'rcs' \| 'webchat'` | — | Quick filter on the category. |
+| `active` | boolean | — | Quick filter: enabled/disabled by the owner. |
+| `status` | `'connected' \| 'disconnected' \| 'error'` | — | Quick filter on connection health. |
+
+```ts
+const { data } = await crm.channels.list({ type: 'whatsapp', active: true });
+```
+
+---
+
+## get
+
+```ts
+crm.channels.get(id: string): Promise<ChannelResponse>
+```
+
+`GET /v1/channels/:id` · `channels:read` · **200**
+
+**Wrapped, and never a 404.** The payload is `{ data }`, and when nothing
+matches it is `{ data: {} }` rather than an error:
+
+```ts
+const { data } = await crm.channels.get(id);
+if (!('id' in data)) throw new Error('no such channel');
+```
+
+---
+
+## updateDetails
+
+```ts
+crm.channels.updateDetails(id: string, input: UpdateChannelDetailsInput): Promise<ChannelResponse>
+```
+
+`PUT /v1/channels/:id` · `channels:write` · **200**, wrapped as `{ data }`
+
+Renames or recolours a channel, and moves its billing currency. **At least one
+field is required** — an empty body is a `422`.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `name` | string | 1–120 chars. |
+| `color` | string | Hex, `#075E54` or `#fff`. |
+| `currency` | `'USD' \| 'EUR' \| 'INR' \| 'IDR'` | See below. |
+
+Currency is the one field with consequences: it decides how every conversation
+is priced, so it only moves on a **WhatsApp channel with an empty wallet** — a
+balance carried across a switch would be worth a different amount on the other
+side. A non-empty wallet is `409 wallet_not_empty`, with the current currency in
+`details`. Asking for the currency the channel already bills in changes nothing
+and is not an error.
+
+```ts
+await crm.channels.updateDetails(id, { name: 'Support', color: '#075E54' });
+```
+
+---
+
+## disable
+
+```ts
+crm.channels.disable(id: string): Promise<{ success: true }>
+```
+
+`POST /v1/channels/:id/disable` · `channels:write` · **200**
+
+Retires a channel for good. It stops delivering, drops out of every listing, and
+**cannot be brought back**. The row stays so its billing, wallet and activity
+history remain readable.
+
+A negative wallet balance blocks it with `409 negative_wallet_balance`: that is
+money owed that nothing would collect afterwards. Settle the balance first.
+
+A webchat channel has its widget subscription removed first — left behind, the
+panel would keep posting into a dead inbox, and nothing would be able to reach
+the widget to remove it afterwards.
+
+---
+
+## rotateToken
+
+```ts
+crm.channels.rotateToken(id: string): Promise<{ success: true }>
+```
+
+`DELETE /v1/channels/:id/token` · `channels:write` · **200**
+
+Issues a new inbound API token and discards the old one, which **stops working
+immediately**. Anything using it starts failing on the next request.
+
+The new value is not in the response. Read it back with:
+
+```ts
+await crm.channels.rotateToken(id);
+const { data: token } = await crm.channels.getProp<string>(id, 'token');
+```
+
+---
+
+## Properties
+
+`getProp` and `setProp` cover everything else a channel can do — the business
+profile, QR codes, media uploads, number registration and migration, the message
+queue, conversation automation. Each property, with its query and body, is on
+**[channel properties](channel-props.md)**.

package/docs/channels/templates.md

@@ -0,0 +1,224 @@
+# Templates
+
+`crm.templates` — `/v1/channels/:channelId/templates`
+
+WhatsApp message templates, per channel.
+
+A template is **local until it is submitted to Meta**. Create it as a `draft`,
+or pass `applyForApproval: true` to send it straight on, at which point it
+becomes `pending` and Meta decides. `sync` pulls Meta's current view back over
+ours, which is how approvals and rejections arrive without waiting on a webhook.
+
+Every method takes the channel id first. A template id belonging to another
+channel is a `404` rather than a match.
+
+| Action | Route | Scope |
+| --- | --- | --- |
+| [`list`](#list) | `GET /v1/channels/:channelId/templates` | `channels:read` |
+| [`get`](#get) | `GET /v1/channels/:channelId/templates/:id` | `channels:read` |
+| [`create`](#create) | `POST /v1/channels/:channelId/templates` | `channels:write` |
+| [`update`](#update) | `PATCH /v1/channels/:channelId/templates/:id` | `channels:write` |
+| [`delete`](#delete) | `DELETE /v1/channels/:channelId/templates/:id` | `channels:write` |
+| [`sync`](#sync) | `POST /v1/channels/:channelId/templates/sync` | `channels:write` |
+
+## The template object
+
+```ts
+interface Template {
+  id: string;
+  channelId: string;
+  type: 'whatsapp';
+  status: 'draft' | 'pending' | 'approved' | 'rejected';
+  source: 'MANUAL' | 'AUTO_GENERATED';
+  templateId?: string;           // Meta's id; absent while still a local draft
+  name: string;
+  category: 'MARKETING' | 'UTILITY' | 'AUTHENTICATION';
+  subCategory: string;
+  parameterFormat: 'POSITIONAL' | 'NAMED';
+  language: string;              // e.g. 'en_US'
+  hash: string;                  // identity within the channel: name + language
+  adDetails: { ad_account: string; ad_campaign: string; ad_set: string; ad_id: string };
+  components: Record<string, unknown>[];  // Meta's HEADER/BODY/FOOTER/BUTTONS array
+  payload?: Record<string, unknown>;      // the last payload sent to Meta
+  extra?: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+}
+```
+
+**Identity is name plus language.** The same name in two languages is two
+templates; that pair is what `hash` encodes.
+
+### Lifecycle
+
+```
+draft ──applyForApproval──▶ pending ──▶ approved
+  ▲                            │
+  └── stays local              └──────▶ rejected
+```
+
+`AUTO_GENERATED` templates are created by the platform, not by a caller.
+
+---
+
+## list
+
+```ts
+crm.templates.list(channelId: string, query?: Partial<ListTemplatesQuery>): Promise<Paginated<Template>>
+```
+
+`GET /v1/channels/:channelId/templates` · `channels:read` · **200**
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `page` | number | `1` | 1-based. |
+| `rows` | number | `25` | 1–100. |
+| `search` | string | — | 1–120 chars. Matches the **name and sub-category**. |
+| `status` | `TemplateStatus` | — | Quick filter. |
+| `category` | `TemplateCategory` | — | Quick filter. |
+| `parameterFormat` | `'POSITIONAL' \| 'NAMED'` | — | Quick filter. |
+| `language` | string | — | Exact language code. |
+
+```ts
+const approved = await crm.templates.list(channelId, { status: 'approved', language: 'en_US' });
+```
+
+---
+
+## get
+
+```ts
+crm.templates.get(channelId: string, id: string): Promise<Template>
+```
+
+`GET /v1/channels/:channelId/templates/:id` · `channels:read` · **200**
+
+---
+
+## create
+
+```ts
+crm.templates.create(channelId: string, input: CreateTemplateInput): Promise<Template>
+```
+
+`POST /v1/channels/:channelId/templates` · `channels:write` · **201**
+
+### Body
+
+| Field | Type | Required | Default | Notes |
+| --- | --- | --- | --- | --- |
+| `name` | string | yes | — | 1–512 chars, `^[a-z0-9_]+$` — Meta's own rule. |
+| `category` | `'MARKETING' \| 'UTILITY' \| 'AUTHENTICATION'` | yes | — | |
+| `language` | string | yes | — | 2–15 chars, e.g. `en` or `en_US`. |
+| `components` | object[] | yes | — | At least one. Meta's component array. |
+| `subCategory` | string | no | `''` | Up to 120 chars. |
+| `parameterFormat` | `'POSITIONAL' \| 'NAMED'` | no | `'POSITIONAL'` | `{{1}}` vs `{{name}}`. |
+| `source` | `'MANUAL' \| 'AUTO_GENERATED'` | no | `'MANUAL'` | |
+| `payload` | object | no | — | |
+| `extra` | object | no | — | |
+| `adDetails` | partial | no | all `''` | Click-to-WhatsApp ad attribution. |
+| `applyForApproval` | boolean | no | `false` | Submit to Meta immediately. |
+
+Re-using a `name` + `language` pair that already exists on the channel is a
+`409 conflict`.
+
+**Meta goes first.** With `applyForApproval: true`, the template is submitted
+before any row is written, so a rejection leaves nothing behind — it surfaces as
+a `400` carrying Meta's reason.
+
+```ts
+const template = await crm.templates.create(channelId, {
+  name: 'order_update',
+  category: 'UTILITY',
+  language: 'en_US',
+  components: [
+    { type: 'BODY', text: 'Hi {{1}}, your order {{2}} has shipped.' },
+  ],
+  applyForApproval: true,
+});
+
+template.status; // 'pending'
+```
+
+---
+
+## update
+
+```ts
+crm.templates.update(channelId: string, id: string, input: UpdateTemplateInput): Promise<Template>
+```
+
+`PATCH /v1/channels/:channelId/templates/:id` · `channels:write` · **200**
+
+Every field from `create`, plus `status`, all optional. At least one is required.
+
+### What may change depends on where the template is
+
+A **draft** is fully editable. **Once it is with Meta its identity is fixed**,
+and `name`, `language`, `category`, `subCategory`, `parameterFormat`, `source`
+and `adDetails` are silently ignored — only `components`, `payload` and `extra`
+still move.
+
+### Nothing is sent to Meta unless you ask
+
+Pass `applyForApproval: true`, or a `status` other than `'draft'`. Then:
+
+- a **draft** is submitted for the first time;
+- a template **already at Meta** is updated in place.
+
+Either way the row comes back `pending`. A non-draft with no Meta id is
+`409 template_not_submitted`.
+
+Changing a draft's `name` or `language` into a pair that already exists is a
+`409 conflict`.
+
+```ts
+// Edit the copy and resubmit
+await crm.templates.update(channelId, id, {
+  components: [{ type: 'BODY', text: 'Hi {{1}}, order {{2}} is on its way.' }],
+  applyForApproval: true,
+});
+```
+
+---
+
+## delete
+
+```ts
+crm.templates.delete(channelId: string, id: string): Promise<void>
+```
+
+`DELETE /v1/channels/:channelId/templates/:id` · `channels:write` · **204**, no body.
+
+A **draft** only exists here and is simply removed. Anything submitted is
+**deleted at Meta first**, so no row is kept for a template the WABA no longer
+has. If Meta refuses, the call fails with `400 template_deletion_failed` and the
+row stays.
+
+---
+
+## sync
+
+```ts
+crm.templates.sync(channelId: string): Promise<TemplateSyncResult>
+```
+
+`POST /v1/channels/:channelId/templates/sync` · `channels:write` · **200**
+
+Pulls the channel's templates from Meta and writes their current state over
+ours, so approvals and rejections show up without waiting for a webhook.
+
+Note the path: **`sync` is a sibling of `:id`, not a child of it.**
+
+```ts
+{ fetched: number, created: number, updated: number, skipped: number }
+```
+
+`skipped` is templates Meta returned that are not storable here — one in a
+category this platform does not model, for instance. `400 template_sync_failed`
+if Meta refuses the listing.
+
+```ts
+const result = await crm.templates.sync(channelId);
+console.log(`${result.updated} templates changed status`);
+```

package/docs/channels/wallet.md

@@ -0,0 +1,67 @@
+# Wallet ledger
+
+`crm.wallet` — `/v1/channels/:channelId/wallet`
+
+Every credit and debit against a channel's balance, with the balance before and
+after each movement.
+
+**Read-only.** Money moves through top-ups and through conversation billing, not
+through this API. To send a user to the top-up page, read
+[`recharge_url`](channel-props.md#recharge_url).
+
+| Action | Route | Scope |
+| --- | --- | --- |
+| [`list`](#list) | `GET /v1/channels/:channelId/wallet` | `channels:read` |
+
+## The wallet log object
+
+```ts
+interface WalletLog {
+  id: string;
+  type: 'credit' | 'debit';
+  currency: string;
+  note: string;
+  amount: number;        // ten-thousandths
+  startBalance: number;  // ten-thousandths
+  endBalance: number;    // ten-thousandths
+  status: string;
+  category: string;
+  createdAt: string;
+  updatedAt: string;
+}
+```
+
+**Amounts here are the raw stored values** — ten-thousandths of a currency unit
+— unlike `channel.wallet.balance`, which is already divided down for display.
+Divide by `10000` to show them:
+
+```ts
+const display = (amount: number) => (amount / 10_000).toFixed(4);
+```
+
+---
+
+## list
+
+```ts
+crm.wallet.list(channelId: string, query?: Partial<ListWalletLogsQuery>): Promise<Paginated<WalletLog>>
+```
+
+`GET /v1/channels/:channelId/wallet` · `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 **note, category and status**. |
+| `type` | `'credit' \| 'debit'` | — | Quick filter. |
+| `range` | `{ start, end }` | — | Unix seconds. `0` on either end means no bound. Serialised to JSON by the SDK. |
+
+```ts
+const topUps = await crm.wallet.list(channelId, {
+  type: 'credit',
+  range: { start: 1767225600, end: 0 },
+});
+```

package/docs/channels/webhooks.md

@@ -0,0 +1,152 @@
+# Channel webhooks
+
+`crm.channelWebhooks` — `/v1/channels/:channelId/webhooks`
+
+Where a channel's message traffic is delivered.
+
+These carry conversation events — `incoming`, `sent`, `delivered`, `read`,
+`failed` — plus the account-level notices Meta sends about templates, the phone
+number and the WABA. Several webhooks may watch the same channel, and each gets
+its own copy.
+
+Distinct from [`crm.webhooks`](../audience/webhooks.md), which carries contact
+changes from the audience module.
+
+| Action | Route | Scope |
+| --- | --- | --- |
+| [`list`](#list) | `GET /v1/channels/:channelId/webhooks` | `channels:read` |
+| [`get`](#get) | `GET /v1/channels/:channelId/webhooks/:id` | `channels:read` |
+| [`create`](#create) | `POST /v1/channels/:channelId/webhooks` | `channels:write` |
+| [`update`](#update) | `PATCH /v1/channels/:channelId/webhooks/:id` | `channels:write` |
+| [`delete`](#delete) | `DELETE /v1/channels/:channelId/webhooks/:id` | `channels:write` |
+
+## The webhook object
+
+```ts
+interface ChannelWebhook {
+  id: string;
+  channelId: string;
+  title: string;
+  active: boolean;
+  events: ChannelWebhookEvent[];
+  url: string;
+  meta?: {
+    source: 'PANEL' | 'API';
+    createdBy?: string;
+    createdIp?: string;
+    updatedBy?: string;
+    updatedIp?: string;
+  };
+  createdAt: string;
+  updatedAt: string;
+}
+```
+
+`meta` is an **audit trail**: who created or last changed the webhook and from
+where. It is filled in by the service from the caller's identity and IP, and is
+never accepted on a write. Webhooks created through this SDK are recorded with
+`source: 'API'`.
+
+### Events
+
+| Event | Fires on |
+| --- | --- |
+| `incoming` | A message from the customer. |
+| `sent` | A message accepted for delivery. |
+| `delivered` | Delivery confirmed. |
+| `read` | The customer read it. |
+| `failed` | Delivery failed. |
+| `deleted` | A message was deleted. |
+| `template` | A template's status changed at Meta. |
+| `account` | A WABA-level notice. |
+| `phone_number` | A phone-number-level notice. |
+| `calls` | A call event. |
+
+Exported as `CHANNEL_WEBHOOK_EVENTS` if you need the list at runtime.
+
+---
+
+## list
+
+```ts
+crm.channelWebhooks.list(channelId: string, query?: Partial<ListChannelWebhooksQuery>): Promise<Paginated<ChannelWebhook>>
+```
+
+`GET /v1/channels/:channelId/webhooks` · `channels:read` · **200**
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `page` | number | `1` | 1-based. |
+| `rows` | number | `25` | 1–100. |
+| `search` | string | — | 1–120 chars. Matches the **title and URL**. |
+| `active` | boolean | — | Quick filter: enabled/disabled. |
+| `event` | `ChannelWebhookEvent` | — | Quick filter: webhooks subscribed to this one event. |
+
+```ts
+const live = await crm.channelWebhooks.list(channelId, { active: true, event: 'incoming' });
+```
+
+---
+
+## get
+
+```ts
+crm.channelWebhooks.get(channelId: string, id: string): Promise<ChannelWebhook>
+```
+
+`GET /v1/channels/:channelId/webhooks/:id` · `channels:read` · **200**
+
+---
+
+## create
+
+```ts
+crm.channelWebhooks.create(channelId: string, input: CreateChannelWebhookInput): Promise<ChannelWebhook>
+```
+
+`POST /v1/channels/:channelId/webhooks` · `channels:write` · **201**
+
+### Body
+
+| Field | Type | Required | Default | Notes |
+| --- | --- | --- | --- | --- |
+| `url` | string | yes | — | Valid absolute URL, up to 2048 chars. |
+| `events` | `ChannelWebhookEvent[]` | yes | — | At least one. |
+| `title` | string | no | `'CRM Channel Webhook'` | 1–120 chars. |
+| `active` | boolean | no | `true` | |
+
+```ts
+await crm.channelWebhooks.create(channelId, {
+  title: 'Inbox bridge',
+  url: 'https://inbox.example.com/hooks/whatsapp',
+  events: ['incoming', 'sent', 'delivered', 'read', 'failed'],
+});
+```
+
+---
+
+## update
+
+```ts
+crm.channelWebhooks.update(channelId: string, id: string, input: UpdateChannelWebhookInput): Promise<ChannelWebhook>
+```
+
+`PATCH /v1/channels/:channelId/webhooks/:id` · `channels:write` · **200**
+
+Same fields as `create`, all optional; at least one is required.
+
+`events` **replaces** the subscription list rather than adding to it. Pause
+delivery with `{ active: false }` rather than deleting, so the configuration
+comes back.
+
+---
+
+## delete
+
+```ts
+crm.channelWebhooks.delete(channelId: string, id: string): Promise<void>
+```
+
+`DELETE /v1/channels/:channelId/webhooks/:id` · `channels:write` · **204**
+
+Delivery stops immediately.