@textbee/sdk 0.1.0 → 0.3.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!',
 })
 ```
@@ -41,11 +41,11 @@ 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({
-  recipients: ['+251912345678'],
+  recipients: ['+12025550123'],
   message: 'Your appointment is tomorrow at 9am',
   deviceId: '65f0000000000000000000aa',
   simSubscriptionId: 2,
@@ -76,9 +76,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 +87,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 +102,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.
@@ -127,6 +133,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.
@@ -135,7 +200,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)
@@ -150,14 +215,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 full path, for example `https://example.com/textbee/api/v1`. Any path other than `/api/v1` is used as given, so a proxy that maps `/sms` onto the API keeps working with `https://example.com/sms`. 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

@@ -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.1.0"}`;
+var CLIENT_ID = `textbee-js/${"0.3.0"}`;
 var Textbee = class {
   #apiKey;
   #baseUrl;
@@ -51,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) {
@@ -122,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' })) {
@@ -148,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",
@@ -184,6 +195,44 @@ 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 (segments.length === 0) {
+    path = ["api", "v1"];
+  } else if (cut === -1) {
+    path = segments;
+  } else {
+    path = [...segments.slice(0, cut - 2), "api", "v1"];
+  }
+  return [url.origin, ...path].join("/");
+}
 function toIsoString(value) {
   return value instanceof Date ? value.toISOString() : value;
 }
@@ -201,16 +250,240 @@ 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}`;
 }
 
+// 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;
@@ -247,5 +520,11 @@ function constantTimeEqual(a, b) {
 0 && (module.exports = {
   Textbee,
   TextbeeError,
+  countSmsSegments,
+  findNonGsm7Characters,
+  getSmsEncoding,
+  isValidE164,
+  normalizePhoneNumber,
+  sanitizeForGsm7,
   verifyWebhookSignature
 });