FOX SMS SDK (Official)

Official JavaScript SDK for FOX SMS — a fast, reliable bulk SMS platform for businesses and developers.

This SDK provides a stable, vendor-agnostic interface to send SMS, manage campaigns, check balance, and retrieve reports using the FOX SMS API.

Designed for production use. Works in Node.js, Bun, Deno, and modern runtimes (including Cloudflare Workers).

Features

• ✅ Single & bulk SMS sending
• ✅ Balance and credit lookup
• ✅ Delivery reports
• ✅ Interactive (campaign-based) SMS
• ✅ Stable, versioned API (v1)
• ✅ No vendor parameters exposed
• ✅ Lightweight, dependency-free
• ✅ Promise-based API
• ✅ TypeScript support

Installation

npm install @snowfoxlab/foxsms

or

yarn add @snowfoxlab/foxsms

or

pnpm add @snowfoxlab/foxsms

Requirements

• Node.js 18+ (or any runtime with fetch)
• A valid FOX SMS API Token

Getting an API Token

1. Log in to your FOX SMS dashboard
2. Navigate to API / Developer Settings
3. Generate an API token

Each user uses their own token. Tokens are securely validated by the FOX SMS backend.

Quick Start

import { FoxSMS } from "@snowfoxlab/foxsms";

const foxsms = new FoxSMS({
  token: "YOUR_FOX_SMS_TOKEN",
});

Usage

Send SMS

Single SMS

await foxsms.send({
  to: "98XXXXXXXX",
  message: "Hello from FOX SMS",
});

Bulk SMS

await foxsms.bulk({
  to: ["98XXXXXXXX", "97XXXXXXXX"],
  message: "Bulk message from FOX SMS",
});

Balance & Credit

Check Balance

const balance = await foxsms.balance();
console.log(balance);

Available Credit

const credit = await foxsms.availableCredit();
console.log(credit);

Reports

Date-Range Report

If no dates are provided, the SDK defaults to the last 24 hours.

await foxsms.report({
  startDate: "2025-01-01", // optional
  endDate: "2025-01-31", // optional
});

Paged Report

await foxsms.pagedReport({
  page: 1,
});

Interactive SMS

Send Interactive SMS

await foxsms.sendInteractive({
  campaignId: "CAMPAIGN_ID",
  to: "98XXXXXXXX",
  message: "Reply YES to confirm",
});

Interactive Report

await foxsms.interactiveReport({
  campaignId: "CAMPAIGN_ID",
  page: 1,
});

Campaigns

const campaigns = await foxsms.campaigns();
console.log(campaigns);

Health Check

await foxsms.health();

Error Handling

All API errors throw a FoxSMSError.

import { FoxSMSError } from "@snowfoxlab/foxsms";

try {
  await foxsms.send({ to: "98XXXXXXXX", message: "Test" });
} catch (err) {
  if (err instanceof FoxSMSError) {
    console.error("Error:", err.message);
    console.error("Status:", err.status);
    console.error("Response:", err.response);
  } else {
    throw err;
  }
}

err.response contains the raw API response returned by the FOX SMS backend (if available).

Configuration

Custom API Base URL (Optional)

const foxsms = new FoxSMS({
  token: "YOUR_TOKEN",
  baseUrl: "https://api.foxlab.com.np",
});

Default: https://api.foxlab.com.np

Design Principles

• No vendor lock-in — Clean, stable interface
• No third-party parameter exposure — Vendor details abstracted
• Stable SDK interface — Predictable across versions
• Strict request normalization — Consistent API calls
• Backward compatibility guaranteed within major versions

Versioning Policy

• v1.x.x — Backward compatible updates
• v2.0.0 — Breaking changes (if ever required)

Runtime Compatibility

• ✅ Node.js
• ✅ Bun
• ✅ Deno
• ✅ Cloudflare Workers
• ✅ Vercel / Netlify Edge Functions

Security

• Tokens are sent via Authorization: Bearer
• No credentials stored in SDK
• TLS enforced at API layer

API Reference

Constructor

new FoxSMS(config: FoxSMSConfig)

Config Options:

• token (required): Your FOX SMS API token
• baseUrl (optional): Custom API base URL

Methods

| Method | Description | Parameters | | --------------------- | ---------------------- | ----------------------------------------------------- | | send() | Send single SMS | { to: string, message: string } | | bulk() | Send bulk SMS | { to: string[], message: string } | | balance() | Check account balance | None | | availableCredit() | Get available credit | None | | report() | Get date-range report | { startDate: string, endDate: string } | | pagedReport() | Get paginated report | { page: number } | | sendInteractive() | Send interactive SMS | { campaignId: string, to: string, message: string } | | interactiveReport() | Get interactive report | { campaignId: string, page: number } | | campaigns() | List campaigns | None | | health() | API health check | None |

Examples

Complete Example

import { FoxSMS, FoxSMSError } from "@snowfoxlab/foxsms";

const foxsms = new FoxSMS({
  token: process.env.FOX_SMS_TOKEN,
});

async function sendWelcomeSMS(phoneNumber) {
  try {
    // Check balance first
    const balance = await foxsms.balance();
    console.log(`Current balance: ${balance}`);

    // Send SMS
    await foxsms.send({
      to: phoneNumber,
      message: "Welcome to our service!",
    });

    console.log("SMS sent successfully");
  } catch (err) {
    if (err instanceof FoxSMSError) {
      console.error(`Failed to send SMS: ${err.message}`);
    } else {
      throw err;
    }
  }
}

sendWelcomeSMS("98XXXXXXXX");

License

MIT License

Support

• Website: https://sms.foxlab.com.np
• Email: [email protected]
• Issues: GitHub Issues

Brand Notice

FOX SMS is a registered brand of Snowfox Lab. This SDK is an official client library for the FOX SMS platform.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Contributors

• Bikash Adhikari
  Founder & SDK Maintainer
  GitHub: https://github.com/bikashadhikari07

Made with ❤️ by Snowfox Lab