ab-ecosystem-cpass 0.1.0 → 1.0.0

package/docs/contact-filter.md

@@ -0,0 +1,157 @@
+# Contact filter
+
+One condition language, four callers:
+
+| Where | Shape |
+| --- | --- |
+| `crm.contacts.list({ filter })` | `ContactFilter` — sent as JSON on the query string |
+| `crm.segments.create({ filter })` | `ContactFilter` — stored under a name |
+| `crm.crmTriggers.create({ filters })` | `ContactFilterEntry[]` — flat, not wrapped |
+| `crm.exports.create({ config: { filter } })` | `ContactFilter` |
+
+A filter that works in one of these works in all of them, and means the same
+thing: a trigger's `filters` are checked by running the contact list query
+pinned to that one contact.
+
+## Shape
+
+```ts
+interface ContactFilter {
+  type?: string;                    // free-form tag for provenance, default 'sheet'
+  conditions?: ContactFilterEntry[]; // at most 50, default [] = match everyone
+}
+
+interface ContactFilterEntry {
+  id?: number;                      // your own row id, echoed back
+  operator?: 'and' | 'or' | null;   // null on the first condition
+  field_id: string;                 // a custom field slug, `tags`, or a SYSTEM_* field
+  field_type: ContactFilterFieldType;
+  condition: ContactFilterCondition;
+  value?: unknown;                  // omitted for conditions that take none
+  direction?: 'LAST' | 'TODAY' | 'NEXT' | '';
+  timeUnit?: 'minutes' | 'hours' | 'days' | 'weeks' | 'months' | 'years' | '';
+  offset?: number;                  // caller's midnight, as a ms shift from UTC midnight
+  props?: { period?: 'daily' | 'weekly' | 'monthly' | 'annually' };
+  requireInput?: boolean;           // UI hint, ignored by the server
+}
+```
+
+## How conditions combine
+
+`and` binds tighter than `or`. The list is split on every `or`, each run is
+`and`ed, and the runs are `or`ed together — so this:
+
+```
+A  and B  or C  and D
+```
+
+means `(A and B) or (C and D)`. There is no nesting and no parentheses; when you
+need them, save the inner group as a segment and narrow it with `filter`.
+
+The first condition's `operator` is `null`. An empty `conditions` array matches
+every contact.
+
+## Fields
+
+| `field_id` | What it addresses |
+| --- | --- |
+| a custom field slug | `contact.custom_field_hash.<slug>` |
+| `tags` | The contact's tags. `value` is one tag id or an array of them; `equal to` is "has any of these", `not equal to` is "has none of them". |
+| `SYSTEM_LAST_SEEN` | `contact.last_seen`, stored as unix **seconds**. |
+| `SYSTEM_CREATED_ON` | `contact.createdAt`, a date. |
+| `SYSTEM_IDENTIFIER` | The identifier of any channel identity — a phone number, handle or address. |
+| `SYSTEM_PROFILE_NAME` | The name on any channel identity. |
+
+`SYSTEM_IDENTIFIER` and `SYSTEM_PROFILE_NAME` live in a separate collection, so
+they resolve through a lookup. Negated conditions on them read the way you would
+say them out loud: `SYSTEM_IDENTIFIER not equal to X` means *no* identity holds
+X — not *some* identity holds something else.
+
+## Conditions by field type
+
+Four conditions apply to every type, whatever its shape:
+
+`is null` · `is not null` · `exist` · `does not exist`
+
+Beyond those:
+
+| `field_type` | Conditions |
+| --- | --- |
+| `string` `text` `url` `email` `phone` `country` `language` `timezone` `dial_code` `dropdown` | `equal to` `not equal to` `start with` `end with` `contains` `does not contains` `is empty` `is not empty` |
+| `number` | `equal to` `not equal to` `greater than` `greater than or equal to` `less than` `less than or equal to` |
+| `date` `timestamp` | `is` `after` `before` `between` `within` |
+| `periodic_time` | `is` `after` `before` `between` `within` — needs `props.period` |
+
+Anything else is rejected with `422`, naming the field and the condition that
+had no meaning for it.
+
+## Values
+
+- **Text and number conditions** take a scalar in `value`.
+- **`is` / `after` / `before` / `between`** on a date take a **JSON array
+  string**: `between` reads two entries, the rest read the first.
+  `value: '["2026-03-01","2026-03-31"]'`.
+- **`within`** reads `direction`, `timeUnit` and a number in `value`: `LAST`
+  counts that many units backwards from the caller's midnight, `NEXT` forwards.
+  `direction: 'TODAY'` is the exception — it means the caller's current day and
+  needs neither `timeUnit` nor `value`. A missing `timeUnit` or an unknown
+  `direction` is a `422`.
+- **`is empty` / `is not empty` / `is null` / `exist` / …** take no `value`.
+
+### `offset`
+
+Relative windows are anchored to the caller's midnight, not UTC's. `offset` is
+the shift in milliseconds from UTC midnight to yours: IST (+5:30) sends
+`-19800000`. Leave it at `0` to work in UTC.
+
+Months and years shift calendar-aware; hours, days and weeks are fixed-width.
+
+## Examples
+
+Everyone in Pune, tagged VIP:
+
+```ts
+await crm.contacts.list({
+  filter: {
+    conditions: [
+      { operator: null, field_id: 'city', field_type: 'text', condition: 'equal to', value: 'Pune' },
+      { operator: 'and', field_id: 'tags', field_type: 'string', condition: 'equal to', value: [vipTagId] },
+    ],
+  },
+});
+```
+
+Seen in the last 7 days, or created today:
+
+```ts
+await crm.contacts.list({
+  filter: {
+    conditions: [
+      {
+        operator: null,
+        field_id: 'SYSTEM_LAST_SEEN',
+        field_type: 'timestamp',
+        condition: 'within',
+        direction: 'LAST',
+        timeUnit: 'days',
+        value: 7,
+        offset: -19800000,
+      },
+      {
+        operator: 'or',
+        field_id: 'SYSTEM_CREATED_ON',
+        field_type: 'date',
+        condition: 'within',
+        direction: 'TODAY',
+        offset: -19800000,
+      },
+    ],
+  },
+});
+```
+
+No email on file:
+
+```ts
+{ operator: null, field_id: 'email', field_type: 'email', condition: 'is empty' }
+```

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "ab-ecosystem-cpass",
-  "version": "0.1.0",
-  "description": "JavaScript/TypeScript SDK for the CPaaS CRM gateway",
+  "version": "1.0.0",
+  "description": "JavaScript/TypeScript SDK for the CPaaS CRM gateway: audience and channels",
   "license": "MIT",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist",
+    "docs",
     "README.md"
   ],
   "sideEffects": false,
@@ -17,7 +18,10 @@
     "crm",
     "cpaas",
     "sdk",
-    "channels"
+    "channels",
+    "contacts",
+    "whatsapp",
+    "audience"
   ],
   "publishConfig": {
     "access": "public"

package/dist/resources/channels.d.ts

@@ -1,10 +0,0 @@
-import type { Channel, ChannelResponse, Page, PageQuery } from '../types';
-import type { HttpClient } from '../http';
-export declare class Channels {
-    private readonly http;
-    constructor(http: HttpClient);
-    /** `GET /v1/channels` */
-    list(query?: Partial<PageQuery>): Promise<Page<Channel>>;
-    /** `GET /v1/channels/:id` */
-    get(id: string): Promise<ChannelResponse>;
-}

package/dist/resources/channels.js

@@ -1,19 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Channels = void 0;
-class Channels {
-    http;
-    constructor(http) {
-        this.http = http;
-    }
-    /** `GET /v1/channels` */
-    list(query = {}) {
-        return this.http.request('GET', '/v1/channels', { query });
-    }
-    /** `GET /v1/channels/:id` */
-    get(id) {
-        return this.http.request('GET', `/v1/channels/${encodeURIComponent(id)}`);
-    }
-}
-exports.Channels = Channels;
-//# sourceMappingURL=channels.js.map

package/dist/resources/channels.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"channels.js","sourceRoot":"","sources":["../../src/resources/channels.ts"],"names":[],"mappings":";;;AAGA,MAAa,QAAQ;IACU;IAA7B,YAA6B,IAAgB;QAAhB,SAAI,GAAJ,IAAI,CAAY;IAAG,CAAC;IAEjD,yBAAyB;IACzB,IAAI,CAAC,QAA4B,EAAE;QACjC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAgB,KAAK,EAAE,cAAc,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IAC5E,CAAC;IAED,6BAA6B;IAC7B,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAkB,KAAK,EAAE,gBAAgB,kBAAkB,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAC7F,CAAC;CAsBF;AAjCD,4BAiCC"}

package/dist/types.d.ts

@@ -1,70 +0,0 @@
-/**
- * Response shapes returned by the gateway. Declared here rather than imported
- * from `@crm/contracts` so the published package has no private dependencies.
- */
-export interface Page<T> {
-    data: T[];
-    nextCursor: string | null;
-}
-export interface PageQuery {
-    limit: number;
-    cursor?: string;
-}
-export interface ChannelMeta {
-    category: string;
-    provider: string;
-    support_template: boolean;
-    show_template: boolean;
-    bypass_webhook_verification: boolean;
-}
-export interface ChannelCloud {
-    instagram_id: string;
-    is_instagram_business_login: boolean;
-    waba_id: string;
-    business: string;
-    phone_number_id: string;
-    is_on_biz_app: boolean;
-    version: string;
-    auto_read_receipt: number;
-    upgrade_eligibility: boolean;
-    wa_biz_registration: 'pending' | 'completed';
-}
-export interface ChannelWallet {
-    free_tier?: number;
-    free_usage?: number;
-    /** `'NULL'` when the wallet is not visible to the caller. */
-    balance: number | 'NULL';
-    visible?: boolean;
-}
-export interface Channel {
-    id: string;
-    active: boolean;
-    ecom?: {
-        store_status: boolean;
-        store?: string;
-    };
-    basic_details: {
-        name: string;
-        color_code: string;
-        channel_identity: string;
-    };
-    meta: ChannelMeta;
-    billing: {
-        status: boolean;
-        currency: string;
-        visible: boolean;
-    };
-    wallet: ChannelWallet;
-    campaign_tps: number;
-    upgraded_webhook_listener: boolean;
-    cloud: ChannelCloud;
-    api_only: boolean;
-    crm_only: boolean;
-    mm_lite_enabled: boolean;
-    access_token: string;
-    [key: string]: unknown;
-}
-/** `GET /v1/channels/:id` wraps its payload, and returns `{}` when nothing matches. */
-export interface ChannelResponse {
-    data: Channel | Record<string, never>;
-}

package/dist/types.js

@@ -1,7 +0,0 @@
-"use strict";
-/**
- * Response shapes returned by the gateway. Declared here rather than imported
- * from `@crm/contracts` so the published package has no private dependencies.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=types.js.map

package/dist/types.js.map

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