@msg91comm/m91 0.0.0-stage → 1.1.0

package/src/client.ts

@@ -0,0 +1,324 @@
+/**
+ * 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, type TransportOptions, redact } from './http.js';
+import {
+  type AlertDetail,
+  type AlertResponse,
+  type ChannelInfo,
+  type Decision,
+  type ResponseOption,
+  type Severity,
+  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;
+
+export interface SendOptions {
+  description?: string;
+  /**
+   * LOW and MEDIUM deliver at alarm volume through Do Not Disturb. **HIGH and
+   * CRITICAL also place a voice call** if nobody answers in 45 seconds, so they
+   * are never the default — "I didn't specify" must not mean "ring everyone".
+   */
+  severity?: Severity;
+  /**
+   * Your own stable id for *the condition*, not for this occurrence. The same
+   * disk filling up is the same `customId` every time. Built from a timestamp
+   * or a UUID it defeats deduplication — a check running every minute raises
+   * sixty alerts an hour — and leaves nothing stable to close by.
+   */
+  customId?: string;
+  /**
+   * Left false, the alert stays open until somebody closes it, even after a
+   * SHARED response claims it. Set true when the first person taking it on is
+   * genuinely the end of the matter.
+   */
+  isAutoClose?: boolean;
+  responseOptions?: Array<ResponseOption | string>;
+  /**
+   * Whether the free-text "Something else" reply is offered. Tri-state: leave
+   * it unset and the server's default (on) stands.
+   */
+  other?: boolean;
+  /** https links to files the alert is about. URLs, never bytes. */
+  attachments?: string[];
+  /** Where the outcome is POSTed when somebody answers. */
+  callbackUrl?: string;
+}
+
+export interface WaitOptions {
+  timeoutMs?: number;
+  pollIntervalMs?: number;
+  throwOnTimeout?: boolean;
+}
+
+export interface ApprovalOptions {
+  customId: string;
+  description?: string;
+  severity?: Severity;
+  approveLabel?: string;
+  rejectLabel?: string;
+  timeoutMs?: number;
+  pollIntervalMs?: number;
+  /** A timeout returns false. There is deliberately no option making it true. */
+  timeoutMeansReject?: boolean;
+}
+
+export interface ClientOptions extends TransportOptions {
+  /**
+   * Throw `M91DeliveryError` when a send reaches nobody. On by default, because
+   * the silent version of this failure is an alert nobody ever hears about.
+   */
+  throwOnZeroDelivery?: boolean;
+}
+
+/** Alerts one channel, through one send link. */
+export class M91Client {
+  readonly sendLink: string;
+  readonly throwOnZeroDelivery: boolean;
+  private readonly http: Transport;
+  private readonly sleep: (ms: number) => Promise<void>;
+  private readonly now: () => number;
+
+  constructor(sendLink: string, options: ClientOptions = {}) {
+    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(): string {
+    return `M91Client(${redact(this.sendLink)})`;
+  }
+
+  private url(suffix = ''): string {
+    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(): Promise<ChannelInfo> {
+    return parseChannelInfo(await this.http.request({ method: 'GET', url: this.url() }));
+  }
+
+  /** Raise an alert on this channel. */
+  async send(title: string, options: SendOptions = {}): Promise<AlertResponse> {
+    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: string): Promise<AlertDetail | null> {
+    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: string, options: WaitOptions = {}): Promise<Decision | null> {
+    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: { customId?: string; alertId?: string }): Promise<boolean> {
+    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: string, options: ApprovalOptions): Promise<boolean> {
+    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: AlertResponse, enabled: boolean): void {
+  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: AlertDetail | null): { stop: boolean; decision: Decision | null } {
+  // 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 };
+}

package/src/exceptions.ts

@@ -0,0 +1,229 @@
+/**
+ * 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 {
+  readonly code: string;
+  readonly statusCode?: number;
+  readonly details?: unknown;
+
+  constructor(message: string, code = 'M91_ERROR', statusCode?: number, details?: unknown) {
+    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: string, details?: unknown, 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?: unknown) {
+    super(message, 'UNAUTHORIZED', 401, details);
+  }
+}
+
+/** 403. Authenticated, but not allowed. On `close()` this means success. */
+export class M91ForbiddenError extends M91Error {
+  constructor(message = 'Forbidden', details?: unknown) {
+    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?: unknown) {
+    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 {
+  readonly unregistered: string[];
+
+  constructor(message: string, unregistered: string[] = [], details?: unknown) {
+    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 {
+  readonly retryAfter: number;
+
+  constructor(message = 'Rate limited', retryAfter = 60, details?: unknown) {
+    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?: unknown) {
+    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?: unknown) {
+    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 {
+  readonly delivered: number;
+  readonly unregistered: string[];
+  readonly noDevice: number;
+  readonly pending: number;
+
+  constructor(
+    message: string,
+    delivered = 0,
+    unregistered: string[] = [],
+    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 {
+  readonly customId: string;
+  readonly timeoutMs: number;
+
+  constructor(customId: string, timeoutMs: number) {
+    super(
+      `Nobody answered '${customId}' within ${Math.round(timeoutMs / 1000)}s. The alert is still open.`,
+      'TIMEOUT',
+    );
+    this.customId = customId;
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+interface ErrorEnvelope {
+  success?: boolean;
+  data?: unknown;
+  error?: { code?: string; message?: string; details?: unknown };
+}
+
+/**
+ * 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: number, body: unknown, headers?: Headers | Record<string, string>): unknown {
+  const envelope = (body ?? {}) as ErrorEnvelope;
+  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 as { unregistered?: string[] } | undefined)?.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<T extends M91Error>(error: T, code?: string): T {
+  if (code) (error as { code: string }).code = code;
+  return error;
+}
+
+/** Seconds from `Retry-After`, or undefined. Header lookups are case-insensitive. */
+export function retryAfter(headers?: Headers | Record<string, string>): number | undefined {
+  if (!headers) return undefined;
+  const raw =
+    typeof (headers as Headers).get === 'function'
+      ? (headers as Headers).get('retry-after')
+      : Object.entries(headers as Record<string, string>).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;
+}