@textbee/sdk 0.0.3 → 0.2.0

package/README.md

@@ -28,7 +28,7 @@ import { Textbee } from '@textbee/sdk'
 const textbee = new Textbee({ apiKey: process.env.TEXTBEE_API_KEY })
 
 await textbee.sendSms({
-  recipients: ['+251912345678'],
+  recipients: ['+12025550123'],
   message: 'Hello from textbee!',
 })
 ```
@@ -45,7 +45,7 @@ await textbee.sendSms({
 
 ```js
 await textbee.sendSms({
-  recipients: ['+251912345678'],
+  recipients: ['+12025550123'],
   message: 'Your appointment is tomorrow at 9am',
   deviceId: '65f0000000000000000000aa',
   simSubscriptionId: 2,
@@ -71,17 +71,33 @@ 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', // filter is lowercase: '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',
 })
 
-// Each message reports its direction uppercase, so compare accordingly
-data.filter((m) => m.type === 'RECEIVED')
+// 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)
@@ -111,6 +127,65 @@ app.post('/webhooks/textbee', express.raw({ type: 'application/json' }), async (
 })
 ```
 
+## SMS utilities
+
+Pure helpers for working with SMS text and phone numbers. No API key, no network calls, and they are useful with any SMS provider, not just textbee. Import only what you need and the rest is tree-shaken away.
+
+### Segments and encoding
+
+Carriers bill per segment, not per message. A message stays in the 7-bit GSM alphabet at 160 characters per segment, but a single character outside that alphabet, one emoji or one curly quote, switches the whole message to UCS-2 and drops the limit to 70.
+
+```js
+import { countSmsSegments, getSmsEncoding, findNonGsm7Characters } from '@textbee/sdk'
+
+countSmsSegments('Your code is 123456')
+// { encoding: 'gsm-7', length: 19, segments: 1, remainingInSegment: 141 }
+
+countSmsSegments('Your code is 123456 🎉')
+// { encoding: 'ucs-2', length: 22, segments: 1, remainingInSegment: 48 }
+
+getSmsEncoding('plain ascii') // 'gsm-7'
+findNonGsm7Characters('Hi 🎉') // ['🎉']
+```
+
+Longer messages are split, and concatenation headers shrink each segment to 153 characters (GSM-7) or 67 (UCS-2). `remainingInSegment` counts single-unit characters, so a two-unit character such as an emoji or `€` may not fit even when it reads as 1.
+
+### Keeping messages in GSM-7
+
+Text pasted from a word processor or a CMS is full of curly quotes, ellipses, and non-breaking spaces. `sanitizeForGsm7` swaps them for plain equivalents so a message does not silently cost three times as much.
+
+```js
+import { sanitizeForGsm7, countSmsSegments } from '@textbee/sdk'
+
+const pasted = '“Your order shipped…”'
+countSmsSegments(pasted).encoding // 'ucs-2'
+
+const clean = sanitizeForGsm7(pasted) // '"Your order shipped..."'
+countSmsSegments(clean).encoding // 'gsm-7'
+
+// Optionally strip accents that GSM-7 does not carry. Letters it does carry,
+// like é, ü, and ñ, are always left alone.
+sanitizeForGsm7('naïve', { transliterateAccents: true }) // 'naive'
+```
+
+It is best effort: characters with no safe equivalent pass through untouched. Check the result with `getSmsEncoding` and see what is left with `findNonGsm7Characters`.
+
+### Phone number helpers
+
+```js
+import { isValidE164, normalizePhoneNumber } from '@textbee/sdk'
+
+isValidE164('+12025550123') // true
+isValidE164('202-555-0123') // false
+
+normalizePhoneNumber('+1 (202) 555-0123') // '+12025550123'
+normalizePhoneNumber('0012025550123') // '+12025550123'
+normalizePhoneNumber('(202) 555-0123', { defaultCountryCode: '1' }) // '+12025550123'
+normalizePhoneNumber('not a number') // null
+```
+
+These are format-only helpers, not [libphonenumber](https://github.com/google/libphonenumber). They know nothing about country dialing plans, so a well-formed but unassigned number still passes. Input that cannot be normalized returns `null`; an unusable `defaultCountryCode` throws a `TypeError`.
+
 ## Errors
 
 Any non-2xx response throws a `TextbeeError` carrying the status and the parsed body. Network failures reject with the underlying `fetch` error instead.
@@ -119,7 +194,7 @@ Any non-2xx response throws a `TextbeeError` carrying the status and the parsed
 import { TextbeeError } from '@textbee/sdk'
 
 try {
-  await textbee.sendSms({ recipients: ['+251912345678'], message: 'hi' })
+  await textbee.sendSms({ recipients: ['+12025550123'], message: 'hi' })
 } catch (error) {
   if (error instanceof TextbeeError) {
     console.error(error.status, error.message)

package/dist/index.cjs

@@ -22,6 +22,12 @@ var index_exports = {};
 __export(index_exports, {
   Textbee: () => Textbee,
   TextbeeError: () => TextbeeError,
+  countSmsSegments: () => countSmsSegments,
+  findNonGsm7Characters: () => findNonGsm7Characters,
+  getSmsEncoding: () => getSmsEncoding,
+  isValidE164: () => isValidE164,
+  normalizePhoneNumber: () => normalizePhoneNumber,
+  sanitizeForGsm7: () => sanitizeForGsm7,
   verifyWebhookSignature: () => verifyWebhookSignature
 });
 module.exports = __toCommonJS(index_exports);
@@ -42,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.0.3"}`;
+var CLIENT_ID = `textbee-js/${"0.2.0"}`;
 var Textbee = class {
   #apiKey;
   #baseUrl;
@@ -99,20 +105,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 +190,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) {
@@ -182,6 +217,226 @@ function errorMessage(payload, status) {
   return `HTTP ${status}`;
 }
 
+// src/sms-utils.ts
+var GSM7_BASE = `@\xA3$\xA5\xE8\xE9\xF9\xEC\xF2\xC7
+\xD8\xF8\r\xC5\xE5\u0394_\u03A6\u0393\u039B\u03A9\u03A0\u03A8\u03A3\u0398\u039E\xC6\xE6\xDF\xC9 !"#\xA4%&'()*+,-./0123456789:;<=>?\xA1ABCDEFGHIJKLMNOPQRSTUVWXYZ\xC4\xD6\xD1\xDC\xA7\xBFabcdefghijklmnopqrstuvwxyz\xE4\xF6\xF1\xFC\xE0`;
+var GSM7_EXTENSION = "\f^{}\\[~]|\u20AC";
+var GSM7_BASE_SET = new Set(GSM7_BASE);
+var GSM7_EXTENSION_SET = new Set(GSM7_EXTENSION);
+var GSM7_SINGLE_SEGMENT_LIMIT = 160;
+var GSM7_CONCATENATED_SEGMENT_LIMIT = 153;
+var UCS2_SINGLE_SEGMENT_LIMIT = 70;
+var UCS2_CONCATENATED_SEGMENT_LIMIT = 67;
+function gsm7Cost(char) {
+  if (GSM7_BASE_SET.has(char)) {
+    return 1;
+  }
+  if (GSM7_EXTENSION_SET.has(char)) {
+    return 2;
+  }
+  return void 0;
+}
+function isGsm7Char(char) {
+  return gsm7Cost(char) !== void 0;
+}
+function getSmsEncoding(message) {
+  for (const char of message) {
+    if (!isGsm7Char(char)) {
+      return "ucs-2";
+    }
+  }
+  return "gsm-7";
+}
+function countSmsSegments(message) {
+  const encoding = getSmsEncoding(message);
+  const costs = characterCosts(message, encoding);
+  const length = costs.reduce((total, cost) => total + cost, 0);
+  if (length === 0) {
+    return {
+      encoding,
+      length: 0,
+      segments: 0,
+      remainingInSegment: encoding === "gsm-7" ? GSM7_SINGLE_SEGMENT_LIMIT : UCS2_SINGLE_SEGMENT_LIMIT
+    };
+  }
+  const singleLimit = encoding === "gsm-7" ? GSM7_SINGLE_SEGMENT_LIMIT : UCS2_SINGLE_SEGMENT_LIMIT;
+  if (length <= singleLimit) {
+    return {
+      encoding,
+      length,
+      segments: 1,
+      remainingInSegment: singleLimit - length
+    };
+  }
+  const concatenatedLimit = encoding === "gsm-7" ? GSM7_CONCATENATED_SEGMENT_LIMIT : UCS2_CONCATENATED_SEGMENT_LIMIT;
+  let segments = 1;
+  let usedInSegment = 0;
+  for (const cost of costs) {
+    if (usedInSegment + cost > concatenatedLimit) {
+      segments += 1;
+      usedInSegment = cost;
+    } else {
+      usedInSegment += cost;
+    }
+  }
+  return {
+    encoding,
+    length,
+    segments,
+    remainingInSegment: concatenatedLimit - usedInSegment
+  };
+}
+function findNonGsm7Characters(message) {
+  const found = /* @__PURE__ */ new Set();
+  for (const char of message) {
+    if (!isGsm7Char(char)) {
+      found.add(char);
+    }
+  }
+  return Array.from(found);
+}
+function characterCosts(message, encoding) {
+  const costs = [];
+  for (const char of message) {
+    costs.push(encoding === "gsm-7" ? gsm7Cost(char) ?? 1 : char.length);
+  }
+  return costs;
+}
+var GSM7_REPLACEMENTS = {
+  // curly single quotes, prime, acute accent, backtick
+  "\u2018": "'",
+  "\u2019": "'",
+  "\u201A": "'",
+  "\u201B": "'",
+  "\u2032": "'",
+  "\xB4": "'",
+  "`": "'",
+  // curly double quotes, double prime, guillemets
+  "\u201C": '"',
+  "\u201D": '"',
+  "\u201E": '"',
+  "\u201F": '"',
+  "\u2033": '"',
+  "\xAB": '"',
+  "\xBB": '"',
+  // ellipsis
+  "\u2026": "...",
+  // hyphen variants, en dash, em dash, horizontal bar, minus sign
+  "\u2010": "-",
+  "\u2011": "-",
+  "\u2012": "-",
+  "\u2013": "-",
+  "\u2014": "-",
+  "\u2015": "-",
+  "\u2212": "-",
+  // non-breaking and typographic spaces
+  "\xA0": " ",
+  "\u2000": " ",
+  "\u2001": " ",
+  "\u2002": " ",
+  "\u2003": " ",
+  "\u2004": " ",
+  "\u2005": " ",
+  "\u2006": " ",
+  "\u2007": " ",
+  "\u2008": " ",
+  "\u2009": " ",
+  "\u200A": " ",
+  "\u202F": " ",
+  "\u205F": " ",
+  "\u3000": " ",
+  // invisible characters worth dropping outright
+  "\u200B": "",
+  "\uFEFF": "",
+  "\xAD": "",
+  // fraction slash
+  "\u2044": "/"
+};
+var TRANSLITERATION_EXTRAS = {
+  "\u0152": "OE",
+  "\u0153": "oe",
+  "\u0141": "L",
+  "\u0142": "l",
+  "\u0110": "D",
+  "\u0111": "d",
+  "\u0131": "i"
+};
+var COMBINING_MARKS = /[\u0300-\u036F]/g;
+function sanitizeForGsm7(message, options = {}) {
+  const { transliterateAccents = false } = options;
+  let result = "";
+  for (const char of message) {
+    const replacement = GSM7_REPLACEMENTS[char];
+    if (replacement !== void 0) {
+      result += replacement;
+      continue;
+    }
+    if (isGsm7Char(char)) {
+      result += char;
+      continue;
+    }
+    result += transliterateAccents ? transliterate(char) : char;
+  }
+  return result;
+}
+function transliterate(char) {
+  const extra = TRANSLITERATION_EXTRAS[char];
+  if (extra !== void 0) {
+    return extra;
+  }
+  const stripped = char.normalize("NFD").replace(COMBINING_MARKS, "");
+  if (stripped.length === 1 && /[A-Za-z]/.test(stripped)) {
+    return stripped;
+  }
+  return char;
+}
+var E164_PATTERN = /^\+[1-9]\d{1,14}$/;
+var FORMATTING_CHARACTERS = /[\s.\-()]/g;
+var DIGITS_ONLY = /^\d+$/;
+var COUNTRY_CODE_PATTERN = /^[1-9]\d{0,2}$/;
+function isValidE164(input) {
+  return E164_PATTERN.test(input);
+}
+function normalizePhoneNumber(input, options = {}) {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    return null;
+  }
+  const hasPlus = trimmed.startsWith("+");
+  const withoutPlus = hasPlus ? trimmed.slice(1) : trimmed;
+  const digits = withoutPlus.replace(FORMATTING_CHARACTERS, "");
+  if (!DIGITS_ONLY.test(digits)) {
+    return null;
+  }
+  if (hasPlus) {
+    return asE164OrNull(`+${digits}`);
+  }
+  if (digits.startsWith("00")) {
+    return asE164OrNull(`+${digits.slice(2)}`);
+  }
+  const countryCode = normalizeCountryCode(options.defaultCountryCode);
+  if (countryCode === void 0) {
+    return null;
+  }
+  const national = digits.startsWith("0") ? digits.slice(1) : digits;
+  return asE164OrNull(`+${countryCode}${national}`);
+}
+function asE164OrNull(candidate) {
+  return isValidE164(candidate) ? candidate : null;
+}
+function normalizeCountryCode(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  const code = value.startsWith("+") ? value.slice(1) : value;
+  if (!COUNTRY_CODE_PATTERN.test(code)) {
+    throw new TypeError(
+      `defaultCountryCode must be 1 to 3 digits starting with 1-9, got ${JSON.stringify(value)}`
+    );
+  }
+  return code;
+}
+
 // src/webhooks.ts
 async function verifyWebhookSignature(options) {
   const { payload, signature, signingSecret } = options;
@@ -218,5 +473,11 @@ function constantTimeEqual(a, b) {
 0 && (module.exports = {
   Textbee,
   TextbeeError,
+  countSmsSegments,
+  findNonGsm7Characters,
+  getSmsEncoding,
+  isValidE164,
+  normalizePhoneNumber,
+  sanitizeForGsm7,
   verifyWebhookSignature
 });

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,14 +108,29 @@ interface Device {
     createdAt?: string;
     updatedAt?: string;
 }
+interface MessageDevice {
+    _id: string;
+    brand?: string;
+    model?: string;
+    buildId?: string;
+    enabled?: boolean;
+}
 interface Message {
     _id: string;
     message: string;
     /**
-     * Direction, uppercase. Note the asymmetry with the `type` filter accepted by
-     * getMessages, which is lowercase.
+     * 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;
@@ -120,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;
@@ -148,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. */
@@ -169,6 +234,97 @@ declare class TextbeeError extends Error {
     constructor(status: number, message: string, body?: unknown);
 }
 
+/**
+ * Pure SMS helpers. No API key, no network, no dependencies. They work with
+ * any SMS provider, not just textbee.
+ */
+/** How the message body will be encoded on the wire. */
+type SmsEncoding = 'gsm-7' | 'ucs-2';
+interface SmsSegmentInfo {
+    /** `gsm-7` when every character fits the GSM 03.38 alphabet, else `ucs-2`. */
+    encoding: SmsEncoding;
+    /**
+     * Encoded length: septets for gsm-7 (extension characters cost 2), UTF-16
+     * code units for ucs-2 (emoji and other astral characters cost 2).
+     */
+    length: number;
+    /** Number of SMS segments the message occupies. 0 for an empty string. */
+    segments: number;
+    /**
+     * How many more single-unit characters fit before another segment is needed.
+     * A two-unit character (extension character or emoji) may not fit even when
+     * this is 1.
+     */
+    remainingInSegment: number;
+}
+/**
+ * Detect the encoding a message requires: `gsm-7` when every character is in
+ * the GSM 03.38 alphabet or its extension table, `ucs-2` otherwise. An empty
+ * string reports `gsm-7`.
+ */
+declare function getSmsEncoding(message: string): SmsEncoding;
+/**
+ * Compute encoding, encoded length, segment count, and remaining room the way
+ * a standards-following handset splits a message.
+ *
+ * Single segment limits are 160 septets (gsm-7) and 70 code units (ucs-2).
+ * Concatenated messages carry a header, shrinking each segment to 153 and 67.
+ * A two-unit character never straddles a boundary: it moves whole to the next
+ * segment and wastes one unit.
+ */
+declare function countSmsSegments(message: string): SmsSegmentInfo;
+/**
+ * The unique characters forcing a message into ucs-2, in first appearance
+ * order. Empty when the message is already gsm-7 safe. Pair it with
+ * {@link sanitizeForGsm7} to see what is left after sanitizing.
+ */
+declare function findNonGsm7Characters(message: string): string[];
+interface SanitizeForGsm7Options {
+    /**
+     * Strip accents from Latin letters that GSM-7 does not carry, so `ï` becomes
+     * `i`. Letters GSM-7 already has (é, ü, ñ, à and friends) are never touched.
+     * Defaults to false.
+     */
+    transliterateAccents?: boolean;
+}
+/**
+ * Replace common Unicode lookalikes (curly quotes, ellipsis, exotic spaces and
+ * dashes) with GSM-7 equivalents, so pasted text does not silently fall into
+ * ucs-2 and more than double its segment count.
+ *
+ * Best effort by design: characters with no safe replacement are left alone.
+ * Check the result with {@link getSmsEncoding} and inspect leftovers with
+ * {@link findNonGsm7Characters}.
+ */
+declare function sanitizeForGsm7(message: string, options?: SanitizeForGsm7Options): string;
+/**
+ * Check that a string is strictly E.164: a plus sign, a leading digit 1-9, then
+ * 1 to 14 more digits, nothing else.
+ *
+ * This is a format check only. It does not know country dialing plans, so a
+ * well-formed but unassigned number still passes.
+ */
+declare function isValidE164(input: string): boolean;
+interface NormalizePhoneNumberOptions {
+    /**
+     * Country calling code applied to national-format input, with or without a
+     * leading plus: `1` and `+1` both work. With it, `(202) 555-0123` becomes
+     * `+12025550123` and one leading trunk zero is dropped. Without it,
+     * national-format input returns null.
+     */
+    defaultCountryCode?: string;
+}
+/**
+ * Normalize free-form phone input to E.164, or return null when it cannot be
+ * done safely. Strips spaces, dots, hyphens and parentheses, converts a leading
+ * `00` to a plus, and optionally applies a default country code.
+ *
+ * This is a formatter, not libphonenumber: it never validates a number against
+ * a country dialing plan. Bad input returns null, a bad
+ * {@link NormalizePhoneNumberOptions.defaultCountryCode} throws.
+ */
+declare function normalizePhoneNumber(input: string, options?: NormalizePhoneNumberOptions): string | null;
+
 interface VerifyWebhookSignatureOptions {
     /**
      * The webhook request body. Prefer the raw body string.
@@ -191,4 +347,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 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 };

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,14 +108,29 @@ interface Device {
     createdAt?: string;
     updatedAt?: string;
 }
+interface MessageDevice {
+    _id: string;
+    brand?: string;
+    model?: string;
+    buildId?: string;
+    enabled?: boolean;
+}
 interface Message {
     _id: string;
     message: string;
     /**
-     * Direction, uppercase. Note the asymmetry with the `type` filter accepted by
-     * getMessages, which is lowercase.
+     * 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;
@@ -120,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;
@@ -148,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. */
@@ -169,6 +234,97 @@ declare class TextbeeError extends Error {
     constructor(status: number, message: string, body?: unknown);
 }
 
+/**
+ * Pure SMS helpers. No API key, no network, no dependencies. They work with
+ * any SMS provider, not just textbee.
+ */
+/** How the message body will be encoded on the wire. */
+type SmsEncoding = 'gsm-7' | 'ucs-2';
+interface SmsSegmentInfo {
+    /** `gsm-7` when every character fits the GSM 03.38 alphabet, else `ucs-2`. */
+    encoding: SmsEncoding;
+    /**
+     * Encoded length: septets for gsm-7 (extension characters cost 2), UTF-16
+     * code units for ucs-2 (emoji and other astral characters cost 2).
+     */
+    length: number;
+    /** Number of SMS segments the message occupies. 0 for an empty string. */
+    segments: number;
+    /**
+     * How many more single-unit characters fit before another segment is needed.
+     * A two-unit character (extension character or emoji) may not fit even when
+     * this is 1.
+     */
+    remainingInSegment: number;
+}
+/**
+ * Detect the encoding a message requires: `gsm-7` when every character is in
+ * the GSM 03.38 alphabet or its extension table, `ucs-2` otherwise. An empty
+ * string reports `gsm-7`.
+ */
+declare function getSmsEncoding(message: string): SmsEncoding;
+/**
+ * Compute encoding, encoded length, segment count, and remaining room the way
+ * a standards-following handset splits a message.
+ *
+ * Single segment limits are 160 septets (gsm-7) and 70 code units (ucs-2).
+ * Concatenated messages carry a header, shrinking each segment to 153 and 67.
+ * A two-unit character never straddles a boundary: it moves whole to the next
+ * segment and wastes one unit.
+ */
+declare function countSmsSegments(message: string): SmsSegmentInfo;
+/**
+ * The unique characters forcing a message into ucs-2, in first appearance
+ * order. Empty when the message is already gsm-7 safe. Pair it with
+ * {@link sanitizeForGsm7} to see what is left after sanitizing.
+ */
+declare function findNonGsm7Characters(message: string): string[];
+interface SanitizeForGsm7Options {
+    /**
+     * Strip accents from Latin letters that GSM-7 does not carry, so `ï` becomes
+     * `i`. Letters GSM-7 already has (é, ü, ñ, à and friends) are never touched.
+     * Defaults to false.
+     */
+    transliterateAccents?: boolean;
+}
+/**
+ * Replace common Unicode lookalikes (curly quotes, ellipsis, exotic spaces and
+ * dashes) with GSM-7 equivalents, so pasted text does not silently fall into
+ * ucs-2 and more than double its segment count.
+ *
+ * Best effort by design: characters with no safe replacement are left alone.
+ * Check the result with {@link getSmsEncoding} and inspect leftovers with
+ * {@link findNonGsm7Characters}.
+ */
+declare function sanitizeForGsm7(message: string, options?: SanitizeForGsm7Options): string;
+/**
+ * Check that a string is strictly E.164: a plus sign, a leading digit 1-9, then
+ * 1 to 14 more digits, nothing else.
+ *
+ * This is a format check only. It does not know country dialing plans, so a
+ * well-formed but unassigned number still passes.
+ */
+declare function isValidE164(input: string): boolean;
+interface NormalizePhoneNumberOptions {
+    /**
+     * Country calling code applied to national-format input, with or without a
+     * leading plus: `1` and `+1` both work. With it, `(202) 555-0123` becomes
+     * `+12025550123` and one leading trunk zero is dropped. Without it,
+     * national-format input returns null.
+     */
+    defaultCountryCode?: string;
+}
+/**
+ * Normalize free-form phone input to E.164, or return null when it cannot be
+ * done safely. Strips spaces, dots, hyphens and parentheses, converts a leading
+ * `00` to a plus, and optionally applies a default country code.
+ *
+ * This is a formatter, not libphonenumber: it never validates a number against
+ * a country dialing plan. Bad input returns null, a bad
+ * {@link NormalizePhoneNumberOptions.defaultCountryCode} throws.
+ */
+declare function normalizePhoneNumber(input: string, options?: NormalizePhoneNumberOptions): string | null;
+
 interface VerifyWebhookSignatureOptions {
     /**
      * The webhook request body. Prefer the raw body string.
@@ -191,4 +347,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 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 };

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.3"}`;
+var CLIENT_ID = `textbee-js/${"0.2.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) {
@@ -154,6 +183,226 @@ function errorMessage(payload, status) {
   return `HTTP ${status}`;
 }
 
+// src/sms-utils.ts
+var GSM7_BASE = `@\xA3$\xA5\xE8\xE9\xF9\xEC\xF2\xC7
+\xD8\xF8\r\xC5\xE5\u0394_\u03A6\u0393\u039B\u03A9\u03A0\u03A8\u03A3\u0398\u039E\xC6\xE6\xDF\xC9 !"#\xA4%&'()*+,-./0123456789:;<=>?\xA1ABCDEFGHIJKLMNOPQRSTUVWXYZ\xC4\xD6\xD1\xDC\xA7\xBFabcdefghijklmnopqrstuvwxyz\xE4\xF6\xF1\xFC\xE0`;
+var GSM7_EXTENSION = "\f^{}\\[~]|\u20AC";
+var GSM7_BASE_SET = new Set(GSM7_BASE);
+var GSM7_EXTENSION_SET = new Set(GSM7_EXTENSION);
+var GSM7_SINGLE_SEGMENT_LIMIT = 160;
+var GSM7_CONCATENATED_SEGMENT_LIMIT = 153;
+var UCS2_SINGLE_SEGMENT_LIMIT = 70;
+var UCS2_CONCATENATED_SEGMENT_LIMIT = 67;
+function gsm7Cost(char) {
+  if (GSM7_BASE_SET.has(char)) {
+    return 1;
+  }
+  if (GSM7_EXTENSION_SET.has(char)) {
+    return 2;
+  }
+  return void 0;
+}
+function isGsm7Char(char) {
+  return gsm7Cost(char) !== void 0;
+}
+function getSmsEncoding(message) {
+  for (const char of message) {
+    if (!isGsm7Char(char)) {
+      return "ucs-2";
+    }
+  }
+  return "gsm-7";
+}
+function countSmsSegments(message) {
+  const encoding = getSmsEncoding(message);
+  const costs = characterCosts(message, encoding);
+  const length = costs.reduce((total, cost) => total + cost, 0);
+  if (length === 0) {
+    return {
+      encoding,
+      length: 0,
+      segments: 0,
+      remainingInSegment: encoding === "gsm-7" ? GSM7_SINGLE_SEGMENT_LIMIT : UCS2_SINGLE_SEGMENT_LIMIT
+    };
+  }
+  const singleLimit = encoding === "gsm-7" ? GSM7_SINGLE_SEGMENT_LIMIT : UCS2_SINGLE_SEGMENT_LIMIT;
+  if (length <= singleLimit) {
+    return {
+      encoding,
+      length,
+      segments: 1,
+      remainingInSegment: singleLimit - length
+    };
+  }
+  const concatenatedLimit = encoding === "gsm-7" ? GSM7_CONCATENATED_SEGMENT_LIMIT : UCS2_CONCATENATED_SEGMENT_LIMIT;
+  let segments = 1;
+  let usedInSegment = 0;
+  for (const cost of costs) {
+    if (usedInSegment + cost > concatenatedLimit) {
+      segments += 1;
+      usedInSegment = cost;
+    } else {
+      usedInSegment += cost;
+    }
+  }
+  return {
+    encoding,
+    length,
+    segments,
+    remainingInSegment: concatenatedLimit - usedInSegment
+  };
+}
+function findNonGsm7Characters(message) {
+  const found = /* @__PURE__ */ new Set();
+  for (const char of message) {
+    if (!isGsm7Char(char)) {
+      found.add(char);
+    }
+  }
+  return Array.from(found);
+}
+function characterCosts(message, encoding) {
+  const costs = [];
+  for (const char of message) {
+    costs.push(encoding === "gsm-7" ? gsm7Cost(char) ?? 1 : char.length);
+  }
+  return costs;
+}
+var GSM7_REPLACEMENTS = {
+  // curly single quotes, prime, acute accent, backtick
+  "\u2018": "'",
+  "\u2019": "'",
+  "\u201A": "'",
+  "\u201B": "'",
+  "\u2032": "'",
+  "\xB4": "'",
+  "`": "'",
+  // curly double quotes, double prime, guillemets
+  "\u201C": '"',
+  "\u201D": '"',
+  "\u201E": '"',
+  "\u201F": '"',
+  "\u2033": '"',
+  "\xAB": '"',
+  "\xBB": '"',
+  // ellipsis
+  "\u2026": "...",
+  // hyphen variants, en dash, em dash, horizontal bar, minus sign
+  "\u2010": "-",
+  "\u2011": "-",
+  "\u2012": "-",
+  "\u2013": "-",
+  "\u2014": "-",
+  "\u2015": "-",
+  "\u2212": "-",
+  // non-breaking and typographic spaces
+  "\xA0": " ",
+  "\u2000": " ",
+  "\u2001": " ",
+  "\u2002": " ",
+  "\u2003": " ",
+  "\u2004": " ",
+  "\u2005": " ",
+  "\u2006": " ",
+  "\u2007": " ",
+  "\u2008": " ",
+  "\u2009": " ",
+  "\u200A": " ",
+  "\u202F": " ",
+  "\u205F": " ",
+  "\u3000": " ",
+  // invisible characters worth dropping outright
+  "\u200B": "",
+  "\uFEFF": "",
+  "\xAD": "",
+  // fraction slash
+  "\u2044": "/"
+};
+var TRANSLITERATION_EXTRAS = {
+  "\u0152": "OE",
+  "\u0153": "oe",
+  "\u0141": "L",
+  "\u0142": "l",
+  "\u0110": "D",
+  "\u0111": "d",
+  "\u0131": "i"
+};
+var COMBINING_MARKS = /[\u0300-\u036F]/g;
+function sanitizeForGsm7(message, options = {}) {
+  const { transliterateAccents = false } = options;
+  let result = "";
+  for (const char of message) {
+    const replacement = GSM7_REPLACEMENTS[char];
+    if (replacement !== void 0) {
+      result += replacement;
+      continue;
+    }
+    if (isGsm7Char(char)) {
+      result += char;
+      continue;
+    }
+    result += transliterateAccents ? transliterate(char) : char;
+  }
+  return result;
+}
+function transliterate(char) {
+  const extra = TRANSLITERATION_EXTRAS[char];
+  if (extra !== void 0) {
+    return extra;
+  }
+  const stripped = char.normalize("NFD").replace(COMBINING_MARKS, "");
+  if (stripped.length === 1 && /[A-Za-z]/.test(stripped)) {
+    return stripped;
+  }
+  return char;
+}
+var E164_PATTERN = /^\+[1-9]\d{1,14}$/;
+var FORMATTING_CHARACTERS = /[\s.\-()]/g;
+var DIGITS_ONLY = /^\d+$/;
+var COUNTRY_CODE_PATTERN = /^[1-9]\d{0,2}$/;
+function isValidE164(input) {
+  return E164_PATTERN.test(input);
+}
+function normalizePhoneNumber(input, options = {}) {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    return null;
+  }
+  const hasPlus = trimmed.startsWith("+");
+  const withoutPlus = hasPlus ? trimmed.slice(1) : trimmed;
+  const digits = withoutPlus.replace(FORMATTING_CHARACTERS, "");
+  if (!DIGITS_ONLY.test(digits)) {
+    return null;
+  }
+  if (hasPlus) {
+    return asE164OrNull(`+${digits}`);
+  }
+  if (digits.startsWith("00")) {
+    return asE164OrNull(`+${digits.slice(2)}`);
+  }
+  const countryCode = normalizeCountryCode(options.defaultCountryCode);
+  if (countryCode === void 0) {
+    return null;
+  }
+  const national = digits.startsWith("0") ? digits.slice(1) : digits;
+  return asE164OrNull(`+${countryCode}${national}`);
+}
+function asE164OrNull(candidate) {
+  return isValidE164(candidate) ? candidate : null;
+}
+function normalizeCountryCode(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  const code = value.startsWith("+") ? value.slice(1) : value;
+  if (!COUNTRY_CODE_PATTERN.test(code)) {
+    throw new TypeError(
+      `defaultCountryCode must be 1 to 3 digits starting with 1-9, got ${JSON.stringify(value)}`
+    );
+  }
+  return code;
+}
+
 // src/webhooks.ts
 async function verifyWebhookSignature(options) {
   const { payload, signature, signingSecret } = options;
@@ -189,5 +438,11 @@ function constantTimeEqual(a, b) {
 export {
   Textbee,
   TextbeeError,
+  countSmsSegments,
+  findNonGsm7Characters,
+  getSmsEncoding,
+  isValidE164,
+  normalizePhoneNumber,
+  sanitizeForGsm7,
   verifyWebhookSignature
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@textbee/sdk",
-  "version": "0.0.3",
+  "version": "0.2.0",
   "description": "Official JavaScript SDK for textbee.dev, the open source SMS gateway",
   "license": "MIT",
   "packageManager": "pnpm@9.14.2",
@@ -44,7 +44,10 @@
     "sms",
     "sms-gateway",
     "textbee",
-    "android"
+    "android",
+    "sms-segments",
+    "gsm-7",
+    "e164"
   ],
   "scripts": {
     "build": "tsup",