ab-ecosystem-cpass 0.1.0 → 1.0.0

package/docs/audience/contact-notes.md

@@ -0,0 +1,129 @@
+# Contact notes
+
+`crm.contactNotes` — `/v1/audience/contacts/:contactId/notes`
+
+Internal notes on a contact: free text, attachments, and team members mentioned
+in them. Notes are never shown to the contact.
+
+> **Not mounted yet.** These routes are commented out in the audience service's
+> `routes.ts`, so they answer `404` until that line is restored. The contract,
+> the service and this client are complete; only the mount is missing.
+
+Every method takes the contact id first — notes are addressed under their
+contact, and a note id belonging to another contact is a `404` rather than a
+match.
+
+| Action | Route | Scope |
+| --- | --- | --- |
+| [`list`](#list) | `GET /v1/audience/contacts/:contactId/notes` | `contacts:read` |
+| [`get`](#get) | `GET /v1/audience/contacts/:contactId/notes/:noteId` | `contacts:read` |
+| [`create`](#create) | `POST /v1/audience/contacts/:contactId/notes` | `contacts:write` |
+| [`update`](#update) | `PATCH /v1/audience/contacts/:contactId/notes/:noteId` | `contacts:write` |
+| [`delete`](#delete) | `DELETE /v1/audience/contacts/:contactId/notes/:noteId` | `contacts:write` |
+
+## The note object
+
+```ts
+interface ContactNote {
+  id: string;
+  contact: string;                       // the contact it hangs off
+  note: string;
+  attachments: ContactNoteAttachment[];
+  mentions: string[];                    // team member ids
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface ContactNoteAttachment {
+  url: string;          // required
+  type?: string;
+  size?: string;
+  mime?: string;
+  file_name?: string;
+}
+```
+
+---
+
+## list
+
+```ts
+crm.contactNotes.list(contactId: string, query?: Partial<ListContactNotesQuery>): Promise<Page<ContactNote>>
+```
+
+`GET /v1/audience/contacts/:contactId/notes` · `contacts:read` · **200**
+
+**Cursor paginated**, not offset — notes are appended constantly, and an offset
+would shift under a caller mid-walk.
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `limit` | number | `50` | 1–100. |
+| `cursor` | string | — | From the previous response's `nextCursor`. |
+
+```ts
+let cursor: string | null = null;
+do {
+  const page = await crm.contactNotes.list(contactId, { limit: 25, cursor: cursor ?? undefined });
+  for (const note of page.data) render(note);
+  cursor = page.nextCursor;
+} while (cursor);
+```
+
+---
+
+## get
+
+```ts
+crm.contactNotes.get(contactId: string, noteId: string): Promise<ContactNote>
+```
+
+`GET /v1/audience/contacts/:contactId/notes/:noteId` · `contacts:read` · **200**
+
+---
+
+## create
+
+```ts
+crm.contactNotes.create(contactId: string, input: CreateContactNoteInput): Promise<ContactNote>
+```
+
+`POST /v1/audience/contacts/:contactId/notes` · `contacts:write` · **201**
+
+| Field | Type | Required | Default | Notes |
+| --- | --- | --- | --- | --- |
+| `note` | string | yes | — | 1–5000 chars. |
+| `attachments` | `ContactNoteAttachment[]` | no | `[]` | `url` is the only required key on each. |
+| `mentions` | ObjectId[] | no | `[]` | Team member ids. |
+
+```ts
+await crm.contactNotes.create(contactId, {
+  note: 'Called back — wants a demo on Friday.',
+  mentions: [teamMemberId],
+});
+```
+
+---
+
+## update
+
+```ts
+crm.contactNotes.update(contactId: string, noteId: string, input: UpdateContactNoteInput): Promise<ContactNote>
+```
+
+`PATCH /v1/audience/contacts/:contactId/notes/:noteId` · `contacts:write` · **200**
+
+Same fields as `create`, all optional. `attachments` and `mentions` **replace**
+their stored value rather than appending to it.
+
+---
+
+## delete
+
+```ts
+crm.contactNotes.delete(contactId: string, noteId: string): Promise<void>
+```
+
+`DELETE /v1/audience/contacts/:contactId/notes/:noteId` · `contacts:write` · **204**, no body.
+
+Destroying a contact (the second `crm.contacts.delete`) removes its notes too.

package/docs/audience/contact-tags.md

@@ -0,0 +1,109 @@
+# Contact tags
+
+`crm.contactTags` — `/v1/audience/contact-tags`
+
+The labels a contact can carry. A tag is its own resource: `crm.contacts` takes
+tag **ids** on a write, and hands back the full tag documents resolved into
+`contact.tags` on a read.
+
+| Action | Route | Scope |
+| --- | --- | --- |
+| [`list`](#list) | `GET /v1/audience/contact-tags` | `contact_tags:read` |
+| [`get`](#get) | `GET /v1/audience/contact-tags/:id` | `contact_tags:read` |
+| [`create`](#create) | `POST /v1/audience/contact-tags` | `contact_tags:write` |
+| [`update`](#update) | `PATCH /v1/audience/contact-tags/:id` | `contact_tags:write` |
+| [`delete`](#delete) | `DELETE /v1/audience/contact-tags/:id` | `contact_tags:write` |
+
+## The tag object
+
+```ts
+interface ContactTag {
+  id: string;
+  name: string;
+  icon: string;   // icon name or emoji; '' when unset
+  color: string;  // free-form; '' when unset
+}
+```
+
+---
+
+## list
+
+```ts
+crm.contactTags.list(query?: Partial<ListContactTagsQuery>): Promise<Paginated<ContactTag>>
+```
+
+`GET /v1/audience/contact-tags` · `contact_tags:read` · **200**
+
+### Query
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `page` | number | `1` | 1-based. |
+| `rows` | number | `25` | 1–100. |
+| `search` | string | — | 1–120 chars. Matches the tag **name**. |
+
+```ts
+const { data, pagination } = await crm.contactTags.list({ search: 'vip' });
+```
+
+---
+
+## get
+
+```ts
+crm.contactTags.get(id: string): Promise<ContactTag>
+```
+
+`GET /v1/audience/contact-tags/:id` · `contact_tags:read` · **200**
+
+`404 not_found` if the tag is not the caller's.
+
+---
+
+## create
+
+```ts
+crm.contactTags.create(input: CreateContactTagInput): Promise<ContactTag>
+```
+
+`POST /v1/audience/contact-tags` · `contact_tags:write` · **201**
+
+### Body
+
+| Field | Type | Required | Default | Notes |
+| --- | --- | --- | --- | --- |
+| `name` | string | yes | — | Trimmed, 1–120 chars. |
+| `icon` | string | no | `''` | Up to 120 chars. |
+| `color` | string | no | `''` | Up to 32 chars. Free-form, so the palette can evolve; only length is checked. |
+
+```ts
+const tag = await crm.contactTags.create({ name: 'VIP', icon: 'star', color: '#f59e0b' });
+```
+
+---
+
+## update
+
+```ts
+crm.contactTags.update(id: string, input: UpdateContactTagInput): Promise<ContactTag>
+```
+
+`PATCH /v1/audience/contact-tags/:id` · `contact_tags:write` · **200**
+
+Same fields as `create`, all optional. Renaming a tag changes it everywhere it
+is shown — contacts hold the id, not a copy of the name.
+
+---
+
+## delete
+
+```ts
+crm.contactTags.delete(id: string): Promise<void>
+```
+
+`DELETE /v1/audience/contact-tags/:id` · `contact_tags:write` · **204**, no body.
+
+> **Known gap.** Deleting a tag does not currently remove its id from the
+> contacts that carry it, so those contacts keep a reference that resolves to
+> nothing. Clear the tag off its contacts first if that matters to you.

package/docs/audience/contacts.md

@@ -0,0 +1,227 @@
+# Contacts
+
+`crm.contacts` — `/v1/audience/contacts`
+
+The people an account talks to, and the resource everything else in the audience
+module hangs off. A contact carries a name, a set of channel identities, the
+values of every custom field, its tags, and the state of its conversation.
+
+**Scoping** — contacts belong to an account, and a request carries two
+identities: the caller and the account they act for. Reads match either; writes
+land on the caller's own.
+
+| Action | Route | Scope |
+| --- | --- | --- |
+| [`list`](#list) | `GET /v1/audience/contacts` | `contacts:read` |
+| [`get`](#get) | `GET /v1/audience/contacts/:id` | `contacts:read` |
+| [`create`](#create) | `POST /v1/audience/contacts` | `contacts:write` |
+| [`update`](#update) | `PATCH /v1/audience/contacts/:id` | `contacts:write` |
+| [`delete`](#delete) | `DELETE /v1/audience/contacts/:id` | `contacts:write` |
+| [`iterate`](#iterate) | — (walks `list`) | `contacts:read` |
+
+## The contact object
+
+```ts
+interface Contact {
+  id: string;
+  name: { salutation: string; first_name: string; last_name: string };
+  profile: Record<string, ContactProfile>;   // channel identities, keyed by channel
+  custom_field_hash: Record<string, unknown>; // values keyed by custom field slug
+  chat_metadata: ContactChatMetadata;
+  order?: string;
+  last_seen: number;                          // unix seconds
+  last_icm_timestamp: number;                 // unix seconds, last inbound message
+  last_interaction_props: Record<string, unknown>;
+  agent: string | null;
+  team: string | null;
+  lead_source: { type?: string; module?: string; id: string | null };
+  status: 'live' | 'trashed';
+  privacy_status: 'open' | 'locked';
+  tags: ContactTag[];                         // resolved documents, not ids
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface ContactProfile {
+  id: string;
+  channel: 'whatsapp' | 'facebook' | 'instagram' | 'telegram' | 'email' | 'rcs' | 'webchat';
+  identifier: string;   // number, handle or address
+  name: string;
+  profile_pic: string;
+  extra: Record<string, unknown>;
+}
+
+interface ContactChatMetadata {
+  new: boolean;
+  archived: boolean;
+  unread: number;
+  pause_duration: number;   // seconds to pause automation for
+  marked_as_unread: boolean;
+  closed: boolean;
+  marked_as_done: boolean;
+  blocked: { incoming: boolean; outgoing: boolean; bot: boolean; api: boolean };
+}
+```
+
+`profile`, `last_seen`, `last_icm_timestamp` and `last_interaction_props` are
+written by the platform as conversations happen. They are not settable.
+
+---
+
+## list
+
+```ts
+crm.contacts.list(query?: Partial<ListContactsQuery>): Promise<Paginated<Contact>>
+```
+
+`GET /v1/audience/contacts` · `contacts:read` · **200**
+
+### Query
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `page` | number | `1` | 1-based. |
+| `rows` | number | `25` | 1–100. |
+| `search` | string | — | 1–120 chars. Matches the first and last name, plus the name and identifier of every channel identity. |
+| `tag` | ObjectId | — | Contacts carrying this tag. |
+| `agent` | ObjectId | — | Contacts assigned to this agent. |
+| `status` | `'live' \| 'trashed'` | `'live'` | The trash needs an explicit `'trashed'`. |
+| `segment` | string | — | A segment's id **or** its name. A reference matching neither is a `404` — listing everyone because the segment went missing would be the wrong answer. |
+| `filter` | `ContactFilter` | — | Ad-hoc conditions. Serialised to JSON by the SDK. See [contact filter](../contact-filter.md). |
+
+`segment` and `filter` can be sent together: the ad-hoc conditions then **narrow**
+the saved ones rather than replacing them. `tag`, `agent` and `status` narrow
+whatever those produce.
+
+### Example
+
+```ts
+const page = await crm.contacts.list({
+  search: 'acme',
+  status: 'live',
+  segment: 'High budget',
+  filter: {
+    conditions: [
+      { operator: null, field_id: 'city', field_type: 'text', condition: 'equal to', value: 'Pune' },
+    ],
+  },
+  rows: 50,
+});
+
+console.log(page.pagination); // { page: 1, rows: 50, total: 128, pages: 3 }
+```
+
+---
+
+## get
+
+```ts
+crm.contacts.get(id: string): Promise<Contact>
+```
+
+`GET /v1/audience/contacts/:id` · `contacts:read` · **200**
+
+One contact with its tags resolved. `404 not_found` if no contact with that id
+belongs to the caller — including a contact in the trash of another account.
+
+---
+
+## create
+
+```ts
+crm.contacts.create(input?: CreateContactInput): Promise<Contact>
+```
+
+`POST /v1/audience/contacts` · `contacts:write` · **201**
+
+### Body
+
+Every field is optional; `crm.contacts.create()` with no argument creates a
+blank contact.
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `name` | `Partial<ContactName>` | — | `salutation` ≤ 20 chars, `first_name` and `last_name` ≤ 120. |
+| `order` | string | — | Free-form external reference. |
+| `tags` | ObjectId[] | `[]` | Contact tag ids. |
+| `agent` | ObjectId \| null | — | Assigned agent. |
+| `team` | ObjectId \| null | — | Assigned team. |
+| `lead_source` | `{ type?, module?, id? }` | — | Where the contact came from. |
+| `status` | `'live' \| 'trashed'` | `'live'` | |
+| `privacy_status` | `'open' \| 'locked'` | `'open'` | |
+| `custom_field_hash` | object | — | Values keyed by custom field **slug**. |
+| `chat_metadata` | partial | — | Including `blocked`, itself partial. |
+
+Channel identities cannot be set here; they are written when a conversation
+starts on a channel.
+
+```ts
+const contact = await crm.contacts.create({
+  name: { first_name: 'Ada', last_name: 'Lovelace' },
+  tags: [vipTagId],
+  custom_field_hash: { city: 'Pune', lead_score: 80 },
+});
+```
+
+---
+
+## update
+
+```ts
+crm.contacts.update(id: string, input: UpdateContactInput): Promise<Contact>
+```
+
+`PATCH /v1/audience/contacts/:id` · `contacts:write` · **200**
+
+Takes the same body as `create`, all optional. Anything left out is untouched.
+
+`tags` and `custom_field_hash` **replace** their stored value rather than merging
+into it — read the contact first if you mean to add one tag to the existing set.
+
+```ts
+await crm.contacts.update(id, { agent: agentId, chat_metadata: { closed: true } });
+```
+
+---
+
+## delete
+
+```ts
+crm.contacts.delete(id: string): Promise<ContactDeleteResult>
+```
+
+`DELETE /v1/audience/contacts/:id` · `contacts:write` · **200**
+
+Two-stage, and **200 rather than 204 both times**: the body is what says which
+stage ran.
+
+| Call | Contact was | Result |
+| --- | --- | --- |
+| first | `live` | `{ id, status: 'trashed' }` — recoverable with `update(id, { status: 'live' })` |
+| second | `trashed` | `{ id, status: 'deleted' }` — the contact, its notes and its channel identities are gone |
+
+```ts
+const first = await crm.contacts.delete(id);  // { status: 'trashed' }
+const second = await crm.contacts.delete(id); // { status: 'deleted' }
+```
+
+---
+
+## iterate
+
+```ts
+crm.contacts.iterate(query?: Partial<ListContactsQuery>): AsyncGenerator<Contact>
+```
+
+Walks every page of `list`, yielding one contact at a time. Takes the same query;
+`page` is managed for you and is ignored if passed.
+
+```ts
+for await (const contact of crm.contacts.iterate({ tag: vipTagId })) {
+  await sync(contact);
+}
+```
+
+The walk reads live data. A contact created while you are part-way through may
+be missed or seen twice — take a `filter` on `SYSTEM_CREATED_ON` if you need a
+stable set.

package/docs/audience/crm-triggers.md

@@ -0,0 +1,240 @@
+# CRM triggers
+
+`crm.crmTriggers` — `/v1/audience/crm-triggers`
+
+Fire a webhook when a contact changes.
+
+A trigger asks three questions, and all three have to pass before its action
+runs:
+
+1. **`trigger`** — which contact event happened.
+2. **`when`** — did the right *fields* move?
+3. **`filters`** — does the contact itself match these conditions?
+
+`filters` speak the same [contact filter](../contact-filter.md) DSL segments do,
+flat rather than wrapped. They are checked by running the contact list query
+pinned to that one contact, so a trigger's conditions mean exactly what they
+mean on the list.
+
+| Action | Route | Scope |
+| --- | --- | --- |
+| [`list`](#list) | `GET /v1/audience/crm-triggers` | `crm_triggers:read` |
+| [`get`](#get) | `GET /v1/audience/crm-triggers/:id` | `crm_triggers:read` |
+| [`create`](#create) | `POST /v1/audience/crm-triggers` | `crm_triggers:write` |
+| [`update`](#update) | `PATCH /v1/audience/crm-triggers/:id` | `crm_triggers:write` |
+| [`delete`](#delete) | `DELETE /v1/audience/crm-triggers/:id` | `crm_triggers:write` |
+| [`logs`](#logs) | `GET /v1/audience/crm-triggers/logs` | `crm_triggers:read` |
+
+## The trigger object
+
+```ts
+interface CrmTrigger {
+  id: string;
+  name: string;
+  active: boolean;
+  module: 'contact';
+  type: 'event' | 'time';
+  trigger: CrmTriggerEvent;
+  when: { condition: 'any' | 'any_of_selected' | 'all'; fields: string[] };
+  filters: ContactFilterEntry[];
+  action: {
+    type: 'webhook';
+    config: { url: string; method: 'POST' | 'PUT' | 'PATCH' | 'GET'; headers: Record<string, string> };
+  };
+  createdAt: string;
+  updatedAt: string;
+}
+```
+
+### Events
+
+| `trigger` | Fires when |
+| --- | --- |
+| `created` | A contact is created. |
+| `edited`, `modified` | Any change — the two are equivalent. |
+| `deleted` | A contact is destroyed. |
+| `agent_assigned`, `agent_deassigned` | The assigned agent changed. |
+| `marked_as_done`, `marked_as_closed`, `marked_as_archived` | The matching `chat_metadata` flag moved. |
+| `blocked` | A `chat_metadata.blocked` flag moved. |
+
+All of these except `created` and `deleted` are narrower readings of the same
+update, decided by which paths moved.
+
+### `when`
+
+| `condition` | Passes when |
+| --- | --- |
+| `any` | Every change — `fields` is ignored. |
+| `any_of_selected` | At least one path in `fields` moved. |
+| `all` | Every path in `fields` moved. |
+
+`fields` are dotted contact paths: `name.first_name`, `chat_metadata.closed`,
+`custom_field_hash.lead_score`.
+
+Events that carry no change set — a creation, a deletion — pass regardless.
+
+> **Known gap.** `filters` are skipped for `deleted` events: the contact is
+> already gone, so there is nothing left to match against.
+
+### Time triggers
+
+`type: 'time'` is stored and served, but **nothing dispatches it yet**. Creating
+one is not an error; it simply never fires.
+
+---
+
+## list
+
+```ts
+crm.crmTriggers.list(query?: Partial<ListCrmTriggersQuery>): Promise<Paginated<CrmTrigger>>
+```
+
+`GET /v1/audience/crm-triggers` · `crm_triggers:read` · **200**
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `page` | number | `1` | 1-based. |
+| `rows` | number | `25` | 1–100. |
+| `search` | string | — | 1–120 chars. Matches the trigger **name**. |
+| `trigger` | `CrmTriggerEvent` | — | Quick filter. |
+| `type` | `'event' \| 'time'` | — | Quick filter. |
+| `active` | boolean | — | Quick filter. |
+
+---
+
+## get
+
+```ts
+crm.crmTriggers.get(id: string): Promise<CrmTrigger>
+```
+
+`GET /v1/audience/crm-triggers/:id` · `crm_triggers:read` · **200**
+
+---
+
+## create
+
+```ts
+crm.crmTriggers.create(input: CreateCrmTriggerInput): Promise<CrmTrigger>
+```
+
+`POST /v1/audience/crm-triggers` · `crm_triggers:write` · **201**
+
+### Body
+
+| Field | Type | Required | Default | Notes |
+| --- | --- | --- | --- | --- |
+| `name` | string | yes | — | Trimmed, 1–120 chars. |
+| `action` | `CrmTriggerAction` | yes | — | See below. |
+| `active` | boolean | no | `true` | |
+| `module` | `'contact'` | no | `'contact'` | |
+| `type` | `'event' \| 'time'` | no | `'event'` | |
+| `trigger` | `CrmTriggerEvent` | no | `'edited'` | |
+| `when` | `CrmTriggerWhen` | no | `{ condition: 'any', fields: [] }` | |
+| `filters` | `ContactFilterEntry[]` | no | `[]` | At most 50. |
+
+With only `name` and `action`, you get an active `event` trigger on `edited`
+with no narrowing — it fires on every change to every contact.
+
+`action.config`:
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `url` | string | — | Required, and must be a valid URL. |
+| `method` | `'POST' \| 'PUT' \| 'PATCH' \| 'GET'` | `'POST'` | |
+| `headers` | `Record<string, string>` | `{}` | Sent alongside the contact payload. |
+
+```ts
+await crm.crmTriggers.create({
+  name: 'Notify ops when a VIP conversation closes',
+  trigger: 'edited',
+  when: { condition: 'any_of_selected', fields: ['chat_metadata.closed'] },
+  filters: [
+    { operator: null, field_id: 'tags', field_type: 'string', condition: 'equal to', value: [vipTagId] },
+  ],
+  action: {
+    config: {
+      url: 'https://ops.example.com/hooks/vip',
+      method: 'POST',
+      headers: { 'x-source': 'crm' },
+    },
+  },
+});
+```
+
+> **Not signed.** Trigger deliveries carry no signature — the schema has no
+> per-trigger secret. Put a shared token in `action.config.headers` and check it
+> at your endpoint. (`crm.webhooks` deliveries *are* signed.)
+
+---
+
+## update
+
+```ts
+crm.crmTriggers.update(id: string, input: UpdateCrmTriggerInput): Promise<CrmTrigger>
+```
+
+`PATCH /v1/audience/crm-triggers/:id` · `crm_triggers:write` · **200**
+
+Same fields as `create`, all optional. `when`, `filters` and `action`
+**replace** their stored value rather than merging into it.
+
+Pause a trigger with `{ active: false }` rather than deleting it — the
+configuration comes back, and the delivery history stays readable either way.
+
+---
+
+## delete
+
+```ts
+crm.crmTriggers.delete(id: string): Promise<void>
+```
+
+`DELETE /v1/audience/crm-triggers/:id` · `crm_triggers:write` · **204**, no body.
+
+---
+
+## logs
+
+```ts
+crm.crmTriggers.logs(query?: Partial<ListCrmTriggerLogsQuery>): Promise<Paginated<CrmTriggerLog>>
+```
+
+`GET /v1/audience/crm-triggers/logs` · `crm_triggers:read` · **200**
+
+Delivery history across every trigger, or one trigger's with `{ trigger: id }`.
+Newest first.
+
+Note the path: **`logs` is a sibling of `:id`, not a child of it** — there is no
+`/crm-triggers/:id/logs`.
+
+Logs are written by the dispatcher, never by a caller, and the collection
+expires them after 30 days. There is no way to write or delete one.
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `page` | number | `1` | 1-based. |
+| `rows` | number | `25` | 1–100. |
+| `search` | string | — | Accepted by the route, but ignored: a log row has no searchable text. |
+| `trigger` | ObjectId | — | One trigger's history. |
+| `event` | `CrmTriggerEvent` | — | Quick filter. |
+| `status` | `'success' \| 'fail'` | — | Quick filter. |
+
+```ts
+interface CrmTriggerLog {
+  id: string;
+  trigger: string;                      // the trigger that fired
+  event: CrmTriggerEvent;
+  status: 'success' | 'fail';
+  payload: { url?: string; body?: unknown };
+  response?: unknown;                   // status and body, or the error that stopped the call
+  expiryDate: string;                   // when the row is removed
+  createdAt: string;
+  updatedAt: string;
+}
+```
+
+```ts
+const failures = await crm.crmTriggers.logs({ trigger: triggerId, status: 'fail' });
+for (const log of failures.data) console.error(log.payload.url, log.response);
+```