📱 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)
• 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 and refresh, 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.