@msg91comm/m91 1.1.0 → 1.2.0

package/src/integrations/vercel-ai.ts

@@ -1,5 +1,22 @@
 /**
- * Vercel AI SDK tools.
+ * Vercel AI SDK: two tools, and a gate for your own tools.
+ *
+ * **Tools** the model calls when it decides to ask (`createM91Tools`).
+ *
+ * **Gate** (`createM91ToolApproval`) plugs into AI SDK 6+'s `toolApproval`
+ * option: every call to the tools you name rings a phone first, and runs only
+ * if a person approves. The model cannot skip it, because it never decides to
+ * ask: the SDK asks for it.
+ *
+ * ```ts
+ * const { text } = await generateText({
+ *   model: 'openai/gpt-5-mini',
+ *   tools: { issueRefund, deleteUser },
+ *   toolApproval: createM91ToolApproval(client, { tools: ['issueRefund', 'deleteUser'] }),
+ *   stopWhen: isStepCount(5),
+ *   prompt: 'Refund order ORD-40122.',
+ * });
+ * ```
  *
  * ```ts
  * import { M91Client } from '@msg91comm/m91';
@@ -13,7 +30,7 @@
  *     m91_request_approval: await createM91ApprovalTool(client),
  *     m91_send_alert: await createM91AlertTool(client),
  *   },
- *   maxSteps: 10,
+ *   stopWhen: isStepCount(10),
  *   prompt: 'Look into order ORD-40122 and refund it if it checks out.',
  * });
  * ```
@@ -23,6 +40,8 @@
  * dependencies.
  */
 
+import type { Tool, ToolApprovalStatus, ToolSet } from 'ai';
+
 import type { M91Client } from '../client.js';
 import {
   ALERT_DESCRIPTION,
@@ -33,6 +52,9 @@ import {
   type AlertDefaults,
   type ApprovalArgs,
   type ApprovalDefaults,
+  type GateOptions,
+  decideToolCall,
+  needsHuman,
   runAlert,
   runApproval,
 } from './specs.js';
@@ -63,7 +85,7 @@ async function aiModule(): Promise<AiModule> {
 export async function createM91ApprovalTool(
   client: M91Client,
   defaults: ApprovalDefaults = {},
-): Promise<unknown> {
+): Promise<Tool<ApprovalArgs, string>> {
   const { tool, jsonSchema } = await aiModule();
   return tool({
     description: APPROVAL_DESCRIPTION,
@@ -71,29 +93,59 @@ export async function createM91ApprovalTool(
     // and the argument docs stay in one file shared with every other framework.
     inputSchema: jsonSchema(APPROVAL_SCHEMA),
     execute: (args: ApprovalArgs) => runApproval(client, args, defaults),
-  });
+  }) as Tool<ApprovalArgs, string>;
 }
 
 /** The fire-and-forget alert. Returns `"sent:delivered=N"` or `"error: …"`. */
 export async function createM91AlertTool(
   client: M91Client,
   defaults: AlertDefaults = {},
-): Promise<unknown> {
+): Promise<Tool<AlertArgs, string>> {
   const { tool, jsonSchema } = await aiModule();
   return tool({
     description: ALERT_DESCRIPTION,
     inputSchema: jsonSchema(ALERT_SCHEMA),
     execute: (args: AlertArgs) => runAlert(client, args, defaults),
-  });
+  }) as Tool<AlertArgs, string>;
 }
 
 /** Both, keyed by tool name, ready to spread into `tools: {…}`. */
 export async function createM91Tools(
   client: M91Client,
   defaults: ApprovalDefaults & AlertDefaults = {},
-): Promise<Record<string, unknown>> {
+): Promise<ToolSet> {
   return {
     m91_request_approval: await createM91ApprovalTool(client, defaults),
     m91_send_alert: await createM91AlertTool(client, defaults),
   };
 }
+
+/** The fields of an AI SDK tool call the gate reads. */
+interface ApprovalRequestLike {
+  toolCall: { toolName: string; input: unknown; toolCallId: string };
+}
+
+/**
+ * A `toolApproval` function for `generateText` / `streamText` / `ToolLoopAgent`.
+ *
+ * Calls to the tools in `options.tools` block while M91 rings a phone, then run
+ * if a person approves and come back to the model as denied otherwise. Every
+ * other call is `not-applicable` and runs as normal. Not synchronous: it waits
+ * up to `timeoutSeconds` (default 300) for an answer.
+ */
+export function createM91ToolApproval(
+  client: M91Client,
+  options: GateOptions & { tools: NonNullable<GateOptions['tools']> },
+): (request: ApprovalRequestLike) => Promise<ToolApprovalStatus> {
+  return async ({ toolCall }) => {
+    if (!(await needsHuman(options, toolCall.toolName, toolCall.input))) return 'not-applicable';
+    const decision = await decideToolCall(
+      client,
+      { toolName: toolCall.toolName, input: toolCall.input, callId: toolCall.toolCallId },
+      options,
+    );
+    return decision.approved
+      ? { type: 'approved', reason: decision.reason }
+      : { type: 'denied', reason: decision.reason };
+  };
+}

package/src/integrations/zod-shapes.ts

@@ -0,0 +1,55 @@
+/**
+ * The approval and alert arguments as zod shapes, for frameworks that only
+ * take zod (Claude Agent SDK, Mastra, Google ADK).
+ *
+ * Built from the zod the caller already has, passed in, so this package never
+ * imports zod itself and the descriptions stay the ones in `specs.ts`.
+ */
+
+import { ALERT_SCHEMA, APPROVAL_SCHEMA } from './specs.js';
+
+/** The slice of zod this file uses; v3 and v4 both satisfy it. */
+export interface ZodLike {
+  string(): any;
+  number(): any;
+  enum(values: readonly [string, ...string[]]): any;
+  object(shape: Record<string, any>): any;
+}
+
+const SEVERITIES = ['LOW', 'MEDIUM', 'HIGH', 'CRITICAL'] as const;
+
+export function approvalShape(z: ZodLike): Record<string, any> {
+  const p = APPROVAL_SCHEMA.properties;
+  return {
+    title: z.string().describe(p.title.description),
+    customId: z.string().describe(p.customId.description),
+    description: z.string().optional().describe(p.description.description),
+    severity: z.enum(SEVERITIES).optional().describe(p.severity.description),
+    approveLabel: z.string().optional().describe(p.approveLabel.description),
+    rejectLabel: z.string().optional().describe(p.rejectLabel.description),
+    timeoutSeconds: z.number().optional().describe(p.timeoutSeconds.description),
+  };
+}
+
+export function alertShape(z: ZodLike): Record<string, any> {
+  const p = ALERT_SCHEMA.properties;
+  return {
+    title: z.string().describe(p.title.description),
+    customId: z.string().optional().describe(p.customId.description),
+    description: z.string().optional().describe(p.description.description),
+    severity: z.enum(SEVERITIES).optional().describe(p.severity.description),
+  };
+}
+
+/** zod is an optional peer dependency: import it only when asked, and say so if it is missing. */
+export async function loadZod(framework: string): Promise<ZodLike> {
+  try {
+    const specifier = 'zod';
+    const mod = (await import(specifier)) as { z?: ZodLike } & ZodLike;
+    return mod.z ?? mod;
+  } catch (error) {
+    throw new Error(`The ${framework} integration needs zod. Install it with: npm install zod`, {
+      cause: error,
+    });
+  }
+}

package/src/platform.ts

@@ -41,7 +41,7 @@ import {
 } from './models.js';
 import { type SendOptions, checkDelivery } from './client.js';
 
-export const DEFAULT_BASE_URL = 'https://m91.msg91.com';
+export const DEFAULT_BASE_URL = 'https://m91-api.msg91.com';
 export const API_KEY_PREFIX = 'm91sk_';
 
 export interface PlatformOptions extends TransportOptions {

package/src/url-builder.ts

@@ -63,7 +63,7 @@ export function normalizeSendLink(sendLink: string): string {
   // 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> — ` +
+      `sendLink must look like https://m91-api.msg91.com/s/<token> — ` +
         `no /s/<token> found in '${parsed.pathname}'`,
     );
   }