@textbee/sdk 0.1.0 → 0.3.0

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`.
+     *
+     * A bare origin such as `https://sms.example.com` gets `/api/v1` added. A URL
+     * that contains `/api/v1` is cut there, so a pasted endpoint URL still works.
+     * Any other path is used as given, for proxies that map a prefix onto the API.
+     * 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>;
 }
 
@@ -234,6 +287,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.
@@ -256,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 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 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`.
+     *
+     * A bare origin such as `https://sms.example.com` gets `/api/v1` added. A URL
+     * that contains `/api/v1` is cut there, so a pasted endpoint URL still works.
+     * Any other path is used as given, for proxies that map a prefix onto the API.
+     * 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>;
 }
 
@@ -234,6 +287,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.
@@ -256,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 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 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 };