@textbee/sdk 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 - 2026 textbee.dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# @textbee/sdk
+
+Official JavaScript SDK for [textbee.dev](https://textbee.dev), the open source SMS gateway that turns an Android phone into an SMS API.
+
+Zero dependencies, TypeScript types included, works in Node 18+, Bun, Deno, Cloudflare Workers, and Vercel Edge.
+
+## Install
+
+```bash
+npm install @textbee/sdk
+```
+
+```bash
+pnpm add @textbee/sdk
+```
+
+## Quickstart
+
+Get an API key from the [textbee dashboard](https://textbee.dev/dashboard), then:
+
+```js
+import { Textbee } from '@textbee/sdk'
+
+const textbee = new Textbee({ apiKey: process.env.TEXTBEE_API_KEY })
+
+await textbee.sendSms({
+  recipients: ['+251912345678'],
+  message: 'Hello from textbee!',
+})
+```
+
+## Send options
+
+`sendSms` needs only `message` and `recipients`. Everything else is optional.
+
+| Option | Type | What it does |
+| --- | --- | --- |
+| `deviceId` | `string` | Which phone sends the message. Omit it and textbee uses your default device, or the enabled device with the most recent heartbeat. |
+| `simSubscriptionId` | `number` | Which SIM sends the message on a multi-SIM phone. Omit it and the phone uses its configured preferred SIM, or the system default. |
+| `scheduledAt` | `string \| Date` | Send later instead of now. ISO 8601 or a `Date`, must be in the future, up to 72 hours ahead. |
+
+```js
+await textbee.sendSms({
+  recipients: ['+251912345678'],
+  message: 'Your appointment is tomorrow at 9am',
+  deviceId: '65f0000000000000000000aa',
+  simSubscriptionId: 2,
+  scheduledAt: new Date(Date.now() + 60 * 60 * 1000),
+})
+```
+
+### Finding your simSubscriptionId
+
+Open the textbee Android app, go to **Dashboard**, and find the **SIM Cards** section. Each SIM shows its subscription id with a copy button.
+
+Be aware that this value is not validated. If the id does not match a SIM currently in the phone it is ignored, and the message goes out from the preferred or default SIM instead. Nothing errors, so confirm which SIM was used by checking the number the message arrived from.
+
+## Devices
+
+```js
+const devices = await textbee.getDevices()
+const device = await textbee.getDevice(deviceId)
+
+// Change which device handles sends that omit deviceId
+await textbee.setDefaultDevice(deviceId)
+```
+
+## Messages and delivery status
+
+```js
+// Paginated history, filterable and searchable
+const { data, meta } = await textbee.getMessages(deviceId, {
+  type: 'received', // 'all' | 'sent' | 'received'
+  page: 1,
+  limit: 50,
+  search: 'invoice',
+})
+
+// A single message and its current status
+const sms = await textbee.getSms(deviceId, smsId)
+
+// A whole batch, using the smsBatchId returned by sendSms
+const { batch, messages } = await textbee.getSmsBatch(deviceId, smsBatchId)
+```
+
+## Verifying webhooks
+
+textbee signs each webhook delivery with HMAC-SHA256 and sends the hex digest in the `X-Signature` header. Pass the raw request body, not a re-serialized object, whenever your framework gives you access to it.
+
+```js
+import { verifyWebhookSignature } from '@textbee/sdk'
+
+app.post('/webhooks/textbee', express.raw({ type: 'application/json' }), async (req, res) => {
+  const valid = await verifyWebhookSignature({
+    payload: req.body.toString('utf8'),
+    signature: req.get('x-signature'),
+    signingSecret: process.env.TEXTBEE_WEBHOOK_SECRET,
+  })
+
+  if (!valid) return res.sendStatus(401)
+
+  const event = JSON.parse(req.body.toString('utf8'))
+  res.sendStatus(200)
+})
+```
+
+## Errors
+
+Any non-2xx response throws a `TextbeeError` carrying the status and the parsed body. Network failures reject with the underlying `fetch` error instead.
+
+```js
+import { TextbeeError } from '@textbee/sdk'
+
+try {
+  await textbee.sendSms({ recipients: ['+251912345678'], message: 'hi' })
+} catch (error) {
+  if (error instanceof TextbeeError) {
+    console.error(error.status, error.message)
+  } else {
+    throw error
+  }
+}
+```
+
+## Client options
+
+```js
+new Textbee({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://api.textbee.dev/api/v1', // override for self-hosted instances
+})
+```
+
+## What is not covered yet
+
+v0.0.1 focuses on sending and reading messages. Bulk send and a few device operations are still REST only, documented at [textbee.dev/docs](https://textbee.dev/docs).
+
+## License
+
+MIT. Part of the [textbee](https://github.com/vernu/textbee) project.

package/dist/index.cjs

@@ -0,0 +1,222 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Textbee: () => Textbee,
+  TextbeeError: () => TextbeeError,
+  verifyWebhookSignature: () => verifyWebhookSignature
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var TextbeeError = class extends Error {
+  /** HTTP status code returned by the API. */
+  status;
+  /** Parsed response body, or the raw text when the body was not JSON. */
+  body;
+  constructor(status, message, body) {
+    super(message);
+    this.name = "TextbeeError";
+    this.status = status;
+    this.body = body;
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.textbee.dev/api/v1";
+var CLIENT_ID = `textbee-js/${"0.0.1"}`;
+var Textbee = class {
+  #apiKey;
+  #baseUrl;
+  constructor(options) {
+    if (!options?.apiKey) {
+      throw new TypeError("Textbee requires an apiKey");
+    }
+    this.#apiKey = options.apiKey;
+    this.#baseUrl = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+  }
+  /** Send an SMS to one or more recipients. */
+  async sendSms(request) {
+    const body = {
+      message: request.message,
+      recipients: request.recipients
+    };
+    if (request.deviceId !== void 0) {
+      body.deviceId = request.deviceId;
+    }
+    if (request.simSubscriptionId !== void 0) {
+      body.simSubscriptionId = request.simSubscriptionId;
+    }
+    if (request.scheduledAt !== void 0) {
+      body.scheduledAt = request.scheduledAt instanceof Date ? request.scheduledAt.toISOString() : request.scheduledAt;
+    }
+    const payload = await this.#request(
+      "POST",
+      "/gateway/send-sms",
+      { body }
+    );
+    return payload.data;
+  }
+  /** List the devices registered to this account. */
+  async getDevices() {
+    const payload = await this.#request(
+      "GET",
+      "/gateway/devices"
+    );
+    return payload.data;
+  }
+  /** Fetch a single device by id. */
+  async getDevice(deviceId) {
+    const payload = await this.#request(
+      "GET",
+      `/gateway/devices/${encodeURIComponent(deviceId)}`
+    );
+    return payload.data;
+  }
+  /** Make a device the default sender for requests that omit `deviceId`. */
+  async setDefaultDevice(deviceId) {
+    const payload = await this.#request(
+      "POST",
+      `/gateway/devices/${encodeURIComponent(deviceId)}/set-default`
+    );
+    return payload.data;
+  }
+  /** Page through a device's sent and received messages. */
+  async getMessages(deviceId, options = {}) {
+    return await this.#request(
+      "GET",
+      `/gateway/devices/${encodeURIComponent(deviceId)}/messages`,
+      {
+        query: {
+          type: options.type,
+          page: options.page,
+          limit: options.limit,
+          search: options.search
+        }
+      }
+    );
+  }
+  /** Fetch a single message, including its delivery status. */
+  async getSms(deviceId, smsId) {
+    const payload = await this.#request(
+      "GET",
+      `/gateway/devices/${encodeURIComponent(deviceId)}/sms/${encodeURIComponent(smsId)}`
+    );
+    return payload.data;
+  }
+  /** Fetch a batch and every message in it. Pair this with `smsBatchId` from a send. */
+  async getSmsBatch(deviceId, smsBatchId) {
+    const payload = await this.#request(
+      "GET",
+      `/gateway/devices/${encodeURIComponent(deviceId)}/sms-batch/${encodeURIComponent(smsBatchId)}`
+    );
+    return payload.data;
+  }
+  async #request(method, path, init = {}) {
+    const url = new URL(`${this.#baseUrl}${path}`);
+    for (const [key, value] of Object.entries(init.query ?? {})) {
+      if (value !== void 0) {
+        url.searchParams.set(key, String(value));
+      }
+    }
+    const headers = {
+      "x-api-key": this.#apiKey,
+      "user-agent": CLIENT_ID,
+      "x-sdk-client": CLIENT_ID,
+      accept: "application/json"
+    };
+    if (init.body !== void 0) {
+      headers["content-type"] = "application/json";
+    }
+    const response = await fetch(url, {
+      method,
+      headers,
+      body: init.body === void 0 ? void 0 : JSON.stringify(init.body)
+    });
+    const payload = await readBody(response);
+    if (!response.ok) {
+      throw new TextbeeError(response.status, errorMessage(payload, response.status), payload);
+    }
+    return payload;
+  }
+};
+async function readBody(response) {
+  const text = await response.text();
+  if (!text) {
+    return void 0;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+function errorMessage(payload, status) {
+  if (payload && typeof payload === "object") {
+    const record = payload;
+    if (typeof record.error === "string" && record.error) {
+      return record.error;
+    }
+    if (typeof record.message === "string" && record.message) {
+      return record.message;
+    }
+  }
+  return `HTTP ${status}`;
+}
+
+// src/webhooks.ts
+async function verifyWebhookSignature(options) {
+  const { payload, signature, signingSecret } = options;
+  if (!signature || !signingSecret) {
+    return false;
+  }
+  const body = typeof payload === "string" ? payload : JSON.stringify(payload);
+  const expected = await hmacSha256Hex(signingSecret, body);
+  return constantTimeEqual(expected, signature.toLowerCase());
+}
+async function hmacSha256Hex(secret, message) {
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const digest = await crypto.subtle.sign("HMAC", key, encoder.encode(message));
+  return Array.from(new Uint8Array(digest)).map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function constantTimeEqual(a, b) {
+  if (a.length !== b.length) {
+    return false;
+  }
+  let mismatch = 0;
+  for (let i = 0; i < a.length; i++) {
+    mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return mismatch === 0;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Textbee,
+  TextbeeError,
+  verifyWebhookSignature
+});

package/dist/index.d.cts

@@ -0,0 +1,189 @@
+interface TextbeeOptions {
+    /** API key from the textbee dashboard. Sent as the `x-api-key` header. */
+    apiKey: string;
+    /** Override the API base URL. Defaults to `https://api.textbee.dev/api/v1`. */
+    baseUrl?: string;
+}
+interface SendSmsRequest {
+    /** The message body. */
+    message: string;
+    /** Phone numbers to send to, in international format. */
+    recipients: string[];
+    /**
+     * Which phone sends the message. Get ids from `getDevices()`.
+     *
+     * Omit it and textbee picks the sender for you: your default device first,
+     * otherwise the enabled device with the most recent heartbeat. A malformed id
+     * fails with 400 rather than falling back, so a typo cannot send from the
+     * wrong phone.
+     */
+    deviceId?: string;
+    /**
+     * Which SIM sends the message on a multi-SIM phone.
+     *
+     * This value is not validated. An id that does not match a SIM currently in
+     * the phone is ignored, and the message goes out from the SIM configured in
+     * the app's settings, or the system default. Nothing errors, so confirm the
+     * SIM by checking which number the message arrived from.
+     *
+     * Find the id in the textbee Android app under Dashboard, "SIM Cards", where
+     * each SIM shows its number with a copy button.
+     */
+    simSubscriptionId?: number;
+    /**
+     * Send later instead of now, as an ISO 8601 string or a `Date`.
+     *
+     * Must be in the future, and up to 72 hours ahead. Omit for an immediate send.
+     */
+    scheduledAt?: string | Date;
+}
+/** Returned when the message was accepted for delivery and queued. */
+interface SendSmsQueuedResponse {
+    success: true;
+    message: string;
+    smsBatchId: string;
+    recipientCount: number;
+}
+/** Returned when the message was dispatched to the device immediately. */
+interface SendSmsImmediateResponse {
+    successCount: number;
+    [key: string]: unknown;
+}
+/**
+ * The send response shape depends on how the message was dispatched. Narrow it
+ * with `'smsBatchId' in result` before reading batch fields.
+ */
+type SendSmsResponse = SendSmsQueuedResponse | SendSmsImmediateResponse;
+interface GetMessagesOptions {
+    /** Filter by direction. Defaults to `all`. */
+    type?: 'all' | 'sent' | 'received';
+    /** 1-based page number. Defaults to 1. */
+    page?: number;
+    /** Items per page. Defaults to 50, capped at 100 by the API. */
+    limit?: number;
+    /** Free text match across the message body, recipient, and sender. */
+    search?: string;
+}
+interface Device {
+    _id: string;
+    name?: string;
+    brand?: string;
+    manufacturer?: string;
+    model?: string;
+    enabled: boolean;
+    isDefault: boolean;
+    lastHeartbeat?: string;
+    sentSMSCount: number;
+    receivedSMSCount: number;
+    os?: string;
+    osVersion?: string;
+    appVersionName?: string;
+    appVersionCode?: number;
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface Message {
+    _id: string;
+    message: string;
+    type: 'sent' | 'received';
+    status: 'pending' | 'dispatched' | 'sent' | 'delivered' | 'failed' | 'unknown' | 'received';
+    sender?: string;
+    recipient?: string;
+    requestedAt?: string;
+    dispatchedAt?: string;
+    sentAt?: string;
+    deliveredAt?: string;
+    failedAt?: string;
+    receivedAt?: string;
+    errorCode?: string;
+    errorMessage?: string;
+    simSubscriptionId?: number;
+    smsBatch?: string;
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface SmsBatch {
+    _id: string;
+    message: string;
+    recipientCount: number;
+    recipientPreview?: string;
+    successCount: number;
+    failureCount: number;
+    status: 'pending' | 'processing' | 'completed' | 'partial_success' | 'failed' | 'unknown';
+    error?: string;
+    completedAt?: string;
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface PaginationMeta {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+}
+interface MessagesPage {
+    data: Message[];
+    meta: PaginationMeta;
+}
+interface SmsBatchResult {
+    batch: SmsBatch;
+    messages: Message[];
+}
+/** Event names textbee sends in a webhook payload. */
+type WebhookEvent = 'MESSAGE_RECEIVED' | 'MESSAGE_SENT' | 'MESSAGE_DELIVERED' | 'MESSAGE_FAILED' | 'UNKNOWN_STATE' | 'SMS_STATUS_UPDATED';
+
+declare class Textbee {
+    #private;
+    constructor(options: TextbeeOptions);
+    /** Send an SMS to one or more recipients. */
+    sendSms(request: SendSmsRequest): Promise<SendSmsResponse>;
+    /** List the devices registered to this account. */
+    getDevices(): Promise<Device[]>;
+    /** Fetch a single device by id. */
+    getDevice(deviceId: string): Promise<Device>;
+    /** Make a device the default sender for requests that omit `deviceId`. */
+    setDefaultDevice(deviceId: string): Promise<Device>;
+    /** Page through a device's sent and received messages. */
+    getMessages(deviceId: string, options?: GetMessagesOptions): Promise<MessagesPage>;
+    /** Fetch a single message, including its delivery status. */
+    getSms(deviceId: string, smsId: string): Promise<Message>;
+    /** Fetch a batch and every message in it. Pair this with `smsBatchId` from a send. */
+    getSmsBatch(deviceId: string, smsBatchId: string): Promise<SmsBatchResult>;
+}
+
+/**
+ * Thrown when the textbee API answers with a non-2xx status.
+ *
+ * Network failures are not wrapped: those reject with whatever `fetch` threw.
+ */
+declare class TextbeeError extends Error {
+    /** HTTP status code returned by the API. */
+    readonly status: number;
+    /** Parsed response body, or the raw text when the body was not JSON. */
+    readonly body: unknown;
+    constructor(status: number, message: string, body?: unknown);
+}
+
+interface VerifyWebhookSignatureOptions {
+    /**
+     * The webhook request body. Prefer the raw body string.
+     *
+     * An object works too, but only because parsing and re-serializing usually
+     * preserves key order. Frameworks that rebuild the body can break that, so
+     * read the raw body when your server makes it available.
+     */
+    payload: string | object;
+    /** Value of the `X-Signature` request header. */
+    signature: string;
+    /** Signing secret shown with the webhook subscription in the dashboard. */
+    signingSecret: string;
+}
+/**
+ * Check that a webhook really came from textbee.
+ *
+ * textbee signs deliveries with HMAC-SHA256 over the request body and sends the
+ * hex digest in the `X-Signature` header. Comparison is constant time.
+ */
+declare function verifyWebhookSignature(options: VerifyWebhookSignatureOptions): Promise<boolean>;
+
+export { type Device, type GetMessagesOptions, type Message, type MessagesPage, type PaginationMeta, type SendSmsImmediateResponse, type SendSmsQueuedResponse, type SendSmsRequest, type SendSmsResponse, type SmsBatch, type SmsBatchResult, Textbee, TextbeeError, type TextbeeOptions, type VerifyWebhookSignatureOptions, type WebhookEvent, verifyWebhookSignature };

package/dist/index.d.ts

@@ -0,0 +1,189 @@
+interface TextbeeOptions {
+    /** API key from the textbee dashboard. Sent as the `x-api-key` header. */
+    apiKey: string;
+    /** Override the API base URL. Defaults to `https://api.textbee.dev/api/v1`. */
+    baseUrl?: string;
+}
+interface SendSmsRequest {
+    /** The message body. */
+    message: string;
+    /** Phone numbers to send to, in international format. */
+    recipients: string[];
+    /**
+     * Which phone sends the message. Get ids from `getDevices()`.
+     *
+     * Omit it and textbee picks the sender for you: your default device first,
+     * otherwise the enabled device with the most recent heartbeat. A malformed id
+     * fails with 400 rather than falling back, so a typo cannot send from the
+     * wrong phone.
+     */
+    deviceId?: string;
+    /**
+     * Which SIM sends the message on a multi-SIM phone.
+     *
+     * This value is not validated. An id that does not match a SIM currently in
+     * the phone is ignored, and the message goes out from the SIM configured in
+     * the app's settings, or the system default. Nothing errors, so confirm the
+     * SIM by checking which number the message arrived from.
+     *
+     * Find the id in the textbee Android app under Dashboard, "SIM Cards", where
+     * each SIM shows its number with a copy button.
+     */
+    simSubscriptionId?: number;
+    /**
+     * Send later instead of now, as an ISO 8601 string or a `Date`.
+     *
+     * Must be in the future, and up to 72 hours ahead. Omit for an immediate send.
+     */
+    scheduledAt?: string | Date;
+}
+/** Returned when the message was accepted for delivery and queued. */
+interface SendSmsQueuedResponse {
+    success: true;
+    message: string;
+    smsBatchId: string;
+    recipientCount: number;
+}
+/** Returned when the message was dispatched to the device immediately. */
+interface SendSmsImmediateResponse {
+    successCount: number;
+    [key: string]: unknown;
+}
+/**
+ * The send response shape depends on how the message was dispatched. Narrow it
+ * with `'smsBatchId' in result` before reading batch fields.
+ */
+type SendSmsResponse = SendSmsQueuedResponse | SendSmsImmediateResponse;
+interface GetMessagesOptions {
+    /** Filter by direction. Defaults to `all`. */
+    type?: 'all' | 'sent' | 'received';
+    /** 1-based page number. Defaults to 1. */
+    page?: number;
+    /** Items per page. Defaults to 50, capped at 100 by the API. */
+    limit?: number;
+    /** Free text match across the message body, recipient, and sender. */
+    search?: string;
+}
+interface Device {
+    _id: string;
+    name?: string;
+    brand?: string;
+    manufacturer?: string;
+    model?: string;
+    enabled: boolean;
+    isDefault: boolean;
+    lastHeartbeat?: string;
+    sentSMSCount: number;
+    receivedSMSCount: number;
+    os?: string;
+    osVersion?: string;
+    appVersionName?: string;
+    appVersionCode?: number;
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface Message {
+    _id: string;
+    message: string;
+    type: 'sent' | 'received';
+    status: 'pending' | 'dispatched' | 'sent' | 'delivered' | 'failed' | 'unknown' | 'received';
+    sender?: string;
+    recipient?: string;
+    requestedAt?: string;
+    dispatchedAt?: string;
+    sentAt?: string;
+    deliveredAt?: string;
+    failedAt?: string;
+    receivedAt?: string;
+    errorCode?: string;
+    errorMessage?: string;
+    simSubscriptionId?: number;
+    smsBatch?: string;
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface SmsBatch {
+    _id: string;
+    message: string;
+    recipientCount: number;
+    recipientPreview?: string;
+    successCount: number;
+    failureCount: number;
+    status: 'pending' | 'processing' | 'completed' | 'partial_success' | 'failed' | 'unknown';
+    error?: string;
+    completedAt?: string;
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface PaginationMeta {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+}
+interface MessagesPage {
+    data: Message[];
+    meta: PaginationMeta;
+}
+interface SmsBatchResult {
+    batch: SmsBatch;
+    messages: Message[];
+}
+/** Event names textbee sends in a webhook payload. */
+type WebhookEvent = 'MESSAGE_RECEIVED' | 'MESSAGE_SENT' | 'MESSAGE_DELIVERED' | 'MESSAGE_FAILED' | 'UNKNOWN_STATE' | 'SMS_STATUS_UPDATED';
+
+declare class Textbee {
+    #private;
+    constructor(options: TextbeeOptions);
+    /** Send an SMS to one or more recipients. */
+    sendSms(request: SendSmsRequest): Promise<SendSmsResponse>;
+    /** List the devices registered to this account. */
+    getDevices(): Promise<Device[]>;
+    /** Fetch a single device by id. */
+    getDevice(deviceId: string): Promise<Device>;
+    /** Make a device the default sender for requests that omit `deviceId`. */
+    setDefaultDevice(deviceId: string): Promise<Device>;
+    /** Page through a device's sent and received messages. */
+    getMessages(deviceId: string, options?: GetMessagesOptions): Promise<MessagesPage>;
+    /** Fetch a single message, including its delivery status. */
+    getSms(deviceId: string, smsId: string): Promise<Message>;
+    /** Fetch a batch and every message in it. Pair this with `smsBatchId` from a send. */
+    getSmsBatch(deviceId: string, smsBatchId: string): Promise<SmsBatchResult>;
+}
+
+/**
+ * Thrown when the textbee API answers with a non-2xx status.
+ *
+ * Network failures are not wrapped: those reject with whatever `fetch` threw.
+ */
+declare class TextbeeError extends Error {
+    /** HTTP status code returned by the API. */
+    readonly status: number;
+    /** Parsed response body, or the raw text when the body was not JSON. */
+    readonly body: unknown;
+    constructor(status: number, message: string, body?: unknown);
+}
+
+interface VerifyWebhookSignatureOptions {
+    /**
+     * The webhook request body. Prefer the raw body string.
+     *
+     * An object works too, but only because parsing and re-serializing usually
+     * preserves key order. Frameworks that rebuild the body can break that, so
+     * read the raw body when your server makes it available.
+     */
+    payload: string | object;
+    /** Value of the `X-Signature` request header. */
+    signature: string;
+    /** Signing secret shown with the webhook subscription in the dashboard. */
+    signingSecret: string;
+}
+/**
+ * Check that a webhook really came from textbee.
+ *
+ * textbee signs deliveries with HMAC-SHA256 over the request body and sends the
+ * hex digest in the `X-Signature` header. Comparison is constant time.
+ */
+declare function verifyWebhookSignature(options: VerifyWebhookSignatureOptions): Promise<boolean>;
+
+export { type Device, type GetMessagesOptions, type Message, type MessagesPage, type PaginationMeta, type SendSmsImmediateResponse, type SendSmsQueuedResponse, type SendSmsRequest, type SendSmsResponse, type SmsBatch, type SmsBatchResult, Textbee, TextbeeError, type TextbeeOptions, type VerifyWebhookSignatureOptions, type WebhookEvent, verifyWebhookSignature };

package/dist/index.js

@@ -0,0 +1,193 @@
+// src/errors.ts
+var TextbeeError = class extends Error {
+  /** HTTP status code returned by the API. */
+  status;
+  /** Parsed response body, or the raw text when the body was not JSON. */
+  body;
+  constructor(status, message, body) {
+    super(message);
+    this.name = "TextbeeError";
+    this.status = status;
+    this.body = body;
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.textbee.dev/api/v1";
+var CLIENT_ID = `textbee-js/${"0.0.1"}`;
+var Textbee = class {
+  #apiKey;
+  #baseUrl;
+  constructor(options) {
+    if (!options?.apiKey) {
+      throw new TypeError("Textbee requires an apiKey");
+    }
+    this.#apiKey = options.apiKey;
+    this.#baseUrl = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+  }
+  /** Send an SMS to one or more recipients. */
+  async sendSms(request) {
+    const body = {
+      message: request.message,
+      recipients: request.recipients
+    };
+    if (request.deviceId !== void 0) {
+      body.deviceId = request.deviceId;
+    }
+    if (request.simSubscriptionId !== void 0) {
+      body.simSubscriptionId = request.simSubscriptionId;
+    }
+    if (request.scheduledAt !== void 0) {
+      body.scheduledAt = request.scheduledAt instanceof Date ? request.scheduledAt.toISOString() : request.scheduledAt;
+    }
+    const payload = await this.#request(
+      "POST",
+      "/gateway/send-sms",
+      { body }
+    );
+    return payload.data;
+  }
+  /** List the devices registered to this account. */
+  async getDevices() {
+    const payload = await this.#request(
+      "GET",
+      "/gateway/devices"
+    );
+    return payload.data;
+  }
+  /** Fetch a single device by id. */
+  async getDevice(deviceId) {
+    const payload = await this.#request(
+      "GET",
+      `/gateway/devices/${encodeURIComponent(deviceId)}`
+    );
+    return payload.data;
+  }
+  /** Make a device the default sender for requests that omit `deviceId`. */
+  async setDefaultDevice(deviceId) {
+    const payload = await this.#request(
+      "POST",
+      `/gateway/devices/${encodeURIComponent(deviceId)}/set-default`
+    );
+    return payload.data;
+  }
+  /** Page through a device's sent and received messages. */
+  async getMessages(deviceId, options = {}) {
+    return await this.#request(
+      "GET",
+      `/gateway/devices/${encodeURIComponent(deviceId)}/messages`,
+      {
+        query: {
+          type: options.type,
+          page: options.page,
+          limit: options.limit,
+          search: options.search
+        }
+      }
+    );
+  }
+  /** Fetch a single message, including its delivery status. */
+  async getSms(deviceId, smsId) {
+    const payload = await this.#request(
+      "GET",
+      `/gateway/devices/${encodeURIComponent(deviceId)}/sms/${encodeURIComponent(smsId)}`
+    );
+    return payload.data;
+  }
+  /** Fetch a batch and every message in it. Pair this with `smsBatchId` from a send. */
+  async getSmsBatch(deviceId, smsBatchId) {
+    const payload = await this.#request(
+      "GET",
+      `/gateway/devices/${encodeURIComponent(deviceId)}/sms-batch/${encodeURIComponent(smsBatchId)}`
+    );
+    return payload.data;
+  }
+  async #request(method, path, init = {}) {
+    const url = new URL(`${this.#baseUrl}${path}`);
+    for (const [key, value] of Object.entries(init.query ?? {})) {
+      if (value !== void 0) {
+        url.searchParams.set(key, String(value));
+      }
+    }
+    const headers = {
+      "x-api-key": this.#apiKey,
+      "user-agent": CLIENT_ID,
+      "x-sdk-client": CLIENT_ID,
+      accept: "application/json"
+    };
+    if (init.body !== void 0) {
+      headers["content-type"] = "application/json";
+    }
+    const response = await fetch(url, {
+      method,
+      headers,
+      body: init.body === void 0 ? void 0 : JSON.stringify(init.body)
+    });
+    const payload = await readBody(response);
+    if (!response.ok) {
+      throw new TextbeeError(response.status, errorMessage(payload, response.status), payload);
+    }
+    return payload;
+  }
+};
+async function readBody(response) {
+  const text = await response.text();
+  if (!text) {
+    return void 0;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+function errorMessage(payload, status) {
+  if (payload && typeof payload === "object") {
+    const record = payload;
+    if (typeof record.error === "string" && record.error) {
+      return record.error;
+    }
+    if (typeof record.message === "string" && record.message) {
+      return record.message;
+    }
+  }
+  return `HTTP ${status}`;
+}
+
+// src/webhooks.ts
+async function verifyWebhookSignature(options) {
+  const { payload, signature, signingSecret } = options;
+  if (!signature || !signingSecret) {
+    return false;
+  }
+  const body = typeof payload === "string" ? payload : JSON.stringify(payload);
+  const expected = await hmacSha256Hex(signingSecret, body);
+  return constantTimeEqual(expected, signature.toLowerCase());
+}
+async function hmacSha256Hex(secret, message) {
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const digest = await crypto.subtle.sign("HMAC", key, encoder.encode(message));
+  return Array.from(new Uint8Array(digest)).map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function constantTimeEqual(a, b) {
+  if (a.length !== b.length) {
+    return false;
+  }
+  let mismatch = 0;
+  for (let i = 0; i < a.length; i++) {
+    mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return mismatch === 0;
+}
+export {
+  Textbee,
+  TextbeeError,
+  verifyWebhookSignature
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@textbee/sdk",
+  "version": "0.0.1",
+  "description": "Official JavaScript SDK for textbee.dev, the open source SMS gateway",
+  "license": "MIT",
+  "packageManager": "pnpm@9.14.2",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/textbee/textbee-js.git"
+  },
+  "homepage": "https://textbee.dev",
+  "bugs": {
+    "url": "https://github.com/textbee/textbee-js/issues"
+  },
+  "keywords": [
+    "sms",
+    "sms-gateway",
+    "textbee",
+    "android"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}