📱 SMSGate TypeScript Client

A TypeScript-first client for the SMSGate API: send and track SMS messages through your Android devices with strict typing, Basic or JWT authentication, and a pluggable HTTP client. See the client libraries overview for the full ecosystem.

📖 About

android-sms-gateway is a typed JS/TS library for the SMSGate 3rd-party API. It covers messages (send, state, listing, cancellation), inbox refresh, devices, webhooks, settings, logs, health checks, and the JWT token lifecycle, with full type definitions and a fetch-based HTTP client that you can replace with any implementation. Designed for server-side (Node.js) use: the API does not provide CORS headers, so the library cannot run in a browser.

📚 Table of Contents

• 📱 SMSGate TypeScript Client
  • 📖 About
  • 📚 Table of Contents
  • ⭐ Features
  • 📦 Installation
  • 🔑 Authentication
    • Basic Authentication
    • JWT Authentication
  • 🚀 Quickstart
  • 💻 Usage
  • 📖 API Reference
  • 🤝 Contributing
  • 📄 License

⭐ Features

• TypeScript-first with full type definitions out of the box
• Basic and JWT authentication; token generate and revoke
• Pluggable HTTP client (default: fetch)
• Message priority, scheduling, and expiry
• Text and binary data message payloads
• Message listing with filters and pagination, and pending message cancellation
• Inbox listing with MMS attachment metadata and attachment download
• Webhooks, devices, settings, logs, and health checks
• Inbox refresh with webhook delivery modes
• Promise-based API, async/await ready
• Customizable base URL for private deployments

📦 Installation

npm install android-sms-gateway

Or with yarn (yarn add android-sms-gateway) or bun (bun add android-sms-gateway). Requires Node.js 18+.

🔑 Authentication

Two methods are supported: Basic authentication with account credentials, and JWT bearer tokens with scoped permissions. Pass an empty login string to switch to JWT.

Basic Authentication

const client = new Client(
    process.env.ANDROID_SMS_GATEWAY_LOGIN!,
    process.env.ANDROID_SMS_GATEWAY_PASSWORD!
);

JWT Authentication

const basicClient = new Client(
    process.env.ANDROID_SMS_GATEWAY_LOGIN!,
    process.env.ANDROID_SMS_GATEWAY_PASSWORD!
);

const token = await basicClient.generateToken({
    scopes: ['messages:send', 'messages:read'],
    ttl: 3600,
});

const jwtClient = new Client('', token.access_token);

🚀 Quickstart

import Client, { MessagePriority } from 'android-sms-gateway';

const client = new Client(
    process.env.ANDROID_SMS_GATEWAY_LOGIN!,
    process.env.ANDROID_SMS_GATEWAY_PASSWORD!
);

const state = await client.send({
    phoneNumbers: ['+12025550123'],
    message: 'Hello from TypeScript',
    priority: MessagePriority.Default,
});

console.log('Message ID:', state.id);

💻 Usage

Beyond sending, the client covers message listing and cancellation, inbox listing (with MMS attachment metadata) and refresh, MMS attachment download by message and part ID, device management, webhooks, settings (get, update, patch), logs, health checks, and the token lifecycle.

See src/client.ts for the complete method list with signatures and src/domain.ts for the type definitions. Webhook payload types live in src/webhooks.ts.

📖 API Reference

• Official API Reference - endpoints, payloads, and error codes
• Authentication Guide - scopes and token management
• Client libraries overview
• Client source - full method reference and examples

🤝 Contributing

Contributions are welcome. Open an issue to discuss major changes before submitting a pull request; PRs target the master branch.

📄 License

Distributed under the Apache License 2.0. See LICENSE.