@msg91comm/m91 0.0.0-stage → 1.1.0

package/src/http.ts

@@ -0,0 +1,174 @@
+/**
+ * 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.
+ */
+
+import { M91NetworkError, retryAfter, unwrap } from './exceptions.js';
+
+export const USER_AGENT = 'm91-node/1.0.0';
+
+/** Delays before the 2nd, 3rd and 4th attempt at a 5xx. Four requests total. */
+export const SERVER_BACKOFF = [1000, 2000, 4000] as const;
+
+export const RETRYABLE_STATUSES = new Set([500, 502, 503, 504]);
+
+/**
+ * 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 const MAX_RETRY_AFTER_MS = 120_000;
+
+/**
+ * Milliseconds to wait before trying again, or `null` to stop and throw.
+ * `attempt` is 1-based and counts requests already made.
+ */
+export function retryDelay(status: number, attempt: number, retryAfterSeconds?: number): number | null {
+  if (status === 429) {
+    // Once, and only on the first 429. A second means the window has not
+    // actually cleared and the caller needs to hear about it.
+    if (attempt >= 2) return null;
+    const wait = (retryAfterSeconds ?? 60) * 1000;
+    return wait > MAX_RETRY_AFTER_MS ? null : Math.max(wait, 0);
+  }
+  if (RETRYABLE_STATUSES.has(status)) {
+    return attempt > SERVER_BACKOFF.length ? null : SERVER_BACKOFF[attempt - 1];
+  }
+  return null;
+}
+
+/**
+ * Matches a send link anywhere — in a bare URL, or buried in a sentence — and
+ * takes any query string attached to it. Bounded on whitespace so it stops at
+ * the end of the URL rather than eating the rest of the message.
+ */
+const SEND_URL_RE = /(\/s\/)[^\s/?#]+(\?[^\s]*)?/g;
+
+/**
+ * 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 function redact(text: string): string {
+  if (typeof text !== 'string') return text;
+  return text.replace(SEND_URL_RE, '$1***');
+}
+
+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>;
+}
+
+const defaultSleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+export class Transport {
+  private readonly timeoutMs: number;
+  private readonly headers: Record<string, string>;
+  private readonly fetchImpl: typeof fetch;
+  private readonly sleepImpl: (ms: number) => Promise<void>;
+
+  constructor(options: TransportOptions = {}) {
+    this.timeoutMs = options.timeoutMs ?? 15_000;
+    this.headers = {
+      // A GET-form send answers with a rendered HTML page when the caller looks
+      // like a browser. That page exists so a person tapping a bookmark sees
+      // something other than a wall of JSON — but an SDK is not a person, and
+      // has to opt out of it explicitly.
+      accept: 'application/json',
+      'user-agent': USER_AGENT,
+      ...options.headers,
+    };
+    this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    this.sleepImpl = options.sleepImpl ?? defaultSleep;
+  }
+
+  async request({ method, url, body, query }: RequestOptions): Promise<unknown> {
+    const target = query ? `${url}?${new URLSearchParams(query).toString()}` : url;
+    let attempt = 0;
+
+    for (;;) {
+      attempt += 1;
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+
+      let status: number;
+      let headers: Headers;
+      let parsed: unknown;
+      try {
+        const response = await this.fetchImpl(target, {
+          method,
+          headers: body === undefined
+            ? this.headers
+            : { ...this.headers, 'content-type': 'application/json' },
+          body: body === undefined ? undefined : JSON.stringify(body),
+          signal: controller.signal,
+        });
+        status = response.status;
+        headers = response.headers;
+        parsed = await readBody(response);
+      } catch (error) {
+        // Redacted AFTER composing, not before: a fetch failure can name the
+        // URL in its own message, so masking only our half still ships the token.
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new M91NetworkError(redact(`Could not reach M91 at ${target}: ${reason}`));
+      } finally {
+        clearTimeout(timer);
+      }
+
+      const delay = retryDelay(status, attempt, retryAfter(headers));
+      if (delay === null) return unwrap(status, parsed, headers);
+      await this.sleepImpl(delay);
+    }
+  }
+}
+
+/**
+ * The parsed envelope, or something `unwrap` can still turn into an error.
+ *
+ * A non-JSON body here means a proxy, a load balancer or an HTML error page
+ * answered instead of M91. Wrapping the text in an envelope-shaped object keeps
+ * all the error construction in one place rather than adding a second path.
+ */
+async function readBody(response: Response): Promise<unknown> {
+  const text = await response.text();
+  if (!text) return { error: { message: `HTTP ${response.status} with an empty body` } };
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { error: { message: text.slice(0, 300) } };
+  }
+}

package/src/index.ts

@@ -0,0 +1,91 @@
+/**
+ * M91 — wake a human when software cannot carry on alone.
+ *
+ * An alert rings every phone in a channel at full volume, through silent mode
+ * and Do Not Disturb, and keeps ringing until somebody answers. HIGH and
+ * CRITICAL place a voice call if 45 seconds pass with no answer. Whoever takes
+ * it on is recorded, and it clears for everyone else.
+ *
+ * ```ts
+ * import { M91Client } from '@msg91comm/m91';
+ *
+ * const m91 = new M91Client(process.env.M91_SEND_LINK!);
+ * await m91.verify();                              // raises nothing; names the channel
+ * await m91.send('Payments API is down', { severity: 'CRITICAL', customId: 'payments-down' });
+ * await m91.close({ customId: 'payments-down' });
+ * ```
+ *
+ * And the reason an agent wants it — a question that blocks until a person
+ * answers on their phone:
+ *
+ * ```ts
+ * if (await m91.requestApproval('Refund 48,000 on ORD-40122?', { customId: 'refund-ORD-40122' })) {
+ *   await processRefund();
+ * }
+ * ```
+ *
+ * Everything here is a convenience over one URL. The send link works from a
+ * browser bar, a cron `curl` or an `<img>` tag with no client at all, and
+ * `M91URLBuilder` is for exactly those.
+ */
+
+export { M91Client } from './client.js';
+export type { ApprovalOptions, ClientOptions, SendOptions, WaitOptions } from './client.js';
+
+export { M91Platform, DEFAULT_BASE_URL } from './platform.js';
+export type { PlatformOptions } from './platform.js';
+
+export { M91URLBuilder, normalizeSendLink } from './url-builder.js';
+export type { BuildManySpec, BuildUrlOptions } from './url-builder.js';
+
+export { redact } from './http.js';
+
+export {
+  M91Error,
+  M91ValidationError,
+  M91AuthError,
+  M91ForbiddenError,
+  M91NotFoundError,
+  M91ChannelEmptyError,
+  M91RateLimitError,
+  M91ServerError,
+  M91NetworkError,
+  M91DeliveryError,
+  M91TimeoutError,
+} from './exceptions.js';
+
+export {
+  SEVERITIES,
+  EFFECTS,
+  ESCALATING_SEVERITIES,
+  isApproved,
+  validatePhone,
+  buildAlertPayload,
+} from './models.js';
+
+export type {
+  AlertDetail,
+  AlertResponse,
+  AlertStatus,
+  ApiKeyInfo,
+  ChannelInfo,
+  Attachment,
+  Decision,
+  Response,
+  Effect,
+  InviteResult,
+  ProvisionedChannel,
+  Recipient,
+  RecipientState,
+  ResponseOption,
+  Severity,
+} from './models.js';
+
+/**
+ * Kept in step with package.json by `tests/version.test.ts`, not by hand.
+ *
+ * ESM has no portable way to read package.json at runtime, so this number is
+ * written twice — and it drifted, reporting 1.0.0 while the package shipped as
+ * 1.1.0. A test is what makes two copies safe.
+ */
+export const VERSION = '1.1.0';

package/src/integrations/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Framework adapters, re-exported.
+ *
+ * Each one imports its framework lazily, so `npm install @msg91comm/m91` pulls in none of
+ * them and using one you have not installed says which package to install
+ * rather than failing with a bare module-not-found from three frames down.
+ *
+ * Importing a specific adapter directly is usually better —
+ * `@msg91comm/m91/integrations/langchain` — because it pulls in only what you use.
+ *
+ * `langchain.ts` and `vercel-ai.ts` both export `createM91ApprovalTool`, so
+ * they are re-exported under namespaces rather than flattened: two functions of
+ * the same name doing the same job for different frameworks is exactly the pair
+ * that would silently resolve to the wrong one.
+ */
+
+export * as langchain from './langchain.js';
+export * as langgraph from './langgraph.js';
+export * as vercelAi from './vercel-ai.js';
+
+export { M91InterruptNotifier, createM91ApprovalNode } from './langgraph.js';
+export { APPROVED, REJECTED, alertResult, errorResult } from './specs.js';
+export type { AlertArgs, ApprovalArgs } from './specs.js';

package/src/integrations/langchain.ts

@@ -0,0 +1,104 @@
+/**
+ * LangChain tools.
+ *
+ * Two of them, and the split matters more than it looks:
+ *
+ * - the approval tool **blocks**. The agent stops until a human answers on
+ *   their phone. Give it to an agent that can do something irreversible.
+ * - the alert tool does not. It wakes somebody and carries on.
+ *
+ * ```ts
+ * import { M91Client } from '@msg91comm/m91';
+ * import { createM91ApprovalTool, createM91AlertTool } from '@msg91comm/m91/integrations/langchain';
+ *
+ * const client = new M91Client(process.env.M91_SEND_LINK!);
+ * const tools = [
+ *   await createM91ApprovalTool(client),
+ *   await createM91AlertTool(client),
+ *   ...myTools,
+ * ];
+ * const agent = createReactAgent({ llm, tools });
+ * ```
+ *
+ * The factories are **async** because `@langchain/core` is an optional peer
+ * dependency, imported only when one of these is called. That keeps `npm
+ * install @msg91comm/m91` at zero dependencies, which matters for a package whose job is
+ * to work when everything else is on fire.
+ */
+
+import type { M91Client } from '../client.js';
+import {
+  ALERT_DESCRIPTION,
+  ALERT_SCHEMA,
+  ALERT_TOOL_NAME,
+  APPROVAL_DESCRIPTION,
+  APPROVAL_SCHEMA,
+  APPROVAL_TOOL_NAME,
+  type AlertArgs,
+  type AlertDefaults,
+  type ApprovalArgs,
+  type ApprovalDefaults,
+  runAlert,
+  runApproval,
+} from './specs.js';
+
+async function langchainTool(): Promise<(fn: unknown, config: unknown) => unknown> {
+  try {
+    // The specifier is a variable so TypeScript does not try to resolve an
+    // optional peer dependency at build time. Compiling this package must not
+    // require every framework it can adapt to.
+    const specifier = '@langchain/core/tools';
+    const mod = (await import(specifier)) as { tool: (fn: unknown, config: unknown) => unknown };
+    return mod.tool;
+  } catch (error) {
+    throw new Error(
+      'The LangChain integration needs @langchain/core. Install it with: ' +
+        'npm install @langchain/core',
+      { cause: error },
+    );
+  }
+}
+
+/**
+ * The blocking approval gate, as a LangChain tool named `m91_request_approval`.
+ * Returns `"approved"`, `"rejected"` or `"error: …"` — and nothing but a real
+ * human approval returns `"approved"`.
+ */
+export async function createM91ApprovalTool(
+  client: M91Client,
+  defaults: ApprovalDefaults = {},
+): Promise<unknown> {
+  const tool = await langchainTool();
+  return tool((args: ApprovalArgs) => runApproval(client, args, defaults), {
+    name: APPROVAL_TOOL_NAME,
+    description: APPROVAL_DESCRIPTION,
+    schema: APPROVAL_SCHEMA,
+  });
+}
+
+/**
+ * The fire-and-forget alert, as a LangChain tool named `m91_send_alert`.
+ * Returns `"sent:delivered=N"` or `"error: …"`.
+ */
+export async function createM91AlertTool(
+  client: M91Client,
+  defaults: AlertDefaults = {},
+): Promise<unknown> {
+  const tool = await langchainTool();
+  return tool((args: AlertArgs) => runAlert(client, args, defaults), {
+    name: ALERT_TOOL_NAME,
+    description: ALERT_DESCRIPTION,
+    schema: ALERT_SCHEMA,
+  });
+}
+
+/** Both, in the order an agent's `tools` array usually wants them. */
+export async function createM91Tools(
+  client: M91Client,
+  defaults: ApprovalDefaults & AlertDefaults = {},
+): Promise<unknown[]> {
+  return [
+    await createM91ApprovalTool(client, defaults),
+    await createM91AlertTool(client, defaults),
+  ];
+}

package/src/integrations/langgraph.ts

@@ -0,0 +1,142 @@
+/**
+ * LangGraph helpers for the `interrupt()` pattern.
+ *
+ * LangGraph already knows how to stop a graph and resume it. What it has no
+ * opinion about is **how the human finds out it stopped** — and the default
+ * answer is that somebody notices a paused run in a web UI. At 2am, for a graph
+ * that paused because it wants to move money, nobody does. M91 fills exactly
+ * that gap: the graph pauses, a phone rings until somebody answers, and the
+ * answer resumes the graph.
+ *
+ * Nothing here imports `@langchain/langgraph`. These are plain callables you use
+ * *around* your graph, so they work the same with `interrupt()`, with
+ * `new Command({ resume })`, or with a node you wrote by hand.
+ */
+
+import type { M91Client } from '../client.js';
+import type { Severity } from '../models.js';
+import { APPROVED, REJECTED } from './specs.js';
+
+export interface NotifyOptions {
+  title: string;
+  customId: string;
+  description?: string;
+  severity?: Severity;
+  approveLabel?: string;
+  rejectLabel?: string;
+  timeoutMs?: number;
+  pollIntervalMs?: number;
+}
+
+export type NotifyDefaults = Omit<NotifyOptions, 'title' | 'customId'>;
+
+export type Verdict = typeof APPROVED | typeof REJECTED;
+
+/**
+ * Wake a human about an interrupted graph and return what they said.
+ *
+ * ```ts
+ * const notifier = new M91InterruptNotifier(client);
+ *
+ * const result = await graph.invoke(state, config);
+ * if (result.__interrupt__) {
+ *   const data = result.__interrupt__[0].value;
+ *   const decision = await notifier.notify({
+ *     title: data.question,
+ *     customId: data.customId,
+ *     timeoutMs: 600_000,
+ *   });
+ *   await graph.invoke(new Command({ resume: decision }), config);
+ * }
+ * ```
+ *
+ * Resolves `"approved"` or `"rejected"` and **never anything else** — a failure
+ * to reach anybody comes back as `"rejected"`, because a graph that resumes
+ * with an ambiguous value resumes with whatever the node's `if` happens to do
+ * with it.
+ */
+export class M91InterruptNotifier {
+  private readonly client: M91Client;
+  private readonly defaults: NotifyDefaults;
+
+  constructor(client: M91Client, defaults: NotifyDefaults = {}) {
+    this.client = client;
+    this.defaults = defaults;
+  }
+
+  async notify(options: NotifyOptions): Promise<Verdict> {
+    const { title, customId, ...rest } = options;
+    const merged = { ...this.defaults, ...strip(rest) };
+    try {
+      const approved = await this.client.requestApproval(title, {
+        customId,
+        severity: 'HIGH',
+        timeoutMs: 300_000,
+        ...merged,
+      });
+      return approved ? APPROVED : REJECTED;
+    } catch {
+      // Nobody could be reached, so nobody approved. Resuming a graph with
+      // "approved" because the pager was down is the one outcome worth ruling
+      // out by construction.
+      return REJECTED;
+    }
+  }
+}
+
+/**
+ * Build a graph node that asks a human and writes the answer into state.
+ *
+ * ```ts
+ * builder.addNode('humanApproval', createM91ApprovalNode(client, {
+ *   approveLabel: 'Deploy Now',
+ *   rejectLabel: 'Hold Release',
+ *   timeoutMs: 600_000,
+ * }));
+ * ```
+ *
+ * The node reads `title` (or `question`) and `customId` from state and returns
+ * `{ decision, approved }` for the next edge to branch on. Anything passed here
+ * is a default the state can override per run.
+ */
+export function createM91ApprovalNode(
+  client: M91Client,
+  defaults: NotifyDefaults = {},
+): (state: unknown) => Promise<{ decision: Verdict; approved: boolean; error?: string }> {
+  const notifier = new M91InterruptNotifier(client, defaults);
+
+  return async (state: unknown) => {
+    const data = (state && typeof state === 'object' ? state : {}) as Record<string, unknown>;
+    const title = data.title ?? data.question;
+    const customId = data.customId ?? data.custom_id;
+
+    if (!title || !customId) {
+      // Said loudly rather than defaulted. A node that invents a customId is a
+      // node whose alerts never deduplicate and never close.
+      return {
+        decision: REJECTED,
+        approved: false,
+        error:
+          "error: the approval node needs 'title' (or 'question') and 'customId' in state",
+      };
+    }
+
+    const decision = await notifier.notify({
+      title: String(title),
+      customId: String(customId),
+      ...strip({
+        description: data.description as string | undefined,
+        severity: data.severity as Severity | undefined,
+        approveLabel: data.approveLabel as string | undefined,
+        rejectLabel: data.rejectLabel as string | undefined,
+        timeoutMs: data.timeoutMs as number | undefined,
+      }),
+    });
+    return { decision, approved: decision === APPROVED };
+  };
+}
+
+/** Drop undefined keys so a spread cannot blank out a default with `undefined`. */
+function strip<T extends Record<string, unknown>>(value: T): Partial<T> {
+  return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined)) as Partial<T>;
+}