@codebucket/sms

TypeScript SMS SDK with pluggable providers for Msg91, Mgov, SmartSol, and custom SMS gateway backends.

Install

npm i @codebucket/sms

Public API

import {
  SmsSender,
  BaseProvider,
  Msg91Provider,
  MgovProvider,
  SmartSolProvider,
  SmsServerProvider,
  type SendOptions,
  type ProviderConfig,
  type Msg91Config,
  type Msg91SendOptions,
  type MgovConfig,
  type SmartSolConfig,
  type SmsServerConfig,
  type SmsServerSendOptions,
} from "@codebucket/sms";

Canonical Usage

Instantiate one provider, pass it to SmsSender, then call send().

import { SmsSender, Msg91Provider } from "@codebucket/sms";

const sms = new SmsSender(
  new Msg91Provider({
    authKey: process.env.MSG91_AUTH_KEY!,
    senderId: process.env.MSG91_SENDER_ID,
  })
);

await sms.send({
  type: "text",
  to: ["919876543210"],
  content: "Your OTP is {{var1}}",
  variables: ["123456"],
});

Send Options

All providers accept SendOptions:

interface SendOptions {
  to: string[];
  content?: string;
  templateId?: string;
  variables?: Record<string, any> | string[];
  type?:
    | "text"
    | "template"
    | "bulk"
    | "unicode"
    | "otp"
    | "unicodeotp"
    | "singlemsg"
    | "bulkmsg"
    | "unicodemsg"
    | "otpmsg"
    | "unicodeotpmsg";
}

Rules:

• to is always an array of phone-number strings.
• variables can be either an object or an array.
• Array variables are mapped to var1, var2, var3, and so on.
• content supports {{name}} interpolation for providers that send raw text.
• templateId is required for template or flow-based sends.

Provider Matrix

| Provider | Use when | Required config | Notes | | --- | --- | --- | --- | | Msg91Provider | Sending via Msg91 APIs | authKey | type: "template" uses Msg91 Flow API. Text-like sends use the v2 SMS API. | | MgovProvider | Sending via Mgov/NIC SMS gateway | username, password, senderId, secureKey, url | Supports both SDK aliases (unicode) and gateway aliases (unicodemsg). | | SmartSolProvider | Sending via SmartSol / 100Coins | apiKey, mask, peid | type: "unicode" sends mtype=2. templateId is sent as tempid. | | SmsServerProvider | Proxying through a custom SMS server | smsServerUrl, senderId, accessToken | Forwards the payload with the configured senderId. |

Provider Examples

Msg91

import {
  SmsSender,
  Msg91Provider,
  type Msg91Config,
  type Msg91SendOptions,
} from "@codebucket/sms";

const providerConfig: Msg91Config = {
  authKey: process.env.MSG91_AUTH_KEY!,
  senderId: process.env.MSG91_SENDER_ID,
  route: "4",
  country: "91",
};

const sms = new SmsSender(new Msg91Provider(providerConfig));

const options: Msg91SendOptions = {
  type: "template",
  to: ["919876543210"],
  templateId: "flow-template-id",
  variables: ["123456", "Alice"],
  shortUrl: "1",
  shortUrlExpiry: "7",
};

await sms.send(options);

Msg91 specifics:

• type: "template" sends to the Msg91 Flow API.
• type: "text", "bulk", and "otp" send plain text through the SMS API.
• shortUrl, shortUrlExpiry, and realTimeResponse are optional Msg91 template options.

Mgov

import {
  SmsSender,
  MgovProvider,
  type MgovConfig,
} from "@codebucket/sms";

const providerConfig: MgovConfig = {
  username: process.env.MGOV_USERNAME!,
  password: process.env.MGOV_PASSWORD!,
  senderId: process.env.MGOV_SENDER_ID!,
  secureKey: process.env.MGOV_SECURE_KEY!,
  url: process.env.MGOV_URL!,
};

const sms = new SmsSender(new MgovProvider(providerConfig));

await sms.send({
  type: "singlemsg",
  to: ["919876543210"],
  content: "Verify your mobile number with OTP {{var1}}",
  variables: ["123456"],
});

Mgov specifics:

• text and template map to singlemsg.
• bulk, unicode, otp, and unicodeotp also accept the direct gateway aliases bulkmsg, unicodemsg, otpmsg, and unicodeotpmsg.
• Unicode message types are converted to Mgov's expected HTML entity format before submission.

SmartSol

import {
  SmsSender,
  SmartSolProvider,
  type SmartSolConfig,
} from "@codebucket/sms";

const providerConfig: SmartSolConfig = {
  apiKey: process.env.SMARTSOL_API_KEY!,
  mask: process.env.SMARTSOL_MASK!,
  peid: process.env.SMARTSOL_PEID!,
  useGet: false,
};

const sms = new SmsSender(new SmartSolProvider(providerConfig));

await sms.send({
  type: "text",
  to: ["919876543210"],
  content: "Your OTP is {{var1}}",
  variables: ["123456"],
  templateId: "smartsol-template-id",
});

SmartSol specifics:

• Leading 91 is removed from each recipient before sending.
• type: "unicode" sends mtype=2; all other types send mtype=0.
• useGet: true switches from POST /postsms to GET /getsms.

SMS Server

import {
  SmsSender,
  SmsServerProvider,
  type SmsServerConfig,
  type SmsServerSendOptions,
} from "@codebucket/sms";

const providerConfig: SmsServerConfig = {
  smsServerUrl: process.env.SMS_SERVER_URL!,
  senderId: process.env.SMS_SENDER_ID!,
  accessToken: process.env.SMS_ACCESS_TOKEN!,
};

const sms = new SmsSender(new SmsServerProvider(providerConfig));

const options: SmsServerSendOptions = {
  type: "template",
  to: ["919876543210"],
  templateId: "gateway-template-id",
  variables: ["123456"],
};

await sms.send(options);

SMS Server specifics:

• The provider forwards your payload and injects the configured senderId.
• It accepts generic SendOptions plus Msg91-style template extras.
• Unlike the other providers, SmsServerProvider.send() currently returns the full Axios response object instead of response.data.

AI Agent Notes

If you want coding agents to use this package correctly:

• Put provider-specific instructions in AGENTS.md.
• Keep exported types accurate and public so agents can discover them from the package.
• Give one canonical example per provider and per special option shape.
• Prefer named exported config types in generated code instead of anonymous inline objects.

Files That Matter

• src/index.ts: public exports
• src/types.ts: shared send and config types
• src/providers: provider implementations
• AGENTS.md: agent-oriented instructions
• openapi.yaml: custom SMS gateway contract