@msg91comm/m91 0.0.0-stage → 1.2.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.2.0';

package/src/integrations/claude-agent-sdk.ts

@@ -0,0 +1,158 @@
+/**
+ * Claude Agent SDK (`@anthropic-ai/claude-agent-sdk`): M91 as the permission
+ * prompt, and M91 as tools.
+ *
+ * **Permission prompt.** `createM91CanUseTool` is a `canUseTool` callback: the
+ * tools you name ring a phone and run only if a person approves. Everything
+ * else is allowed through untouched.
+ *
+ * ```ts
+ * import { query } from '@anthropic-ai/claude-agent-sdk';
+ * import { M91Client } from '@msg91comm/m91';
+ * import { createM91CanUseTool } from '@msg91comm/m91/integrations/claude-agent-sdk';
+ *
+ * const client = new M91Client(process.env.M91_SEND_LINK!);
+ *
+ * for await (const message of query({
+ *   prompt: 'Clean up the stale feature branches and deploy main.',
+ *   options: { canUseTool: createM91CanUseTool(client, { tools: ['Bash', 'Write'] }) },
+ * })) {
+ *   if (message.type === 'result') console.log(message);
+ * }
+ * ```
+ *
+ * `canUseTool` only runs when the SDK would otherwise ask. To gate a tool
+ * whatever the permission mode (including `bypassPermissions`), use the
+ * `PreToolUse` hook from `createM91PreToolUseHook` instead.
+ *
+ * **Tools.** `createM91McpServer` exposes `m91_request_approval` and
+ * `m91_send_alert` as an in-process MCP server, for when the agent itself
+ * should decide to ask or to wake somebody.
+ */
+
+import type {
+  CanUseTool,
+  HookCallbackMatcher,
+  McpSdkServerConfigWithInstance,
+  PermissionResult,
+} from '@anthropic-ai/claude-agent-sdk';
+
+import type { M91Client } from '../client.js';
+import {
+  ALERT_DESCRIPTION,
+  ALERT_TOOL_NAME,
+  APPROVAL_DESCRIPTION,
+  APPROVAL_TOOL_NAME,
+  type AlertArgs,
+  type AlertDefaults,
+  type ApprovalArgs,
+  type ApprovalDefaults,
+  type GateOptions,
+  decideToolCall,
+  needsHuman,
+  runAlert,
+  runApproval,
+} from './specs.js';
+import { alertShape, approvalShape, loadZod } from './zod-shapes.js';
+
+/** Tool names, or a predicate. Required: an agent that rings for every `Read` gets muted. */
+type ClaudeGateOptions = GateOptions & { tools: NonNullable<GateOptions['tools']> };
+
+/**
+ * A `canUseTool` callback that asks a person on their phone before the tools
+ * in `options.tools` run.
+ */
+export function createM91CanUseTool(client: M91Client, options: ClaudeGateOptions): CanUseTool {
+  return async (toolName, input, { toolUseID }): Promise<PermissionResult> => {
+    if (!(await needsHuman(options, toolName, input))) {
+      return { behavior: 'allow', updatedInput: input };
+    }
+    const decision = await decideToolCall(client, { toolName, input, callId: toolUseID }, options);
+    return decision.approved
+      ? { behavior: 'allow', updatedInput: input }
+      : { behavior: 'deny', message: decision.reason };
+  };
+}
+
+/**
+ * A `PreToolUse` hook matcher that asks a person before the tools in
+ * `options.tools` run, in every permission mode. Pass it as
+ * `options.hooks.PreToolUse`.
+ *
+ * ```ts
+ * query({ prompt, options: { hooks: { PreToolUse: createM91PreToolUseHook(client, { tools: ['Bash'] }) } } })
+ * ```
+ */
+export function createM91PreToolUseHook(
+  client: M91Client,
+  options: ClaudeGateOptions & { timeoutSeconds?: number },
+): HookCallbackMatcher[] {
+  return [
+    {
+      // The hook must outlive the wait for a human, or the SDK gives up first.
+      timeout: (options.timeoutSeconds ?? 300) + 60,
+      hooks: [
+        async (input) => {
+          if (input.hook_event_name !== 'PreToolUse') return {};
+          if (!(await needsHuman(options, input.tool_name, input.tool_input))) return {};
+          const decision = await decideToolCall(
+            client,
+            { toolName: input.tool_name, input: input.tool_input, callId: input.tool_use_id },
+            options,
+          );
+          return {
+            hookSpecificOutput: {
+              hookEventName: 'PreToolUse',
+              permissionDecision: decision.approved ? 'allow' : 'deny',
+              permissionDecisionReason: decision.reason,
+            },
+          };
+        },
+      ],
+    },
+  ];
+}
+
+interface ClaudeSdkModule {
+  tool: (name: string, description: string, shape: unknown, handler: unknown) => unknown;
+  createSdkMcpServer: (options: { name: string; version?: string; tools: unknown[] }) => unknown;
+}
+
+async function claudeSdk(): Promise<ClaudeSdkModule> {
+  try {
+    const specifier = '@anthropic-ai/claude-agent-sdk';
+    return (await import(specifier)) as unknown as ClaudeSdkModule;
+  } catch (error) {
+    throw new Error(
+      'The Claude Agent SDK integration needs @anthropic-ai/claude-agent-sdk. Install it with: ' +
+        'npm install @anthropic-ai/claude-agent-sdk',
+      { cause: error },
+    );
+  }
+}
+
+const text = (value: string) => ({ content: [{ type: 'text' as const, text: value }] });
+
+/**
+ * `m91_request_approval` and `m91_send_alert` as an in-process MCP server.
+ * Register it under `mcpServers.m91`; the tools appear to Claude as
+ * `mcp__m91__m91_request_approval` and `mcp__m91__m91_send_alert`.
+ */
+export async function createM91McpServer(
+  client: M91Client,
+  defaults: ApprovalDefaults & AlertDefaults = {},
+): Promise<McpSdkServerConfigWithInstance> {
+  const { tool, createSdkMcpServer } = await claudeSdk();
+  const z = await loadZod('Claude Agent SDK');
+  return createSdkMcpServer({
+    name: 'm91',
+    tools: [
+      tool(APPROVAL_TOOL_NAME, APPROVAL_DESCRIPTION, approvalShape(z), async (args: ApprovalArgs) =>
+        text(await runApproval(client, args, defaults)),
+      ),
+      tool(ALERT_TOOL_NAME, ALERT_DESCRIPTION, alertShape(z), async (args: AlertArgs) =>
+        text(await runAlert(client, args, defaults)),
+      ),
+    ],
+  }) as McpSdkServerConfigWithInstance;
+}

package/src/integrations/google-adk.ts

@@ -0,0 +1,122 @@
+/**
+ * Google Agent Development Kit for TypeScript (`@google/adk`): M91 as a
+ * before-tool gate, and M91 as tools.
+ *
+ * **Gate.** `createM91BeforeToolCallback` goes in an `LlmAgent`'s
+ * `beforeToolCallback`. Calls to the tools you name ring a phone first; if the
+ * person rejects (or does not answer), the tool does not run and the agent
+ * gets the reason back as the tool's result.
+ *
+ * ```ts
+ * import { LlmAgent } from '@google/adk';
+ * import { M91Client } from '@msg91comm/m91';
+ * import { createM91BeforeToolCallback, createM91Tools } from '@msg91comm/m91/integrations/google-adk';
+ *
+ * const client = new M91Client(process.env.M91_SEND_LINK!);
+ *
+ * const agent = new LlmAgent({
+ *   name: 'support_agent',
+ *   model: 'gemini-2.5-flash',
+ *   instruction: 'Resolve refund requests.',
+ *   tools: [issueRefund, ...(await createM91Tools(client))],
+ *   beforeToolCallback: createM91BeforeToolCallback(client, { tools: ['issue_refund'] }),
+ * });
+ * ```
+ *
+ * The gate waits for the answer in-process. For approvals that take hours,
+ * use ADK's own Tool Confirmation and resume the session when M91's answer
+ * arrives.
+ */
+
+import type { BaseTool, FunctionTool, SingleBeforeToolCallback } from '@google/adk';
+
+import type { M91Client } from '../client.js';
+import {
+  ALERT_DESCRIPTION,
+  ALERT_TOOL_NAME,
+  APPROVAL_DESCRIPTION,
+  APPROVAL_TOOL_NAME,
+  type AlertArgs,
+  type AlertDefaults,
+  type ApprovalArgs,
+  type ApprovalDefaults,
+  type GateOptions,
+  decideToolCall,
+  needsHuman,
+  runAlert,
+  runApproval,
+} from './specs.js';
+import { alertShape, approvalShape, loadZod } from './zod-shapes.js';
+
+/**
+ * A `beforeToolCallback` that asks a person on their phone before the tools
+ * in `options.tools` run. Returning a result object skips the tool, which is
+ * how a rejection reaches the model.
+ */
+export function createM91BeforeToolCallback(
+  client: M91Client,
+  options: GateOptions & { tools: NonNullable<GateOptions['tools']> },
+): SingleBeforeToolCallback {
+  return async ({ tool, args, context }) => {
+    const toolName = tool.name;
+    if (!(await needsHuman(options, toolName, args))) return undefined;
+    const callId = context.functionCallId ?? `${context.invocationId}-${toolName}`;
+    const decision = await decideToolCall(client, { toolName, input: args, callId }, options);
+    if (decision.approved) return undefined;
+    return { status: 'rejected', error: decision.reason };
+  };
+}
+
+interface AdkModule {
+  FunctionTool: new (options: unknown) => FunctionTool<any>;
+}
+
+async function adkModule(): Promise<AdkModule> {
+  try {
+    const specifier = '@google/adk';
+    return (await import(specifier)) as unknown as AdkModule;
+  } catch (error) {
+    throw new Error(
+      'The Google ADK integration needs @google/adk. Install it with: npm install @google/adk',
+      { cause: error },
+    );
+  }
+}
+
+/** The blocking approval tool, `m91_request_approval`, as an ADK `FunctionTool`. */
+export async function createM91ApprovalTool(
+  client: M91Client,
+  defaults: ApprovalDefaults = {},
+): Promise<BaseTool> {
+  const { FunctionTool } = await adkModule();
+  const z = await loadZod('Google ADK');
+  return new FunctionTool({
+    name: APPROVAL_TOOL_NAME,
+    description: APPROVAL_DESCRIPTION,
+    parameters: z.object(approvalShape(z)),
+    execute: async (args: ApprovalArgs) => ({ result: await runApproval(client, args, defaults) }),
+  });
+}
+
+/** The fire-and-forget alert tool, `m91_send_alert`, as an ADK `FunctionTool`. */
+export async function createM91AlertTool(
+  client: M91Client,
+  defaults: AlertDefaults = {},
+): Promise<BaseTool> {
+  const { FunctionTool } = await adkModule();
+  const z = await loadZod('Google ADK');
+  return new FunctionTool({
+    name: ALERT_TOOL_NAME,
+    description: ALERT_DESCRIPTION,
+    parameters: z.object(alertShape(z)),
+    execute: async (args: AlertArgs) => ({ result: await runAlert(client, args, defaults) }),
+  });
+}
+
+/** Both tools, for an agent's `tools` array. */
+export async function createM91Tools(
+  client: M91Client,
+  defaults: ApprovalDefaults & AlertDefaults = {},
+): Promise<BaseTool[]> {
+  return [await createM91ApprovalTool(client, defaults), await createM91AlertTool(client, defaults)];
+}

package/src/integrations/index.ts

@@ -0,0 +1,27 @@
+/**
+ * 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.
+ *
+ * Several adapters 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 * as openaiAgents from './openai-agents.js';
+export * as claudeAgentSdk from './claude-agent-sdk.js';
+export * as googleAdk from './google-adk.js';
+export * as mastra from './mastra.js';
+
+export { M91InterruptNotifier, createM91ApprovalNode } from './langgraph.js';
+export { APPROVED, REJECTED, alertResult, decideToolCall, errorResult } from './specs.js';
+export type { AlertArgs, ApprovalArgs, GateDecision, GateOptions, GatedCall } from './specs.js';