ab-ecosystem-cpass 1.0.5 → 1.0.7

package/dist/resources/campaigns.js

@@ -0,0 +1,300 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Campaigns = void 0;
+const errors_1 = require("../errors");
+const inbox_media_1 = require("./audience/inbox-media");
+const receiver_file_1 = require("../internal/receiver-file");
+const campaign_audience_1 = require("./campaign-audience");
+/** The dispatch route a file-backed audience is sent under. */
+const BULK_TYPE = 'bulk_campaign';
+/**
+ * The dispatch route a bucketed audience is stored under.
+ *
+ * Stored as `group_campaign`; the campaign service relabels it to
+ * `bulk_campaign` on the hand-off to the sending service, because the two differ
+ * only in how many receiver files there are. Our own records keep the real name.
+ */
+const GROUP_TYPE = 'group_campaign';
+/** Buckets uploaded at once. Bounded so fifty buckets is not fifty open sockets. */
+const UPLOAD_CONCURRENCY = 3;
+class Campaigns {
+    http;
+    media;
+    constructor(http, media) {
+        this.http = http;
+        // Defaults to the audience service's own presigned-upload endpoint, which is
+        // the same path chat media takes.
+        this.media = media ?? new inbox_media_1.InboxMedia(http);
+    }
+    list(query = {}) {
+        return this.http.request('GET', '/v1/campaigns', { query });
+    }
+    get(id) {
+        return this.http.request('GET', `/v1/campaigns/${encodeURIComponent(id)}`);
+    }
+    /**
+     * Creates a campaign from a payload you have already assembled.
+     *
+     * For a bulk recipient list, prefer {@link createBulk} -- it does the
+     * encrypting and uploading that a file-backed audience requires, which is not
+     * something a caller should have to reproduce.
+     */
+    create(input) {
+        return this.http.request('POST', '/v1/campaigns', { body: input });
+    }
+    /**
+     * Creates a campaign addressed to a list of numbers you supply directly.
+     *
+     * This is the "bulk campaign" path, and the SDK does the whole of it: the
+     * recipient list never travels as part of the campaign, because a million
+     * numbers is not a request body. Instead it is encrypted into a file, uploaded
+     * to storage, and the campaign stores a pointer to it -- which the sending
+     * service fetches and decrypts when the campaign runs.
+     *
+     * ```ts
+     * // Pasted numbers, no variables
+     * const { campaign, receivers } = await crm.campaigns.createBulk({
+     *   name: 'Diwali offer',
+     *   audience: { numbers: '919000000001, 919000000002\n919000000003' },
+     *   messages: [{ channel: { id: channelId }, message: template }],
+     * });
+     *
+     * // A CSV, with every column available as a template variable
+     * await crm.campaigns.createBulk({
+     *   name: 'Renewal reminder',
+     *   audience: { csv: await file.text(), recipientColumn: 'phone' },
+     *   messages: [{ channel: { id: channelId }, message: template }],
+     *   trigger: 'schedule',
+     *   scheduledAt: '2026-11-01T04:30:00.000Z',
+     * });
+     * ```
+     *
+     * ## What it does, in order
+     *
+     * 1. **Resolves the audience.** Numbers are reduced to digits; CSV or TSV text
+     *    is parsed with quoted fields honoured; every column becomes a per-recipient
+     *    variable. Rows with no usable number are skipped and duplicates dropped,
+     *    both counted in the result rather than passed over in silence.
+     * 2. **Encrypts the list.** AES-256-CBC under a secret generated fresh for this
+     *    one file. See `internal/receiver-file.ts` for the exact scheme.
+     * 3. **Uploads it** as a `document` through the media endpoint: a presigned URL
+     *    is issued and the bytes go straight to storage, so the file never passes
+     *    through the API.
+     * 4. **Creates the campaign** with `type: 'bulk_campaign'` and
+     *    `filters: [{numbers: <url>, hash: <secret>}]`.
+     *
+     * ## Two things worth knowing
+     *
+     * **The returned `campaign.receivers` is `0`, and that is correct.** The
+     * audience is resolved when the campaign is sent, not when it is created. Use
+     * the `receivers` on this result -- the number actually written into the file --
+     * for anything you show the user now.
+     *
+     * **The file is readable by anyone holding both the URL and the `hash`.** The
+     * URL is a public storage link, so the secret stored alongside it on the
+     * campaign is the only thing protecting the list. It is a credential: do not log
+     * it, and do not copy a `filters` entry from one campaign into another system.
+     *
+     * Throws `validation_failed` if the audience resolves to no recipients, or to
+     * more than a million.
+     */
+    async createBulk(input) {
+        const { audience, signal, ...campaign } = input;
+        const resolved = (0, campaign_audience_1.resolveAudience)(audience);
+        if (!resolved.receivers.length) {
+            throw new errors_1.CrmApiError(400, 'validation_failed', resolved.skipped > 0
+                ? `None of the ${resolved.skipped} entries supplied held a usable number`
+                : 'The audience resolved to no recipients');
+        }
+        if (resolved.receivers.length > campaign_audience_1.MAX_BULK_RECEIVERS) {
+            throw new errors_1.CrmApiError(400, 'validation_failed', `A bulk campaign may address at most ${campaign_audience_1.MAX_BULK_RECEIVERS.toLocaleString('en-US')} recipients; ` +
+                `this audience has ${resolved.receivers.length.toLocaleString('en-US')}. Split it across campaigns.`);
+        }
+        const filter = await this.uploadReceivers(resolved.receivers, signal);
+        const created = await this.create({
+            ...campaign,
+            type: input.type ?? BULK_TYPE,
+            filters: [filter],
+        });
+        return {
+            campaign: created,
+            receivers: resolved.receivers.length,
+            skipped: resolved.skipped,
+            duplicates: resolved.duplicates,
+            fileUrl: filter.numbers,
+        };
+    }
+    /**
+     * Creates a campaign whose recipients are split into buckets, each sent through
+     * a different channel or rendered with a different message.
+     *
+     * ```ts
+     * const { campaign, buckets, receivers } = await crm.campaigns.createGroup({
+     *   name: 'Diwali offer',
+     *   distributeBy: 'channel',
+     *   buckets: [
+     *     { channel: channelA, audience: { rows: north, recipientColumn: 'phone' } },
+     *     { channel: channelB, audience: { rows: south, recipientColumn: 'phone' } },
+     *   ],
+     *   messages: [{ channel: { id: channelA }, message: template }],
+     * });
+     * ```
+     *
+     * ## How this differs from `createBulk`
+     *
+     * Three ways, and each of them is a thing that would be wrong if you built the
+     * payload by hand:
+     *
+     * - **One file per bucket, not one per campaign.** Each bucket is encrypted
+     *   under its own secret and uploaded separately, and `filters` carries one
+     *   entry per bucket. This is the only audience mode where `filters` has more
+     *   than one element.
+     * - **A different file format.** A bucket file is a `||`-delimited table with a
+     *   header row, not the JSON array a bulk file holds. The reading side chooses
+     *   by campaign type, so the wrong encoding decrypts cleanly and then parses to
+     *   nothing.
+     * - **Columns are fixed by the first recipient.** A table has one header, so
+     *   every row carries the same variables in the same order. A bucket whose rows
+     *   have differing columns will have the missing ones filled in as empty.
+     *
+     * Everything else is the same: numbers are reduced to digits, CSV is parsed
+     * with quoted fields honoured, duplicates and unusable rows are dropped and
+     * counted -- per bucket, and summed on the result.
+     *
+     * ## Empty buckets are dropped, not refused
+     *
+     * A bucket whose audience resolves to nobody is left out of `filters`
+     * altogether, matching the panel: distributing a list across six channels
+     * routinely leaves one or two with nothing in them, and that is not an error.
+     * The call fails only when **every** bucket is empty.
+     *
+     * De-duplication is per bucket. A number appearing in two buckets is sent to
+     * twice -- which is usually the intent, since the buckets are different
+     * channels, and is not something this can second-guess.
+     */
+    async createGroup(input) {
+        const { buckets, distributeBy, signal, ...campaign } = input;
+        const resolved = buckets.map((bucket) => ({ bucket, audience: (0, campaign_audience_1.resolveAudience)(bucket.audience) }));
+        const usable = resolved.filter((entry) => entry.audience.receivers.length > 0);
+        const totals = resolved.reduce((sum, entry) => ({
+            receivers: sum.receivers + entry.audience.receivers.length,
+            skipped: sum.skipped + entry.audience.skipped,
+            duplicates: sum.duplicates + entry.audience.duplicates,
+        }), { receivers: 0, skipped: 0, duplicates: 0 });
+        if (!usable.length) {
+            throw new errors_1.CrmApiError(400, 'validation_failed', buckets.length
+                ? `None of the ${buckets.length} buckets resolved to a recipient`
+                : 'A group campaign needs at least one bucket');
+        }
+        if (totals.receivers > campaign_audience_1.MAX_BULK_RECEIVERS) {
+            throw new errors_1.CrmApiError(400, 'validation_failed', `A campaign may address at most ${campaign_audience_1.MAX_BULK_RECEIVERS.toLocaleString('en-US')} recipients across all ` +
+                `buckets; this one has ${totals.receivers.toLocaleString('en-US')}. Split it across campaigns.`);
+        }
+        const uploaded = await mapWithLimit(usable, UPLOAD_CONCURRENCY, async ({ bucket, audience }) => {
+            const filter = await this.uploadReceivers(audience.receivers, signal, 'table');
+            return {
+                filter: {
+                    ...bucket.extra,
+                    type: distributeBy,
+                    ...(bucket.channel === undefined ? {} : { channel: bucket.channel }),
+                    ...(bucket.pairIndex === undefined ? {} : { pairIndex: bucket.pairIndex }),
+                    // Carried because the panel carried it: the manager can read a bucket's
+                    // size without downloading and decrypting the file to count it.
+                    count: audience.receivers.length,
+                    ...filter,
+                },
+                result: {
+                    receivers: audience.receivers.length,
+                    skipped: audience.skipped,
+                    duplicates: audience.duplicates,
+                    fileUrl: filter.numbers,
+                    ...(bucket.channel === undefined ? {} : { channel: bucket.channel }),
+                    ...(bucket.pairIndex === undefined ? {} : { pairIndex: bucket.pairIndex }),
+                },
+            };
+        });
+        const created = await this.create({
+            ...campaign,
+            type: input.type ?? GROUP_TYPE,
+            filters: uploaded.map((entry) => entry.filter),
+        });
+        return { campaign: created, buckets: uploaded.map((entry) => entry.result), ...totals };
+    }
+    /**
+     * Encrypts and uploads a receiver list, answering with the audience filter it
+     * produced.
+     *
+     * The file half of {@link createBulk}, exposed because the two halves can fail
+     * for unrelated reasons. Holding the filter lets you retry a failed campaign
+     * creation -- or create several campaigns against one uploaded list -- without
+     * re-uploading, which matters when the list is large.
+     *
+     * The returned `hash` is the decryption secret. Keep it with the URL or the
+     * file becomes unreadable; there is no copy of it anywhere else.
+     */
+    async uploadReceivers(receivers, signal, 
+    /**
+     * How the list is encoded inside the file. `json` for a bulk campaign's
+     * single file, `table` for a group campaign's bucket. The reading side picks
+     * by campaign type, so this has to match the campaign it is for.
+     */
+    encoding = 'json') {
+        const file = await (0, receiver_file_1.buildReceiverFile)([...receivers], encoding);
+        const source = {
+            body: file.body,
+            filename: file.filename,
+            contentType: file.contentType,
+            size: file.size,
+        };
+        // `document` rather than a kind of its own: it is the one kind that accepts
+        // an arbitrary media type, and at 100MB its ceiling is far above a million
+        // encrypted numbers.
+        const numbers = await this.media.upload(source, {
+            kind: 'document',
+            filename: file.filename,
+            contentType: file.contentType,
+            signal,
+        });
+        return { numbers, hash: file.secret };
+    }
+    update(id, input) {
+        return this.http.request('PATCH', `/v1/campaigns/${encodeURIComponent(id)}`, { body: input });
+    }
+    schedule(id, scheduledAt) {
+        return this.http.request('POST', `/v1/campaigns/${encodeURIComponent(id)}/schedule`, {
+            body: { scheduledAt },
+        });
+    }
+    cancel(id) {
+        return this.http.request('POST', `/v1/campaigns/${encodeURIComponent(id)}/cancel`);
+    }
+    delete(id) {
+        return this.http.request('DELETE', `/v1/campaigns/${encodeURIComponent(id)}`);
+    }
+}
+exports.Campaigns = Campaigns;
+/**
+ * `Promise.all` with a ceiling.
+ *
+ * A group campaign can have fifty buckets, and the panel uploaded them with an
+ * unbounded `Promise.all` -- fifty simultaneous uploads, which a browser queues
+ * anyway and a flaky connection turns into fifty retries at once. Three at a
+ * time finishes a realistic campaign in about the same wall-clock time without
+ * that.
+ *
+ * Results stay in input order, which `filters` depends on: a `template` bucket
+ * is addressed by its `pairIndex`, and reordering would silently re-point them.
+ */
+const mapWithLimit = async (items, limit, run) => {
+    const results = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const index = next++;
+            results[index] = await run(items[index]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return results;
+};
+//# sourceMappingURL=campaigns.js.map

package/dist/resources/campaigns.js.map

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

package/dist/types/audience.d.ts

@@ -520,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'>;