@msg91comm/m91 0.0.0-stage → 1.1.0

package/dist/src/client.js

@@ -0,0 +1,221 @@
+/**
+ * The send-link client: raise an alert, read what was decided, close it.
+ *
+ * A send link is a credential in a URL. It goes in a Grafana webhook field, a
+ * cron, a CI job or an agent's environment, and it needs no header, no account
+ * and no library — which is why this client is a convenience over one URL
+ * rather than the only way in.
+ *
+ * Two things it does that a bare `fetch` does not, and both are why it exists:
+ *
+ * - **It checks that somebody was actually reached.** A 201 means the alert was
+ *   filed, not that a phone rang.
+ * - **It reads the decision, not the responses.** Only a SHARED response decides.
+ */
+import { M91DeliveryError, M91ForbiddenError, M91NotFoundError, M91TimeoutError, M91ValidationError, } from './exceptions.js';
+import { Transport, redact } from './http.js';
+import { buildAlertPayload, isApproved, parseAlertDetail, parseAlertResponse, parseChannelInfo, } from './models.js';
+import { normalizeSendLink } from './url-builder.js';
+/**
+ * Below this, polling is a busy loop against a rate-limited endpoint and buys
+ * nothing: a human waking up and reaching for a phone is not a sub-second event.
+ */
+export const MIN_POLL_INTERVAL_MS = 2000;
+/** Alerts one channel, through one send link. */
+export class M91Client {
+    sendLink;
+    throwOnZeroDelivery;
+    http;
+    sleep;
+    now;
+    constructor(sendLink, options = {}) {
+        this.sendLink = normalizeSendLink(sendLink);
+        this.throwOnZeroDelivery = options.throwOnZeroDelivery !== false;
+        this.http = new Transport(options);
+        this.sleep = options.sleepImpl ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+        this.now = () => Date.now();
+    }
+    /** Redacted, always: a token in a log, a trace or a crash report can wake a team. */
+    toString() {
+        return `M91Client(${redact(this.sendLink)})`;
+    }
+    url(suffix = '') {
+        return this.sendLink + suffix;
+    }
+    /**
+     * Check the link works, and see which channel it points at.
+     *
+     * **Raises no alert.** Safe on startup, in a health check, or while somebody
+     * is pasting the URL into a settings page — which is the point: a mistyped
+     * link otherwise shows "connected" and only reveals itself days later, when
+     * an alert silently fails to fire.
+     */
+    async verify() {
+        return parseChannelInfo(await this.http.request({ method: 'GET', url: this.url() }));
+    }
+    /** Raise an alert on this channel. */
+    async send(title, options = {}) {
+        const payload = buildAlertPayload(title, options);
+        const alert = parseAlertResponse(await this.http.request({ method: 'POST', url: this.url(), body: payload }));
+        checkDelivery(alert, this.throwOnZeroDelivery);
+        return alert;
+    }
+    /**
+     * Read one alert back. `null` when there is no such alert on this channel.
+     *
+     * The id is **either** the `customId` you invented or the `_id` the send
+     * returned — a caller knows one of them and should not have to say which.
+     */
+    async getAlert(customIdOrAlertId) {
+        try {
+            const raw = await this.http.request({
+                method: 'GET',
+                url: this.url(`/alerts/${encodeURIComponent(String(customIdOrAlertId))}`),
+            });
+            return parseAlertDetail(raw);
+        }
+        catch (error) {
+            if (error instanceof M91NotFoundError)
+                return null;
+            throw error;
+        }
+    }
+    /**
+     * Wait until somebody takes the alert on, or the clock runs out.
+     *
+     * Resolves with the SHARED response that claimed it. **PERSONAL responses
+     * never end this wait** — a "Seen" is an acknowledgement, not an answer, and
+     * treating it as one is the mistake `decision` exists to prevent.
+     *
+     * Stops early and resolves `null` if the alert is closed without ever being
+     * claimed: there is nothing left to wait for.
+     */
+    async waitForDecision(customId, options = {}) {
+        const timeoutMs = options.timeoutMs ?? 300_000;
+        const requested = options.pollIntervalMs ?? 5000;
+        if (requested < MIN_POLL_INTERVAL_MS) {
+            console.warn(`[m91] pollIntervalMs=${requested} is below ${MIN_POLL_INTERVAL_MS}. The send link is ` +
+                `rate limited to 60 requests a minute and a person cannot answer that fast; ` +
+                `using ${MIN_POLL_INTERVAL_MS}ms instead.`);
+        }
+        const interval = Math.max(requested, MIN_POLL_INTERVAL_MS);
+        const deadline = this.now() + timeoutMs;
+        for (;;) {
+            const verdict = waitVerdict(await this.getAlert(customId));
+            if (verdict.stop)
+                return verdict.decision;
+            const remaining = deadline - this.now();
+            if (remaining <= 0) {
+                if (options.throwOnTimeout)
+                    throw new M91TimeoutError(customId, timeoutMs);
+                return null;
+            }
+            await this.sleep(Math.min(interval, remaining));
+        }
+    }
+    /**
+     * Close an alert this link raised. Always `true` when there is nothing open.
+     *
+     * A monitor that sees the problem heal closes it itself rather than waiting
+     * for a person to wake up and notice.
+     *
+     * **404 and 403 are success.** "No such alert" and "not yours to close" both
+     * mean the alert is not open on this channel, which is the state the caller
+     * asked for. Anything else would make every close a branch, and every retry
+     * after a dropped response a false failure.
+     */
+    async close(options) {
+        const { customId, alertId } = options ?? {};
+        if (Boolean(customId) === Boolean(alertId)) {
+            throw new M91ValidationError(`close() needs exactly one of customId or alertId — got ${customId ? 'both' : 'neither'}`);
+        }
+        try {
+            await this.http.request({
+                method: 'POST',
+                url: this.url('/close'),
+                body: customId ? { customId } : { alertId },
+            });
+        }
+        catch (error) {
+            if (error instanceof M91NotFoundError || error instanceof M91ForbiddenError)
+                return true;
+            throw error;
+        }
+        return true;
+    }
+    /**
+     * Ask a human, on their phone, and wait for the answer. `true` = approved.
+     *
+     * The shape of every human-in-the-loop gate: raise the question, block, act
+     * on the answer, close the alert either way. Severity defaults to HIGH here —
+     * unlike `send` — because something is *waiting* on the answer, so a phone
+     * call after 45 seconds of silence is the point rather than an escalation.
+     *
+     * Both labels are SHARED: approving and rejecting are each a final answer
+     * that settles the question for everybody, and neither is an "I saw it".
+     *
+     * On timeout with `timeoutMeansReject` (the default) it resolves false —
+     * nobody answered, so nothing consequential happens. Set it false to get
+     * `M91TimeoutError` instead. There is deliberately no way to make a timeout
+     * mean approved.
+     */
+    async requestApproval(title, options) {
+        const { customId, description, severity = 'HIGH', approveLabel = 'Approve', rejectLabel = 'Reject', timeoutMs = 300_000, pollIntervalMs = 5000, timeoutMeansReject = true, } = options;
+        await this.send(title, {
+            description,
+            severity,
+            customId,
+            isAutoClose: false,
+            responseOptions: [
+                { label: approveLabel, effect: 'SHARED' },
+                { label: rejectLabel, effect: 'SHARED' },
+            ],
+        });
+        try {
+            const decision = await this.waitForDecision(customId, { timeoutMs, pollIntervalMs });
+            if (decision === null) {
+                if (!timeoutMeansReject)
+                    throw new M91TimeoutError(customId, timeoutMs);
+                return false;
+            }
+            return isApproved(decision, approveLabel);
+        }
+        finally {
+            // Answered or not, the question is no longer live. Left open, a rejected
+            // deploy keeps somebody's phone in the "needs attention" list for an
+            // action that already resolved.
+            await this.close({ customId });
+        }
+    }
+}
+/**
+ * A 2xx that woke nobody is a failure, and only the caller can decide what to do.
+ *
+ * `delivered` counts phones actually sent to, so this fires when a channel's
+ * devices are all stale or its members have not installed the app — a case that
+ * answers 201 and looks exactly like success.
+ */
+export function checkDelivery(alert, enabled) {
+    if (!enabled || alert.actuallyReachedSomeone)
+        return;
+    throw new M91DeliveryError(`The alert was filed but reached nobody: delivered=0, ` +
+        `unregistered=${alert.unregistered.length}, noDevice=${alert.noDevice}, ` +
+        `pending=${alert.pending}. Nobody's phone rang.`, alert.delivered, alert.unregistered, alert.noDevice, alert.pending);
+}
+/**
+ * Whether one poll ends the wait. Pure, so the rule lives in one place.
+ */
+export function waitVerdict(detail) {
+    // Not visible yet. A send answers before the fan-out finishes, so an
+    // immediate read can outrun it; keep waiting rather than calling it gone.
+    if (detail === null)
+        return { stop: false, decision: null };
+    if (detail.decision !== null)
+        return { stop: true, decision: detail.decision };
+    // Closed with nobody having claimed it — by a monitor that saw the problem
+    // heal, or by hand. There is no answer coming.
+    if (detail.isClosed)
+        return { stop: true, decision: null };
+    return { stop: false, decision: null };
+}
+//# sourceMappingURL=client.js.map

package/dist/src/client.js.map

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

package/dist/src/exceptions.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Every failure the SDK can throw, and the one place an HTTP response becomes one.
+ *
+ * Branch on `.code` — a stable string the API contract pins down — never on
+ * `.message`, which is written for a person reading a terminal and is expected
+ * to change.
+ */
+export declare class M91Error extends Error {
+    readonly code: string;
+    readonly statusCode?: number;
+    readonly details?: unknown;
+    constructor(message: string, code?: string, statusCode?: number, details?: unknown);
+}
+/**
+ * 400/413. The request was wrong, and it is never retried.
+ *
+ * Also thrown locally, before any HTTP call, when a field breaks a documented
+ * limit. Every schema server-side is `.strict()`, so a mistyped field name is a
+ * 400 rather than a silent drop — and a round trip to learn that is a round
+ * trip wasted.
+ */
+export declare class M91ValidationError extends M91Error {
+    constructor(message: string, details?: unknown, statusCode?: number, code?: string);
+}
+/** 401. Credential invalid, expired or revoked — nothing is cached server-side. */
+export declare class M91AuthError extends M91Error {
+    constructor(message?: string, details?: unknown);
+}
+/** 403. Authenticated, but not allowed. On `close()` this means success. */
+export declare class M91ForbiddenError extends M91Error {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * 404. Absent — **or present and not yours**. The API answers the same way to
+ * both on purpose, so an id cannot become an oracle for what exists.
+ */
+export declare class M91NotFoundError extends M91Error {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * 409. The channel has nobody who can actually be woken.
+ *
+ * `unregistered` is the invited numbers with no M91 account — invited, never
+ * installed the app, and unreachable. An ordinary SMS would not pierce Do Not
+ * Disturb, would not repeat, and would not escalate.
+ */
+export declare class M91ChannelEmptyError extends M91Error {
+    readonly unregistered: string[];
+    constructor(message: string, unregistered?: string[], details?: unknown);
+}
+/**
+ * 429. 60 sends a minute per send link.
+ *
+ * `retryAfter` always has a value: the server sets `Retry-After` on every 429
+ * precisely so a caller does not have to guess, and the usual guess is to retry
+ * immediately and forever.
+ */
+export declare class M91RateLimitError extends M91Error {
+    readonly retryAfter: number;
+    constructor(message?: string, retryAfter?: number, details?: unknown);
+}
+/** 5xx. Not the caller's fault. Retried with backoff before it reaches you. */
+export declare class M91ServerError extends M91Error {
+    constructor(message?: string, statusCode?: number, details?: unknown);
+}
+/**
+ * The request never got an answer — DNS, TLS, connect or read timeout.
+ *
+ * Not retried. A send that timed out may or may not have raised an alert, and
+ * retrying it blindly is how one condition wakes a team four times.
+ */
+export declare class M91NetworkError extends M91Error {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * The API said 2xx and **nobody's phone rang**.
+ *
+ * The failure mode integrations actually hit, and it is invisible if you only
+ * check the status code. `delivered` counts phones sent to, not the size of the
+ * roster: a channel of four whose device tokens are all stale answers 201 with
+ * `delivered: 0`.
+ *
+ * A *deduplicated* send is not this error — `delivered` is 0 because the same
+ * alert is already open and already ringing, which is success.
+ */
+export declare class M91DeliveryError extends M91Error {
+    readonly delivered: number;
+    readonly unregistered: string[];
+    readonly noDevice: number;
+    readonly pending: number;
+    constructor(message: string, delivered?: number, unregistered?: string[], noDevice?: number, pending?: number);
+}
+/** `waitForDecision` ran out of time with no SHARED response. Nobody answered. */
+export declare class M91TimeoutError extends M91Error {
+    readonly customId: string;
+    readonly timeoutMs: number;
+    constructor(customId: string, timeoutMs: number);
+}
+/**
+ * Turn one HTTP response into either the payload or a thrown error.
+ *
+ * **Every M91 route answers in an envelope** — `{ success: true, data }` or
+ * `{ success: false, error: { code, message, details } }` — and this is the only
+ * place the SDK knows that. Everything above this line sees the inner `data`.
+ *
+ * The error class is chosen by HTTP status rather than by `error.code`, because
+ * the status is what the server derives the code from in the first place;
+ * keeping them in step in two places is how they drift apart. The body's `code`
+ * is still carried onto the error.
+ */
+export declare function unwrap(status: number, body: unknown, headers?: Headers | Record<string, string>): unknown;
+/** Seconds from `Retry-After`, or undefined. Header lookups are case-insensitive. */
+export declare function retryAfter(headers?: Headers | Record<string, string>): number | undefined;
+//# sourceMappingURL=exceptions.d.ts.map

package/dist/src/exceptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exceptions.d.ts","sourceRoot":"","sources":["../../src/exceptions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;gBAEf,OAAO,EAAE,MAAM,EAAE,IAAI,SAAc,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAUxF;AAED;;;;;;;GAOG;AACH,qBAAa,kBAAmB,SAAQ,QAAQ;gBAClC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,UAAU,SAAM,EAAE,IAAI,SAAqB;CAG5F;AAED,mFAAmF;AACnF,qBAAa,YAAa,SAAQ,QAAQ;gBAC5B,OAAO,SAAiB,EAAE,OAAO,CAAC,EAAE,OAAO;CAGxD;AAED,4EAA4E;AAC5E,qBAAa,iBAAkB,SAAQ,QAAQ;gBACjC,OAAO,SAAc,EAAE,OAAO,CAAC,EAAE,OAAO;CAGrD;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,QAAQ;gBAChC,OAAO,SAAc,EAAE,OAAO,CAAC,EAAE,OAAO;CAGrD;AAED;;;;;;GAMG;AACH,qBAAa,oBAAqB,SAAQ,QAAQ;IAChD,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC;gBAEpB,OAAO,EAAE,MAAM,EAAE,YAAY,GAAE,MAAM,EAAO,EAAE,OAAO,CAAC,EAAE,OAAO;CAI5E;AAED;;;;;;GAMG;AACH,qBAAa,iBAAkB,SAAQ,QAAQ;IAC7C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,OAAO,SAAiB,EAAE,UAAU,SAAK,EAAE,OAAO,CAAC,EAAE,OAAO;CAIzE;AAED,+EAA+E;AAC/E,qBAAa,cAAe,SAAQ,QAAQ;gBAC9B,OAAO,SAA0B,EAAE,UAAU,SAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAGnF;AAED;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;gBAC/B,OAAO,SAAkB,EAAE,OAAO,CAAC,EAAE,OAAO;CAGzD;AAED;;;;;;;;;;GAUG;AACH,qBAAa,gBAAiB,SAAQ,QAAQ;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAGvB,OAAO,EAAE,MAAM,EACf,SAAS,SAAI,EACb,YAAY,GAAE,MAAM,EAAO,EAC3B,QAAQ,SAAI,EACZ,OAAO,SAAI;CAQd;AAED,kFAAkF;AAClF,qBAAa,eAAgB,SAAQ,QAAQ;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAQhD;AAQD;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CA8BzG;AAOD,qFAAqF;AACrF,wBAAgB,UAAU,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,SAAS,CAWzF"}

package/dist/src/exceptions.js

@@ -0,0 +1,199 @@
+/**
+ * Every failure the SDK can throw, and the one place an HTTP response becomes one.
+ *
+ * Branch on `.code` — a stable string the API contract pins down — never on
+ * `.message`, which is written for a person reading a terminal and is expected
+ * to change.
+ */
+export class M91Error extends Error {
+    code;
+    statusCode;
+    details;
+    constructor(message, code = 'M91_ERROR', statusCode, details) {
+        super(message);
+        this.name = new.target.name;
+        this.code = code;
+        this.statusCode = statusCode;
+        this.details = details;
+        // Without this, `err instanceof M91ValidationError` is false when the
+        // package is compiled down to ES5 by a consumer's bundler.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * 400/413. The request was wrong, and it is never retried.
+ *
+ * Also thrown locally, before any HTTP call, when a field breaks a documented
+ * limit. Every schema server-side is `.strict()`, so a mistyped field name is a
+ * 400 rather than a silent drop — and a round trip to learn that is a round
+ * trip wasted.
+ */
+export class M91ValidationError extends M91Error {
+    constructor(message, details, statusCode = 400, code = 'VALIDATION_ERROR') {
+        super(message, code, statusCode, details);
+    }
+}
+/** 401. Credential invalid, expired or revoked — nothing is cached server-side. */
+export class M91AuthError extends M91Error {
+    constructor(message = 'Unauthorized', details) {
+        super(message, 'UNAUTHORIZED', 401, details);
+    }
+}
+/** 403. Authenticated, but not allowed. On `close()` this means success. */
+export class M91ForbiddenError extends M91Error {
+    constructor(message = 'Forbidden', details) {
+        super(message, 'FORBIDDEN', 403, details);
+    }
+}
+/**
+ * 404. Absent — **or present and not yours**. The API answers the same way to
+ * both on purpose, so an id cannot become an oracle for what exists.
+ */
+export class M91NotFoundError extends M91Error {
+    constructor(message = 'Not found', details) {
+        super(message, 'NOT_FOUND', 404, details);
+    }
+}
+/**
+ * 409. The channel has nobody who can actually be woken.
+ *
+ * `unregistered` is the invited numbers with no M91 account — invited, never
+ * installed the app, and unreachable. An ordinary SMS would not pierce Do Not
+ * Disturb, would not repeat, and would not escalate.
+ */
+export class M91ChannelEmptyError extends M91Error {
+    unregistered;
+    constructor(message, unregistered = [], details) {
+        super(message, 'CHANNEL_EMPTY', 409, details);
+        this.unregistered = unregistered;
+    }
+}
+/**
+ * 429. 60 sends a minute per send link.
+ *
+ * `retryAfter` always has a value: the server sets `Retry-After` on every 429
+ * precisely so a caller does not have to guess, and the usual guess is to retry
+ * immediately and forever.
+ */
+export class M91RateLimitError extends M91Error {
+    retryAfter;
+    constructor(message = 'Rate limited', retryAfter = 60, details) {
+        super(message, 'RATE_LIMITED', 429, details);
+        this.retryAfter = retryAfter;
+    }
+}
+/** 5xx. Not the caller's fault. Retried with backoff before it reaches you. */
+export class M91ServerError extends M91Error {
+    constructor(message = 'Internal server error', statusCode = 500, details) {
+        super(message, 'INTERNAL_ERROR', statusCode, details);
+    }
+}
+/**
+ * The request never got an answer — DNS, TLS, connect or read timeout.
+ *
+ * Not retried. A send that timed out may or may not have raised an alert, and
+ * retrying it blindly is how one condition wakes a team four times.
+ */
+export class M91NetworkError extends M91Error {
+    constructor(message = 'Network error', details) {
+        super(message, 'NETWORK_ERROR', undefined, details);
+    }
+}
+/**
+ * The API said 2xx and **nobody's phone rang**.
+ *
+ * The failure mode integrations actually hit, and it is invisible if you only
+ * check the status code. `delivered` counts phones sent to, not the size of the
+ * roster: a channel of four whose device tokens are all stale answers 201 with
+ * `delivered: 0`.
+ *
+ * A *deduplicated* send is not this error — `delivered` is 0 because the same
+ * alert is already open and already ringing, which is success.
+ */
+export class M91DeliveryError extends M91Error {
+    delivered;
+    unregistered;
+    noDevice;
+    pending;
+    constructor(message, delivered = 0, unregistered = [], noDevice = 0, pending = 0) {
+        super(message, 'DELIVERY_FAILED');
+        this.delivered = delivered;
+        this.unregistered = unregistered;
+        this.noDevice = noDevice;
+        this.pending = pending;
+    }
+}
+/** `waitForDecision` ran out of time with no SHARED response. Nobody answered. */
+export class M91TimeoutError extends M91Error {
+    customId;
+    timeoutMs;
+    constructor(customId, timeoutMs) {
+        super(`Nobody answered '${customId}' within ${Math.round(timeoutMs / 1000)}s. The alert is still open.`, 'TIMEOUT');
+        this.customId = customId;
+        this.timeoutMs = timeoutMs;
+    }
+}
+/**
+ * Turn one HTTP response into either the payload or a thrown error.
+ *
+ * **Every M91 route answers in an envelope** — `{ success: true, data }` or
+ * `{ success: false, error: { code, message, details } }` — and this is the only
+ * place the SDK knows that. Everything above this line sees the inner `data`.
+ *
+ * The error class is chosen by HTTP status rather than by `error.code`, because
+ * the status is what the server derives the code from in the first place;
+ * keeping them in step in two places is how they drift apart. The body's `code`
+ * is still carried onto the error.
+ */
+export function unwrap(status, body, headers) {
+    const envelope = (body ?? {});
+    const err = envelope.error ?? {};
+    const details = err.details;
+    const code = err.code;
+    if (status >= 200 && status < 300) {
+        if (envelope && typeof envelope === 'object' && 'data' in envelope)
+            return envelope.data;
+        // A route outside the envelope, or a proxy that rewrote the body. Hand it
+        // back rather than inventing a failure the server never reported.
+        return body;
+    }
+    const message = err.message || `M91 request failed with HTTP ${status}`;
+    if (status === 409 || code === 'CHANNEL_EMPTY') {
+        const unregistered = details?.unregistered ?? [];
+        throw new M91ChannelEmptyError(message, unregistered, details);
+    }
+    if (status === 429)
+        throw new M91RateLimitError(message, retryAfter(headers) ?? 60, details);
+    if (status === 400)
+        throw withCode(new M91ValidationError(message, details), code);
+    if (status === 413) {
+        throw new M91ValidationError(message, details, 413, code || 'PAYLOAD_TOO_LARGE');
+    }
+    if (status === 401)
+        throw withCode(new M91AuthError(message, details), code);
+    if (status === 403)
+        throw withCode(new M91ForbiddenError(message, details), code);
+    if (status === 404)
+        throw withCode(new M91NotFoundError(message, details), code);
+    if (status >= 500)
+        throw new M91ServerError(message, status, details);
+    throw new M91Error(message, code || 'M91_ERROR', status, details);
+}
+function withCode(error, code) {
+    if (code)
+        error.code = code;
+    return error;
+}
+/** Seconds from `Retry-After`, or undefined. Header lookups are case-insensitive. */
+export function retryAfter(headers) {
+    if (!headers)
+        return undefined;
+    const raw = typeof headers.get === 'function'
+        ? headers.get('retry-after')
+        : Object.entries(headers).find(([k]) => k.toLowerCase() === 'retry-after')?.[1];
+    if (raw === null || raw === undefined)
+        return undefined;
+    const seconds = Number(String(raw).trim());
+    return Number.isFinite(seconds) ? Math.max(0, Math.trunc(seconds)) : undefined;
+}
+//# sourceMappingURL=exceptions.js.map

package/dist/src/exceptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exceptions.js","sourceRoot":"","sources":["../../src/exceptions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,IAAI,CAAS;IACb,UAAU,CAAU;IACpB,OAAO,CAAW;IAE3B,YAAY,OAAe,EAAE,IAAI,GAAG,WAAW,EAAE,UAAmB,EAAE,OAAiB;QACrF,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,sEAAsE;QACtE,2DAA2D;QAC3D,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,kBAAmB,SAAQ,QAAQ;IAC9C,YAAY,OAAe,EAAE,OAAiB,EAAE,UAAU,GAAG,GAAG,EAAE,IAAI,GAAG,kBAAkB;QACzF,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC;CACF;AAED,mFAAmF;AACnF,MAAM,OAAO,YAAa,SAAQ,QAAQ;IACxC,YAAY,OAAO,GAAG,cAAc,EAAE,OAAiB;QACrD,KAAK,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;IAC/C,CAAC;CACF;AAED,4EAA4E;AAC5E,MAAM,OAAO,iBAAkB,SAAQ,QAAQ;IAC7C,YAAY,OAAO,GAAG,WAAW,EAAE,OAAiB;QAClD,KAAK,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,gBAAiB,SAAQ,QAAQ;IAC5C,YAAY,OAAO,GAAG,WAAW,EAAE,OAAiB;QAClD,KAAK,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,oBAAqB,SAAQ,QAAQ;IACvC,YAAY,CAAW;IAEhC,YAAY,OAAe,EAAE,eAAyB,EAAE,EAAE,OAAiB;QACzE,KAAK,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;QAC9C,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACnC,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,iBAAkB,SAAQ,QAAQ;IACpC,UAAU,CAAS;IAE5B,YAAY,OAAO,GAAG,cAAc,EAAE,UAAU,GAAG,EAAE,EAAE,OAAiB;QACtE,KAAK,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;QAC7C,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED,+EAA+E;AAC/E,MAAM,OAAO,cAAe,SAAQ,QAAQ;IAC1C,YAAY,OAAO,GAAG,uBAAuB,EAAE,UAAU,GAAG,GAAG,EAAE,OAAiB;QAChF,KAAK,CAAC,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;IACxD,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,eAAgB,SAAQ,QAAQ;IAC3C,YAAY,OAAO,GAAG,eAAe,EAAE,OAAiB;QACtD,KAAK,CAAC,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IACtD,CAAC;CACF;AAED;;;;;;;;;;GAUG;AACH,MAAM,OAAO,gBAAiB,SAAQ,QAAQ;IACnC,SAAS,CAAS;IAClB,YAAY,CAAW;IACvB,QAAQ,CAAS;IACjB,OAAO,CAAS;IAEzB,YACE,OAAe,EACf,SAAS,GAAG,CAAC,EACb,eAAyB,EAAE,EAC3B,QAAQ,GAAG,CAAC,EACZ,OAAO,GAAG,CAAC;QAEX,KAAK,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;QAClC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED,kFAAkF;AAClF,MAAM,OAAO,eAAgB,SAAQ,QAAQ;IAClC,QAAQ,CAAS;IACjB,SAAS,CAAS;IAE3B,YAAY,QAAgB,EAAE,SAAiB;QAC7C,KAAK,CACH,oBAAoB,QAAQ,YAAY,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,6BAA6B,EACjG,SAAS,CACV,CAAC;QACF,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF;AAQD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,MAAM,CAAC,MAAc,EAAE,IAAa,EAAE,OAA0C;IAC9F,MAAM,QAAQ,GAAG,CAAC,IAAI,IAAI,EAAE,CAAkB,CAAC;IAC/C,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,IAAI,EAAE,CAAC;IACjC,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;IAC5B,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IAEtB,IAAI,MAAM,IAAI,GAAG,IAAI,MAAM,GAAG,GAAG,EAAE,CAAC;QAClC,IAAI,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,MAAM,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC,IAAI,CAAC;QACzF,0EAA0E;QAC1E,kEAAkE;QAClE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,gCAAgC,MAAM,EAAE,CAAC;IAExE,IAAI,MAAM,KAAK,GAAG,IAAI,IAAI,KAAK,eAAe,EAAE,CAAC;QAC/C,MAAM,YAAY,GAAI,OAAmD,EAAE,YAAY,IAAI,EAAE,CAAC;QAC9F,MAAM,IAAI,oBAAoB,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;IACjE,CAAC;IACD,IAAI,MAAM,KAAK,GAAG;QAAE,MAAM,IAAI,iBAAiB,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;IAC7F,IAAI,MAAM,KAAK,GAAG;QAAE,MAAM,QAAQ,CAAC,IAAI,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,CAAC;IACnF,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACnB,MAAM,IAAI,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,IAAI,mBAAmB,CAAC,CAAC;IACnF,CAAC;IACD,IAAI,MAAM,KAAK,GAAG;QAAE,MAAM,QAAQ,CAAC,IAAI,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,CAAC;IAC7E,IAAI,MAAM,KAAK,GAAG;QAAE,MAAM,QAAQ,CAAC,IAAI,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,CAAC;IAClF,IAAI,MAAM,KAAK,GAAG;QAAE,MAAM,QAAQ,CAAC,IAAI,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,CAAC;IACjF,IAAI,MAAM,IAAI,GAAG;QAAE,MAAM,IAAI,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IAEtE,MAAM,IAAI,QAAQ,CAAC,OAAO,EAAE,IAAI,IAAI,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AACpE,CAAC;AAED,SAAS,QAAQ,CAAqB,KAAQ,EAAE,IAAa;IAC3D,IAAI,IAAI;QAAG,KAA0B,CAAC,IAAI,GAAG,IAAI,CAAC;IAClD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,UAAU,CAAC,OAA0C;IACnE,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAC/B,MAAM,GAAG,GACP,OAAQ,OAAmB,CAAC,GAAG,KAAK,UAAU;QAC5C,CAAC,CAAE,OAAmB,CAAC,GAAG,CAAC,aAAa,CAAC;QACzC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,OAAiC,CAAC,CAAC,IAAI,CACpD,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,aAAa,CAC3C,EAAE,CAAC,CAAC,CAAC,CAAC;IACb,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACxD,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAC3C,OAAO,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACjF,CAAC"}

package/dist/src/http.d.ts

@@ -0,0 +1,71 @@
+/**
+ * HTTP on native `fetch`, with the retry policy applied. Zero dependencies.
+ *
+ * The rules, which are the interesting part:
+ *
+ * - **429 is retried exactly once**, after exactly the delay the server asked
+ *   for. The send limit is 60/minute per link and every 429 carries
+ *   `Retry-After: 60`. Retrying a second time would be arguing with it.
+ * - **5xx is retried with backoff.** Not the caller's fault, and the alert has
+ *   not been raised, so repeating it cannot double-page anybody.
+ * - **4xx is never retried.** Not transient; the next identical request fails
+ *   identically.
+ * - **A network failure is never retried.** A send that timed out may or may not
+ *   have raised the alert — the response is what was lost, not necessarily the
+ *   request. Blind retries are how one condition wakes a team four times.
+ */
+export declare const USER_AGENT = "m91-node/1.0.0";
+/** Delays before the 2nd, 3rd and 4th attempt at a 5xx. Four requests total. */
+export declare const SERVER_BACKOFF: readonly [1000, 2000, 4000];
+export declare const RETRYABLE_STATUSES: Set<number>;
+/**
+ * A 429 whose `Retry-After` is longer than this is thrown rather than slept
+ * through. The server sends 60; anything far past that is a caller sitting
+ * blocked in an alerting path, which is worse than an error it can see.
+ */
+export declare const MAX_RETRY_AFTER_MS = 120000;
+/**
+ * Milliseconds to wait before trying again, or `null` to stop and throw.
+ * `attempt` is 1-based and counts requests already made.
+ */
+export declare function retryDelay(status: number, attempt: number, retryAfterSeconds?: number): number | null;
+/**
+ * Replace a send link's token with `***`, wherever it appears.
+ *
+ * **The token is the credential and it lives in the path**, so a URL is as
+ * sensitive as a password and must never reach a log, an error message or a
+ * stack trace intact. The server holds itself to the same rule — its error
+ * handler reports the route *pattern*, never `req.path`.
+ *
+ * This takes free text, not only a URL, and that is the point. Redacting only
+ * the URL the SDK interpolates is not enough: a fetch failure can carry the URL
+ * in its own message, so a carefully-redacted sentence would arrive with the
+ * raw token attached to it by the runtime.
+ *
+ * Query strings go too: a GET-form send carries the alert title, and titles
+ * routinely name customers and hosts.
+ */
+export declare function redact(text: string): string;
+export interface RequestOptions {
+    method: string;
+    url: string;
+    body?: unknown;
+    query?: Record<string, string>;
+}
+export interface TransportOptions {
+    /** Whole-request budget in milliseconds. Default 15s (5s connect + 10s read). */
+    timeoutMs?: number;
+    headers?: Record<string, string>;
+    /** Swappable so tests need no network and no mocking library. */
+    fetchImpl?: typeof fetch;
+    sleepImpl?: (ms: number) => Promise<void>;
+}
+export declare class Transport {
+    private readonly timeoutMs;
+    private readonly headers;
+    private readonly fetchImpl;
+    private readonly sleepImpl;
+    constructor(options?: TransportOptions);
+    request({ method, url, body, query }: RequestOptions): Promise<unknown>;
+}
+//# sourceMappingURL=http.d.ts.map

package/dist/src/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,eAAO,MAAM,UAAU,mBAAmB,CAAC;AAE3C,gFAAgF;AAChF,eAAO,MAAM,cAAc,6BAA8B,CAAC;AAE1D,eAAO,MAAM,kBAAkB,aAAgC,CAAC;AAEhE;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,SAAU,CAAC;AAE1C;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,iBAAiB,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAYrG;AASD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG3C;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,gBAAgB;IAC/B,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,iEAAiE;IACjE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C;AAID,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgC;gBAE9C,OAAO,GAAE,gBAAqB;IAepC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC;CAsC9E"}