@msg91comm/m91 0.0.0-stage → 1.1.0

package/dist/src/url-builder.js

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

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

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

package/examples/approval-gate.ts

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

package/examples/basic-alert.ts

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

package/examples/langchain-agent.ts

@@ -0,0 +1,65 @@
+/**
+ * A LangChain agent that has to ask before it spends money.
+ *
+ * The interesting part is not the wiring — it is the system prompt. A tool the
+ * model *can* call is not a tool the model *will* call, and "ask a human before
+ * anything irreversible" has to be stated as a rule with a list, not implied.
+ */
+
+import { ChatAnthropic } from '@langchain/anthropic';
+import { createReactAgent } from '@langchain/langgraph/prebuilt';
+
+import { M91Client } from '@msg91comm/m91';
+import { createM91AlertTool, createM91ApprovalTool } from '@msg91comm/m91/integrations/langchain';
+
+const client = new M91Client(process.env.M91_SEND_LINK!);
+
+const tools = [
+  await createM91ApprovalTool(client), // blocks until a human answers
+  await createM91AlertTool(client), // wakes somebody and carries on
+  // ...your own tools: issueRefund, deploy, deleteAccount, and so on.
+];
+
+const SYSTEM = `You are an operations agent with access to production systems.
+
+Before ANY of the following, you must call m91_request_approval and wait for the
+answer:
+  - moving money: refunds, payouts, charges, credits
+  - deleting or overwriting anything a customer owns
+  - deploying, rolling back, or changing production configuration
+  - sending a message to a customer on the company's behalf
+
+Rules for that call:
+  - \`title\` is what somebody reads on a lock screen at 3am. Name the action and
+    the amount or the target: "Refund 48,000 on ORD-40122?" — not "approve action".
+  - \`description\` is everything they need to answer without asking you anything.
+  - \`customId\` is derived from the thing being decided — the order id, the
+    commit sha, the account id. Never a timestamp, never a UUID: it is what
+    stops a retry raising a second alert, and what closes the alert afterwards.
+  - The result is "approved" or "rejected". If it is not exactly "approved",
+    do not do the thing. Say what you were going to do and stop.
+
+Use m91_send_alert, which does not wait, when something has already gone wrong
+and a human needs to know now — a failed job, a breach, a stuck queue. Do not
+use it for anything that could wait until morning: it wakes people up.`;
+
+const agent = createReactAgent({
+  llm: new ChatAnthropic({ model: 'claude-sonnet-5' }),
+  tools,
+  prompt: SYSTEM,
+});
+
+// The agent pauses here — a phone rings, somebody taps Approve or Reject, and
+// the run continues with their answer in the transcript.
+const result = await agent.invoke({
+  messages: [
+    {
+      role: 'user',
+      content:
+        'Customer on order ORD-40122 says their item never arrived. ' +
+        'Look into it and refund them if it checks out.',
+    },
+  ],
+});
+
+console.log(result.messages.at(-1)?.content);

package/examples/langgraph-hitl.ts

@@ -0,0 +1,70 @@
+/**
+ * LangGraph's `interrupt()` pattern, with M91 filling the gap.
+ *
+ * LangGraph 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 is the part between the pause and the resume.
+ */
+
+import { Annotation, Command, END, MemorySaver, START, StateGraph, interrupt } from '@langchain/langgraph';
+
+import { M91Client } from '@msg91comm/m91';
+import { M91InterruptNotifier } from '@msg91comm/m91/integrations/langgraph';
+
+const client = new M91Client(process.env.M91_SEND_LINK!);
+const notifier = new M91InterruptNotifier(client, { severity: 'HIGH', timeoutMs: 600_000 });
+
+const State = Annotation.Root({
+  id: Annotation<string>,
+  amount: Annotation<number>,
+  result: Annotation<string>,
+});
+
+const builder = new StateGraph(State)
+  .addNode('riskyAction', (state) => {
+    if (state.amount > 10_000) {
+      // The graph stops here and hands the payload out to the orchestrator.
+      const decision = interrupt({
+        question: `Approve payment of ₹${state.amount.toLocaleString()} on order ${state.id}?`,
+        customId: `payment-${state.id}`,
+      });
+      if (decision !== 'approved') return { result: 'payment_rejected' };
+    }
+    // await executePayment(state);
+    return { result: 'payment_completed' };
+  })
+  .addEdge(START, 'riskyAction')
+  .addEdge('riskyAction', END);
+
+const graph = builder.compile({ checkpointer: new MemorySaver() });
+const config = { configurable: { thread_id: 'order-40122' } };
+
+let result = await graph.invoke({ id: 'ORD-40122', amount: 48_000 }, config);
+
+if (result.__interrupt__) {
+  const data = result.__interrupt__[0].value as { question: string; customId: string };
+
+  // A phone rings at full volume, through Do Not Disturb, until somebody
+  // answers — and gets a voice call if 45 seconds pass in silence.
+  const decision = await notifier.notify({
+    title: data.question,
+    customId: data.customId, // the graph chose it, and it is stable
+  });
+
+  result = await graph.invoke(new Command({ resume: decision }), config);
+}
+
+console.log(result.result);
+
+// The same thing as a node, when you would rather the graph own it:
+//
+//   import { createM91ApprovalNode } from '@msg91comm/m91/integrations/langgraph';
+//   builder.addNode('approveRefund', createM91ApprovalNode(client, {
+//     approveLabel: 'Process Refund', rejectLabel: 'Hold Refund', timeoutMs: 600_000,
+//   }));
+//
+// It reads `title`/`question` and `customId` from state, and writes
+// { decision, approved } back for the next edge to branch on.

package/examples/vercel-ai-agent.ts

@@ -0,0 +1,34 @@
+/**
+ * An agent on the Vercel AI SDK that asks before it deletes anything.
+ */
+
+import { openai } from '@ai-sdk/openai';
+import { generateText, stepCountIs } from 'ai';
+
+import { M91Client } from '@msg91comm/m91';
+import { createM91AlertTool, createM91ApprovalTool } from '@msg91comm/m91/integrations/vercel-ai';
+
+const client = new M91Client(process.env.M91_SEND_LINK!);
+
+const { text } = await generateText({
+  model: openai('gpt-4o'),
+  system:
+    'You are an operations agent. Before anything irreversible — deleting customer ' +
+    'data, moving money, deploying to production — you must call m91_request_approval ' +
+    'and wait. Give it a title naming the action and its target, a description with ' +
+    'everything the person needs to decide, and a customId derived from what is being ' +
+    'decided (never a timestamp). Proceed only on exactly "approved". ' +
+    'Use m91_send_alert, which does not wait, to report something that has already ' +
+    'gone wrong and needs somebody now.',
+  tools: {
+    m91_request_approval: await createM91ApprovalTool(client),
+    m91_send_alert: await createM91AlertTool(client),
+    // ...your own tools
+  },
+  stopWhen: stepCountIs(10),
+  prompt:
+    'Account acct_8821 has asked to be deleted under GDPR. Verify the request and, ' +
+    'if it is valid, delete the account.',
+});
+
+console.log(text);

package/examples/webhook-urls.ts

@@ -0,0 +1,44 @@
+/**
+ * Alert URLs for tools whose only integration field is "URL to call".
+ *
+ * Grafana, Sentry, UptimeRobot, Zapier, a GitHub Action, a cron `curl`, an iOS
+ * Shortcut, a browser bookmark, an `<img>` tag in a status page. No client, no
+ * headers, no code — which is the point: this is the difference between M91
+ * being wired into something this afternoon and being wired in never.
+ */
+
+import { M91URLBuilder } from '@msg91comm/m91';
+
+const builder = new M91URLBuilder(process.env.M91_SEND_LINK!);
+
+// Paste this into Grafana's webhook URL field.
+console.log(
+  builder.build('CPU above 95% on prod-server-3', {
+    severity: 'HIGH',
+    customId: 'cpu-high-prod3',
+    // First label is SHARED — one person takes it on and it clears for the rest.
+    // The others are PERSONAL: an acknowledgement that leaves it looking for an owner.
+    respond: ['On it', 'Escalate'],
+  }),
+);
+
+// The bare link. Opening it RAISES NOTHING and answers with the channel's name,
+// so whoever is pasting it can see they picked the right team. That is also why
+// a link preview, a crawler or a mail scanner touching the URL wakes nobody.
+console.log(builder.testUrl());
+
+// A batch, for generating a dashboard's worth at once.
+for (const url of builder.buildMany([
+  { title: 'Disk above 90% on prod-3', customId: 'disk-high-prod3', severity: 'MEDIUM' },
+  { title: 'Certificate expires in 48 hours', customId: 'cert-expiry', severity: 'LOW' },
+  { title: 'Payment gateway unreachable', customId: 'gateway-down', severity: 'CRITICAL' },
+])) {
+  console.log(url);
+}
+
+// In a crontab, where there is no Node at all:
+//
+//   0 9 * * * curl -fsS "https://m91.msg91.com/s/TOKEN?title=Daily+backup+did+not+run&severity=HIGH"
+//
+// The URL contains the token, so it is a credential. Keep it out of anything
+// public, and out of anything that ends up in a screenshot.

package/package.json

@@ -1,6 +1,85 @@
 {
   "name": "@msg91comm/m91",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "Critical alerting and human-in-the-loop approval for AI agents and on-call systems",
+  "type": "module",
+  "license": "MIT",
+  "author": "MSG91",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "alerting",
+    "on-call",
+    "paging",
+    "human-in-the-loop",
+    "agent",
+    "approval",
+    "escalation"
+  ],
+  "homepage": "https://m91.msg91.com",
+  "repository": { "type": "git", "url": "git+https://github.com/MSG91/m91-sdk.git" },
+  "bugs": { "url": "https://github.com/MSG91/m91-sdk/issues" },
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./integrations/langchain": {
+      "types": "./dist/src/integrations/langchain.d.ts",
+      "default": "./dist/src/integrations/langchain.js"
+    },
+    "./integrations/langgraph": {
+      "types": "./dist/src/integrations/langgraph.d.ts",
+      "default": "./dist/src/integrations/langgraph.js"
+    },
+    "./integrations/vercel-ai": {
+      "types": "./dist/src/integrations/vercel-ai.d.ts",
+      "default": "./dist/src/integrations/vercel-ai.js"
+    }
+  },
+  "files": [
+    "dist/src",
+    "src",
+    "examples",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc && node --test dist/tests/*.test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.4.0"
+  },
+  "peerDependencies": {
+    "@langchain/core": ">=0.2.0",
+    "@langchain/langgraph": ">=0.2.0",
+    "ai": ">=3.0.0",
+    "zod": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@langchain/core": {
+      "optional": true
+    },
+    "@langchain/langgraph": {
+      "optional": true
+    },
+    "ai": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  }
+}