@textbee/sdk 0.2.0 → 0.3.1

package/README.md

@@ -8,6 +8,8 @@ Official JavaScript SDK for [textbee.dev](https://textbee.dev), the open source
 
 Zero dependencies, TypeScript types included, works in Node 18+, Bun, Deno, Cloudflare Workers, and Vercel Edge.
 
+Writing Python? Use the official [Python SDK](https://github.com/textbee/textbee-python): `pip install textbee`.
+
 ## Install
 
 ```bash
@@ -41,7 +43,7 @@ await textbee.sendSms({
 | --- | --- | --- |
 | `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. |
+| `scheduledAt` | `string \| Date` | Send later instead of now. ISO 8601 or a `Date`, must be in the future. |
 
 ```js
 await textbee.sendSms({
@@ -76,9 +78,9 @@ History is account-level: one call covers every device, and `deviceIds` narrows
 ```js
 // Paginated history across the whole account, filterable and searchable
 const { data, meta } = await textbee.getMessages({
-  direction: 'received', // 'all' | 'sent' | 'received'
+  direction: 'sent', // 'all' | 'sent' | 'received'
   deviceIds: [deviceId], // omit for every device
-  status: 'delivered', // delivery state; direction=sent + status=failed lists failed sends
+  status: 'delivered', // delivery state; 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
@@ -87,7 +89,7 @@ const { data, meta } = await textbee.getMessages({
 })
 
 // direction on each message is lowercase and feeds straight back into filters
-data.filter((m) => m.direction === 'received')
+data.filter((m) => m.direction === 'sent')
 
 // Which recipients of a bulk send failed: filter by the batch a send returned
 const { smsBatchId } = await textbee.sendSms({ recipients, message })
@@ -102,10 +104,16 @@ for await (const message of textbee.iterateMessages({ direction: 'received', ord
 // A single message and its current status
 const sms = await textbee.getSms(deviceId, smsId)
 
-// A whole batch, using the smsBatchId returned by sendSms
+// A whole batch, using the smsBatchId returned by sendSms. This needs the id
+// of the device that sent it; when textbee picked the device, use
+// getMessages({ smsBatchId }) instead.
 const { batch, messages } = await textbee.getSmsBatch(deviceId, smsBatchId)
 ```
 
+`getSms` and `getSmsBatch` return the `Sms` type. It differs from the `Message` that `getMessages` returns: `device` is the device id string, not an object with the phone's name and model, and `direction` is absent (read `type`).
+
+`batch.status` and the batch counts come from the messages in the batch, so they change as each message reports. `successCount` counts messages sent or delivered, and `failureCount` counts failed ones. `pendingCount`, `dispatchedCount`, `sentCount`, `deliveredCount` and `unknownCount` break the rest down by state.
+
 ## 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.
@@ -209,14 +217,30 @@ try {
 ```js
 new Textbee({
   apiKey: 'your-api-key',
-  baseUrl: 'https://api.textbee.dev/api/v1', // override for self-hosted instances
+  baseUrl: 'https://api.textbee.dev/api/v1', // the default
 })
 ```
 
+### Self-hosted textbee
+
+Point `baseUrl` at your own instance. The `/api/v1` suffix is optional, so all of these reach the same API:
+
+```js
+new Textbee({ apiKey, baseUrl: 'https://sms.example.com' })
+new Textbee({ apiKey, baseUrl: 'https://sms.example.com/api/v1' })
+new Textbee({ apiKey, baseUrl: 'http://localhost:3001' })
+```
+
+If the API sits under a path prefix, give the prefix: `https://example.com/textbee` reaches `https://example.com/textbee/api/v1`. The SDK adds `/api/v1` unless the path already contains it, the same rule the textbee MCP server uses for `TEXTBEE_BASE_URL`. A value with no scheme gets `https://`. An invalid URL, or one with a username or password, throws a `TypeError` instead of falling back to the hosted API, so a typo never sends your key to textbee.dev.
+
 ## What is not covered yet
 
 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).
 
+## Community and support
+
+Questions or feedback? Join the community on [Discord](https://textbee.dev/discord) or email support@textbee.dev.
+
 ## License
 
-MIT. Part of the [textbee](https://github.com/vernu/textbee) project.
+MIT. Part of the [textbee](https://github.com/textbee/textbee) project.

package/dist/index.cjs

@@ -48,7 +48,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.2.0"}`;
+var CLIENT_ID = `textbee-js/${"0.3.1"}`;
 var Textbee = class {
   #apiKey;
   #baseUrl;
@@ -57,7 +57,7 @@ var Textbee = class {
       throw new TypeError("Textbee requires an apiKey");
     }
     this.#apiKey = options.apiKey;
-    this.#baseUrl = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.#baseUrl = normalizeBaseUrl(options.baseUrl);
   }
   /** Send an SMS to one or more recipients. */
   async sendSms(request) {
@@ -128,9 +128,10 @@ var Textbee = class {
   }
   /**
    * 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.
+   * cursor until the end. `limit` is the page size, not a cap on the total.
+   * Use `order: 'asc'` with a `from` bound to drain forward when polling.
+   * `from` is inclusive, so a poll that resumes from the last `createdAt` sees
+   * that message again; skip ids you have already handled.
    *
    * ```ts
    * for await (const message of textbee.iterateMessages({ direction: 'received' })) {
@@ -154,7 +155,11 @@ var Textbee = class {
     );
     return payload.data;
   }
-  /** Fetch a batch and every message in it. Pair this with `smsBatchId` from a send. */
+  /**
+   * Fetch a batch and every message in it, by the `smsBatchId` a send returns.
+   * Needs the id of the device that sent the batch. When textbee picked the
+   * device, use `getMessages({ smsBatchId })` instead.
+   */
   async getSmsBatch(deviceId, smsBatchId) {
     const payload = await this.#request(
       "GET",
@@ -190,6 +195,42 @@ var Textbee = class {
     return payload;
   }
 };
+function normalizeBaseUrl(raw) {
+  const value = raw?.trim();
+  if (!value) {
+    return DEFAULT_BASE_URL;
+  }
+  const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(value) ? value : `https://${value}`;
+  let url;
+  try {
+    url = new URL(withScheme);
+  } catch {
+    throw new TypeError(
+      "baseUrl is not a valid URL. Use your textbee api, for example https://sms.example.com. The /api/v1 suffix is added for you."
+    );
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw new TypeError(`baseUrl must be http or https, got "${url.protocol}"`);
+  }
+  if (url.username || url.password) {
+    throw new TypeError("baseUrl must not contain a username or password");
+  }
+  const segments = url.pathname.split("/").filter(Boolean);
+  let cut = -1;
+  for (let i = segments.length - 2; i >= 0; i--) {
+    if (segments[i].toLowerCase() === "api" && segments[i + 1].toLowerCase() === "v1") {
+      cut = i + 2;
+      break;
+    }
+  }
+  let path;
+  if (cut === -1) {
+    path = [...segments, "api", "v1"];
+  } else {
+    path = [...segments.slice(0, cut - 2), "api", "v1"];
+  }
+  return [url.origin, ...path].join("/");
+}
 function toIsoString(value) {
   return value instanceof Date ? value.toISOString() : value;
 }
@@ -207,11 +248,15 @@ async function readBody(response) {
 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;
+    const keys = "statusCode" in record ? ["message", "error"] : ["error", "message"];
+    for (const key of keys) {
+      const value = record[key];
+      if (typeof value === "string" && value) {
+        return value;
+      }
+      if (Array.isArray(value) && value.length > 0 && value.every((item) => typeof item === "string")) {
+        return value.join("; ");
+      }
     }
   }
   return `HTTP ${status}`;

package/dist/index.d.cts

@@ -1,7 +1,15 @@
 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`. */
+    /**
+     * Your self-hosted textbee API. Defaults to `https://api.textbee.dev/api/v1`.
+     *
+     * `/api/v1` is added unless the path already contains it, so
+     * `https://sms.example.com` and `https://example.com/textbee` both work. A URL
+     * that contains `/api/v1` is cut there, so a pasted endpoint URL still works.
+     * A value with no scheme gets `https://`. An invalid URL throws a `TypeError`
+     * rather than falling back, so a typo never sends your key to the public API.
+     */
     baseUrl?: string;
 }
 interface SendSmsRequest {
@@ -33,20 +41,32 @@ interface SendSmsRequest {
     /**
      * 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.
+     * Must be in the future. Omit for an immediate send.
      */
     scheduledAt?: string | Date;
 }
+/** A reason the send will probably fail, such as `SMS_PERMISSION_MISSING`. */
+interface SendSmsWarning {
+    code: string;
+    message: string;
+}
 /** Returned when the message was accepted for delivery and queued. */
 interface SendSmsQueuedResponse {
     success: true;
     message: string;
     smsBatchId: string;
     recipientCount: number;
+    /** When a large send, spread over several waves, should finish. */
+    estimatedCompletionAt?: string;
+    /** Present when the phone last reported a problem, such as the SMS permission off. */
+    warning?: SendSmsWarning;
 }
 /** Returned when the message was dispatched to the device immediately. */
 interface SendSmsImmediateResponse {
     successCount: number;
+    failureCount?: number;
+    /** Present when the phone last reported a problem, such as the SMS permission off. */
+    warning?: SendSmsWarning;
     [key: string]: unknown;
 }
 /**
@@ -110,6 +130,7 @@ interface Device {
 }
 interface MessageDevice {
     _id: string;
+    name?: string;
     brand?: string;
     model?: string;
     buildId?: string;
@@ -129,7 +150,7 @@ interface Message {
     direction?: 'sent' | 'received';
     /** Message channel. Currently always `sms`; absent means `sms`. */
     channel?: string;
-    /** The sending or receiving device, populated by the history endpoints. */
+    /** The sending or receiving device. */
     device?: MessageDevice;
     /** Lowercase, and absent on messages stored before status tracking. */
     status?: 'pending' | 'dispatched' | 'sent' | 'delivered' | 'failed' | 'unknown' | 'received';
@@ -148,16 +169,35 @@ interface Message {
     createdAt?: string;
     updatedAt?: string;
 }
+/**
+ * A send batch. The status and counts are calculated from the batch's
+ * messages, so they change as each message reports.
+ */
 interface SmsBatch {
     _id: string;
     message: string;
     recipientCount: number;
     recipientPreview?: string;
+    /** Messages sent or delivered: `sentCount + deliveredCount`. */
     successCount: number;
+    /** Messages that failed. */
     failureCount: number;
+    /** Messages not yet handed to the phone. */
+    pendingCount?: number;
+    /** Messages handed to the phone with no result yet. */
+    dispatchedCount?: number;
+    /** Messages sent with no delivery report yet. */
+    sentCount?: number;
+    /** Messages with a delivery report. */
+    deliveredCount?: number;
+    /** Messages with no report from the phone within 20 minutes. */
+    unknownCount?: number;
     status: 'pending' | 'processing' | 'completed' | 'partial_success' | 'failed' | 'unknown';
     error?: string;
+    /** When the batch reached its current final status. Absent while processing. */
     completedAt?: string;
+    /** When the status and counts were last calculated. */
+    statusCheckedAt?: string;
     createdAt?: string;
     updatedAt?: string;
 }
@@ -175,13 +215,21 @@ interface MessageListMeta {
     nextCursor?: string | null;
     hasMore?: boolean;
 }
+/**
+ * A message as `getSms` and `getSmsBatch` return it: `device` is the id
+ * string, and `direction` is absent (read `type`).
+ */
+interface Sms extends Omit<Message, 'device' | 'direction'> {
+    /** The id of the sending or receiving device. */
+    device?: string;
+}
 interface MessageList {
     data: Message[];
     meta: MessageListMeta;
 }
 interface SmsBatchResult {
     batch: SmsBatch;
-    messages: Message[];
+    messages: Sms[];
 }
 /** Event names textbee sends in a webhook payload. */
 type WebhookEvent = 'MESSAGE_RECEIVED' | 'MESSAGE_SENT' | 'MESSAGE_DELIVERED' | 'MESSAGE_FAILED' | 'UNKNOWN_STATE' | 'SMS_STATUS_UPDATED';
@@ -204,9 +252,10 @@ declare class Textbee {
     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.
+     * cursor until the end. `limit` is the page size, not a cap on the total.
+     * Use `order: 'asc'` with a `from` bound to drain forward when polling.
+     * `from` is inclusive, so a poll that resumes from the last `createdAt` sees
+     * that message again; skip ids you have already handled.
      *
      * ```ts
      * for await (const message of textbee.iterateMessages({ direction: 'received' })) {
@@ -216,8 +265,12 @@ declare class Textbee {
      */
     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. */
+    getSms(deviceId: string, smsId: string): Promise<Sms>;
+    /**
+     * Fetch a batch and every message in it, by the `smsBatchId` a send returns.
+     * Needs the id of the device that sent the batch. When textbee picked the
+     * device, use `getMessages({ smsBatchId })` instead.
+     */
     getSmsBatch(deviceId: string, smsBatchId: string): Promise<SmsBatchResult>;
 }
 
@@ -347,4 +400,4 @@ interface VerifyWebhookSignatureOptions {
  */
 declare function verifyWebhookSignature(options: VerifyWebhookSignatureOptions): Promise<boolean>;
 
-export { type Device, type IterateMessagesOptions, type ListMessagesOptions, type Message, type MessageDevice, type MessageList, type MessageListMeta, type NormalizePhoneNumberOptions, type SanitizeForGsm7Options, type SendSmsImmediateResponse, type SendSmsQueuedResponse, type SendSmsRequest, type SendSmsResponse, type SmsBatch, type SmsBatchResult, type SmsEncoding, type SmsSegmentInfo, Textbee, TextbeeError, type TextbeeOptions, type VerifyWebhookSignatureOptions, type WebhookEvent, countSmsSegments, findNonGsm7Characters, getSmsEncoding, isValidE164, normalizePhoneNumber, sanitizeForGsm7, verifyWebhookSignature };
+export { type Device, type IterateMessagesOptions, type ListMessagesOptions, type Message, type MessageDevice, type MessageList, type MessageListMeta, type NormalizePhoneNumberOptions, type SanitizeForGsm7Options, type SendSmsImmediateResponse, type SendSmsQueuedResponse, type SendSmsRequest, type SendSmsResponse, type SendSmsWarning, type Sms, type SmsBatch, type SmsBatchResult, type SmsEncoding, type SmsSegmentInfo, Textbee, TextbeeError, type TextbeeOptions, type VerifyWebhookSignatureOptions, type WebhookEvent, countSmsSegments, findNonGsm7Characters, getSmsEncoding, isValidE164, normalizePhoneNumber, sanitizeForGsm7, verifyWebhookSignature };

package/dist/index.d.ts

@@ -1,7 +1,15 @@
 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`. */
+    /**
+     * Your self-hosted textbee API. Defaults to `https://api.textbee.dev/api/v1`.
+     *
+     * `/api/v1` is added unless the path already contains it, so
+     * `https://sms.example.com` and `https://example.com/textbee` both work. A URL
+     * that contains `/api/v1` is cut there, so a pasted endpoint URL still works.
+     * A value with no scheme gets `https://`. An invalid URL throws a `TypeError`
+     * rather than falling back, so a typo never sends your key to the public API.
+     */
     baseUrl?: string;
 }
 interface SendSmsRequest {
@@ -33,20 +41,32 @@ interface SendSmsRequest {
     /**
      * 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.
+     * Must be in the future. Omit for an immediate send.
      */
     scheduledAt?: string | Date;
 }
+/** A reason the send will probably fail, such as `SMS_PERMISSION_MISSING`. */
+interface SendSmsWarning {
+    code: string;
+    message: string;
+}
 /** Returned when the message was accepted for delivery and queued. */
 interface SendSmsQueuedResponse {
     success: true;
     message: string;
     smsBatchId: string;
     recipientCount: number;
+    /** When a large send, spread over several waves, should finish. */
+    estimatedCompletionAt?: string;
+    /** Present when the phone last reported a problem, such as the SMS permission off. */
+    warning?: SendSmsWarning;
 }
 /** Returned when the message was dispatched to the device immediately. */
 interface SendSmsImmediateResponse {
     successCount: number;
+    failureCount?: number;
+    /** Present when the phone last reported a problem, such as the SMS permission off. */
+    warning?: SendSmsWarning;
     [key: string]: unknown;
 }
 /**
@@ -110,6 +130,7 @@ interface Device {
 }
 interface MessageDevice {
     _id: string;
+    name?: string;
     brand?: string;
     model?: string;
     buildId?: string;
@@ -129,7 +150,7 @@ interface Message {
     direction?: 'sent' | 'received';
     /** Message channel. Currently always `sms`; absent means `sms`. */
     channel?: string;
-    /** The sending or receiving device, populated by the history endpoints. */
+    /** The sending or receiving device. */
     device?: MessageDevice;
     /** Lowercase, and absent on messages stored before status tracking. */
     status?: 'pending' | 'dispatched' | 'sent' | 'delivered' | 'failed' | 'unknown' | 'received';
@@ -148,16 +169,35 @@ interface Message {
     createdAt?: string;
     updatedAt?: string;
 }
+/**
+ * A send batch. The status and counts are calculated from the batch's
+ * messages, so they change as each message reports.
+ */
 interface SmsBatch {
     _id: string;
     message: string;
     recipientCount: number;
     recipientPreview?: string;
+    /** Messages sent or delivered: `sentCount + deliveredCount`. */
     successCount: number;
+    /** Messages that failed. */
     failureCount: number;
+    /** Messages not yet handed to the phone. */
+    pendingCount?: number;
+    /** Messages handed to the phone with no result yet. */
+    dispatchedCount?: number;
+    /** Messages sent with no delivery report yet. */
+    sentCount?: number;
+    /** Messages with a delivery report. */
+    deliveredCount?: number;
+    /** Messages with no report from the phone within 20 minutes. */
+    unknownCount?: number;
     status: 'pending' | 'processing' | 'completed' | 'partial_success' | 'failed' | 'unknown';
     error?: string;
+    /** When the batch reached its current final status. Absent while processing. */
     completedAt?: string;
+    /** When the status and counts were last calculated. */
+    statusCheckedAt?: string;
     createdAt?: string;
     updatedAt?: string;
 }
@@ -175,13 +215,21 @@ interface MessageListMeta {
     nextCursor?: string | null;
     hasMore?: boolean;
 }
+/**
+ * A message as `getSms` and `getSmsBatch` return it: `device` is the id
+ * string, and `direction` is absent (read `type`).
+ */
+interface Sms extends Omit<Message, 'device' | 'direction'> {
+    /** The id of the sending or receiving device. */
+    device?: string;
+}
 interface MessageList {
     data: Message[];
     meta: MessageListMeta;
 }
 interface SmsBatchResult {
     batch: SmsBatch;
-    messages: Message[];
+    messages: Sms[];
 }
 /** Event names textbee sends in a webhook payload. */
 type WebhookEvent = 'MESSAGE_RECEIVED' | 'MESSAGE_SENT' | 'MESSAGE_DELIVERED' | 'MESSAGE_FAILED' | 'UNKNOWN_STATE' | 'SMS_STATUS_UPDATED';
@@ -204,9 +252,10 @@ declare class Textbee {
     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.
+     * cursor until the end. `limit` is the page size, not a cap on the total.
+     * Use `order: 'asc'` with a `from` bound to drain forward when polling.
+     * `from` is inclusive, so a poll that resumes from the last `createdAt` sees
+     * that message again; skip ids you have already handled.
      *
      * ```ts
      * for await (const message of textbee.iterateMessages({ direction: 'received' })) {
@@ -216,8 +265,12 @@ declare class Textbee {
      */
     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. */
+    getSms(deviceId: string, smsId: string): Promise<Sms>;
+    /**
+     * Fetch a batch and every message in it, by the `smsBatchId` a send returns.
+     * Needs the id of the device that sent the batch. When textbee picked the
+     * device, use `getMessages({ smsBatchId })` instead.
+     */
     getSmsBatch(deviceId: string, smsBatchId: string): Promise<SmsBatchResult>;
 }
 
@@ -347,4 +400,4 @@ interface VerifyWebhookSignatureOptions {
  */
 declare function verifyWebhookSignature(options: VerifyWebhookSignatureOptions): Promise<boolean>;
 
-export { type Device, type IterateMessagesOptions, type ListMessagesOptions, type Message, type MessageDevice, type MessageList, type MessageListMeta, type NormalizePhoneNumberOptions, type SanitizeForGsm7Options, type SendSmsImmediateResponse, type SendSmsQueuedResponse, type SendSmsRequest, type SendSmsResponse, type SmsBatch, type SmsBatchResult, type SmsEncoding, type SmsSegmentInfo, Textbee, TextbeeError, type TextbeeOptions, type VerifyWebhookSignatureOptions, type WebhookEvent, countSmsSegments, findNonGsm7Characters, getSmsEncoding, isValidE164, normalizePhoneNumber, sanitizeForGsm7, verifyWebhookSignature };
+export { type Device, type IterateMessagesOptions, type ListMessagesOptions, type Message, type MessageDevice, type MessageList, type MessageListMeta, type NormalizePhoneNumberOptions, type SanitizeForGsm7Options, type SendSmsImmediateResponse, type SendSmsQueuedResponse, type SendSmsRequest, type SendSmsResponse, type SendSmsWarning, type Sms, type SmsBatch, type SmsBatchResult, type SmsEncoding, type SmsSegmentInfo, Textbee, TextbeeError, type TextbeeOptions, type VerifyWebhookSignatureOptions, type WebhookEvent, countSmsSegments, findNonGsm7Characters, getSmsEncoding, isValidE164, normalizePhoneNumber, sanitizeForGsm7, 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.2.0"}`;
+var CLIENT_ID = `textbee-js/${"0.3.1"}`;
 var Textbee = class {
   #apiKey;
   #baseUrl;
@@ -23,7 +23,7 @@ var Textbee = class {
       throw new TypeError("Textbee requires an apiKey");
     }
     this.#apiKey = options.apiKey;
-    this.#baseUrl = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.#baseUrl = normalizeBaseUrl(options.baseUrl);
   }
   /** Send an SMS to one or more recipients. */
   async sendSms(request) {
@@ -94,9 +94,10 @@ var Textbee = class {
   }
   /**
    * 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.
+   * cursor until the end. `limit` is the page size, not a cap on the total.
+   * Use `order: 'asc'` with a `from` bound to drain forward when polling.
+   * `from` is inclusive, so a poll that resumes from the last `createdAt` sees
+   * that message again; skip ids you have already handled.
    *
    * ```ts
    * for await (const message of textbee.iterateMessages({ direction: 'received' })) {
@@ -120,7 +121,11 @@ var Textbee = class {
     );
     return payload.data;
   }
-  /** Fetch a batch and every message in it. Pair this with `smsBatchId` from a send. */
+  /**
+   * Fetch a batch and every message in it, by the `smsBatchId` a send returns.
+   * Needs the id of the device that sent the batch. When textbee picked the
+   * device, use `getMessages({ smsBatchId })` instead.
+   */
   async getSmsBatch(deviceId, smsBatchId) {
     const payload = await this.#request(
       "GET",
@@ -156,6 +161,42 @@ var Textbee = class {
     return payload;
   }
 };
+function normalizeBaseUrl(raw) {
+  const value = raw?.trim();
+  if (!value) {
+    return DEFAULT_BASE_URL;
+  }
+  const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(value) ? value : `https://${value}`;
+  let url;
+  try {
+    url = new URL(withScheme);
+  } catch {
+    throw new TypeError(
+      "baseUrl is not a valid URL. Use your textbee api, for example https://sms.example.com. The /api/v1 suffix is added for you."
+    );
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw new TypeError(`baseUrl must be http or https, got "${url.protocol}"`);
+  }
+  if (url.username || url.password) {
+    throw new TypeError("baseUrl must not contain a username or password");
+  }
+  const segments = url.pathname.split("/").filter(Boolean);
+  let cut = -1;
+  for (let i = segments.length - 2; i >= 0; i--) {
+    if (segments[i].toLowerCase() === "api" && segments[i + 1].toLowerCase() === "v1") {
+      cut = i + 2;
+      break;
+    }
+  }
+  let path;
+  if (cut === -1) {
+    path = [...segments, "api", "v1"];
+  } else {
+    path = [...segments.slice(0, cut - 2), "api", "v1"];
+  }
+  return [url.origin, ...path].join("/");
+}
 function toIsoString(value) {
   return value instanceof Date ? value.toISOString() : value;
 }
@@ -173,11 +214,15 @@ async function readBody(response) {
 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;
+    const keys = "statusCode" in record ? ["message", "error"] : ["error", "message"];
+    for (const key of keys) {
+      const value = record[key];
+      if (typeof value === "string" && value) {
+        return value;
+      }
+      if (Array.isArray(value) && value.length > 0 && value.every((item) => typeof item === "string")) {
+        return value.join("; ");
+      }
     }
   }
   return `HTTP ${status}`;

package/package.json

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