ab-ecosystem-cpass 1.0.0 → 1.0.6

package/dist/types/audience.d.ts

@@ -97,6 +97,12 @@ export interface Contact {
  */
 export interface CreateContactInput {
     name?: Partial<ContactName>;
+    /**
+     * Creates the contact's WhatsApp identity with it, and writes its id to
+     * `profile.whatsapp`. Any shape is accepted -- `+91 98765 43210` -- and stored
+     * as digits only, which is the form an inbound message carries. Create-only.
+     */
+    whatsapp?: string;
     order?: string;
     /** Contact tag ids. Default `[]`. */
     tags?: ObjectId[];
@@ -115,7 +121,11 @@ export interface CreateContactInput {
         blocked?: Partial<ContactBlocked>;
     };
 }
-export type UpdateContactInput = Partial<CreateContactInput>;
+/**
+ * `whatsapp` is absent: changing a channel identity is a write to the profile
+ * collection, which a contact patch cannot express.
+ */
+export type UpdateContactInput = Partial<Omit<CreateContactInput, 'whatsapp'>>;
 /**
  * `search` matches the first and last name, plus the name and identifier of
  * every channel identity. `segment` names a saved filter; `filter` carries
@@ -510,3 +520,85 @@ export interface WebhookEnvelope {
     createdAt: IsoDate;
     data: unknown;
 }
+/**
+ * Where a push notification can be delivered.
+ *
+ * It decides which half of the FCM payload the send path fills in -- `webpush`
+ * for a browser, `android`/`apns` for an app -- and it is the one thing about a
+ * device that cannot be inferred from its token. A registration token is an
+ * opaque string identifying a browser or app *instance*; nothing in it says what
+ * kind of thing that instance is.
+ */
+export type DevicePlatform = 'web' | 'android' | 'ios';
+/**
+ * A subscribed device, as it reads back.
+ *
+ * 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 -- and 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.
+ */
+export interface Device {
+    id: ObjectId;
+    platform: DevicePlatform;
+    /** Whatever `device_label` was sent on registration; `''` when none was. */
+    label: string;
+    /** The reseller frontend it registered from; `null` for the white-label one. */
+    clientId: string | null;
+    /**
+     * Last time a notification to this device succeeded, or it re-subscribed.
+     *
+     * The only signal that a device is still real: FCM does not revoke a token
+     * when an app is uninstalled or a browser's site data is cleared, it simply
+     * stops delivering to it. A device unseen for 60 days is pruned on that basis,
+     * which is another reason to call {@link Notifications.subscribe} on every app
+     * load rather than once.
+     */
+    lastSeenAt: IsoDate;
+    createdAt: IsoDate;
+}
+/**
+ * What `notifications.subscribe()` takes. Mirrors the wire body field for field.
+ *
+ * There is deliberately no user field. 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 browser.
+ */
+export interface SubscribeNotificationsInput {
+    /**
+     * The FCM registration token for this browser or app instance, from
+     * `getToken()`. 20..4096 characters -- a sanity check rather than a format,
+     * since Google publishes no shape for these.
+     */
+    token: string;
+    /**
+     * Defaults to `'web'` when the SDK can see a DOM, and is otherwise required:
+     * a React Native runtime has a `navigator` but no `document`, and guessing
+     * `'web'` there would send the wrong half of every payload.
+     */
+    platform?: DevicePlatform;
+    /**
+     * What the user would recognise this device as, for the device list -- up to
+     * 200 characters. Left out, the SDK derives something like `Chrome on Windows`
+     * from the user agent when it is running in a browser. Cosmetic, never matched
+     * on.
+     */
+    device_label?: string;
+    /**
+     * The reseller client this frontend belongs to (`tpc_…`), when there is one.
+     *
+     * Rarely needed: the client id the `CrmClient` already sends is verified and
+     * wins. Supplying a *different* one is refused with 403 rather than ignored.
+     * Omitted by the white-label frontend, which has no client.
+     */
+    tpc_id?: string;
+}
+/**
+ * `page` and `rows` only.
+ *
+ * The endpoint's schema accepts `search` because it shares the common list
+ * query, but the service does not apply it -- a device list is one person's few
+ * rows, so there is nothing to search. It is left out here rather than accepted
+ * and silently dropped.
+ */
+export type ListDevicesQuery = Pick<ListQuery, 'page' | 'rows'>;

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/contact-filter.d.ts

@@ -1,8 +1,9 @@
 /**
  * The contact filter DSL.
  *
- * One vocabulary, four callers: `GET /contacts?filter=`, a saved `Segment`, a
- * `CrmTrigger`'s `filters`, and an export's `config.filter`. Conditions are a
+ * One vocabulary, five callers: `GET /contacts?filter=`, a saved `Segment`, a
+ * `CrmTrigger`'s `filters`, an export's `config.filter`, and a scheduled
+ * message's `conditions`. Conditions are a
  * flat list rather than a tree -- `and` binds tighter than `or`, so the list is
  * split on every `or`, each run is `and`ed, and the runs are `or`ed together.
  */

package/dist/types/contact-filter.js

@@ -2,8 +2,9 @@
 /**
  * The contact filter DSL.
  *
- * One vocabulary, four callers: `GET /contacts?filter=`, a saved `Segment`, a
- * `CrmTrigger`'s `filters`, and an export's `config.filter`. Conditions are a
+ * One vocabulary, five callers: `GET /contacts?filter=`, a saved `Segment`, a
+ * `CrmTrigger`'s `filters`, an export's `config.filter`, and a scheduled
+ * message's `conditions`. Conditions are a
  * flat list rather than a tree -- `and` binds tighter than `or`, so the list is
  * split on every `or`, each run is `and`ed, and the runs are `or`ed together.
  */

package/dist/types/contact-filter.js.map

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