ab-ecosystem-cpass 0.1.0 → 1.0.0

package/docs/audience/custom-fields.md

@@ -0,0 +1,174 @@
+# Custom fields
+
+`crm.customFields` — `/v1/audience/custom-fields`
+
+The per-account schema for contacts. A field's `slug` is the key its values are
+stored under in `contact.custom_field_hash`, and the `field_id` the
+[contact filter](../contact-filter.md) addresses it by.
+
+**Every route takes either the field's id or its slug**, so a caller that knows
+the schema never has to look an id up first. A value that reads as a 24-hex id
+is looked up as one; anything else is read as a slug.
+
+| Action | Route | Scope |
+| --- | --- | --- |
+| [`list`](#list) | `GET /v1/audience/custom-fields` | `custom_fields:read` |
+| [`get`](#get) | `GET /v1/audience/custom-fields/:ref` | `custom_fields:read` |
+| [`create`](#create) | `POST /v1/audience/custom-fields` | `custom_fields:write` |
+| [`update`](#update) | `PATCH /v1/audience/custom-fields/:ref` | `custom_fields:write` |
+| [`delete`](#delete) | `DELETE /v1/audience/custom-fields/:ref` | `custom_fields:write` |
+
+## The field object
+
+```ts
+interface CustomField {
+  id: string;
+  slug: string;                  // machine name, unique per account
+  name?: string;                 // label
+  caption?: string;              // helper text
+  type: 'system' | 'user';       // who owns it — NOT the data type
+  dataType?: CustomFieldType;    // the data type
+  default: Record<string, unknown>;
+  props: Record<string, unknown>;  // type-specific config: dropdown options, precision, …
+  required: boolean;
+  displayInPanel: boolean;
+  showInSidebar: boolean;
+  showAsLabel: boolean;
+  isBoard: boolean;
+  teamAccess: 'restricted' | 'open_to_all';
+  createdAt: string;
+  updatedAt: string;
+}
+```
+
+`type` and `dataType` are easy to confuse. `type` says **who owns the field** —
+`system` for platform-provisioned, `user` for the account's own. `dataType` is
+what it holds.
+
+### Data types
+
+`text` `textarea` `url` `email` `phone` `dial_code` `country` `language`
+`timezone` `date` `timestamp` `periodic_time` `number` `decimal` `amount`
+`percent` `address` `location` `attachment` `checkbox` `dropdown`
+`multi_select`
+
+---
+
+## list
+
+```ts
+crm.customFields.list(query?: Partial<ListCustomFieldsQuery>): Promise<Paginated<CustomField>>
+```
+
+`GET /v1/audience/custom-fields` · `custom_fields:read` · **200**
+
+### Query
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `page` | number | `1` | 1-based. |
+| `rows` | number | `25` | 1–100. |
+| `search` | string | — | 1–120 chars. Matches the **slug, the label and the caption**. |
+| `dataType` | `CustomFieldType` | — | Quick filter. |
+| `type` | `'system' \| 'user'` | — | Quick filter: platform-provisioned or the account's own. |
+| `teamAccess` | `'restricted' \| 'open_to_all'` | — | Quick filter. |
+
+```ts
+const fields = await crm.customFields.list({ type: 'user', dataType: 'dropdown' });
+```
+
+---
+
+## get
+
+```ts
+crm.customFields.get(ref: string): Promise<CustomField>
+```
+
+`GET /v1/audience/custom-fields/:ref` · `custom_fields:read` · **200**
+
+`ref` is the field's id **or** its slug.
+
+```ts
+await crm.customFields.get('lead_score');                  // by slug
+await crm.customFields.get('65f0a1b2c3d4e5f6a7b8c9d0');    // by id
+```
+
+---
+
+## create
+
+```ts
+crm.customFields.create(input: CreateCustomFieldInput): Promise<CustomField>
+```
+
+`POST /v1/audience/custom-fields` · `custom_fields:write` · **201**
+
+### Body
+
+| Field | Type | Required | Default | Notes |
+| --- | --- | --- | --- | --- |
+| `slug` | string | yes | — | `^[a-z][a-z0-9_]{0,63}$`, and not reserved. Immutable once created. |
+| `name` | string | yes | — | 1–120 chars. The label. |
+| `caption` | string | no | — | Up to 240 chars. |
+| `dataType` | `CustomFieldType` | yes | — | See the list above. |
+| `default` | object | no | `{}` | Default value, shaped by `dataType`. |
+| `props` | object | no | `{}` | Type-specific config — dropdown options, number precision, and so on. |
+| `required` | boolean | no | `false` | |
+| `displayInPanel` | boolean | no | `false` | |
+| `showInSidebar` | boolean | no | `false` | |
+| `showAsLabel` | boolean | no | `false` | |
+| `isBoard` | boolean | no | `false` | |
+| `teamAccess` | `'restricted' \| 'open_to_all'` | no | `'open_to_all'` | |
+
+### Reserved slugs
+
+A slug that would shadow something else is rejected with `422`. Three groups:
+
+- **Contact document paths** — `id` `_id` `__v` `user` `business` `name`
+  `profile` `custom_field_hash` `custom_fields` `chat_metadata` `bot` `order`
+  `last_seen` `last_icm_timestamp` `last_interaction_props` `agent` `team`
+  `lead_source` `status` `privacy_status` `tags` `createdat` `updatedat`
+- **Channel keys**, which `profile` is keyed by — `waba` `whatsapp` `facebook`
+  `instagram` `telegram` `email` `rcs` `webchat`
+- **Built-in filter fields** — `referral_id` `system_last_seen`
+  `system_created_on` `system_identifier` `system_profile_name`
+
+The check is case-insensitive. A slug already in use on the account is a
+`409 conflict`.
+
+```ts
+const field = await crm.customFields.create({
+  slug: 'lead_score',
+  name: 'Lead score',
+  dataType: 'number',
+  required: true,
+  showInSidebar: true,
+});
+```
+
+---
+
+## update
+
+```ts
+crm.customFields.update(ref: string, input: UpdateCustomFieldInput): Promise<CustomField>
+```
+
+`PATCH /v1/audience/custom-fields/:ref` · `custom_fields:write` · **200**
+
+Every field from `create` except `slug`, all optional. The slug is not updatable:
+values already stored under it would be orphaned.
+
+---
+
+## delete
+
+```ts
+crm.customFields.delete(ref: string): Promise<void>
+```
+
+`DELETE /v1/audience/custom-fields/:ref` · `custom_fields:write` · **204**, no body.
+
+Deleting the definition does not rewrite the contacts that hold values under its
+slug; those values stay in `custom_field_hash` and simply stop being described.

package/docs/audience/exports.md

@@ -0,0 +1,163 @@
+# Export history
+
+`crm.exports` — `/v1/audience/exports`
+
+One row per bulk extract, moved by a worker through
+`pending → processing → completed | failed`.
+
+Creating a row **queues** the work. When the run completes, `file` holds the
+storage key of the written file and `count` the number of rows in it; when it
+fails, `error` says why.
+
+The route is `/exports`, not `/contact-exports`: a row's `module` is `contact`
+**or** `datastore`.
+
+> **Worker status.** The row, its lifecycle and its counters are live. The
+> worker that writes the file is still a stub — it moves a row to `processing`
+> and then to `completed` without producing anything. No file is written yet.
+
+| Action | Route | Scope |
+| --- | --- | --- |
+| [`list`](#list) | `GET /v1/audience/exports` | `contacts:read` |
+| [`get`](#get) | `GET /v1/audience/exports/:id` | `contacts:read` |
+| [`create`](#create) | `POST /v1/audience/exports` | `contacts:read` |
+| [`delete`](#delete) | `DELETE /v1/audience/exports/:id` | `contacts:write` |
+
+There is no `update`: a row is moved by the worker, not by a caller.
+
+Note the scope on `create` — reading contacts out is a **read**, so an export
+can be started with read-only access.
+
+## The export object
+
+```ts
+interface ExportHistory {
+  id: string;
+  member?: string;          // the team member who started it
+  module: 'contact' | 'datastore';
+  file?: string;            // storage key; absent until the worker writes one
+  title: string;
+  count: number;            // rows written; 0 until it completes
+  status: 'pending' | 'processing' | 'completed' | 'failed';
+  error?: string;           // why it failed, when it did
+  config: ExportConfig;
+  extra: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface ExportConfig {
+  segment?: string;          // a saved segment's id or its name
+  filter?: ContactFilter;    // ad-hoc conditions
+  fields?: string[];         // columns to write; [] means the worker's default set
+  [key: string]: unknown;    // anything else is carried through
+}
+```
+
+`config` says **what to write out**, in the same vocabulary the contact list
+speaks. Sending both a `segment` and a `filter` narrows the segment, exactly as
+`crm.contacts.list` reads the pair — so an export means what the list it came
+from means.
+
+Unlike imports, the export schema has a real `error` column, so a failure goes
+there rather than into `extra`.
+
+---
+
+## list
+
+```ts
+crm.exports.list(query?: Partial<ListExportHistoryQuery>): Promise<Paginated<ExportHistory>>
+```
+
+`GET /v1/audience/exports` · `contacts: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 **title**. |
+| `module` | `'contact' \| 'datastore'` | — | Quick filter. |
+| `status` | `HistoryStatus` | — | Quick filter. |
+
+---
+
+## get
+
+```ts
+crm.exports.get(id: string): Promise<ExportHistory>
+```
+
+`GET /v1/audience/exports/:id` · `contacts:read` · **200**
+
+The progress endpoint: the row with its current `status` and `count`, and — once
+finished — `file`.
+
+```ts
+const run = await crm.exports.get(id);
+if (run.status === 'completed') download(run.file!);
+if (run.status === 'failed') console.error(run.error);
+```
+
+---
+
+## create
+
+```ts
+crm.exports.create(input: CreateExportHistoryInput): Promise<ExportHistory>
+```
+
+`POST /v1/audience/exports` · `contacts:read` · **202**
+
+**202, not 201**: the row exists, but no file has been written yet. The response
+is the row at `status: 'pending'` with `count: 0` and no `file`.
+
+### Body
+
+| Field | Type | Required | Default | Notes |
+| --- | --- | --- | --- | --- |
+| `title` | string | yes | — | Trimmed, 1–200 chars. |
+| `module` | `'contact' \| 'datastore'` | no | `'contact'` | |
+| `config` | `ExportConfig` | no | `{}` | The default exports every contact with the worker's default columns. |
+| `extra` | object | no | `{}` | Carried through untouched. |
+
+Only a title is required:
+
+```ts
+await crm.exports.create({ title: 'Everyone' });
+```
+
+A narrower one:
+
+```ts
+await crm.exports.create({
+  title: 'High budget, Pune',
+  config: {
+    segment: 'High budget',
+    filter: {
+      conditions: [
+        { operator: null, field_id: 'city', field_type: 'text', condition: 'equal to', value: 'Pune' },
+      ],
+    },
+    fields: ['name.first_name', 'name.last_name', 'email', 'city'],
+  },
+});
+```
+
+`fields` names the columns to write; leave it out (or empty) for the worker's
+default set.
+
+---
+
+## delete
+
+```ts
+crm.exports.delete(id: string): Promise<void>
+```
+
+`DELETE /v1/audience/exports/:id` · `contacts:write` · **204**, no body.
+
+Removes the history row. **A file already written to storage is not deleted with
+it** — take the `file` key first if you need to clean it up.

package/docs/audience/imports.md

@@ -0,0 +1,161 @@
+# Import history
+
+`crm.imports` — `/v1/audience/imports`
+
+One row per bulk load, and the record a worker moves through
+`pending → processing → completed | failed`.
+
+Creating a row **queues** the work; it does not do it. The file itself is
+uploaded out of band and named here by its storage key. `statistics` fill in as
+the worker walks the file, so poll `get` to follow a run.
+
+The route is `/imports`, not `/contact-imports`: a row's `module` is `contact`
+**or** `datastore`, so these were never contact-only.
+
+> **Worker status.** The row, its lifecycle and its counters are live. The
+> worker that reads the file is still a stub — it moves a row to `processing`
+> and then to `completed` without reading anything. Nothing parses a file yet.
+
+| Action | Route | Scope |
+| --- | --- | --- |
+| [`list`](#list) | `GET /v1/audience/imports` | `contacts:read` |
+| [`get`](#get) | `GET /v1/audience/imports/:id` | `contacts:read` |
+| [`create`](#create) | `POST /v1/audience/imports` | `contacts:write` |
+| [`delete`](#delete) | `DELETE /v1/audience/imports/:id` | `contacts:write` |
+
+There is no `update`: a row is moved by the worker, not by a caller.
+
+## The import object
+
+```ts
+interface ImportHistory {
+  id: string;
+  member?: string;          // the team member who started it
+  module: 'contact' | 'datastore';
+  file: string;             // storage key of the uploaded file
+  title: string;
+  status: 'pending' | 'processing' | 'completed' | 'failed';
+  config: ImportConfig;
+  extra: Record<string, unknown>;
+  statistics: {
+    total: number;
+    success: number;   // = new + duplicate
+    failed: number;
+    new: number;       // rows that created a contact
+    duplicate: number; // rows that matched one that already existed
+  };
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface ImportConfig {
+  mapping?: Record<string, string>;          // column header -> contact field
+  duplicateStrategy?: 'skip' | 'update';
+  [key: string]: unknown;                    // anything else is carried through
+}
+```
+
+`config` and `extra` are untyped columns. The keys the platform acts on are
+named above; anything else you put there is stored and handed back untouched.
+A whole-run failure puts its reason in **`extra.error`** — the import schema has
+no `error` column of its own.
+
+---
+
+## list
+
+```ts
+crm.imports.list(query?: Partial<ListImportHistoryQuery>): Promise<Paginated<ImportHistory>>
+```
+
+`GET /v1/audience/imports` · `contacts: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 **title**. |
+| `module` | `'contact' \| 'datastore'` | — | Quick filter. |
+| `status` | `HistoryStatus` | — | Quick filter. |
+
+```ts
+const running = await crm.imports.list({ status: 'processing' });
+```
+
+---
+
+## get
+
+```ts
+crm.imports.get(id: string): Promise<ImportHistory>
+```
+
+`GET /v1/audience/imports/:id` · `contacts:read` · **200**
+
+The progress endpoint: the row with its current `status` and `statistics`.
+
+```ts
+const poll = async (id: string) => {
+  for (;;) {
+    const run = await crm.imports.get(id);
+    if (run.status === 'completed' || run.status === 'failed') return run;
+    await new Promise((r) => setTimeout(r, 2000));
+  }
+};
+```
+
+---
+
+## create
+
+```ts
+crm.imports.create(input: CreateImportHistoryInput): Promise<ImportHistory>
+```
+
+`POST /v1/audience/imports` · `contacts:write` · **202**
+
+**202, not 201**: the row exists, but nothing has been read out of the file yet.
+The response is the row at `status: 'pending'` with every counter at zero.
+
+### Body
+
+| Field | Type | Required | Default | Notes |
+| --- | --- | --- | --- | --- |
+| `file` | string | yes | — | 1–1024 chars. Storage key of the already-uploaded file; the worker resolves it. |
+| `title` | string | yes | — | Trimmed, 1–200 chars. |
+| `module` | `'contact' \| 'datastore'` | no | `'contact'` | |
+| `config` | `ImportConfig` | no | `{}` | Defaults to an empty mapping and `duplicateStrategy: 'skip'`. |
+| `extra` | object | no | `{}` | Carried through untouched. |
+
+```ts
+const run = await crm.imports.create({
+  title: 'March contacts',
+  file: 'uploads/2026-03/contacts.csv',
+  config: {
+    mapping: { Email: 'email', 'First name': 'name.first_name', City: 'city' },
+    duplicateStrategy: 'update',
+    delimiter: ';',          // unknown keys survive the round trip
+  },
+});
+
+run.status;     // 'pending'
+run.statistics; // { total: 0, success: 0, failed: 0, new: 0, duplicate: 0 }
+```
+
+`duplicateStrategy` decides what a row matching an existing contact does:
+`'skip'` leaves the contact alone, `'update'` writes the row's values over it.
+
+---
+
+## delete
+
+```ts
+crm.imports.delete(id: string): Promise<void>
+```
+
+`DELETE /v1/audience/imports/:id` · `contacts:write` · **204**, no body.
+
+Removes the history row. **Contacts the import already created are not touched** —
+this deletes the receipt, not the work.

package/docs/audience/segments.md

@@ -0,0 +1,120 @@
+# Segments
+
+`crm.segments` — `/v1/audience/segments`
+
+A saved [contact filter](../contact-filter.md) under a name.
+
+Nothing is materialised: a segment holds no contact ids. It covers whatever its
+conditions match at the moment it is next run — by
+`crm.contacts.list({ segment })`, by an export's `config.segment`, or by a
+campaign. Two runs a day apart can return different people, by design.
+
+| Action | Route | Scope |
+| --- | --- | --- |
+| [`list`](#list) | `GET /v1/audience/segments` | `segments:read` |
+| [`get`](#get) | `GET /v1/audience/segments/:id` | `segments:read` |
+| [`create`](#create) | `POST /v1/audience/segments` | `segments:write` |
+| [`update`](#update) | `PATCH /v1/audience/segments/:id` | `segments:write` |
+| [`delete`](#delete) | `DELETE /v1/audience/segments/:id` | `segments:write` |
+
+## The segment object
+
+```ts
+interface Segment {
+  id: string;
+  name: string;
+  description?: string;
+  filter: ContactFilter;
+  createdAt: string;
+  updatedAt: string;
+}
+```
+
+---
+
+## list
+
+```ts
+crm.segments.list(query?: Partial<ListSegmentsQuery>): Promise<Paginated<Segment>>
+```
+
+`GET /v1/audience/segments` · `segments: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 description**. |
+
+---
+
+## get
+
+```ts
+crm.segments.get(id: string): Promise<Segment>
+```
+
+`GET /v1/audience/segments/:id` · `segments:read` · **200**
+
+---
+
+## create
+
+```ts
+crm.segments.create(input: CreateSegmentInput): Promise<Segment>
+```
+
+`POST /v1/audience/segments` · `segments:write` · **201**
+
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `name` | string | yes | Trimmed, 1–120 chars. Addressable by name as well as by id wherever a segment is referenced. |
+| `description` | string | no | Trimmed, up to 500 chars. |
+| `filter` | `ContactFilter` | yes | Validated on write, not when first run — a segment that stores cannot fail later for a condition that never parsed. |
+
+```ts
+const segment = await crm.segments.create({
+  name: 'High budget, Pune',
+  description: 'Lead score over 70 in Pune',
+  filter: {
+    conditions: [
+      { operator: null, field_id: 'city', field_type: 'text', condition: 'equal to', value: 'Pune' },
+      { operator: 'and', field_id: 'lead_score', field_type: 'number', condition: 'greater than', value: 70 },
+    ],
+  },
+});
+
+// Replay it
+const contacts = await crm.contacts.list({ segment: segment.id });
+// …or by name
+const same = await crm.contacts.list({ segment: 'High budget, Pune' });
+```
+
+---
+
+## update
+
+```ts
+crm.segments.update(id: string, input: UpdateSegmentInput): Promise<Segment>
+```
+
+`PATCH /v1/audience/segments/:id` · `segments:write` · **200**
+
+Same fields as `create`, all optional. Sending `filter` **replaces** the whole
+condition list — there is no per-condition edit. Read the segment, change the
+array, send it back.
+
+---
+
+## delete
+
+```ts
+crm.segments.delete(id: string): Promise<void>
+```
+
+`DELETE /v1/audience/segments/:id` · `segments:write` · **204**, no body.
+
+Contacts are untouched: a segment never owned them. Anything still referencing
+the segment by id or name — a scheduled export, a campaign — will start failing
+with `404`, since listing everyone because the segment went missing would be the
+wrong answer.