npm package: @snowfoxlab/foxsms
Description: Official FOX SMS Node.js SDK - send SMS, manage campaigns, check balance, and retrieve reports via FOX SMS API
Author: Snowfox Lab Pvt Ltd
Latest version: 1.0.1

# FOX SMS SDK (Official)

<p align="center">
  <img
    src="https://raw.githubusercontent.com/snowfoxlab/foxsms/main/src/assets/foxsms-logo.png"
    alt="FOX SMS Logo"
    width="400"
  />
</p>

<p align="center">
  <strong>Supercharge your communication with the FOX SMS API</strong>
</p>

[![npm version](https://img.shields.io/npm/v/@snowfoxlab/foxsms.svg)](https://www.npmjs.com/package/@snowfoxlab/foxsms)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
![npm bundle size](https://img.shields.io/bundlephobia/min/@snowfoxlab/foxsms)
![Developed at SnowfoxLab](https://img.shields.io/badge/Developed%20at-SnowfoxLab-informational)

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

```bash
npm install @snowfoxlab/foxsms
```

or

```bash
yarn add @snowfoxlab/foxsms
```

or

```bash
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](https://sms.foxlab.com.np)
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

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

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

---

## Usage

### Send SMS

#### Single SMS

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

#### Bulk SMS

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

---

### Balance & Credit

#### Check Balance

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

#### Available Credit

```javascript
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.

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

#### Paged Report

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

---

### Interactive SMS

#### Send Interactive SMS

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

#### Interactive Report

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

---

### Campaigns

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

---

### Health Check

```javascript
await foxsms.health();
```

---

## Error Handling

All API errors throw a `FoxSMSError`.

```javascript
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)

```javascript
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

```typescript
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

```javascript
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](https://sms.foxlab.com.np)
- **Email:** support@foxlab.com.np
- **Issues:** [GitHub Issues](https://github.com/snowfoxlab/foxsms-sdk/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**