@msg91comm/m91 0.0.0-stage → 1.2.0

package/dist/src/platform.js

@@ -0,0 +1,286 @@
+/**
+ * The API-key client: alerting **one person, by phone number**.
+ *
+ * The narrowness is the point, and worth understanding before reaching for
+ * this. A team is already solved — somebody creates the channel in the app and
+ * the integration posts to its send link. What a link cannot do is address a
+ * person a platform is discovering at runtime: a CRM signing up its
+ * five-thousandth salesman cannot mint and store five thousand bearer
+ * credentials, each able to wake somebody through Do Not Disturb, sitting in a
+ * user table with no rotation. So for one person, the secret is one header and
+ * the address is a phone number.
+ *
+ * **An API key cannot alert a team channel.** It can *provision* one — create
+ * it, staff it, read its send link — because that is the same authority its
+ * owner has in the app. Raising the alert is still the send link's job. A
+ * leaked key can rename or restaff a channel; it cannot ring a single phone in
+ * it, and that split is the entire reason the two capabilities sit on two
+ * credentials.
+ */
+import { M91ForbiddenError, M91NotFoundError, M91ValidationError } from './exceptions.js';
+import { Transport } from './http.js';
+import { CHANNEL_NAME_MAX, MAX_MEMBERS_PER_CALL, buildAlertPayload, collapse, parseAlertDetail, parseAlertResponse, parseApiKeyInfo, parseInviteResult, parseProvisionedChannel, parseRecipient, validatePhone, } from './models.js';
+import { checkDelivery } from './client.js';
+export const DEFAULT_BASE_URL = 'https://m91-api.msg91.com';
+export const API_KEY_PREFIX = 'm91sk_';
+/** Invite people, alert them one at a time, and provision team channels. */
+export class M91Platform {
+    baseUrl;
+    throwOnZeroDelivery;
+    apiKey;
+    http;
+    constructor(apiKey, options = {}) {
+        this.apiKey = checkApiKey(apiKey);
+        this.throwOnZeroDelivery = options.throwOnZeroDelivery !== false;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.http = new Transport({
+            ...options,
+            headers: { authorization: `Bearer ${this.apiKey}`, ...options.headers },
+        });
+    }
+    /** The key is a live credential that can wake people. Only its prefix. */
+    toString() {
+        return `M91Platform(${this.apiKey.slice(0, 10)}…, ${this.baseUrl})`;
+    }
+    url(path) {
+        return `${this.baseUrl}/api/v1${path}`;
+    }
+    /**
+     * Check the key works, and see which key it is. **Alerts nobody.**
+     *
+     * The only route on this surface that is safe to call just to find out
+     * whether a credential works — everything else writes something or needs an
+     * id that already exists. On an alerting product, "test the connection" must
+     * never mean "wake somebody", so do not verify a key by sending an alert.
+     *
+     * A revoked key never reaches this route, so a success means *live*, not
+     * merely well-formed.
+     *
+     * Note what it does **not** prove: a perfectly good key with nobody accepted
+     * behind it still alerts nobody. Invite a real number and check the state
+     * before you believe the integration works.
+     */
+    async verify() {
+        return parseApiKeyInfo(await this.http.request({ method: 'GET', url: this.url('/me') }));
+    }
+    /**
+     * Invite somebody to accept direct alerts. **Idempotent.**
+     *
+     * Keyed on the phone number, so calling it on every login is safe and is the
+     * intended usage — retries cannot produce a second channel.
+     *
+     * The returned `state` needs different handling in each case, and the
+     * important one is that only `accepted` can actually be woken. A `pending`
+     * recipient has been asked and has not answered: nag them in your own UI, do
+     * not re-invite them in a loop. `declined` is terminal — no API re-invites a
+     * declined number, and only they can undo it from their own app.
+     *
+     * Inviting is deliberately separate from alerting: **an alert must never be
+     * what invites somebody**, because an invited person is not an M91 user yet
+     * and the urgent thing would arrive as an ordinary message that does not
+     * pierce Do Not Disturb, does not repeat and does not escalate.
+     *
+     * `label` is **the name the person sees on the alert**, not a name for the
+     * person. It is the only thing on their screen saying where the alert came
+     * from, so it should be your product — "Acme CRM", not "Priya" and not an id.
+     * Woken at 3am, "Acme CRM" answers the question they have and their own name
+     * does not.
+     *
+     * Two things follow, and both bite: it defaults to `"Direct alerts"` when
+     * omitted, and **every invite overwrites it**. Since this call belongs in
+     * your login handler, omitting the label on the second login resets a good
+     * name back to the default. Pass the same constant every time.
+     */
+    async inviteRecipient(phone, label) {
+        const body = { phone: validatePhone(phone) };
+        if (label !== undefined && label !== null && collapse(label))
+            body.label = collapse(label);
+        return parseRecipient(await this.http.request({ method: 'POST', url: this.url('/recipients'), body }));
+    }
+    /**
+     * Stop alerting somebody. `true` when they are no longer a recipient.
+     *
+     * Worth wiring to whatever your system calls offboarding. Nothing in an
+     * integration is as routinely forgotten, and forgetting it means somebody who
+     * left the company is still woken at 3am.
+     */
+    async removeRecipient(phone) {
+        return this.tolerateMissing({
+            method: 'DELETE',
+            url: this.url(`/recipients/${encodeURIComponent(validatePhone(phone))}`),
+        });
+    }
+    /**
+     * Wake one person. They must have been invited **and have accepted**.
+     *
+     * Alerting a number nobody invited throws `M91NotFoundError`, never a silent
+     * invitation.
+     *
+     * A direct alert *is* a channel with one member, so responses, escalation,
+     * deduplication and the consent gate behave exactly as they do for a team —
+     * there is no second implementation to keep in step.
+     */
+    async alertPerson(phone, title, options = {}) {
+        const body = buildAlertPayload(title, options);
+        body.phone = validatePhone(phone);
+        const alert = parseAlertResponse(await this.http.request({ method: 'POST', url: this.url('/alerts'), body }));
+        // The same guard the send link gets. A person who reinstalled their phone
+        // still has an account and still shows as an accepted recipient, so this
+        // path answers 201 with delivered: 0 and looks exactly like success — and
+        // with one recipient there is nobody else it reached.
+        checkDelivery(alert, this.throwOnZeroDelivery);
+        return alert;
+    }
+    /**
+     * Read back what one person decided. `null` if there is no such alert.
+     * `alertId` is the `customId` you invented or the `_id` a send returned.
+     */
+    async getAlert(alertId, phone) {
+        try {
+            const raw = await this.http.request({
+                method: 'GET',
+                url: this.url(`/alerts/${encodeURIComponent(String(alertId))}`),
+                query: { phone: validatePhone(phone) },
+            });
+            return parseAlertDetail(raw);
+        }
+        catch (error) {
+            if (error instanceof M91NotFoundError)
+                return null;
+            throw error;
+        }
+    }
+    /**
+     * Close one person's alert.
+     *
+     * **404 and 403 are success**, as on the send link: "no such alert" and
+     * "already resolved" both mean it is not open, which is what was asked for.
+     */
+    async closeAlert(phone, options) {
+        const { customId, alertId } = options ?? {};
+        if (Boolean(customId) === Boolean(alertId)) {
+            throw new M91ValidationError(`closeAlert() needs exactly one of customId or alertId — got ${customId ? 'both' : 'neither'}`);
+        }
+        try {
+            await this.http.request({
+                method: 'POST',
+                url: this.url('/alerts/close'),
+                body: { phone: validatePhone(phone), ...(customId ? { customId } : { alertId }) },
+            });
+        }
+        catch (error) {
+            // 403 as well as 404, matching M91Client.close(). Production answers 403
+            // `already_resolved` when the alert is closed already, and "it is closed"
+            // is the state the caller asked for. Only close gets this: on a REMOVE a
+            // 403 means the channel is not yours, which must not be swallowed.
+            if (error instanceof M91NotFoundError || error instanceof M91ForbiddenError)
+                return true;
+            throw error;
+        }
+        return true;
+    }
+    /**
+     * Create a team channel and get back the send link that alerts it.
+     *
+     * **Not idempotent, and deliberately takes no id of your own to make it so.**
+     * Calling this twice makes two channels. Store the returned `id` and
+     * `sendLink` against your own team the moment you get them — a lost response
+     * is an orphaned channel, not something to retry.
+     *
+     * `alertOwner: false` skips adding the key's owner as a member: a platform
+     * minting one channel per customer team has no reason for its own account to
+     * be paged for every one of them. They stay the owner either way.
+     */
+    /**
+     * Every team channel this key can raise an alert on.
+     *
+     * The missing half of {@link createChannel}, which is **not idempotent**: a
+     * platform that lost the response to a create had an orphaned channel and no
+     * way to find it. Now it can read back what it already has.
+     *
+     * **Scoped by send access, not by ownership.** Every row carries a
+     * `sendLink`, so the list answers "what can I alert?" — which includes a
+     * channel whose owner granted this person send access, not only the ones they
+     * created. Creating a channel grants its owner send access too, so owned
+     * channels are a subset of this rather than a separate case.
+     *
+     * Channels they merely joined stay absent: being a member means you get
+     * woken, not that you may wake others. Archived channels are left out, since
+     * a link that cannot alert anybody is worse than no link.
+     */
+    async listChannels() {
+        const rows = await this.http.request({ method: 'GET', url: this.url('/channels') });
+        return (Array.isArray(rows) ? rows : []).map(parseProvisionedChannel);
+    }
+    async createChannel(name, alertOwner = true) {
+        const clean = collapse(name ?? '');
+        if (!clean)
+            throw new M91ValidationError('channel name is required');
+        if (clean.length > CHANNEL_NAME_MAX) {
+            throw new M91ValidationError(`channel name must be ${CHANNEL_NAME_MAX} characters or fewer, got ${clean.length}`);
+        }
+        return parseProvisionedChannel(await this.http.request({
+            method: 'POST',
+            url: this.url('/channels'),
+            body: { name: clean, alertOwner: alertOwner !== false },
+        }));
+    }
+    /**
+     * Invite people into a team channel. Up to 500 per call.
+     *
+     * Adding somebody to the roster is not the same as being able to alert them:
+     * they are invited, and an invitation is theirs to accept.
+     */
+    async addMembers(channelId, phones) {
+        return parseInviteResult(await this.http.request({
+            method: 'POST',
+            url: this.url(`/channels/${encodeURIComponent(String(channelId))}/members`),
+            body: { phones: checkPhones(phones) },
+        }));
+    }
+    /** Take somebody off a team channel's roster. */
+    async removeMember(channelId, phone) {
+        return this.tolerateMissing({
+            method: 'DELETE',
+            url: this.url(`/channels/${encodeURIComponent(String(channelId))}/members/${encodeURIComponent(validatePhone(phone))}`),
+        });
+    }
+    /** Already-not-there is the state the caller asked for. */
+    async tolerateMissing(request) {
+        try {
+            await this.http.request(request);
+        }
+        catch (error) {
+            if (error instanceof M91NotFoundError)
+                return true;
+            throw error;
+        }
+        return true;
+    }
+}
+/**
+ * An API key is told apart from a mobile JWT by its prefix, server-side. So a
+ * key without it never reaches the key verifier at all, and comes back as a
+ * bare 401 that looks like revocation. Checked here to say what is actually
+ * wrong.
+ */
+export function checkApiKey(apiKey) {
+    const key = String(apiKey ?? '').trim();
+    if (!key)
+        throw new M91ValidationError('apiKey is required');
+    if (!key.startsWith(API_KEY_PREFIX)) {
+        throw new M91ValidationError(`apiKey must start with '${API_KEY_PREFIX}' — mint one in the M91 app. ` +
+            'A mobile JWT will not work here.');
+    }
+    return key;
+}
+export function checkPhones(phones) {
+    if (!phones?.length)
+        throw new M91ValidationError('phones needs at least one number');
+    if (phones.length > MAX_MEMBERS_PER_CALL) {
+        throw new M91ValidationError(`cannot invite more than ${MAX_MEMBERS_PER_CALL} numbers at once, got ${phones.length}. ` +
+            'Send them in batches.');
+    }
+    return phones.map(validatePhone);
+}
+//# sourceMappingURL=platform.js.map

package/dist/src/platform.js.map

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

package/dist/src/url-builder.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The GET form of a send: an alert spelled as a URL.
+ *
+ * This is the integration surface that needs no client at all. It goes in a
+ * browser bar, a phone shortcut, an `<img>` tag, a cron `curl`, a smart button,
+ * or any field in any tool labelled "URL to call". Somebody who has never made
+ * an HTTP request in their life can raise an alert by tapping a bookmark, and
+ * that is the difference between M91 being wired into something today and being
+ * wired in never.
+ *
+ * **A bare send link raises nothing.** It is the connection test: it answers
+ * with the channel's name so whoever pasted it can see they picked the right
+ * one. Only a URL with `?title=` fires. That is not a default nobody got round
+ * to — the token is in the path, so link previews, crawlers and mail scanners
+ * fetch these routinely, and `title` having no default is the only thing
+ * between a pasted link and a woken team.
+ */
+import { type ResponseOption, type Severity } from './models.js';
+/**
+ * Validate a send link and strip anything after the token.
+ *
+ * Callers paste these out of the app, out of a create-channel response, or out
+ * of a colleague's message, so a trailing slash, a stray query string or an
+ * already-built alert URL all arrive here. All of them normalise to the bare
+ * link.
+ */
+export declare function normalizeSendLink(sendLink: string): string;
+/**
+ * Render `respond=` from labels or response options.
+ *
+ * The compact syntax exists because `[{label, effect}]` cannot survive a query
+ * string without becoming unreadable. So: a comma-separated list where the
+ * **first label is SHARED and the rest are PERSONAL** — the shape almost every
+ * real alert has, one button that takes the job for the whole group and some
+ * number of "seen" buttons that do not. A trailing `!` forces SHARED on any
+ * label, for the caller who wants two people able to claim.
+ *
+ * Two things a link cannot express, both of which throw here rather than
+ * producing a URL that quietly does something else: a **PERSONAL first option**,
+ * and a label that genuinely **ends in `!`**. Both are reachable with a POST.
+ */
+export declare function buildRespond(labels: Array<ResponseOption | string>): string;
+export interface BuildUrlOptions {
+    description?: string;
+    severity?: Severity;
+    customId?: string;
+    /** First label is SHARED, the rest PERSONAL. Up to 6. */
+    respond?: Array<ResponseOption | string>;
+    isAutoClose?: boolean;
+}
+export interface BuildManySpec extends BuildUrlOptions {
+    title: string;
+}
+/** Builds ready-to-paste alert URLs for tools whose only field is "URL to call". */
+export declare class M91URLBuilder {
+    readonly sendLink: string;
+    constructor(sendLink: string);
+    /** The bare link. Answers with the channel name and **raises nothing**. */
+    testUrl(): string;
+    /** A full URL that raises this alert when anything opens it. */
+    build(title: string, options?: BuildUrlOptions): string;
+    /** One URL per spec. Each takes the same options as `build`. */
+    buildMany(alerts: BuildManySpec[]): string[];
+}
+//# sourceMappingURL=url-builder.d.ts.map

package/dist/src/url-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-builder.d.ts","sourceRoot":"","sources":["../../src/url-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAKL,KAAK,cAAc,EACnB,KAAK,QAAQ,EAKd,MAAM,aAAa,CAAC;AAErB;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CA+B1D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC,cAAc,GAAG,MAAM,CAAC,GAAG,MAAM,CAoD3E;AAED,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,OAAO,CAAC,EAAE,KAAK,CAAC,cAAc,GAAG,MAAM,CAAC,CAAC;IACzC,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,aAAc,SAAQ,eAAe;IACpD,KAAK,EAAE,MAAM,CAAC;CACf;AAED,oFAAoF;AACpF,qBAAa,aAAa;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,QAAQ,EAAE,MAAM;IAI5B,2EAA2E;IAC3E,OAAO,IAAI,MAAM;IAIjB,gEAAgE;IAChE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,MAAM;IA+C3D,gEAAgE;IAChE,SAAS,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,EAAE;CAQ7C"}

package/dist/src/url-builder.js

@@ -0,0 +1,167 @@
+/**
+ * The GET form of a send: an alert spelled as a URL.
+ *
+ * This is the integration surface that needs no client at all. It goes in a
+ * browser bar, a phone shortcut, an `<img>` tag, a cron `curl`, a smart button,
+ * or any field in any tool labelled "URL to call". Somebody who has never made
+ * an HTTP request in their life can raise an alert by tapping a bookmark, and
+ * that is the difference between M91 being wired into something today and being
+ * wired in never.
+ *
+ * **A bare send link raises nothing.** It is the connection test: it answers
+ * with the channel's name so whoever pasted it can see they picked the right
+ * one. Only a URL with `?title=` fires. That is not a default nobody got round
+ * to — the token is in the path, so link previews, crawlers and mail scanners
+ * fetch these routinely, and `title` having no default is the only thing
+ * between a pasted link and a woken team.
+ */
+import { M91ValidationError } from './exceptions.js';
+import { CUSTOM_ID_MAX, DESCRIPTION_MAX, LABEL_MAX, MAX_LINK_RESPONSE_OPTIONS, TITLE_MAX, TITLE_MIN, checkSeverity, collapse, } from './models.js';
+/**
+ * Validate a send link and strip anything after the token.
+ *
+ * Callers paste these out of the app, out of a create-channel response, or out
+ * of a colleague's message, so a trailing slash, a stray query string or an
+ * already-built alert URL all arrive here. All of them normalise to the bare
+ * link.
+ */
+export function normalizeSendLink(sendLink) {
+    if (!sendLink || typeof sendLink !== 'string') {
+        throw new M91ValidationError('sendLink is required — the full https://…/s/<token> URL');
+    }
+    let parsed;
+    try {
+        parsed = new URL(sendLink.trim());
+    }
+    catch {
+        throw new M91ValidationError(`sendLink must be a full URL beginning http:// or https://, got '${sendLink}'`);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new M91ValidationError(`sendLink must be a full URL beginning http:// or https://, got '${sendLink}'`);
+    }
+    const segments = parsed.pathname.split('/').filter(Boolean);
+    // Checked because the failure it prevents is silent: a URL without a token
+    // authenticates as nothing and every call 401s, which reads like a revoked
+    // link rather than a mistyped one.
+    if (segments.length < 2 || segments[segments.length - 2] !== 's') {
+        throw new M91ValidationError(`sendLink must look like https://m91-api.msg91.com/s/<token> — ` +
+            `no /s/<token> found in '${parsed.pathname}'`);
+    }
+    return `${parsed.origin}/${segments.join('/')}`;
+}
+/**
+ * Render `respond=` from labels or response options.
+ *
+ * The compact syntax exists because `[{label, effect}]` cannot survive a query
+ * string without becoming unreadable. So: a comma-separated list where the
+ * **first label is SHARED and the rest are PERSONAL** — the shape almost every
+ * real alert has, one button that takes the job for the whole group and some
+ * number of "seen" buttons that do not. A trailing `!` forces SHARED on any
+ * label, for the caller who wants two people able to claim.
+ *
+ * Two things a link cannot express, both of which throw here rather than
+ * producing a URL that quietly does something else: a **PERSONAL first option**,
+ * and a label that genuinely **ends in `!`**. Both are reachable with a POST.
+ */
+export function buildRespond(labels) {
+    const rendered = labels.map((entry, index) => {
+        let label;
+        let marker = '';
+        if (typeof entry === 'string') {
+            label = collapse(entry);
+        }
+        else {
+            label = collapse(entry?.label ?? '');
+            const shared = (entry?.effect ?? 'SHARED') === 'SHARED';
+            if (index === 0 && !shared) {
+                throw new M91ValidationError(`the first response option in a link is always SHARED — '${label}' cannot be ` +
+                    'PERSONAL here. Use POST with responseOptions.');
+            }
+            marker = shared && index > 0 ? '!' : '';
+        }
+        if (!label)
+            throw new M91ValidationError('respond labels cannot be empty');
+        if (label.includes(',')) {
+            // The separator is a comma, so a label containing one would silently
+            // become two buttons — an alert offering "Restart" and "then page Ana"
+            // as separate answers.
+            throw new M91ValidationError(`a respond label cannot contain a comma — it is the separator. ` +
+                `Use POST with responseOptions for '${label}'.`);
+        }
+        const bare = label.replace(/!+$/, '').trim();
+        if (bare.length > LABEL_MAX) {
+            throw new M91ValidationError(`response label must be ${LABEL_MAX} characters or fewer, got '${label}'`);
+        }
+        return { rendered: label + marker, key: bare.toLowerCase() };
+    });
+    if (rendered.length > MAX_LINK_RESPONSE_OPTIONS) {
+        throw new M91ValidationError(`a link can carry at most ${MAX_LINK_RESPONSE_OPTIONS} response labels, ` +
+            `got ${rendered.length}. Use POST for more.`);
+    }
+    const seen = new Set();
+    for (const { rendered: text, key } of rendered) {
+        if (seen.has(key)) {
+            throw new M91ValidationError(`cannot repeat the same response label twice: '${text}'`);
+        }
+        seen.add(key);
+    }
+    return rendered.map((r) => r.rendered).join(',');
+}
+/** Builds ready-to-paste alert URLs for tools whose only field is "URL to call". */
+export class M91URLBuilder {
+    sendLink;
+    constructor(sendLink) {
+        this.sendLink = normalizeSendLink(sendLink);
+    }
+    /** The bare link. Answers with the channel name and **raises nothing**. */
+    testUrl() {
+        return this.sendLink;
+    }
+    /** A full URL that raises this alert when anything opens it. */
+    build(title, options = {}) {
+        const cleanTitle = collapse(title ?? '');
+        if (!cleanTitle || cleanTitle.length < TITLE_MIN) {
+            throw new M91ValidationError(`title must be at least ${TITLE_MIN} characters, got '${title}'`);
+        }
+        if (cleanTitle.length > TITLE_MAX) {
+            throw new M91ValidationError(`title must be ${TITLE_MAX} characters or fewer, got ${cleanTitle.length}`);
+        }
+        const severity = checkSeverity(options.severity ?? 'MEDIUM');
+        const query = new URLSearchParams();
+        query.set('title', cleanTitle);
+        if (options.description !== undefined && options.description !== null) {
+            const description = collapse(options.description);
+            if (description.length > DESCRIPTION_MAX) {
+                throw new M91ValidationError(`description must be ${DESCRIPTION_MAX} characters or fewer, got ${description.length}`);
+            }
+            query.set('description', description);
+        }
+        // MEDIUM is the server's default, so spelling it costs URL length and buys
+        // nothing. These get pasted into text boxes and retyped by hand.
+        if (severity !== 'MEDIUM')
+            query.set('severity', severity);
+        if (options.customId !== undefined && options.customId !== null) {
+            const customId = collapse(String(options.customId));
+            if (customId.length > CUSTOM_ID_MAX) {
+                throw new M91ValidationError(`customId must be ${CUSTOM_ID_MAX} characters or fewer, got ${customId.length}`);
+            }
+            query.set('customId', customId);
+        }
+        if (options.respond?.length)
+            query.set('respond', buildRespond(options.respond));
+        if (options.isAutoClose !== undefined) {
+            query.set('isAutoClose', options.isAutoClose ? 'true' : 'false');
+        }
+        return `${this.sendLink}?${query.toString()}`;
+    }
+    /** One URL per spec. Each takes the same options as `build`. */
+    buildMany(alerts) {
+        return alerts.map(({ title, ...options }) => {
+            if (title === undefined) {
+                throw new M91ValidationError("every alert in buildMany needs a 'title'");
+            }
+            return this.build(title, options);
+        });
+    }
+}
+//# sourceMappingURL=url-builder.js.map

package/dist/src/url-builder.js.map

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

package/examples/approval-gate.ts

@@ -0,0 +1,35 @@
+/**
+ * The approval gate: ask a human, on their phone, and wait.
+ *
+ * This is the shape of every human-in-the-loop decision — raise the question,
+ * block, act on the answer. One call does all of it, including closing the
+ * alert afterwards so nobody is left with a live question that has been
+ * answered.
+ */
+
+import { M91Client } from '@msg91comm/m91';
+
+const client = new M91Client(process.env.M91_SEND_LINK!);
+
+const approved = await client.requestApproval(
+  'Agent wants to process a refund of ₹48,000 for order ORD-40122',
+  {
+    description:
+      'Customer says the item never arrived. The courier\'s tracking shows delivered, ' +
+      "signed for by 'R. Kumar'. The customer's name is Rahul Kumar. " +
+      'Approving pays out immediately and cannot be reversed.',
+    customId: 'refund-ORD-40122', // stable: the order id, never a timestamp
+    severity: 'HIGH',
+    approveLabel: 'Refund',
+    rejectLabel: 'Hold',
+    timeoutMs: 300_000,
+  },
+);
+
+if (approved) {
+  console.log('A human approved it. Processing the refund.');
+} else {
+  // Rejected, or nobody answered in five minutes. Both mean: do not pay out.
+  // There is no configuration that makes silence mean yes.
+  console.log('Not approved. Leaving the refund for the morning queue.');
+}

package/examples/basic-alert.ts

@@ -0,0 +1,53 @@
+/**
+ * Raise an alert, then close it when the condition heals.
+ *
+ *   export M91_SEND_LINK="https://m91-api.msg91.com/s/your_token"
+ *   npx tsx examples/basic-alert.ts
+ *
+ * The send link is the whole credential. It goes in the environment, never in
+ * the repository — the token is in the URL path, so the URL *is* the password.
+ */
+
+import { M91Client, M91DeliveryError } from '@msg91comm/m91';
+
+const client = new M91Client(process.env.M91_SEND_LINK!);
+
+// Raises nothing. Worth doing on startup: a mistyped link otherwise looks fine
+// until the night it has to work.
+const channel = await client.verify();
+console.log(`Connected to '${channel.name}' (${channel.visibility})`);
+
+const alert = await client.send('Database disk 90% full on node-7', {
+  description: '/var/lib/postgresql at 90%. Growing ~2GB/hour. ~5 hours left.',
+  severity: 'HIGH', // HIGH also places a voice call after 45s of silence
+  // Stable: the SAME string every time this condition is true. A check running
+  // every minute then raises one alert, not sixty — and this is what closes it.
+  customId: 'disk-full-node7',
+  responseOptions: [
+    { label: 'On it', effect: 'SHARED' }, // takes it on, clears for everyone
+    { label: 'Seen', effect: 'PERSONAL' }, // acknowledges, stays with the team
+  ],
+});
+
+// Not "did the request succeed" — `delivered` is phones actually reached.
+console.log(`Delivered to ${alert.delivered} phones (alert ${alert.id})`);
+if (alert.deduplicated) {
+  console.log('An alert for this was already open — nobody was woken a second time.');
+}
+
+// ...later, when the disk has been cleared:
+await client.close({ customId: 'disk-full-node7' });
+
+// The failure worth catching by name: a 2xx where nobody's phone rang.
+try {
+  await client.send('Heartbeat check from the example', { customId: 'example-heartbeat' });
+} catch (error) {
+  if (error instanceof M91DeliveryError) {
+    console.error(
+      `Nobody was reachable: ${error.unregistered.length} unregistered, ` +
+        `${error.noDevice} without a device`,
+    );
+  } else {
+    throw error;
+  }
+}

package/examples/claude-agent-sdk.ts

@@ -0,0 +1,23 @@
+/**
+ * A Claude agent that can read anything, but rings a phone before it runs a
+ * shell command or writes a file.
+ *
+ *   M91_SEND_LINK=... ANTHROPIC_API_KEY=... npx tsx examples/claude-agent-sdk.ts
+ */
+
+import { query } from '@anthropic-ai/claude-agent-sdk';
+
+import { M91Client } from '@msg91comm/m91';
+import { createM91CanUseTool, createM91McpServer } from '@msg91comm/m91/integrations/claude-agent-sdk';
+
+const client = new M91Client(process.env.M91_SEND_LINK!);
+
+for await (const message of query({
+  prompt: 'Find the feature branches merged more than 30 days ago and delete them.',
+  options: {
+    canUseTool: createM91CanUseTool(client, { tools: ['Bash', 'Write', 'Edit'] }),
+    mcpServers: { m91: await createM91McpServer(client) },
+  },
+})) {
+  if (message.type === 'result') console.log(message);
+}