ab-ecosystem-cpass 1.0.9 → 1.0.10

package/README.md

@@ -159,6 +159,44 @@ try {
 Common codes: `422` for a body or query that fails validation (`details` lists
 the paths), `404 not_found`, `409 conflict` for a name or slug already taken.
 
+### Plan limits
+
+Every call needs an active subscription, and the metered resources are capped at
+what the plan includes. Both refusals are `402`, told apart by `code`:
+
+| Code | When | `details` |
+| --- | --- | --- |
+| `subscription_required` | The account has no subscription, or it has lapsed. Any call. | — |
+| `not_included` | The plan includes none of that resource. | `{ resource }` |
+| `quota_exceeded` | The plan's allowance is used up. | `{ resource, limit, used }` |
+
+What counts, and against which inclusion:
+
+| `resource` | Counted as | Inclusion |
+| --- | --- | --- |
+| `contact` | one contact | `contact_18472` — **1 unit = 1000 contacts** |
+| `canned_reply` | one reply | `canned_reply_14172` |
+| `scheduled_series` | one series, whatever its length — a one-off `schedule` is free | `series_91922` |
+| `data_store` | one registered store | `data_store_52360` |
+| `campaign` | one campaign | `campaign_73018` |
+| `super_field` | one custom field | `super_field_29689` |
+| `whatsapp_channel` | one live WhatsApp channel | `whatsapp_channels_28335` |
+
+Counts are of what exists now, so deleting a row gives the allowance back.
+`limit` and `used` are returned on `quota_exceeded` so a panel can say how far
+over the account is without a second call.
+
+```ts
+try {
+  await crm.campaigns.create(input);
+} catch (err) {
+  if (err instanceof CrmApiError && err.status === 402) {
+    // err.code: 'subscription_required' | 'not_included' | 'quota_exceeded'
+    console.error(err.message, err.details);
+  }
+}
+```
+
 ## Modules
 
 One page per resource, every action with its payload, query and response. The

package/dist/resources/data-stores.d.ts

@@ -1,9 +1,10 @@
-import type { BulkDeleteDataStoreRecordsInput, BulkUpdateDataStoreRecordsInput, CreateDataStoreCollectionInput, CreateDataStoreInput, DataStore, DataStoreCollection, DataStoreDeleteResult, DataStoreRecord, DataStoreTestResult, DataStoreUpdateResult, DataStoreWriteResult, InsertDataStoreRecordsInput, ListDataStoreRecordsQuery, ListQuery, Paginated, SearchDataStoreRecordsInput, UpdateDataStoreCollectionInput, UpdateDataStoreInput, UpdateDataStoreRecordInput } from '../types';
+import type { BulkDeleteDataStoreRecordsInput, CloudDataStoreRegion, BulkUpdateDataStoreRecordsInput, CreateDataStoreCollectionInput, CreateDataStoreInput, DataStore, DataStoreCollection, DataStoreDeleteResult, DataStoreRecord, DataStoreTestResult, DataStoreUpdateResult, DataStoreWriteResult, InsertDataStoreRecordsInput, ListDataStoreRecordsQuery, ListQuery, Paginated, SearchDataStoreRecordsInput, UpdateDataStoreCollectionInput, UpdateDataStoreInput, UpdateDataStoreRecordInput } from '../types';
 import type { HttpClient } from '../http';
 /**
- * Data stores: a MongoDB **you** own, registered with the platform.
+ * Data stores: a MongoDB you own, or one the platform runs for you.
  *
  * ```ts
+ * // your own cluster, registered with a credential
  * const store = await crm.dataStores.create({
  *   title: 'Orders DB',
  *   credentials: {
@@ -15,6 +16,9 @@ import type { HttpClient } from '../http';
  *   },
  * });
  *
+ * // or one of the platform's -- no credential, no cluster to run
+ * const hosted = await crm.dataStores.create({ title: 'Leads', type: 'cloud' });
+ *
  * const orders = await crm.dataStoreCollections.create(store.id, {
  *   title: 'Orders',
  *   fields: [
@@ -29,12 +33,30 @@ import type { HttpClient } from '../http';
  * });
  * ```
  *
+ * ## Which kind to pick
+ *
+ * A **cloud** store (`type: 'cloud'`) is a database the platform provisions on
+ * one of its clusters, in a location you choose from `regions()` -- Germany for
+ * now. There is no credential to manage, nothing to expose to the internet, and
+ * no IP access list to maintain. Use it for data that does not already live
+ * somewhere.
+ *
+ * A **self** store is your own cluster, and the default. Use it when the data is
+ * already there, or has to stay there.
+ *
+ * The difference that matters beyond setup is **who the system of record is**,
+ * and it shows up on delete -- see below.
+ *
  * ## What the platform holds, and what it does not
  *
- * It holds the credential -- encrypted -- and the schemas you declare. It holds
- * **none of your data**: records are read from and written to your cluster on
- * every call, so nothing here is a copy that can go stale, and nothing here
- * survives you revoking the credential.
+ * For a `self` store it holds the credential -- encrypted -- and the schemas you
+ * declare. It holds **none of your data**: records are read from and written to
+ * your cluster on every call, so nothing here is a copy that can go stale, and
+ * nothing here survives you revoking the credential.
+ *
+ * For a `cloud` store it holds the database itself. Nothing about that cluster
+ * is returned -- no host, no user, no connection string -- because there is no
+ * second way in: the API is the only door to those records.
  *
  * Which also means every record call costs a round trip to your database. The
  * platform keeps the connection open between calls, so that is one query's
@@ -42,14 +64,17 @@ import type { HttpClient } from '../http';
  * single inserts is a thousand round trips: send them as one `insert` with
  * `records` instead.
  *
- * ## Deleting never deletes your data
+ * ## Deleting a `self` store never deletes your data. Deleting a `cloud` store does
+ *
+ * On a **self** store, `remove()` forgets the credential and the schemas, and
+ * `remove()` on a collection forgets the declaration. **Neither touches your
+ * database** -- the collections and every document in them are exactly as they
+ * were, and re-registering the same credential with the same collection name
+ * reads it all straight back.
  *
- * `remove()` on a store forgets the credential and the schemas. `remove()` on a
- * collection forgets the declaration. **Neither touches your database** -- the
- * collections and every document in them are exactly as they were, and
- * re-registering the same credential with the same collection name reads it all
- * straight back. Deleting *records* is the only thing here that deletes
- * anything of yours.
+ * On a **cloud** store, `remove()` **destroys the database**. Every record in it
+ * is gone, there is no undo, and re-creating the store gets a fresh empty one.
+ * Ask before you call it.
  *
  * ## The host must be reachable from the internet
  *
@@ -62,6 +87,21 @@ import type { HttpClient } from '../http';
 export declare class DataStores {
     private readonly http;
     constructor(http: HttpClient);
+    /**
+     * `GET /v1/datastores/cloud-regions` -- `{ data: [{ code, location }] }`.
+     *
+     * The clusters a cloud store can be provisioned on. Read it to render the
+     * location choice rather than hardcoding one: locations are added over time,
+     * and the `code` is what a create takes.
+     *
+     * An **empty list** means this deployment provisions none -- an on-premise
+     * install, typically -- and a `type: 'cloud'` create would be refused.
+     *
+     * Scope: `datastores:read`.
+     */
+    regions(): Promise<{
+        data: CloudDataStoreRegion[];
+    }>;
     /**
      * `POST /v1/datastores` -- 201 with the store.
      *
@@ -70,7 +110,25 @@ export declare class DataStores {
      * | Field | Type | Required | Notes |
      * | --- | --- | --- | --- |
      * | `title` | string | yes | What you call it. 1-120 characters. |
-     * | `credentials` | object | yes | Either form below. |
+     * | `type` | `'self' \| 'cloud'` | no | Default `self`: your own database. |
+     * | `credentials` | object | for `self` | Either form below. Refused for `cloud`. |
+     * | `code` | string | no | `cloud` only: a cluster from `regions()`. Defaults to the platform's. |
+     *
+     * ### A cloud store
+     *
+     * ```ts
+     * await crm.dataStores.create({ title: 'Leads', type: 'cloud' });
+     * ```
+     *
+     * That is the whole payload: the platform provisions a database of its own,
+     * in the default location, and the response carries the `code` and `location`
+     * it ended up in. Nothing below about credentials, hosts or IP access lists
+     * applies -- and neither does the 502 pair, because there is no cluster of
+     * yours to be unreachable.
+     *
+     * | Status | Code | Meaning |
+     * | --- | --- | --- |
+     * | 422 | `validation_failed` | Credentials sent with `type: 'cloud'`, or a `code` that is not on offer -- including when this deployment offers none. |
      *
      * **`credentials.type: 'field'`**
      *
@@ -128,7 +186,13 @@ export declare class DataStores {
      * | Field | Type | Notes |
      * | --- | --- | --- |
      * | `title` | string | |
-     * | `credentials` | object | Replaced whole, and tested before it is stored. |
+     * | `credentials` | object | Replaced whole, and tested before it is stored. `self` stores only. |
+     *
+     * `type` and `code` are not editable: they say where the records are, not how
+     * the store is configured. Sending `credentials` for a **cloud** store is a
+     * `422` -- there is nothing to replace, and re-pointing it would leave its
+     * records in a database nothing addresses. Register your own database as a
+     * second store instead.
      *
      * A partial credential is not accepted: send all four fields, or the whole
      * URI. New credentials go through the same checks as `create`, and the old
@@ -141,10 +205,19 @@ export declare class DataStores {
     /**
      * `DELETE /v1/datastores/:store` -- 204.
      *
-     * Forgets the credential and every schema declared on it. **Your database is
-     * not touched**: the collections and all their documents remain, and
-     * registering the same credential again with the same collection names reads
-     * them straight back.
+     * **A `self` store:** forgets the credential and every schema declared on it.
+     * Your database is not touched -- the collections and all their documents
+     * remain, and registering the same credential again with the same collection
+     * names reads them straight back.
+     *
+     * **A `cloud` store:** drops every collection in its database, which destroys
+     * the database with them. Every record is gone, there is no undo, and a new
+     * store of the same name is a new empty database. Confirm with the user before
+     * calling this on one.
+     *
+     * | Status | Code | Meaning |
+     * | --- | --- | --- |
+     * | 502 | `datastore_purge_failed` | A collection could not be deleted, named in `details`. Nothing was removed -- the store is intact and the call can be retried. |
      *
      * Scope: `datastores:write`.
      */

package/dist/resources/data-stores.js

@@ -8,9 +8,10 @@ const collectionsPath = (store) => `${storePath(store)}/collections`;
 const collectionPath = (store, collection) => `${collectionsPath(store)}/${(0, paths_1.seg)(collection)}`;
 const recordsPath = (store, collection) => `${collectionPath(store, collection)}/records`;
 /**
- * Data stores: a MongoDB **you** own, registered with the platform.
+ * Data stores: a MongoDB you own, or one the platform runs for you.
  *
  * ```ts
+ * // your own cluster, registered with a credential
  * const store = await crm.dataStores.create({
  *   title: 'Orders DB',
  *   credentials: {
@@ -22,6 +23,9 @@ const recordsPath = (store, collection) => `${collectionPath(store, collection)}
  *   },
  * });
  *
+ * // or one of the platform's -- no credential, no cluster to run
+ * const hosted = await crm.dataStores.create({ title: 'Leads', type: 'cloud' });
+ *
  * const orders = await crm.dataStoreCollections.create(store.id, {
  *   title: 'Orders',
  *   fields: [
@@ -36,12 +40,30 @@ const recordsPath = (store, collection) => `${collectionPath(store, collection)}
  * });
  * ```
  *
+ * ## Which kind to pick
+ *
+ * A **cloud** store (`type: 'cloud'`) is a database the platform provisions on
+ * one of its clusters, in a location you choose from `regions()` -- Germany for
+ * now. There is no credential to manage, nothing to expose to the internet, and
+ * no IP access list to maintain. Use it for data that does not already live
+ * somewhere.
+ *
+ * A **self** store is your own cluster, and the default. Use it when the data is
+ * already there, or has to stay there.
+ *
+ * The difference that matters beyond setup is **who the system of record is**,
+ * and it shows up on delete -- see below.
+ *
  * ## What the platform holds, and what it does not
  *
- * It holds the credential -- encrypted -- and the schemas you declare. It holds
- * **none of your data**: records are read from and written to your cluster on
- * every call, so nothing here is a copy that can go stale, and nothing here
- * survives you revoking the credential.
+ * For a `self` store it holds the credential -- encrypted -- and the schemas you
+ * declare. It holds **none of your data**: records are read from and written to
+ * your cluster on every call, so nothing here is a copy that can go stale, and
+ * nothing here survives you revoking the credential.
+ *
+ * For a `cloud` store it holds the database itself. Nothing about that cluster
+ * is returned -- no host, no user, no connection string -- because there is no
+ * second way in: the API is the only door to those records.
  *
  * Which also means every record call costs a round trip to your database. The
  * platform keeps the connection open between calls, so that is one query's
@@ -49,14 +71,17 @@ const recordsPath = (store, collection) => `${collectionPath(store, collection)}
  * single inserts is a thousand round trips: send them as one `insert` with
  * `records` instead.
  *
- * ## Deleting never deletes your data
+ * ## Deleting a `self` store never deletes your data. Deleting a `cloud` store does
+ *
+ * On a **self** store, `remove()` forgets the credential and the schemas, and
+ * `remove()` on a collection forgets the declaration. **Neither touches your
+ * database** -- the collections and every document in them are exactly as they
+ * were, and re-registering the same credential with the same collection name
+ * reads it all straight back.
  *
- * `remove()` on a store forgets the credential and the schemas. `remove()` on a
- * collection forgets the declaration. **Neither touches your database** -- the
- * collections and every document in them are exactly as they were, and
- * re-registering the same credential with the same collection name reads it all
- * straight back. Deleting *records* is the only thing here that deletes
- * anything of yours.
+ * On a **cloud** store, `remove()` **destroys the database**. Every record in it
+ * is gone, there is no undo, and re-creating the store gets a fresh empty one.
+ * Ask before you call it.
  *
  * ## The host must be reachable from the internet
  *
@@ -71,6 +96,21 @@ class DataStores {
     constructor(http) {
         this.http = http;
     }
+    /**
+     * `GET /v1/datastores/cloud-regions` -- `{ data: [{ code, location }] }`.
+     *
+     * The clusters a cloud store can be provisioned on. Read it to render the
+     * location choice rather than hardcoding one: locations are added over time,
+     * and the `code` is what a create takes.
+     *
+     * An **empty list** means this deployment provisions none -- an on-premise
+     * install, typically -- and a `type: 'cloud'` create would be refused.
+     *
+     * Scope: `datastores:read`.
+     */
+    regions() {
+        return this.http.request('GET', `${BASE}/cloud-regions`);
+    }
     /**
      * `POST /v1/datastores` -- 201 with the store.
      *
@@ -79,7 +119,25 @@ class DataStores {
      * | Field | Type | Required | Notes |
      * | --- | --- | --- | --- |
      * | `title` | string | yes | What you call it. 1-120 characters. |
-     * | `credentials` | object | yes | Either form below. |
+     * | `type` | `'self' \| 'cloud'` | no | Default `self`: your own database. |
+     * | `credentials` | object | for `self` | Either form below. Refused for `cloud`. |
+     * | `code` | string | no | `cloud` only: a cluster from `regions()`. Defaults to the platform's. |
+     *
+     * ### A cloud store
+     *
+     * ```ts
+     * await crm.dataStores.create({ title: 'Leads', type: 'cloud' });
+     * ```
+     *
+     * That is the whole payload: the platform provisions a database of its own,
+     * in the default location, and the response carries the `code` and `location`
+     * it ended up in. Nothing below about credentials, hosts or IP access lists
+     * applies -- and neither does the 502 pair, because there is no cluster of
+     * yours to be unreachable.
+     *
+     * | Status | Code | Meaning |
+     * | --- | --- | --- |
+     * | 422 | `validation_failed` | Credentials sent with `type: 'cloud'`, or a `code` that is not on offer -- including when this deployment offers none. |
      *
      * **`credentials.type: 'field'`**
      *
@@ -143,7 +201,13 @@ class DataStores {
      * | Field | Type | Notes |
      * | --- | --- | --- |
      * | `title` | string | |
-     * | `credentials` | object | Replaced whole, and tested before it is stored. |
+     * | `credentials` | object | Replaced whole, and tested before it is stored. `self` stores only. |
+     *
+     * `type` and `code` are not editable: they say where the records are, not how
+     * the store is configured. Sending `credentials` for a **cloud** store is a
+     * `422` -- there is nothing to replace, and re-pointing it would leave its
+     * records in a database nothing addresses. Register your own database as a
+     * second store instead.
      *
      * A partial credential is not accepted: send all four fields, or the whole
      * URI. New credentials go through the same checks as `create`, and the old
@@ -158,10 +222,19 @@ class DataStores {
     /**
      * `DELETE /v1/datastores/:store` -- 204.
      *
-     * Forgets the credential and every schema declared on it. **Your database is
-     * not touched**: the collections and all their documents remain, and
-     * registering the same credential again with the same collection names reads
-     * them straight back.
+     * **A `self` store:** forgets the credential and every schema declared on it.
+     * Your database is not touched -- the collections and all their documents
+     * remain, and registering the same credential again with the same collection
+     * names reads them straight back.
+     *
+     * **A `cloud` store:** drops every collection in its database, which destroys
+     * the database with them. Every record is gone, there is no undo, and a new
+     * store of the same name is a new empty database. Confirm with the user before
+     * calling this on one.
+     *
+     * | Status | Code | Meaning |
+     * | --- | --- | --- |
+     * | 502 | `datastore_purge_failed` | A collection could not be deleted, named in `details`. Nothing was removed -- the store is intact and the call can be retried. |
      *
      * Scope: `datastores:write`.
      */

package/dist/resources/data-stores.js.map

@@ -1 +1 @@
-{"version":3,"file":"data-stores.js","sourceRoot":"","sources":["../../src/resources/data-stores.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"data-stores.js","sourceRoot":"","sources":["../../src/resources/data-stores.ts"],"names":[],"mappings":"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"}

package/dist/types/datastore.d.ts

@@ -1,10 +1,25 @@
 /**
  * Data Store: a customer's own MongoDB, registered with the platform.
  *
+ * A store is one of two things, and `type` says which:
+ *
+ * - **`self`** -- a database **you** own, registered with a credential. The
+ *   platform holds that credential and nothing else: no copy, no mirror, and
+ *   deleting the store never touches your data.
+ * - **`cloud`** -- a database the **platform** provisions for you, on one of its
+ *   clusters, in a location you pick. No credential to manage, nothing to open
+ *   to the internet -- and the platform is then the system of record, so
+ *   deleting the store deletes the records with it.
+ *
+ * Everything else is identical: the same collections, the same records, the same
+ * calls. Pick `cloud` to store data you do not already have somewhere, and
+ * `self` to work with a database you do.
+ *
  * Three nested things:
  *
- * 1. **A data store** -- a connection to a database *you* own. The platform
- *    holds the credential and nothing else: no copy of the data, no mirror.
+ * 1. **A data store** -- the database, yours or ours. For a `self` store the
+ *    platform holds the credential and nothing else: no copy of the data, no
+ *    mirror.
  * 2. **A collection** -- a schema you declare, naming a collection inside that
  *    database and the fields in it.
  * 3. **Records** -- the documents. They live in your database, and every record
@@ -16,6 +31,21 @@
  * guarantee -- a document may carry fields the schema never mentioned, or lack
  * ones it does.
  */
+/** Whose database the records are in. */
+export type DataStoreType = 'self' | 'cloud';
+/**
+ * One cluster the platform can provision a cloud store on.
+ *
+ * `code` identifies the cluster and is what you send on a create; `location` is
+ * the country it is in, which is the half worth showing a user. New locations
+ * appear in this list rather than in a release note -- read it, do not hardcode
+ * it -- and an existing store never moves when one is added, which is why its
+ * `code` is returned on the store itself.
+ */
+export interface CloudDataStoreRegion {
+    code: string;
+    location: string;
+}
 /** The five storage types a field can declare. */
 export type DataStoreFieldType = 'String' | 'Number' | 'Boolean' | 'Date' | 'Array';
 /**
@@ -55,9 +85,32 @@ export type DataStoreCredentials = {
      */
     uri: string;
 };
+/**
+ * Register your own database, or ask for one of the platform's.
+ *
+ * ```ts
+ * // yours
+ * await crm.dataStores.create({ title: 'Orders DB', credentials: { … } });
+ *
+ * // theirs, in Germany
+ * await crm.dataStores.create({ title: 'Leads', type: 'cloud' });
+ * ```
+ *
+ * `type` defaults to `self`, so existing code is unaffected. The two halves do
+ * not mix: a `self` store needs `credentials` and takes no `code`, a `cloud`
+ * store takes a `code` and no credentials, and anything else is a `422`.
+ */
 export interface CreateDataStoreInput {
     title: string;
-    credentials: DataStoreCredentials;
+    /** `self` -- your database. `cloud` -- one of the platform's. Default `self`. */
+    type?: DataStoreType;
+    /** Required for `self`, and refused for `cloud`. */
+    credentials?: DataStoreCredentials;
+    /**
+     * `cloud` only: which cluster to put it on, from
+     * {@link DataStores.regions}. Omitted, the platform picks its default.
+     */
+    code?: string;
 }
 /**
  * Rename, re-point, or both.
@@ -81,12 +134,25 @@ export interface UpdateDataStoreInput {
 export interface DataStore {
     id: string;
     title: string;
-    credentialType: 'field' | 'string';
+    /** Whose database it is. Stores created before cloud stores existed are `self`. */
+    type: DataStoreType;
+    /** `cloud` only: the cluster it is on. Quote it in a support request. */
+    code?: string;
+    /** `cloud` only: where that cluster is -- `Germany`. */
+    location?: string;
+    /** How the credential was given. Absent on a `cloud` store, which has none. */
+    credentialType?: 'field' | 'string';
     engine: 'mongodb';
+    /** Your host. Empty on a `cloud` store: the platform's own is not disclosed. */
     host: string;
     database: string;
+    /** Your database user. Empty on a `cloud` store. */
     username: string;
-    /** The connection string with the password removed, for display. */
+    /**
+     * For display. The connection string with the password removed for a `self`
+     * store, and `cloud://<location>/<database>` for a cloud one -- a label, not
+     * something to connect with.
+     */
     summary: string;
     /** When the connection was last proven to work: a create, an update, or a test. */
     verifiedAt?: string;

package/dist/types/datastore.js

@@ -2,10 +2,25 @@
 /**
  * Data Store: a customer's own MongoDB, registered with the platform.
  *
+ * A store is one of two things, and `type` says which:
+ *
+ * - **`self`** -- a database **you** own, registered with a credential. The
+ *   platform holds that credential and nothing else: no copy, no mirror, and
+ *   deleting the store never touches your data.
+ * - **`cloud`** -- a database the **platform** provisions for you, on one of its
+ *   clusters, in a location you pick. No credential to manage, nothing to open
+ *   to the internet -- and the platform is then the system of record, so
+ *   deleting the store deletes the records with it.
+ *
+ * Everything else is identical: the same collections, the same records, the same
+ * calls. Pick `cloud` to store data you do not already have somewhere, and
+ * `self` to work with a database you do.
+ *
  * Three nested things:
  *
- * 1. **A data store** -- a connection to a database *you* own. The platform
- *    holds the credential and nothing else: no copy of the data, no mirror.
+ * 1. **A data store** -- the database, yours or ours. For a `self` store the
+ *    platform holds the credential and nothing else: no copy of the data, no
+ *    mirror.
  * 2. **A collection** -- a schema you declare, naming a collection inside that
  *    database and the fields in it.
  * 3. **Records** -- the documents. They live in your database, and every record

package/dist/types/datastore.js.map

@@ -1 +1 @@
-{"version":3,"file":"datastore.js","sourceRoot":"","sources":["../../src/types/datastore.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG"}
+{"version":3,"file":"datastore.js","sourceRoot":"","sources":["../../src/types/datastore.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG"}

package/docs/campaign/campaigns.md

@@ -425,6 +425,18 @@ const { data, nextCursor } = await crm.campaigns.list({ limit: 50, status: 'comp
 const campaign = await crm.campaigns.get(id);
 ```
 
+### What a campaign's `id` is
+
+The `id` on a campaign is its own identity and the only one this API accepts —
+the same value the campaign manager is handed as `broadcast.id` and stamps on
+every report row as `cid`. So it is what you pass to `get`, `trigger`, `report`,
+and what a re-target filter's `cid` must name.
+
+It is a 24-character ObjectId string, but it is not the document's `_id`: that
+is Mongo's key and never appears in a request or a response. The `nextCursor`
+from [`list`](#list) is a paging position rather than an id — pass it back as a
+cursor, never as a campaign id.
+
 ## `create`
 
 For an audience you have already expressed as `filters` — every contact,

package/docs/data-store.md

@@ -2,9 +2,18 @@
 
 `crm.dataStores`, `crm.dataStoreCollections`, `crm.dataStoreRecords` — `/v1/datastores`
 
-A MongoDB **you** own, registered with the platform. You give it a connection,
-declare the collections and fields you want, and read and write records through
-the API — from a chatbot flow, an automation, or your own code.
+A MongoDB — **yours**, registered with a credential, or **ours**, provisioned
+for you in a location you pick. Either way you declare the collections and
+fields you want and read and write records through the API: from a chatbot flow,
+an automation, or your own code.
+
+```ts
+// your own cluster
+await crm.dataStores.create({ title: 'Orders DB', credentials: { … } });
+
+// or one of ours, no credential to manage
+await crm.dataStores.create({ title: 'Leads', type: 'cloud' });
+```
 
 This runs as **its own service**, with its own database and its own deployment.
 Nothing else in the platform depends on it, and it depends on nothing else: a
@@ -22,12 +31,84 @@ connections it holds to customer clusters cannot crowd out anything but itself.
 Three things, nested:
 
 ```
-data store            a connection to a database you own
+data store            a database — yours by credential, or ours by request
 └── collection        a schema: one collection name, and its fields
-    └── records       the documents, in your database
+    └── records       the documents, in that database
 ```
 
-The platform holds **the credential and the schemas, and nothing else**. There
+## Two kinds of store
+
+`type` on a store says whose database the records are actually in, and it is the
+one decision here with consequences:
+
+| | `self` *(default)* | `cloud` |
+| --- | --- | --- |
+| The database | Yours | Ours, provisioned per store |
+| To create one | A credential, tested before anything is stored | Nothing. Optionally a `code` for the location |
+| Reachability | Your cluster must be reachable from the internet, and usually needs our egress in its IP access list | Nothing to open, nothing to allow |
+| System of record | You. Anything else with the credential writes the same documents | Us. The API is the only door |
+| `remove()` on the store | Forgets the credential. **Your data stays** | **Drops the database.** The records are gone |
+
+Pick `cloud` for data that does not already live somewhere — a form's
+submissions, a chatbot's answers, a lookup table someone maintains in the panel.
+Pick `self` when the data is already in your cluster, or has to stay there.
+
+Everything past this point — collections, records, filters, paging — is
+identical for both.
+
+### Where a cloud store lives
+
+```ts
+const { data: regions } = await crm.dataStores.regions();
+// [{ code: '6869Z798672Z296Z152Z286Z307', location: 'Germany' }]
+
+const store = await crm.dataStores.create({
+  title: 'Leads',
+  type: 'cloud',
+  code: regions[0].code,   // omit it and the platform picks its default
+});
+
+store.location; // 'Germany'
+store.code;     // the cluster it is on — quote it in a support request
+```
+
+Read `regions()` rather than hardcoding a code: locations are added over time,
+and an existing store **never moves** when one is added. That is why the code
+comes back on the store itself, and it is the answer to a data-residency
+question in writing.
+
+An empty `regions()` means this deployment provisions none — an on-premise
+install, typically — and a `type: 'cloud'` create is then a `422`.
+
+Nothing about our cluster is returned on a cloud store: `host` and `username`
+are empty, there is no `credentialType`, and `summary` is a label
+(`cloud://Germany/ds_…`) rather than a connection string. There is no second way
+into those records, by design.
+
+## What `remove()` deletes
+
+Worth stating before anything else, because the opposite assumption is the
+expensive one in both directions:
+
+| Call | What it removes |
+| --- | --- |
+| `dataStores.remove()` on a **`self`** store | The stored credential, and every schema on it. **Your database is untouched.** |
+| `dataStores.remove()` on a **`cloud`** store | The schemas, and **every collection in its database — which destroys the database, irreversibly.** |
+| `dataStoreCollections.remove()` | The schema. The collection and its documents remain, in either kind of store. |
+| `dataStoreRecords.remove()` / `bulkRemove()` | Documents, irreversibly. |
+
+For a `self` store: register the same credential again, declare the same
+collection name, and all of it reads straight back. For a `cloud` store there is
+nothing to re-register — the database was named after that store and a new one
+is empty — so confirm with the user before calling it.
+
+If a collection cannot be deleted, the call is a `502 datastore_purge_failed`
+naming it, and **nothing** has been removed: the store and its schemas are
+intact and the call can be retried once the cause is fixed.
+
+## What the platform holds
+
+For a `self` store, **the credential and the schemas, and nothing else**. There
 is no copy of your data here, no mirror and no sync: a record read is a live
 query against your cluster, and a record write lands in it before the response
 comes back.
@@ -43,19 +124,9 @@ Two consequences worth holding on to:
   TLS handshake each time — but a loop of a thousand single inserts is a
   thousand round trips. Send one `insert` with `records`.
 
-## Deleting never deletes your data
-
-Worth stating before anything else, because the opposite assumption is the
-expensive one:
-
-| Call | What it removes |
-| --- | --- |
-| `dataStores.remove()` | The stored credential, and every schema on it. **Your database is untouched.** |
-| `dataStoreCollections.remove()` | The schema. **Your collection and its documents remain.** |
-| `dataStoreRecords.remove()` / `bulkRemove()` | Documents, from your database, irreversibly. |
-
-Register the same credential again, declare the same collection name, and all of
-it reads straight back. Only the record calls delete anything of yours.
+For a `cloud` store the platform holds the database too, and the first
+consequence does not apply: nothing else can write those documents. The second
+still does — it is a different cluster, not a local one.
 
 ---
 
@@ -140,6 +211,15 @@ order to show which database it is looking at. Host, user and database come back
 in the clear because an edit form has to render them, and none of them opens a
 connection on its own.
 
+A cloud store takes no credentials at all:
+
+```ts
+await crm.dataStores.create({ title: 'Leads', type: 'cloud' });
+```
+
+Sending both is a `422`, as is a `code` on a `self` store: the two halves of the
+body do not mix.
+
 ### Re-pointing one
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ab-ecosystem-cpass",
-  "version": "1.0.9",
+  "version": "1.0.10",
   "description": "JavaScript/TypeScript SDK for the CPaaS CRM gateway: audience and channels",
   "license": "MIT",
   "main": "dist/index.js",