ab-ecosystem-cpass 1.0.5 → 1.0.6

package/dist/resources/audience/notifications.js

@@ -0,0 +1,215 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Notifications = void 0;
+const errors_1 = require("../../errors");
+const device_1 = require("../../internal/device");
+const paths_1 = require("../paths");
+const BASE = `${paths_1.AUDIENCE}/devices`;
+/** The bounds the server applies, checked here so a bad token fails without a round trip. */
+const TOKEN_LENGTH = { min: 20, max: 4096 };
+/** What the server accepts as a label, so a long one is trimmed rather than refused. */
+const MAX_LABEL = 200;
+/**
+ * Push notification subscriptions: which browsers and apps a user wants
+ * notifications delivered to.
+ *
+ * ```ts
+ * // after the browser has granted permission and Firebase has a token
+ * await crm.notifications.subscribe({ token });
+ *
+ * // logout, or the user turning notifications off
+ * await crm.notifications.unsubscribe(token);
+ *
+ * // what the user sees in "notification settings"
+ * const { data } = await crm.notifications.devices();
+ * ```
+ *
+ * ## What this does and does not cover
+ *
+ * A push subscription has two halves and only one of them is an API call:
+ *
+ * 1. **In the browser** -- ask for permission (`Notification.requestPermission()`),
+ *    then get a registration token for this instance
+ *    (`getToken(messaging, { vapidKey })` from `firebase/messaging`). This SDK
+ *    deliberately does none of that: it would mean a hard dependency on
+ *    `firebase/*`, in a package that also runs on Node, to wrap two calls whose
+ *    arguments come from your own Firebase project.
+ * 2. **Here** -- hand that token to the platform so the send path can reach it,
+ *    which is what {@link subscribe} does, and withdraw it on logout, which is
+ *    {@link unsubscribe}.
+ *
+ * ## Where a 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 not on
+ * the delivery path. Nothing in the subscription call names the Firebase project:
+ * the platform resolves it from the client the call arrives on and stamps it onto
+ * the row, because a token is only sendable through the project that minted it
+ * and nothing in the token says which.
+ */
+class Notifications {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Subscribes this browser or app instance to notifications.
+     *
+     * ```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",
+     *   "tpc_id": "tpc_8Kd3mXp7qR2wL9zB"
+     * }
+     * ```
+     *
+     * Answers `201` with the stored {@link Device}, token omitted. Of those four
+     * fields the SDK fills in two for you: `platform` defaults to `'web'` when it
+     * can see a DOM, and `device_label` to something like `Chrome on Windows` from
+     * the user agent.
+     *
+     * ## 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. A user who receives no notifications for two
+     *   months would otherwise fall off the list.
+     *
+     * Re-registering a token that is 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 must stop reaching it the moment
+     * someone else logs in there.
+     *
+     * ## Identity
+     *
+     * The user comes from the verified token this client was built with, and there
+     * is no field that could say otherwise. `tpc_id` is the one tenant field
+     * accepted, because it is not an identity claim -- it says which reseller
+     * frontend is registering, which decides whose Firebase project and which deep
+     * link host apply. It is cross-checked against the verified `client-id`, so it
+     * can confirm the surface but never move the device to another tenant: a value
+     * that contradicts the token is refused with `403` rather than ignored.
+     *
+     * ## Failures worth handling
+     *
+     * - `400 validation_failed` -- the token is missing or implausible, or
+     *   `platform` could not be defaulted (see {@link SubscribeNotificationsInput}).
+     * - `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 set up. Nothing the caller can fix; notifications are simply off
+     *   for this account.
+     * - `503 push_unavailable` -- the platform could not reach core to read the
+     *   configuration. Transient.
+     *
+     * Both `503`s deserve the same handling as a successful call: try again on the
+     * next app load, which the advice above means you are doing anyway.
+     *
+     * Scope: `devices:write`.
+     */
+    subscribe(input) {
+        const token = (input.token ?? '').trim();
+        if (token.length < TOKEN_LENGTH.min || token.length > TOKEN_LENGTH.max) {
+            throw new errors_1.CrmApiError(400, 'validation_failed', `token must be a Firebase registration token of ${TOKEN_LENGTH.min}..${TOKEN_LENGTH.max} characters`);
+        }
+        const platform = input.platform ?? (0, device_1.detectPlatform)();
+        if (!platform) {
+            // Not defaulted to 'web' outside a browser on purpose: a mobile runtime
+            // registered as web gets the webpush half of the payload, which FCM
+            // accepts and the device never displays.
+            throw new errors_1.CrmApiError(400, 'validation_failed', 'platform is required outside a browser: pass "android", "ios", or "web" explicitly');
+        }
+        const label = (input.device_label ?? (0, device_1.describeDevice)() ?? '').trim().slice(0, MAX_LABEL);
+        return this.http.request('POST', BASE, {
+            body: {
+                token,
+                platform,
+                // Both omitted when empty rather than sent as '': the server treats an
+                // absent optional and an empty one the same way, and a body carrying only
+                // what it means is easier to read in a log.
+                ...(label ? { device_label: label } : {}),
+                ...(input.tpc_id ? { tpc_id: input.tpc_id.trim() } : {}),
+            },
+        });
+    }
+    /**
+     * Stops notifications reaching one device. What logout calls.
+     *
+     * ```http
+     * POST /v1/audience/devices/unregister
+     * { "token": "fNx8...:APA91bH..." }
+     * ```
+     *
+     * `204`, no body, whether or not a row went -- the caller is 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, not `DELETE /devices/:token`: a
+     * registration token is hundreds of characters and may contain `:` and `/`, and
+     * putting one in a path would invite proxy length limits and write a live send
+     * credential into every access log on the way.
+     *
+     * ## Also delete it on the device
+     *
+     * This revokes the platform's permission to send to the token. If the user is
+     * turning notifications *off* -- rather than logging out -- also call
+     * `deleteToken(messaging)` in the browser, otherwise the next `getToken()`
+     * hands back the same token and the subscription can come back by accident.
+     *
+     * Scope: `devices:write`.
+     */
+    unsubscribe(token) {
+        const value = (token ?? '').trim();
+        if (!value)
+            throw new errors_1.CrmApiError(400, 'validation_failed', 'token is required');
+        return this.http.request('POST', `${BASE}/unregister`, { body: { token: value } });
+    }
+    /**
+     * The caller's own subscribed devices, newest contact first.
+     *
+     * ```http
+     * GET /v1/audience/devices?page=1&rows=25
+     * ```
+     *
+     * Offset paginated, `rows` 1..100 and default 25, sorted by `lastSeenAt`
+     * descending. This is what a "notification settings" screen lists, and the 20
+     * most recently seen devices are also the only ones a notification is sent to,
+     * so a longer list is itself the answer to "why did my old laptop stop
+     * buzzing".
+     *
+     * 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, and the only
+     * party with a reason to see or revoke it is that person.
+     *
+     * Tokens are not included, so this cannot tell you whether *this* browser is
+     * subscribed. Decide that locally: the browser knows its own
+     * `Notification.permission` and its own token, and {@link subscribe} being
+     * idempotent means the cheap answer to "am I still subscribed" is to subscribe
+     * again.
+     *
+     * Scope: `devices:read`.
+     */
+    devices(query = {}) {
+        return this.http.request('GET', BASE, { query });
+    }
+}
+exports.Notifications = Notifications;
+//# sourceMappingURL=notifications.js.map

package/dist/resources/audience/notifications.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.js","sourceRoot":"","sources":["../../../src/resources/audience/notifications.ts"],"names":[],"mappings":";;;AAEA,yCAA2C;AAC3C,kDAAuE;AACvE,oCAAoC;AAEpC,MAAM,IAAI,GAAG,GAAG,gBAAQ,UAAU,CAAC;AAEnC,6FAA6F;AAC7F,MAAM,YAAY,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;AAE5C,wFAAwF;AACxF,MAAM,SAAS,GAAG,GAAG,CAAC;AAEtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAa,aAAa;IACK;IAA7B,YAA6B,IAAgB;QAAhB,SAAI,GAAJ,IAAI,CAAY;IAAG,CAAC;IAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiEG;IACH,SAAS,CAAC,KAAkC;QAC1C,MAAM,KAAK,GAAG,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QAEzC,IAAI,KAAK,CAAC,MAAM,GAAG,YAAY,CAAC,GAAG,IAAI,KAAK,CAAC,MAAM,GAAG,YAAY,CAAC,GAAG,EAAE,CAAC;YACvE,MAAM,IAAI,oBAAW,CACnB,GAAG,EACH,mBAAmB,EACnB,kDAAkD,YAAY,CAAC,GAAG,KAAK,YAAY,CAAC,GAAG,aAAa,CACrG,CAAC;QACJ,CAAC;QAED,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,IAAA,uBAAc,GAAE,CAAC;QAEpD,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,wEAAwE;YACxE,oEAAoE;YACpE,yCAAyC;YACzC,MAAM,IAAI,oBAAW,CACnB,GAAG,EACH,mBAAmB,EACnB,oFAAoF,CACrF,CAAC;QACJ,CAAC;QAED,MAAM,KAAK,GAAG,CAAC,KAAK,CAAC,YAAY,IAAI,IAAA,uBAAc,GAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;QAExF,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAS,MAAM,EAAE,IAAI,EAAE;YAC7C,IAAI,EAAE;gBACJ,KAAK;gBACL,QAAQ;gBACR,uEAAuE;gBACvE,0EAA0E;gBAC1E,4CAA4C;gBAC5C,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACzC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACzD;SACF,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,WAAW,CAAC,KAAa;QACvB,MAAM,KAAK,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QAEnC,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,oBAAW,CAAC,GAAG,EAAE,mBAAmB,EAAE,mBAAmB,CAAC,CAAC;QAEjF,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAO,MAAM,EAAE,GAAG,IAAI,aAAa,EAAE,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;IAC3F,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,OAAO,CAAC,QAAmC,EAAE;QAC3C,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAoB,KAAK,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IACtE,CAAC;CACF;AAhLD,sCAgLC"}

package/dist/resources/campaign-audience.d.ts

@@ -0,0 +1,132 @@
+import type { CampaignReceiver } from '../internal/receiver-file';
+/**
+ * Most recipients one bulk campaign may carry.
+ *
+ * The same ceiling the panel has always enforced. It is not arbitrary: the list
+ * is encrypted into a single file and read back into memory by the campaign
+ * manager, so this is the point at which "one campaign" stops being a sensible
+ * unit of work.
+ */
+export declare const MAX_BULK_RECEIVERS = 1000000;
+/**
+ * How a bulk audience is described.
+ *
+ * Four shapes, because there are four ways a person actually has this data to
+ * hand. All of them end as the same encrypted file; the difference is only how
+ * much parsing the SDK does on the way.
+ */
+export type BulkAudienceInput = 
+/**
+ * Just numbers, with no per-recipient variables.
+ *
+ * Accepts an array, or one string holding many -- a textarea's contents,
+ * separated by commas, newlines, semicolons or spaces, in any combination.
+ */
+{
+    numbers: string | readonly string[];
+    dedupe?: boolean;
+}
+/**
+ * Raw CSV or TSV text whose first row is the header.
+ *
+ * `recipientColumn` names the header holding the number; every column,
+ * including that one, also becomes a template variable. The delimiter is
+ * detected from the header row unless you pass one.
+ */
+ | {
+    csv: string;
+    recipientColumn: string;
+    delimiter?: string;
+    dedupe?: boolean;
+}
+/**
+ * Rows you have already parsed -- from your own CSV reader, a spreadsheet API,
+ * or a database query.
+ */
+ | {
+    rows: readonly Record<string, unknown>[];
+    recipientColumn: string;
+    dedupe?: boolean;
+}
+/** Receivers you have already built. The escape hatch; nothing is inferred. */
+ | {
+    receivers: readonly CampaignReceiver[];
+};
+/** What resolving an audience produced, including what it discarded. */
+export interface ResolvedAudience {
+    receivers: CampaignReceiver[];
+    /** Entries that carried no usable digits and were skipped. */
+    skipped: number;
+    /** Entries dropped because an earlier entry had the same number. */
+    duplicates: number;
+}
+/**
+ * Normalises a column name into a template variable id.
+ *
+ * Lower-cased with every non-alphanumeric character replaced by `_`, which is
+ * what the panel's CSV reader and its paste-a-table path both did -- so a header
+ * of `First Name` is the variable `first_name` here exactly as it was there, and
+ * templates built against the old behaviour keep working.
+ *
+ * A blank header becomes `empty_<index>` rather than `_`, so two unnamed columns
+ * do not collapse into one variable.
+ */
+export declare const normaliseColumn: (header: unknown, index: number) => string;
+/**
+ * Pulls the numbers out of one string, or tidies an array of them.
+ *
+ * Splits on commas, newlines, carriage returns, tabs, semicolons and spaces --
+ * all of them, in any mixture. The panel chose a single separator per paste
+ * (commas if the text contained any, otherwise newlines), which quietly mangled
+ * the common case of pasting a column from a spreadsheet into a field that
+ * already had comma-separated numbers: the newlines were never split on, so two
+ * numbers merged into one 24-digit number and the send went nowhere. Splitting on
+ * every separator cannot produce that, and for input with one separator it
+ * behaves identically.
+ */
+export declare const normaliseNumbers: (input: string | readonly string[]) => string[];
+/**
+ * Splits delimited text into a header and rows, RFC 4180 style.
+ *
+ * A proper parser rather than `split(',')`, because a quoted field may contain
+ * the delimiter, a newline, or an escaped quote -- and a currency-formatted
+ * variable (`"1,299"`) is exactly the sort of value that appears in these files.
+ * Splitting naively turns one such row into two bad ones.
+ *
+ * Values stay strings. The panel parsed with `dynamicTyping`, which coerced
+ * numeric-looking cells to JavaScript numbers -- and that silently corrupted the
+ * one column that matters: a 16-digit number exceeds `Number.MAX_SAFE_INTEGER`
+ * and comes back with its last digits changed, while a number written with a
+ * leading zero loses it. Keeping text as text avoids both.
+ */
+export declare const parseDelimited: (text: string, delimiter?: string) => {
+    headers: string[];
+    rows: Record<string, string>[];
+};
+/**
+ * Turns parsed rows into receivers.
+ *
+ * Every column becomes a variable, including the recipient column itself -- which
+ * is intentional and matches the panel: a template that greets someone by the
+ * number they were messaged on still works.
+ *
+ * A row whose recipient column holds no digits is skipped rather than failing the
+ * whole batch. In a file of ten thousand rows, a handful of blanks and a trailing
+ * footer line are normal, and refusing the campaign over them would mean the
+ * caller has to clean a file they may not control. The count comes back in
+ * {@link ResolvedAudience.skipped} so the omission is visible rather than silent.
+ */
+export declare const buildReceivers: (rows: readonly Record<string, unknown>[], recipientColumn: string, options?: {
+    dedupe?: boolean;
+}) => ResolvedAudience;
+/**
+ * Resolves any of the four audience shapes into one receiver list.
+ *
+ * De-duplicates by number unless `dedupe: false`. On by default because the cost
+ * of a duplicate here is not a wasted row in a table -- it is the same person
+ * receiving the same marketing message twice, billed twice, and more likely to
+ * report the sender. A caller who genuinely wants two sends to one number can
+ * say so.
+ */
+export declare const resolveAudience: (input: BulkAudienceInput) => ResolvedAudience;
+export type { CampaignReceiver };

package/dist/resources/campaign-audience.js

@@ -0,0 +1,224 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveAudience = exports.buildReceivers = exports.parseDelimited = exports.normaliseNumbers = exports.normaliseColumn = exports.MAX_BULK_RECEIVERS = void 0;
+/**
+ * Most recipients one bulk campaign may carry.
+ *
+ * The same ceiling the panel has always enforced. It is not arbitrary: the list
+ * is encrypted into a single file and read back into memory by the campaign
+ * manager, so this is the point at which "one campaign" stops being a sensible
+ * unit of work.
+ */
+exports.MAX_BULK_RECEIVERS = 1_000_000;
+/** Digits only: no `+`, no spaces, no dashes, no parentheses. */
+const digitsOf = (value) => (value === null || value === undefined ? '' : String(value).replace(/\D/g, ''));
+/**
+ * Normalises a column name into a template variable id.
+ *
+ * Lower-cased with every non-alphanumeric character replaced by `_`, which is
+ * what the panel's CSV reader and its paste-a-table path both did -- so a header
+ * of `First Name` is the variable `first_name` here exactly as it was there, and
+ * templates built against the old behaviour keep working.
+ *
+ * A blank header becomes `empty_<index>` rather than `_`, so two unnamed columns
+ * do not collapse into one variable.
+ */
+const normaliseColumn = (header, index) => {
+    const name = String(header ?? '').trim();
+    if (!name)
+        return `empty_${index}`;
+    return name.toLowerCase().replace(/[^a-z0-9]/g, '_');
+};
+exports.normaliseColumn = normaliseColumn;
+/**
+ * Pulls the numbers out of one string, or tidies an array of them.
+ *
+ * Splits on commas, newlines, carriage returns, tabs, semicolons and spaces --
+ * all of them, in any mixture. The panel chose a single separator per paste
+ * (commas if the text contained any, otherwise newlines), which quietly mangled
+ * the common case of pasting a column from a spreadsheet into a field that
+ * already had comma-separated numbers: the newlines were never split on, so two
+ * numbers merged into one 24-digit number and the send went nowhere. Splitting on
+ * every separator cannot produce that, and for input with one separator it
+ * behaves identically.
+ */
+const normaliseNumbers = (input) => {
+    const parts = typeof input === 'string' ? input.split(/[\s,;]+/) : input;
+    return parts.map(digitsOf).filter((value) => value.length > 0);
+};
+exports.normaliseNumbers = normaliseNumbers;
+/**
+ * Splits delimited text into a header and rows, RFC 4180 style.
+ *
+ * A proper parser rather than `split(',')`, because a quoted field may contain
+ * the delimiter, a newline, or an escaped quote -- and a currency-formatted
+ * variable (`"1,299"`) is exactly the sort of value that appears in these files.
+ * Splitting naively turns one such row into two bad ones.
+ *
+ * Values stay strings. The panel parsed with `dynamicTyping`, which coerced
+ * numeric-looking cells to JavaScript numbers -- and that silently corrupted the
+ * one column that matters: a 16-digit number exceeds `Number.MAX_SAFE_INTEGER`
+ * and comes back with its last digits changed, while a number written with a
+ * leading zero loses it. Keeping text as text avoids both.
+ */
+const parseDelimited = (text, delimiter) => {
+    const rows = splitRows(text, delimiter ?? detectDelimiter(text));
+    const headerRow = rows.shift();
+    if (!headerRow)
+        return { headers: [], rows: [] };
+    const headers = headerRow.map(exports.normaliseColumn);
+    const parsed = rows
+        // A trailing newline, or a blank line in the middle, is not a record.
+        .filter((cells) => cells.some((cell) => cell.trim() !== ''))
+        .map((cells) => {
+        const row = {};
+        headers.forEach((header, index) => {
+            row[header] = cells[index] ?? '';
+        });
+        return row;
+    });
+    return { headers, rows: parsed };
+};
+exports.parseDelimited = parseDelimited;
+/** Tab if the header row has one, else semicolon, else comma. */
+const detectDelimiter = (text) => {
+    const firstLine = text.slice(0, text.search(/\r?\n/) === -1 ? undefined : text.search(/\r?\n/));
+    if (firstLine.includes('\t'))
+        return '\t';
+    if (firstLine.includes(';') && !firstLine.includes(','))
+        return ';';
+    return ',';
+};
+/** The parser proper: quotes, doubled quotes inside them, and newlines within a field. */
+const splitRows = (text, delimiter) => {
+    const rows = [];
+    let row = [];
+    let field = '';
+    let quoted = false;
+    for (let i = 0; i < text.length; i += 1) {
+        const char = text[i];
+        if (quoted) {
+            if (char !== '"') {
+                field += char;
+            }
+            else if (text[i + 1] === '"') {
+                // A doubled quote inside a quoted field is one literal quote.
+                field += '"';
+                i += 1;
+            }
+            else {
+                quoted = false;
+            }
+            continue;
+        }
+        if (char === '"' && field === '') {
+            quoted = true;
+        }
+        else if (char === delimiter) {
+            row.push(field);
+            field = '';
+        }
+        else if (char === '\n' || char === '\r') {
+            // Either line ending, and CRLF counts once.
+            if (char === '\r' && text[i + 1] === '\n')
+                i += 1;
+            row.push(field);
+            rows.push(row);
+            row = [];
+            field = '';
+        }
+        else {
+            field += char;
+        }
+    }
+    if (field !== '' || row.length) {
+        row.push(field);
+        rows.push(row);
+    }
+    return rows;
+};
+/**
+ * Turns parsed rows into receivers.
+ *
+ * Every column becomes a variable, including the recipient column itself -- which
+ * is intentional and matches the panel: a template that greets someone by the
+ * number they were messaged on still works.
+ *
+ * A row whose recipient column holds no digits is skipped rather than failing the
+ * whole batch. In a file of ten thousand rows, a handful of blanks and a trailing
+ * footer line are normal, and refusing the campaign over them would mean the
+ * caller has to clean a file they may not control. The count comes back in
+ * {@link ResolvedAudience.skipped} so the omission is visible rather than silent.
+ */
+const buildReceivers = (rows, recipientColumn, options = {}) => {
+    const column = (0, exports.normaliseColumn)(recipientColumn, 0);
+    const receivers = [];
+    const seen = new Set();
+    let skipped = 0;
+    let duplicates = 0;
+    for (const row of rows) {
+        // Accept the column as written or as normalised, so a caller passing
+        // `'First Name'` against already-normalised rows still resolves.
+        const raw = row[recipientColumn] ?? row[column];
+        const waba = digitsOf(raw);
+        if (!waba) {
+            skipped += 1;
+            continue;
+        }
+        if (options.dedupe !== false) {
+            if (seen.has(waba)) {
+                duplicates += 1;
+                continue;
+            }
+            seen.add(waba);
+        }
+        receivers.push({
+            waba,
+            custom_fields: Object.keys(row).map((key, index) => ({
+                id: (0, exports.normaliseColumn)(key, index),
+                value: row[key] === null || row[key] === undefined ? '' : String(row[key]),
+            })),
+        });
+    }
+    return { receivers, skipped, duplicates };
+};
+exports.buildReceivers = buildReceivers;
+/**
+ * Resolves any of the four audience shapes into one receiver list.
+ *
+ * De-duplicates by number unless `dedupe: false`. On by default because the cost
+ * of a duplicate here is not a wasted row in a table -- it is the same person
+ * receiving the same marketing message twice, billed twice, and more likely to
+ * report the sender. A caller who genuinely wants two sends to one number can
+ * say so.
+ */
+const resolveAudience = (input) => {
+    if ('receivers' in input) {
+        // Taken as given: a caller who built these chose the shape deliberately.
+        return { receivers: [...input.receivers], skipped: 0, duplicates: 0 };
+    }
+    if ('numbers' in input) {
+        const numbers = (0, exports.normaliseNumbers)(input.numbers);
+        const receivers = [];
+        const seen = new Set();
+        let duplicates = 0;
+        for (const waba of numbers) {
+            if (input.dedupe !== false) {
+                if (seen.has(waba)) {
+                    duplicates += 1;
+                    continue;
+                }
+                seen.add(waba);
+            }
+            receivers.push({ waba, custom_fields: [] });
+        }
+        const supplied = typeof input.numbers === 'string' ? numbers.length + countBlank(input.numbers) : input.numbers.length;
+        return { receivers, skipped: Math.max(0, supplied - numbers.length - duplicates), duplicates };
+    }
+    const rows = 'csv' in input ? (0, exports.parseDelimited)(input.csv, input.delimiter).rows : input.rows;
+    return (0, exports.buildReceivers)(rows, input.recipientColumn, { dedupe: input.dedupe });
+};
+exports.resolveAudience = resolveAudience;
+/** Entries in a pasted string that held no digits at all, for the skipped count. */
+const countBlank = (text) => text.split(/[\s,;]+/).filter((part) => part !== '' && digitsOf(part) === '').length;
+//# sourceMappingURL=campaign-audience.js.map

package/dist/resources/campaign-audience.js.map

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

package/dist/resources/campaign-report-exports.d.ts

@@ -0,0 +1,14 @@
+import type { CampaignReportExport, CreateCampaignReportExportInput } from '../types/campaign';
+import type { Page, PageQuery } from '../types/common';
+import type { HttpClient } from '../http';
+export declare class CampaignReportExports {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(query?: Partial<PageQuery>): Promise<Page<CampaignReportExport>>;
+    /**
+     * One export. Poll this until `status` is `completed`, then read `fileUrl` --
+     * which expires, so download rather than storing the link.
+     */
+    get(id: string): Promise<CampaignReportExport>;
+    create(input: CreateCampaignReportExportInput): Promise<CampaignReportExport>;
+}

package/dist/resources/campaign-report-exports.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CampaignReportExports = void 0;
+class CampaignReportExports {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    list(query = {}) {
+        return this.http.request('GET', '/v1/campaign-report-exports', {
+            query,
+        });
+    }
+    /**
+     * One export. Poll this until `status` is `completed`, then read `fileUrl` --
+     * which expires, so download rather than storing the link.
+     */
+    get(id) {
+        return this.http.request('GET', `/v1/campaign-report-exports/${encodeURIComponent(id)}`);
+    }
+    create(input) {
+        return this.http.request('POST', '/v1/campaign-report-exports', {
+            body: input,
+        });
+    }
+}
+exports.CampaignReportExports = CampaignReportExports;
+//# sourceMappingURL=campaign-report-exports.js.map

package/dist/resources/campaign-report-exports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"campaign-report-exports.js","sourceRoot":"","sources":["../../src/resources/campaign-report-exports.ts"],"names":[],"mappings":";;;AAIA,MAAa,qBAAqB;IACH;IAA7B,YAA6B,IAAgB;QAAhB,SAAI,GAAJ,IAAI,CAAY;IAAG,CAAC;IAEjD,IAAI,CAAC,QAA4B,EAAE;QACjC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAA6B,KAAK,EAAE,6BAA6B,EAAE;YACzF,KAAK;SACN,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CACtB,KAAK,EACL,+BAA+B,kBAAkB,CAAC,EAAE,CAAC,EAAE,CACxD,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,KAAsC;QAC3C,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAuB,MAAM,EAAE,6BAA6B,EAAE;YACpF,IAAI,EAAE,KAAK;SACZ,CAAC,CAAC;IACL,CAAC;CACF;AAzBD,sDAyBC"}

package/dist/resources/campaign-reports.d.ts

@@ -0,0 +1,15 @@
+import type { CampaignReport, GetCampaignReportQuery } from '../types/campaign';
+import type { Page, PageQuery } from '../types/common';
+import type { HttpClient } from '../http';
+export declare class CampaignReports {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(query?: Partial<PageQuery>): Promise<Page<CampaignReport>>;
+    /**
+     * The report for one campaign.
+     *
+     * `from`/`to` narrow the window the metrics are rolled up over; without them
+     * the report covers the campaign's whole life.
+     */
+    getByCampaign(campaignId: string, query?: GetCampaignReportQuery): Promise<CampaignReport>;
+}