ab-ecosystem-cpass 1.0.5 → 1.0.7

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-messages.d.ts

@@ -0,0 +1,150 @@
+import type { CampaignMessageRecord, CampaignMessageStats, CampaignMessageStatsQuery, CampaignRepliesQuery, CampaignReplyBreakdown, ListCampaignMessagesQuery } from '../types/campaign';
+import type { Paginated } from '../types/common';
+import type { HttpClient } from '../http';
+/**
+ * Campaign reporting: what actually happened to each message.
+ *
+ * ```ts
+ * const stats = await crm.campaignMessages.stats({ campaign });
+ * // { total: 12480, sent: 12410, delivered: 11980, read: 7420, replied: 310, failed: 70 }
+ *
+ * const { data } = await crm.campaignMessages.list({ campaign, status: 'failed' });
+ * data[0].error; // why that one did not go
+ * ```
+ *
+ * ## Where these numbers come from
+ *
+ * One row per attempted send, written by the campaign manager as it hands each
+ * message to a channel, with its `status` moved forward by the channel's
+ * delivery webhooks -- which are processed outside the CRM entirely. The report
+ * is **counted off those rows when you ask for it**, not rolled up on a
+ * schedule, so there is no "generated at" to reason about and no staleness
+ * window: the numbers are as current as the webhooks that have arrived.
+ *
+ * The flip side is that a campaign still going out has moving numbers. Reading
+ * `stats` seconds after launching under-counts everything, and that is correct
+ * rather than a lag.
+ *
+ * ## The funnel
+ *
+ * `status` is a single field holding the furthest stage reached, so the counts
+ * are cumulative and nest: `replied ⊆ read ⊆ delivered ⊆ sent`. For a stage's
+ * exclusive count, subtract the next one -- `delivered - read` is "delivered but
+ * unread". `failed` is outside the funnel and never inside `sent`.
+ *
+ * ## There is no export endpoint
+ *
+ * An export is {@link list} written to a file, so {@link iterate} does the
+ * paging and the caller formats the rows. Nothing is queued, nothing has to be
+ * polled, and no generated file expires before someone downloads it.
+ */
+export declare class CampaignMessages {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * The campaign's funnel counts.
+     *
+     * `GET /v1/campaign-messages/stats?campaign=<id>` · `campaigns:read` · **200**
+     *
+     * ### Query
+     *
+     * | Field | Type | Required | Notes |
+     * | --- | --- | --- | --- |
+     * | `campaign` | string | yes | The campaign id. |
+     * | `message` | number | no | One message of a multi-message campaign, zero-based. |
+     *
+     * ```ts
+     * const overall = await crm.campaignMessages.stats({ campaign });
+     * const second = await crm.campaignMessages.stats({ campaign, message: 1 });
+     * ```
+     *
+     * No date window: a campaign is one send, so its whole life is the only
+     * meaningful window. A repeating campaign's runs are separate campaigns with
+     * their own ids.
+     *
+     * `404 not_found` if the campaign is not the caller's -- the same answer as a
+     * campaign that does not exist, so the error cannot be used to probe ids.
+     */
+    stats(query: CampaignMessageStatsQuery): Promise<CampaignMessageStats>;
+    /**
+     * The rows behind the funnel. This is the report table.
+     *
+     * `GET /v1/campaign-messages?campaign=<id>` · `campaigns:read` · **200**
+     *
+     * ### Query
+     *
+     * | Field | Type | Default | Notes |
+     * | --- | --- | --- | --- |
+     * | `campaign` | string | — | Required. |
+     * | `message` | number | — | Zero-based index of one campaign message. |
+     * | `status` | `sent \| delivered \| read \| replied \| failed` | — | Cumulative; see below. Omit for every row. |
+     * | `exact` | boolean | `false` | Only rows sitting at `status` right now. |
+     * | `identifier` | string | — | Exact match on one recipient. Not a search. |
+     * | `reply_type` | string | — | Replied rows only; refused otherwise. |
+     * | `replied_within_hours` | number | — | Replied rows only; refused otherwise. |
+     * | `page` | number | `1` | 1-based. |
+     * | `rows` | number | `25` | 1–100. |
+     *
+     * Newest attempt first, ordered by when the row was written -- not by a stage
+     * timestamp, which would reorder the list as webhooks arrive and make paging
+     * skip and repeat rows.
+     *
+     * ```ts
+     * // the two queries a report screen actually makes
+     * const failures = await crm.campaignMessages.list({ campaign, status: 'failed', rows: 100 });
+     * const unread = await crm.campaignMessages.list({ campaign, status: 'delivered', exact: true });
+     * ```
+     *
+     * `reply_type` and `replied_within_hours` are **refused** with
+     * `400 validation_failed` unless `status` is `replied`, rather than quietly
+     * matching nothing.
+     */
+    list(query: ListCampaignMessagesQuery): Promise<Paginated<CampaignMessageRecord>>;
+    /**
+     * Every matching row, paged through for you. What an export is.
+     *
+     * ```ts
+     * for await (const row of crm.campaignMessages.iterate({ campaign })) {
+     *   csv.write([row.identifier, row.name, row.status, row.error ?? '']);
+     * }
+     * ```
+     *
+     * Pages at 100 rows unless told otherwise -- the server's maximum, and the
+     * fewest round trips. A campaign of a million recipients is ten thousand
+     * requests, so for exports that size prefer running it where the latency is
+     * low rather than from a browser.
+     *
+     * The collection is live: rows are written while a campaign is going out, and
+     * statuses change under an export that takes minutes. Offset paging over
+     * moving data can repeat or skip a row -- for a stable snapshot, export after
+     * the campaign completes.
+     */
+    iterate(query: ListCampaignMessagesQuery): AsyncGenerator<CampaignMessageRecord>;
+    /**
+     * What people replied, grouped by the reply itself.
+     *
+     * `GET /v1/campaign-messages/replies?campaign=<id>` · `campaigns:read` · **200**
+     *
+     * ### Query
+     *
+     * | Field | Type | Default | Notes |
+     * | --- | --- | --- | --- |
+     * | `campaign` | string | — | Required. |
+     * | `message` | number | — | Zero-based index of one campaign message. |
+     * | `limit` | number | `50` | Distinct replies to return, 1–200. |
+     *
+     * ```ts
+     * const { groups, replied, distinct } = await crm.campaignMessages.replies({ campaign });
+     * groups; // [{ reply: 'Yes', replyType: 'button', count: 182 }, …]
+     * ```
+     *
+     * This is what a poll or a button message is sent to find out. Grouped on the
+     * reply **and** its type, so a tapped `Yes` and a typed `Yes` stay apart --
+     * they say different things about how engaged the recipient was.
+     *
+     * `distinct` against `groups.length` tells you whether the breakdown is
+     * complete. A campaign that asked an open question has as many groups as it
+     * has repliers, so a truncated answer there is normal rather than a problem.
+     */
+    replies(query: CampaignRepliesQuery): Promise<CampaignReplyBreakdown>;
+}