@textbee/sdk 0.0.2 → 0.1.0

package/README.md

@@ -71,15 +71,34 @@ await textbee.setDefaultDevice(deviceId)
 
 ## Messages and delivery status
 
+History is account-level: one call covers every device, and `deviceIds` narrows it.
+
 ```js
-// Paginated history, filterable and searchable
-const { data, meta } = await textbee.getMessages(deviceId, {
-  type: 'received', // 'all' | 'sent' | 'received'
+// Paginated history across the whole account, filterable and searchable
+const { data, meta } = await textbee.getMessages({
+  direction: 'received', // 'all' | 'sent' | 'received'
+  deviceIds: [deviceId], // omit for every device
+  status: 'delivered', // delivery state; direction=sent + status=failed lists failed sends
+  search: 'invoice',
+  from: '2026-08-01', // dates are UTC; datetimes need an explicit timezone
+  to: '2026-09-01T00:00:00Z', // exclusive, so windows never double-count
   page: 1,
   limit: 50,
-  search: 'invoice',
 })
 
+// direction on each message is lowercase and feeds straight back into filters
+data.filter((m) => m.direction === 'received')
+
+// Which recipients of a bulk send failed: filter by the batch a send returned
+const { smsBatchId } = await textbee.sendSms({ recipients, message })
+const failed = await textbee.getMessages({ smsBatchId, status: 'failed' })
+
+// Drain everything matching a filter: iterateMessages follows the
+// pagination cursor for you until there is nothing left
+for await (const message of textbee.iterateMessages({ direction: 'received', order: 'asc' })) {
+  console.log(message.sender, message.message)
+}
+
 // A single message and its current status
 const sms = await textbee.getSms(deviceId, smsId)
 
@@ -137,7 +156,7 @@ new Textbee({
 
 ## 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).
+The SDK 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
 

package/dist/index.cjs

@@ -42,7 +42,7 @@ var TextbeeError = class extends Error {
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.textbee.dev/api/v1";
-var CLIENT_ID = `textbee-js/${"0.0.2"}`;
+var CLIENT_ID = `textbee-js/${"0.1.0"}`;
 var Textbee = class {
   #apiKey;
   #baseUrl;
@@ -99,20 +99,46 @@ var Textbee = class {
     );
     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
-        }
+  /**
+   * Page through the account's sent and received messages, filtered by
+   * device, batch, direction, status, text, and time range.
+   */
+  async getMessages(options = {}) {
+    return await this.#request("GET", "/gateway/messages", {
+      query: {
+        deviceIds: options.deviceIds?.length ? options.deviceIds.join(",") : void 0,
+        smsBatchId: options.smsBatchId,
+        direction: options.direction,
+        status: options.status,
+        search: options.search,
+        from: toIsoString(options.from),
+        to: toIsoString(options.to),
+        order: options.order,
+        page: options.page,
+        limit: options.limit,
+        cursor: options.cursor
       }
-    );
+    });
+  }
+  /**
+   * Iterate every message matching the filters, following the pagination
+   * cursor until the end. Use `order: 'asc'` with a `from` bound to drain
+   * forward when polling; keep the last message's `createdAt` (or track
+   * `meta.nextCursor` via `getMessages`) to resume the next poll.
+   *
+   * ```ts
+   * for await (const message of textbee.iterateMessages({ direction: 'received' })) {
+   *   handle(message)
+   * }
+   * ```
+   */
+  async *iterateMessages(options = {}) {
+    let page = await this.getMessages(options);
+    yield* page.data;
+    while (page.meta.nextCursor) {
+      page = await this.getMessages({ ...options, cursor: page.meta.nextCursor });
+      yield* page.data;
+    }
   }
   /** Fetch a single message, including its delivery status. */
   async getSms(deviceId, smsId) {
@@ -158,6 +184,9 @@ var Textbee = class {
     return payload;
   }
 };
+function toIsoString(value) {
+  return value instanceof Date ? value.toISOString() : value;
+}
 async function readBody(response) {
   const text = await response.text();
   if (!text) {

package/dist/index.d.cts

@@ -54,16 +54,42 @@ interface SendSmsImmediateResponse {
  * with `'smsBatchId' in result` before reading batch fields.
  */
 type SendSmsResponse = SendSmsQueuedResponse | SendSmsImmediateResponse;
-interface GetMessagesOptions {
+interface ListMessagesOptions {
+    /** Only messages from these devices. Omit for every device on the account. */
+    deviceIds?: string[];
+    /**
+     * Only messages from this batch, using the `smsBatchId` a send returns.
+     * Combine with `status: 'failed'` to list the recipients that failed.
+     */
+    smsBatchId?: string;
     /** Filter by direction. Defaults to `all`. */
-    type?: 'all' | 'sent' | 'received';
-    /** 1-based page number. Defaults to 1. */
+    direction?: 'all' | 'sent' | 'received';
+    /** Filter by delivery state, e.g. `failed` to list sends that failed. */
+    status?: 'pending' | 'dispatched' | 'sent' | 'delivered' | 'failed' | 'unknown' | 'received';
+    /** Free text match across the message body, recipient, and sender. */
+    search?: string;
+    /**
+     * Inclusive lower bound on when the platform stored the message. A string
+     * must carry an explicit timezone (`2026-08-01T00:00:00Z`); a bare date like
+     * `2026-08-01` is read as UTC midnight.
+     */
+    from?: string | Date;
+    /** Exclusive upper bound, same formats as `from`. */
+    to?: string | Date;
+    /** `desc` (default) for newest first, `asc` to walk forward when polling. */
+    order?: 'desc' | 'asc';
+    /** 1-based page number. Defaults to 1. Mutually exclusive with `cursor`. */
     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;
+    /**
+     * Opaque position from a previous response's `meta.nextCursor`. When set,
+     * `meta` switches to cursor mode and omits the total count.
+     */
+    cursor?: string;
 }
+/** Everything `iterateMessages` accepts: a filter set, minus the paging knobs it drives itself. */
+type IterateMessagesOptions = Omit<ListMessagesOptions, 'page' | 'cursor'>;
 interface Device {
     _id: string;
     name?: string;
@@ -82,11 +108,31 @@ interface Device {
     createdAt?: string;
     updatedAt?: string;
 }
+interface MessageDevice {
+    _id: string;
+    brand?: string;
+    model?: string;
+    buildId?: string;
+    enabled?: boolean;
+}
 interface Message {
     _id: string;
     message: string;
-    type: 'sent' | 'received';
-    status: 'pending' | 'dispatched' | 'sent' | 'delivered' | 'failed' | 'unknown' | 'received';
+    /**
+     * Direction, uppercase.
+     *
+     * @deprecated Read `direction` instead: it is lowercase and matches the
+     * `direction` filter, so a response value feeds straight back into a query.
+     */
+    type: 'SENT' | 'RECEIVED';
+    /** Direction, lowercase. Matches the `direction` filter values. */
+    direction?: 'sent' | 'received';
+    /** Message channel. Currently always `sms`; absent means `sms`. */
+    channel?: string;
+    /** The sending or receiving device, populated by the history endpoints. */
+    device?: MessageDevice;
+    /** Lowercase, and absent on messages stored before status tracking. */
+    status?: 'pending' | 'dispatched' | 'sent' | 'delivered' | 'failed' | 'unknown' | 'received';
     sender?: string;
     recipient?: string;
     requestedAt?: string;
@@ -115,15 +161,23 @@ interface SmsBatch {
     createdAt?: string;
     updatedAt?: string;
 }
-interface PaginationMeta {
-    page: number;
+/**
+ * Meta for the account-level message list. Page mode carries the counters and
+ * the cursor fields; cursor mode carries `limit`, `nextCursor`, and `hasMore`
+ * only, skipping the expensive total count.
+ */
+interface MessageListMeta {
     limit: number;
-    total: number;
-    totalPages: number;
+    page?: number;
+    total?: number;
+    totalPages?: number;
+    /** Opaque position after the last message. Null on the final page. */
+    nextCursor?: string | null;
+    hasMore?: boolean;
 }
-interface MessagesPage {
+interface MessageList {
     data: Message[];
-    meta: PaginationMeta;
+    meta: MessageListMeta;
 }
 interface SmsBatchResult {
     batch: SmsBatch;
@@ -143,8 +197,24 @@ declare class Textbee {
     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>;
+    /**
+     * Page through the account's sent and received messages, filtered by
+     * device, batch, direction, status, text, and time range.
+     */
+    getMessages(options?: ListMessagesOptions): Promise<MessageList>;
+    /**
+     * Iterate every message matching the filters, following the pagination
+     * cursor until the end. Use `order: 'asc'` with a `from` bound to drain
+     * forward when polling; keep the last message's `createdAt` (or track
+     * `meta.nextCursor` via `getMessages`) to resume the next poll.
+     *
+     * ```ts
+     * for await (const message of textbee.iterateMessages({ direction: 'received' })) {
+     *   handle(message)
+     * }
+     * ```
+     */
+    iterateMessages(options?: IterateMessagesOptions): AsyncGenerator<Message, void, undefined>;
     /** 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. */
@@ -186,4 +256,4 @@ interface VerifyWebhookSignatureOptions {
  */
 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 };
+export { type Device, type IterateMessagesOptions, type ListMessagesOptions, type Message, type MessageDevice, type MessageList, type MessageListMeta, 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

@@ -54,16 +54,42 @@ interface SendSmsImmediateResponse {
  * with `'smsBatchId' in result` before reading batch fields.
  */
 type SendSmsResponse = SendSmsQueuedResponse | SendSmsImmediateResponse;
-interface GetMessagesOptions {
+interface ListMessagesOptions {
+    /** Only messages from these devices. Omit for every device on the account. */
+    deviceIds?: string[];
+    /**
+     * Only messages from this batch, using the `smsBatchId` a send returns.
+     * Combine with `status: 'failed'` to list the recipients that failed.
+     */
+    smsBatchId?: string;
     /** Filter by direction. Defaults to `all`. */
-    type?: 'all' | 'sent' | 'received';
-    /** 1-based page number. Defaults to 1. */
+    direction?: 'all' | 'sent' | 'received';
+    /** Filter by delivery state, e.g. `failed` to list sends that failed. */
+    status?: 'pending' | 'dispatched' | 'sent' | 'delivered' | 'failed' | 'unknown' | 'received';
+    /** Free text match across the message body, recipient, and sender. */
+    search?: string;
+    /**
+     * Inclusive lower bound on when the platform stored the message. A string
+     * must carry an explicit timezone (`2026-08-01T00:00:00Z`); a bare date like
+     * `2026-08-01` is read as UTC midnight.
+     */
+    from?: string | Date;
+    /** Exclusive upper bound, same formats as `from`. */
+    to?: string | Date;
+    /** `desc` (default) for newest first, `asc` to walk forward when polling. */
+    order?: 'desc' | 'asc';
+    /** 1-based page number. Defaults to 1. Mutually exclusive with `cursor`. */
     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;
+    /**
+     * Opaque position from a previous response's `meta.nextCursor`. When set,
+     * `meta` switches to cursor mode and omits the total count.
+     */
+    cursor?: string;
 }
+/** Everything `iterateMessages` accepts: a filter set, minus the paging knobs it drives itself. */
+type IterateMessagesOptions = Omit<ListMessagesOptions, 'page' | 'cursor'>;
 interface Device {
     _id: string;
     name?: string;
@@ -82,11 +108,31 @@ interface Device {
     createdAt?: string;
     updatedAt?: string;
 }
+interface MessageDevice {
+    _id: string;
+    brand?: string;
+    model?: string;
+    buildId?: string;
+    enabled?: boolean;
+}
 interface Message {
     _id: string;
     message: string;
-    type: 'sent' | 'received';
-    status: 'pending' | 'dispatched' | 'sent' | 'delivered' | 'failed' | 'unknown' | 'received';
+    /**
+     * Direction, uppercase.
+     *
+     * @deprecated Read `direction` instead: it is lowercase and matches the
+     * `direction` filter, so a response value feeds straight back into a query.
+     */
+    type: 'SENT' | 'RECEIVED';
+    /** Direction, lowercase. Matches the `direction` filter values. */
+    direction?: 'sent' | 'received';
+    /** Message channel. Currently always `sms`; absent means `sms`. */
+    channel?: string;
+    /** The sending or receiving device, populated by the history endpoints. */
+    device?: MessageDevice;
+    /** Lowercase, and absent on messages stored before status tracking. */
+    status?: 'pending' | 'dispatched' | 'sent' | 'delivered' | 'failed' | 'unknown' | 'received';
     sender?: string;
     recipient?: string;
     requestedAt?: string;
@@ -115,15 +161,23 @@ interface SmsBatch {
     createdAt?: string;
     updatedAt?: string;
 }
-interface PaginationMeta {
-    page: number;
+/**
+ * Meta for the account-level message list. Page mode carries the counters and
+ * the cursor fields; cursor mode carries `limit`, `nextCursor`, and `hasMore`
+ * only, skipping the expensive total count.
+ */
+interface MessageListMeta {
     limit: number;
-    total: number;
-    totalPages: number;
+    page?: number;
+    total?: number;
+    totalPages?: number;
+    /** Opaque position after the last message. Null on the final page. */
+    nextCursor?: string | null;
+    hasMore?: boolean;
 }
-interface MessagesPage {
+interface MessageList {
     data: Message[];
-    meta: PaginationMeta;
+    meta: MessageListMeta;
 }
 interface SmsBatchResult {
     batch: SmsBatch;
@@ -143,8 +197,24 @@ declare class Textbee {
     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>;
+    /**
+     * Page through the account's sent and received messages, filtered by
+     * device, batch, direction, status, text, and time range.
+     */
+    getMessages(options?: ListMessagesOptions): Promise<MessageList>;
+    /**
+     * Iterate every message matching the filters, following the pagination
+     * cursor until the end. Use `order: 'asc'` with a `from` bound to drain
+     * forward when polling; keep the last message's `createdAt` (or track
+     * `meta.nextCursor` via `getMessages`) to resume the next poll.
+     *
+     * ```ts
+     * for await (const message of textbee.iterateMessages({ direction: 'received' })) {
+     *   handle(message)
+     * }
+     * ```
+     */
+    iterateMessages(options?: IterateMessagesOptions): AsyncGenerator<Message, void, undefined>;
     /** 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. */
@@ -186,4 +256,4 @@ interface VerifyWebhookSignatureOptions {
  */
 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 };
+export { type Device, type IterateMessagesOptions, type ListMessagesOptions, type Message, type MessageDevice, type MessageList, type MessageListMeta, 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

@@ -14,7 +14,7 @@ var TextbeeError = class extends Error {
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.textbee.dev/api/v1";
-var CLIENT_ID = `textbee-js/${"0.0.2"}`;
+var CLIENT_ID = `textbee-js/${"0.1.0"}`;
 var Textbee = class {
   #apiKey;
   #baseUrl;
@@ -71,20 +71,46 @@ var Textbee = class {
     );
     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
-        }
+  /**
+   * Page through the account's sent and received messages, filtered by
+   * device, batch, direction, status, text, and time range.
+   */
+  async getMessages(options = {}) {
+    return await this.#request("GET", "/gateway/messages", {
+      query: {
+        deviceIds: options.deviceIds?.length ? options.deviceIds.join(",") : void 0,
+        smsBatchId: options.smsBatchId,
+        direction: options.direction,
+        status: options.status,
+        search: options.search,
+        from: toIsoString(options.from),
+        to: toIsoString(options.to),
+        order: options.order,
+        page: options.page,
+        limit: options.limit,
+        cursor: options.cursor
       }
-    );
+    });
+  }
+  /**
+   * Iterate every message matching the filters, following the pagination
+   * cursor until the end. Use `order: 'asc'` with a `from` bound to drain
+   * forward when polling; keep the last message's `createdAt` (or track
+   * `meta.nextCursor` via `getMessages`) to resume the next poll.
+   *
+   * ```ts
+   * for await (const message of textbee.iterateMessages({ direction: 'received' })) {
+   *   handle(message)
+   * }
+   * ```
+   */
+  async *iterateMessages(options = {}) {
+    let page = await this.getMessages(options);
+    yield* page.data;
+    while (page.meta.nextCursor) {
+      page = await this.getMessages({ ...options, cursor: page.meta.nextCursor });
+      yield* page.data;
+    }
   }
   /** Fetch a single message, including its delivery status. */
   async getSms(deviceId, smsId) {
@@ -130,6 +156,9 @@ var Textbee = class {
     return payload;
   }
 };
+function toIsoString(value) {
+  return value instanceof Date ? value.toISOString() : value;
+}
 async function readBody(response) {
   const text = await response.text();
   if (!text) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@textbee/sdk",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "description": "Official JavaScript SDK for textbee.dev, the open source SMS gateway",
   "license": "MIT",
   "packageManager": "pnpm@9.14.2",