ab-ecosystem-cpass 1.0.5 → 1.0.6

package/dist/types/campaign.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Campaign shapes. Declared here rather than imported from `@crm/contracts` so
+ * the published package has no private dependencies; they are kept in step with
+ * the zod schemas in `packages/contracts/src/campaign/`.
+ */
+import type { IsoDate, JsonObject } from './common';
+import type { ContactFilterEntry } from './contact-filter';
+export type CampaignStatus = 'pending' | 'processing' | 'completed' | 'failed' | 'cancelled';
+/** What the campaign charges for. `payment` is the collect-a-payment flow. */
+export type CampaignType = 'general' | 'payment';
+export type CampaignTrigger = 'immediate' | 'schedule';
+export type CampaignRepeatUnit = 'minutes' | 'hours' | 'days' | 'weeks' | 'months';
+export interface CampaignRepeat {
+    every: number;
+    unit: CampaignRepeatUnit;
+    /** Inclusive: the last occurrence is the final one at or before this moment. */
+    until?: IsoDate;
+}
+/**
+ * A bulk recipient list held in an uploaded file.
+ *
+ * This is what `campaigns.createBulk()` produces, and it is the only audience
+ * mode whose contents are not in the campaign document: the numbers live in an
+ * encrypted file and the campaign holds a pointer to it.
+ */
+export interface CampaignNumbersFilter {
+    /**
+     * HTTPS URL of the encrypted receiver file. Must be a public host -- the
+     * service that sends the campaign fetches it.
+     */
+    numbers: string;
+    /**
+     * The secret the file was encrypted under, 32-128 hex characters.
+     *
+     * Named `hash` for historical reasons; it is a key, not a digest. Whatever
+     * reads the file derives the AES key from it. Treat it as a credential: anyone
+     * holding this and the URL can read the recipient list.
+     */
+    hash: string;
+}
+/** Re-target by what happened to a previous campaign's messages. */
+export interface CampaignRetargetStatusFilter {
+    type: 'status';
+    /** The campaign to re-target. */
+    cid: string;
+    /** Its numeric message id. A number, not a string. */
+    cmid: number;
+    status: 'all' | 'sent' | 'delivered' | 'read' | 'replied' | 'failed';
+    delivered?: boolean | null;
+    read?: boolean | null;
+    replied?: boolean | null;
+    /** Hours within which a reply counts. */
+    replied_in?: number | null;
+    reply_type?: string | null;
+    reply?: string[] | null;
+}
+/** Re-target an explicit set of previous recipients. */
+export interface CampaignRetargetSelectionFilter {
+    type: 'selection';
+    records: string[];
+}
+/**
+ * One entry in a campaign's `filters`.
+ *
+ * The audience is one field with four modes, and the mode is decided by the
+ * **shape of the array** rather than by a selector:
+ *
+ * | `filters` | Audience |
+ * |---|---|
+ * | `[]` | every contact in the account |
+ * | `ContactFilterEntry[]` | a segment, built from contact conditions |
+ * | `[{numbers, hash}]` | a bulk list from an uploaded file |
+ * | `[{type: 'status' \| 'selection', …}]` | re-target of an earlier campaign |
+ *
+ * The modes cannot be mixed, and the three non-segment modes take exactly one
+ * entry -- everything downstream reads `filters[0]` and nothing else. The server
+ * rejects a mixture rather than guessing.
+ */
+export type CampaignFilter = CampaignNumbersFilter | CampaignRetargetStatusFilter | CampaignRetargetSelectionFilter | ContactFilterEntry;
+/** Which of the four modes a `filters` array expresses. */
+export type CampaignAudienceKind = 'all' | 'segment' | 'numbers' | 'retarget';
+export interface CampaignMessage {
+    id?: string | number;
+    channel: {
+        id: string;
+        version?: string;
+        category?: string;
+    };
+    category?: string;
+    /** The provider payload. Shape is per channel type, so it is left open. */
+    message: JsonObject;
+    /** Save a reply to a contact field. */
+    replyStatus?: {
+        save: boolean;
+        fieldId: string;
+    };
+    polls?: string[];
+    /** Anything else the panel put here is carried through. */
+    [key: string]: unknown;
+}
+/** Who launched a campaign and from where. Stamped by the server; never sent. */
+export interface CampaignTriggerInfo {
+    userIp?: string;
+    userType?: string;
+    psuid?: string;
+    userRefId?: string;
+    [key: string]: unknown;
+}
+export interface Campaign {
+    id: string;
+    version: string;
+    crmVersion: string;
+    name: string;
+    /**
+     * The dispatch route, as the sending service understands it -- `general`,
+     * `bulk_campaign`, `retarget`, and others. Distinct from `campaignType`.
+     */
+    type: string;
+    campaignType: CampaignType;
+    trigger: CampaignTrigger;
+    triggerInfo: CampaignTriggerInfo;
+    channelType: string;
+    messagingPattern: string;
+    status: CampaignStatus;
+    filters: CampaignFilter[];
+    messages: CampaignMessage[];
+    showMessageInPanel: boolean;
+    isRepeating: boolean;
+    repeat?: CampaignRepeat;
+    parentBroadcastId?: string;
+    scheduleId?: string;
+    hidden: boolean;
+    scheduledAt?: IsoDate;
+    processedAt?: IsoDate;
+    completedAt?: IsoDate;
+    /**
+     * Recipients resolved at send time, not at creation.
+     *
+     * `0` until the campaign is processed. The audience is a stored query -- even a
+     * bulk list is a file the sender reads later -- so a scheduled campaign's final
+     * count can differ from what was shown when it was built.
+     */
+    receivers: number;
+    totalMessages: number;
+    error?: string;
+    metaInfo: JsonObject[];
+    createdAt: IsoDate;
+    updatedAt: IsoDate;
+}
+export interface CreateCampaignInput {
+    name: string;
+    /** Defaults to `general`. `createBulk()` sets `bulk_campaign` itself. */
+    type?: string;
+    campaignType?: CampaignType;
+    trigger?: CampaignTrigger;
+    channelType?: string;
+    messagingPattern?: string;
+    /** The audience. `[]` means every contact. See {@link CampaignFilter}. */
+    filters?: CampaignFilter[];
+    messages: CampaignMessage[];
+    showMessageInPanel?: boolean;
+    isRepeating?: boolean;
+    repeat?: CampaignRepeat;
+    parentBroadcastId?: string;
+    hidden?: boolean;
+    /** Required when `trigger` is `schedule`. */
+    scheduledAt?: IsoDate;
+}
+export type UpdateCampaignInput = Partial<CreateCampaignInput>;
+/**
+ * Declared as a type alias rather than an interface, and that is load-bearing:
+ * only an alias of an object literal gets TypeScript's implicit index signature,
+ * which is what lets it be passed as a request's query record.
+ */
+export type ListCampaignsQuery = {
+    limit: number;
+    cursor?: string;
+    status?: CampaignStatus;
+    campaignType?: CampaignType;
+    type?: string;
+    hidden?: boolean;
+};
+/** Delivery counts for one campaign. Every field is a running total. */
+export interface CampaignMetrics {
+    queued: number;
+    sent: number;
+    delivered: number;
+    failed: number;
+    opened: number;
+    clicked: number;
+    unsubscribed: number;
+}
+export interface CampaignReport {
+    id: string;
+    campaignId: string;
+    metrics: CampaignMetrics;
+    /** When the metrics were last rolled up, which may lag the campaign. */
+    generatedAt: IsoDate;
+    createdAt: IsoDate;
+    updatedAt: IsoDate;
+}
+/** A report export shares the job lifecycle used across the platform. */
+export type CampaignReportExportStatus = 'queued' | 'processing' | 'completed' | 'failed';
+export interface CampaignReportExport {
+    id: string;
+    campaignId: string;
+    format: 'csv' | 'xlsx';
+    status: CampaignReportExportStatus;
+    rowCount: number;
+    /** Present once `status` is `completed`. Expires; see `expiresAt`. */
+    fileUrl?: string;
+    expiresAt?: IsoDate;
+    errorMessage?: string;
+    createdAt: IsoDate;
+    updatedAt: IsoDate;
+}
+export interface CreateCampaignReportExportInput {
+    campaignId: string;
+    /** Defaults to `csv`. */
+    format?: 'csv' | 'xlsx';
+    /** Narrows the rows by the period they fall in. */
+    from?: IsoDate;
+    to?: IsoDate;
+}
+/** A type alias, for the same reason as {@link ListCampaignsQuery}. */
+export type GetCampaignReportQuery = {
+    from?: IsoDate;
+    to?: IsoDate;
+};

package/dist/types/campaign.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=campaign.js.map

package/dist/types/campaign.js.map

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

package/dist/types/index.d.ts

@@ -4,3 +4,4 @@ export * from './audience';
 export * from './channels';
 export * from './inbox';
 export * from './scheduled-message';
+export * from './campaign';

package/dist/types/index.js

@@ -21,4 +21,6 @@ __exportStar(require("./channels"), exports);
 __exportStar(require("./inbox"), exports);
 // After './inbox': a scheduled message's body is a `MessageContent`.
 __exportStar(require("./scheduled-message"), exports);
+// After './contact-filter': a campaign's audience may be a list of its entries.
+__exportStar(require("./campaign"), exports);
 //# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,mDAAiC;AACjC,6CAA2B;AAC3B,6CAA2B;AAC3B,0CAAwB;AACxB,qEAAqE;AACrE,sDAAoC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,mDAAiC;AACjC,6CAA2B;AAC3B,6CAA2B;AAC3B,0CAAwB;AACxB,qEAAqE;AACrE,sDAAoC;AACpC,gFAAgF;AAChF,6CAA2B"}

package/docs/audience/notifications.md

@@ -0,0 +1,263 @@
+# Push notifications
+
+`crm.notifications` — `/v1/audience/devices`
+
+Which browsers and apps a user wants notifications delivered to. A subscription
+is one device — one browser profile, one app installation — held against the
+acting user, and the only party who can see or revoke it is that user.
+
+| Action | Route | Scope |
+| --- | --- | --- |
+| [`subscribe`](#subscribe) | `POST /v1/audience/devices` | `devices:write` |
+| [`unsubscribe`](#unsubscribe) | `POST /v1/audience/devices/unregister` | `devices:write` |
+| [`devices`](#devices) | `GET /v1/audience/devices` | `devices:read` |
+
+## What the SDK does, and what you do
+
+A push subscription has two halves and only one of them is an API call.
+
+**In the browser**, which this SDK deliberately does not wrap:
+
+```js
+const permission = await Notification.requestPermission(); // 'granted' | 'denied' | 'default'
+const token = await getToken(messaging, { vapidKey });     // firebase/messaging
+```
+
+Wrapping those two would mean a hard dependency on `firebase/*` — in a package
+that also runs on Node — to pass arguments that come from your own Firebase
+project.
+
+**Here**, which is the part that is an API call:
+
+```ts
+if (permission === 'granted') {
+  await crm.notifications.subscribe({ token });
+}
+```
+
+## Where the subscription lives
+
+On the platform, against the acting user, **in this product** — not in the core
+platform. Core owns identity and the agency's Firebase credentials; messages
+arrive here, so the tokens and the sending live here too, and core is never on
+the delivery path.
+
+Nothing you send names a Firebase project. The platform resolves it from the
+client the call arrives on and stamps it onto the row, because a registration
+token is only sendable through the project that minted it and nothing in the
+token itself says which. That resolution is a cached read, so it costs nothing in
+steady state — but it is why `subscribe` is the one method here that can answer
+`503`.
+
+## The device object
+
+```ts
+interface Device {
+  id: string;
+  platform: 'web' | 'android' | 'ios';
+  label: string;          // what you sent as device_label; '' when you sent none
+  clientId: string | null; // the reseller frontend it registered from
+  lastSeenAt: string;     // ISO; last successful send, or last subscribe
+  createdAt: string;
+}
+```
+
+The **registration token is never returned**. It is a send credential: anything
+holding one can push to that browser through the agency's Firebase project. The
+list exists so a user can recognise and revoke their own devices, which needs the
+label and the last-seen time and nothing more.
+
+---
+
+## subscribe
+
+```ts
+crm.notifications.subscribe(input: SubscribeNotificationsInput): Promise<Device>
+```
+
+`POST /v1/audience/devices` · `devices:write` · **201**
+
+### Payload
+
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `token` | string | yes | The FCM registration token for this instance, from `getToken()`. 20–4096 characters — a sanity check, not a format; Google publishes no shape for these. Trimmed. |
+| `platform` | `'web' \| 'android' \| 'ios'` | defaulted | `'web'` when the SDK can see a DOM. Required otherwise — see below. |
+| `device_label` | string | no | Up to 200 characters; longer is trimmed, not refused. Defaults to something like `Chrome on Windows`, derived from the user agent. Cosmetic, never matched on. |
+| `tpc_id` | string | no | The reseller client (`tpc_…`) this frontend belongs to. Rarely needed. |
+
+What goes on the wire, with everything defaulted:
+
+```http
+POST /v1/audience/devices
+authorization: Bearer <ecosystem token>
+client-id: tpc_8Kd3mXp7qR2wL9zB
+content-type: application/json
+
+{
+  "token": "fNx8…:APA91bH…",
+  "platform": "web",
+  "device_label": "Chrome on Windows"
+}
+```
+
+```ts
+const device = await crm.notifications.subscribe({ token });
+// → { id: '…', platform: 'web', label: 'Chrome on Windows', clientId: 'tpc_…', … }
+```
+
+There is **no user field**, and that is deliberate: the acting user comes from
+the verified token the client was constructed with. A body that could name its
+own user would let any caller point someone else's notifications at their own
+browser.
+
+### Call it on every app load, not once
+
+It is an idempotent upsert keyed on the token, so re-sending one the platform
+already holds costs a single indexed update. That is the intended usage, because
+two things change underneath you:
+
+- FCM rotates registration tokens on its own schedule, and the old one stops
+  being delivered to without anyone being told.
+- A device unseen for **60 days** is pruned, and "seen" means a successful send
+  or a call to this method. Someone who receives no notifications for two months
+  would otherwise quietly fall off the list.
+
+Re-subscribing a token already on file against **another** user moves it rather
+than duplicating it. One browser has one person signed in, and the previous
+owner's notifications have to stop reaching it the moment someone else logs in
+there.
+
+### `platform` off-browser
+
+The SDK defaults it from `document`, not from `navigator` — which is the
+distinction that matters. React Native defines a `navigator` and no `document`,
+so a navigator-based guess would register every phone as a browser, and the send
+path would fill in the `webpush` block instead of `android`/`apns`: a
+notification FCM accepts and the device never shows. Outside a browser the SDK
+asks instead of guessing:
+
+```ts
+await crm.notifications.subscribe({ token, platform: 'android' });
+```
+
+### `tpc_id`
+
+Only ever a confirmation. The `clientId` the `CrmClient` already sends is
+verified by the gateway and wins; this field says which reseller frontend is
+registering, which decides whose Firebase project and which deep-link host apply.
+A value that contradicts the verified client is refused with `403` rather than
+ignored — the two disagreeing means either a frontend bug or an attempt to file a
+device under another tenant, and silently preferring one would hide the first and
+partially succeed at the second. The white-label frontend has no client and sends
+nothing.
+
+### Errors
+
+| Status | Code | Meaning |
+| --- | --- | --- |
+| 400 | `validation_failed` | Token missing or implausible, or `platform` could not be defaulted. Thrown by the SDK before a request is made. |
+| 403 | `forbidden` | `tpc_id` names a different client than the token was issued for. |
+| 503 | `push_not_configured` | The agency has no Firebase notification resource. Nothing the caller can fix; push is simply off for this account. |
+| 503 | `push_unavailable` | The platform could not read the configuration from core. Transient. |
+
+Both `503`s want the same handling as success: try again on the next app load,
+which the advice above means you are doing anyway.
+
+---
+
+## unsubscribe
+
+```ts
+crm.notifications.unsubscribe(token: string): Promise<void>
+```
+
+`POST /v1/audience/devices/unregister` · `devices:write` · **204**
+
+```ts
+await crm.notifications.unsubscribe(token);
+```
+
+### Payload
+
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `token` | string | yes | The same registration token. Trimmed. |
+
+`204` with no body **whether or not a row went** — you are asking for a
+guarantee about the future, and a token that is already gone provides it. So this
+is safe to call unconditionally on logout without first checking whether the
+device was ever subscribed.
+
+Scoped to the caller's own devices. A token identifies a browser rather than a
+person, so by the time one user logs out the row may already belong to whoever
+logged in after them; an unscoped delete would cut off the person now holding it.
+
+A `POST` with the token in the body rather than `DELETE /devices/:token`: a
+registration token is hundreds of characters and may contain `:` and `/`, and
+putting one in a path invites proxy length limits and writes a live send
+credential into every access log along the way.
+
+### Also delete it on the device
+
+This withdraws the platform's permission to send to that token. If the user is
+turning notifications **off** — rather than logging out — also drop the token in
+the browser, or the next `getToken()` hands back the same one and the
+subscription can come back by accident:
+
+```ts
+await crm.notifications.unsubscribe(token);
+await deleteToken(messaging); // firebase/messaging
+```
+
+---
+
+## devices
+
+```ts
+crm.notifications.devices(query?: Partial<ListDevicesQuery>): Promise<Paginated<Device>>
+```
+
+`GET /v1/audience/devices` · `devices:read` · **200**
+
+### Query
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `page` | number | `1` | 1-based. |
+| `rows` | number | `25` | 1–100. |
+
+Sorted by `lastSeenAt` descending. This is what a "notification settings" screen
+lists.
+
+```ts
+const { data } = await crm.notifications.devices();
+data.map((d) => `${d.label || 'This device'} · last seen ${d.lastSeenAt}`);
+```
+
+No `search`: the endpoint shares the common list query so the server would accept
+one, but the service does not apply it — a device list is one person's handful of
+rows. It is left out of the SDK type rather than accepted and silently dropped.
+
+Only ever the acting user's own devices. There is no account-wide view and no
+device id in the path: a device is one person's browser.
+
+Worth knowing: a notification is sent to the **20 most recently seen** devices
+of a user. A longer list is itself the answer to "why did my old laptop stop
+buzzing".
+
+### Telling whether *this* browser is subscribed
+
+You can't, from here — tokens are not returned, by design. Decide it locally
+instead. The browser knows its own `Notification.permission` and its own token,
+and because `subscribe` is an idempotent upsert, the cheap and correct answer to
+"am I still subscribed?" is to subscribe again:
+
+```ts
+if (Notification.permission === 'granted') {
+  await crm.notifications.subscribe({ token: await getToken(messaging, { vapidKey }) });
+}
+```
+
+That also repairs the two cases a stored flag gets wrong: a rotated token, and a
+row pruned for staleness.