retransmit.dev 0.5.0 → 0.6.0

package/README.md

@@ -229,6 +229,47 @@ const { data } = await retransmit.sms.get("sms_xxxxxxxxxxxx");
 console.log(data?.status); // "sent" | "delivered" | "undelivered" | ...
 ```
 
+### Sender IDs
+
+`from` is the name shown on the handset instead of a phone number. Approval is
+per country, so request it first in the dashboard under **SMS > Sender IDs**.
+The request asks for the name and the countries you send to. Most countries
+accept the name as it is; where the carriers require a registration, the form
+adds what that filing needs (what you send, a sample message, your legal
+entity). Retransmit files it for you, and there is no AWS or carrier account to
+set up.
+
+Sending with a name that is not approved for the destination country fails with
+`sender_not_allowed`. Leave `from` out to use your approved sender for that
+country, or the provider default when you have none.
+
+The United States, Canada, and Mexico do not accept alphanumeric sender IDs.
+
+### Choosing a carrier
+
+You do not have to work out which carrier fits a number. Leave `provider` out
+and Retransmit routes by destination country and price.
+
+Pass it to pin the send to one carrier. `sns` (AWS End User Messaging) is the
+one that reaches every destination; `mtn` and `orange` only cover the countries
+Retransmit has that carrier in:
+
+```ts
+await retransmit.sms.send({
+  to: "+237670000000",
+  text: "Your verification code is 482913",
+  provider: "sns", // "sns" | "mtn" | "orange"
+});
+```
+
+The value is the carrier, not one of its country operations, so it keeps
+working as more countries are added. A pinned send never falls back: if that
+carrier cannot deliver to the destination, the request fails with `no_route`.
+
+`get` returns both. `requested_provider` is what you asked for, `provider` is
+the country operation that carried the message (`mtn_cm`, `orange_cm`,
+`aws_sns`), and is null until the message is routed.
+
 ## Email batches
 
 Send up to 10,000 emails in one request:

package/dist/index.cjs

@@ -24,6 +24,7 @@ __export(index_exports, {
   EMAIL_STATUSES: () => EMAIL_STATUSES,
   Emails: () => Emails,
   Retransmit: () => Retransmit,
+  SMS_PROVIDERS: () => SMS_PROVIDERS,
   SMS_STATUSES: () => SMS_STATUSES,
   Sms: () => Sms,
   WHATSAPP_STATUSES: () => WHATSAPP_STATUSES,
@@ -159,7 +160,8 @@ var Sms = class {
     return this.client.request("POST", "/v1/sms", {
       from: options.from,
       to: options.to,
-      text: options.text
+      text: options.text,
+      provider: options.provider
     });
   }
   /** Retrieves an SMS with its current status and event history. */
@@ -199,7 +201,7 @@ var Whatsapp = class {
 
 // src/retransmit.ts
 var DEFAULT_BASE_URL = "https://api.retransmit.dev";
-var USER_AGENT = "retransmit.dev-node/0.5.0";
+var USER_AGENT = "retransmit.dev-node/0.6.0";
 function readEnv(name) {
   return typeof process !== "undefined" ? process.env?.[name] : void 0;
 }
@@ -300,6 +302,7 @@ var SMS_STATUSES = [
   "rejected",
   "failed"
 ];
+var SMS_PROVIDERS = ["sns", "mtn", "orange"];
 var WHATSAPP_STATUSES = ["queued", "sent", "delivered", "read", "failed"];
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -307,6 +310,7 @@ var WHATSAPP_STATUSES = ["queued", "sent", "delivered", "read", "failed"];
   EMAIL_STATUSES,
   Emails,
   Retransmit,
+  SMS_PROVIDERS,
   SMS_STATUSES,
   Sms,
   WHATSAPP_STATUSES,

package/dist/index.d.cts

@@ -200,16 +200,38 @@ interface ListEmailTagsResponse {
 }
 declare const SMS_STATUSES: readonly ["queued", "sent", "delivered", "undelivered", "expired", "rejected", "failed"];
 type SmsStatus = (typeof SMS_STATUSES)[number];
+/**
+ * Carriers a send can be pinned to. Carrier-level, not per-country: `mtn`
+ * covers every MTN network Retransmit integrates with. `sns` (AWS End User
+ * Messaging) is first because it is the one that reaches every destination.
+ */
+declare const SMS_PROVIDERS: readonly ["sns", "mtn", "orange"];
+type SmsProvider = (typeof SMS_PROVIDERS)[number];
 interface SendSmsOptions {
     /**
      * Sender id shown on the recipient's device (up to 11 characters:
-     * letters, digits, space, - and _). Defaults to the sender configured for
-     * the routed provider.
+     * letters, digits, space, - and _).
+     *
+     * Approval is per country, so this must be a name your organization has had
+     * approved for the destination; request it in the dashboard under
+     * SMS > Sender IDs, which asks for the name and the countries, and for
+     * registration details only where the carriers require a filing. Sending
+     * with an unapproved name fails with `sender_not_allowed`. Leave it out to
+     * use your approved sender for that country, or the provider default when
+     * you have none.
      */
     from?: string;
     /** One recipient or up to 50, in international format (`+237670000000`). All must share one country. */
     to: string | string[];
     text: string;
+    /**
+     * Pins the send to one carrier. Leave it out to let Retransmit route by
+     * destination country and price. `sns` covers every destination; `mtn` and
+     * `orange` only the countries Retransmit has that carrier in. A pinned send
+     * never falls back to another carrier: it fails with `no_route` when that
+     * one cannot deliver.
+     */
+    provider?: SmsProvider;
 }
 interface SendSmsResponse {
     id: string;
@@ -231,7 +253,13 @@ interface GetSmsResponse {
     text: string;
     country: string | null;
     segments: number;
-    /** Upstream provider that carried the message, e.g. `mtn_cm`. */
+    /** Carrier the send was pinned to, null when routing chose freely. */
+    requested_provider: SmsProvider | null;
+    /**
+     * Country operation that carried the message, e.g. `mtn_cm`, `orange_cm`
+     * or `aws_sns`. More specific than `requested_provider`, and null until
+     * the message is routed.
+     */
     provider: string | null;
     status: SmsStatus;
     error: string | null;
@@ -404,4 +432,4 @@ declare class Retransmit {
     request<T>(method: "GET" | "POST", path: string, body?: unknown, query?: Record<string, string | number | string[] | undefined>, options?: RequestOptions): Promise<Result<T>>;
 }
 
-export { type Attachment, Batch, EMAIL_STATUSES, type EmailAttachment, type EmailAttachmentWithDownload, type EmailEvent, type EmailStatus, type EmailSummary, type EmailTag, type EmailTagCount, Emails, type GetBatchResponse, type GetEmailResponse, type GetSmsResponse, type GetWhatsappResponse, type ListEmailAttachmentsResponse, type ListEmailTagsResponse, type ListEmailsOptions, type ListEmailsResponse, type RequestOptions, type Result, Retransmit, type RetransmitError, type RetransmitOptions, SMS_STATUSES, type SendBatchResponse, type SendEmailOptions, type SendEmailResponse, type SendSmsOptions, type SendSmsResponse, type SendWhatsappOptions, type SendWhatsappResponse, Sms, type SmsEvent, type SmsStatus, WHATSAPP_STATUSES, Whatsapp, type WhatsappDocument, type WhatsappEvent, type WhatsappMedia, type WhatsappMessageType, type WhatsappStatus, type WhatsappTemplate };
+export { type Attachment, Batch, EMAIL_STATUSES, type EmailAttachment, type EmailAttachmentWithDownload, type EmailEvent, type EmailStatus, type EmailSummary, type EmailTag, type EmailTagCount, Emails, type GetBatchResponse, type GetEmailResponse, type GetSmsResponse, type GetWhatsappResponse, type ListEmailAttachmentsResponse, type ListEmailTagsResponse, type ListEmailsOptions, type ListEmailsResponse, type RequestOptions, type Result, Retransmit, type RetransmitError, type RetransmitOptions, SMS_PROVIDERS, SMS_STATUSES, type SendBatchResponse, type SendEmailOptions, type SendEmailResponse, type SendSmsOptions, type SendSmsResponse, type SendWhatsappOptions, type SendWhatsappResponse, Sms, type SmsEvent, type SmsProvider, type SmsStatus, WHATSAPP_STATUSES, Whatsapp, type WhatsappDocument, type WhatsappEvent, type WhatsappMedia, type WhatsappMessageType, type WhatsappStatus, type WhatsappTemplate };

package/dist/index.d.ts

@@ -200,16 +200,38 @@ interface ListEmailTagsResponse {
 }
 declare const SMS_STATUSES: readonly ["queued", "sent", "delivered", "undelivered", "expired", "rejected", "failed"];
 type SmsStatus = (typeof SMS_STATUSES)[number];
+/**
+ * Carriers a send can be pinned to. Carrier-level, not per-country: `mtn`
+ * covers every MTN network Retransmit integrates with. `sns` (AWS End User
+ * Messaging) is first because it is the one that reaches every destination.
+ */
+declare const SMS_PROVIDERS: readonly ["sns", "mtn", "orange"];
+type SmsProvider = (typeof SMS_PROVIDERS)[number];
 interface SendSmsOptions {
     /**
      * Sender id shown on the recipient's device (up to 11 characters:
-     * letters, digits, space, - and _). Defaults to the sender configured for
-     * the routed provider.
+     * letters, digits, space, - and _).
+     *
+     * Approval is per country, so this must be a name your organization has had
+     * approved for the destination; request it in the dashboard under
+     * SMS > Sender IDs, which asks for the name and the countries, and for
+     * registration details only where the carriers require a filing. Sending
+     * with an unapproved name fails with `sender_not_allowed`. Leave it out to
+     * use your approved sender for that country, or the provider default when
+     * you have none.
      */
     from?: string;
     /** One recipient or up to 50, in international format (`+237670000000`). All must share one country. */
     to: string | string[];
     text: string;
+    /**
+     * Pins the send to one carrier. Leave it out to let Retransmit route by
+     * destination country and price. `sns` covers every destination; `mtn` and
+     * `orange` only the countries Retransmit has that carrier in. A pinned send
+     * never falls back to another carrier: it fails with `no_route` when that
+     * one cannot deliver.
+     */
+    provider?: SmsProvider;
 }
 interface SendSmsResponse {
     id: string;
@@ -231,7 +253,13 @@ interface GetSmsResponse {
     text: string;
     country: string | null;
     segments: number;
-    /** Upstream provider that carried the message, e.g. `mtn_cm`. */
+    /** Carrier the send was pinned to, null when routing chose freely. */
+    requested_provider: SmsProvider | null;
+    /**
+     * Country operation that carried the message, e.g. `mtn_cm`, `orange_cm`
+     * or `aws_sns`. More specific than `requested_provider`, and null until
+     * the message is routed.
+     */
     provider: string | null;
     status: SmsStatus;
     error: string | null;
@@ -404,4 +432,4 @@ declare class Retransmit {
     request<T>(method: "GET" | "POST", path: string, body?: unknown, query?: Record<string, string | number | string[] | undefined>, options?: RequestOptions): Promise<Result<T>>;
 }
 
-export { type Attachment, Batch, EMAIL_STATUSES, type EmailAttachment, type EmailAttachmentWithDownload, type EmailEvent, type EmailStatus, type EmailSummary, type EmailTag, type EmailTagCount, Emails, type GetBatchResponse, type GetEmailResponse, type GetSmsResponse, type GetWhatsappResponse, type ListEmailAttachmentsResponse, type ListEmailTagsResponse, type ListEmailsOptions, type ListEmailsResponse, type RequestOptions, type Result, Retransmit, type RetransmitError, type RetransmitOptions, SMS_STATUSES, type SendBatchResponse, type SendEmailOptions, type SendEmailResponse, type SendSmsOptions, type SendSmsResponse, type SendWhatsappOptions, type SendWhatsappResponse, Sms, type SmsEvent, type SmsStatus, WHATSAPP_STATUSES, Whatsapp, type WhatsappDocument, type WhatsappEvent, type WhatsappMedia, type WhatsappMessageType, type WhatsappStatus, type WhatsappTemplate };
+export { type Attachment, Batch, EMAIL_STATUSES, type EmailAttachment, type EmailAttachmentWithDownload, type EmailEvent, type EmailStatus, type EmailSummary, type EmailTag, type EmailTagCount, Emails, type GetBatchResponse, type GetEmailResponse, type GetSmsResponse, type GetWhatsappResponse, type ListEmailAttachmentsResponse, type ListEmailTagsResponse, type ListEmailsOptions, type ListEmailsResponse, type RequestOptions, type Result, Retransmit, type RetransmitError, type RetransmitOptions, SMS_PROVIDERS, SMS_STATUSES, type SendBatchResponse, type SendEmailOptions, type SendEmailResponse, type SendSmsOptions, type SendSmsResponse, type SendWhatsappOptions, type SendWhatsappResponse, Sms, type SmsEvent, type SmsProvider, type SmsStatus, WHATSAPP_STATUSES, Whatsapp, type WhatsappDocument, type WhatsappEvent, type WhatsappMedia, type WhatsappMessageType, type WhatsappStatus, type WhatsappTemplate };

package/dist/index.js

@@ -126,7 +126,8 @@ var Sms = class {
     return this.client.request("POST", "/v1/sms", {
       from: options.from,
       to: options.to,
-      text: options.text
+      text: options.text,
+      provider: options.provider
     });
   }
   /** Retrieves an SMS with its current status and event history. */
@@ -166,7 +167,7 @@ var Whatsapp = class {
 
 // src/retransmit.ts
 var DEFAULT_BASE_URL = "https://api.retransmit.dev";
-var USER_AGENT = "retransmit.dev-node/0.5.0";
+var USER_AGENT = "retransmit.dev-node/0.6.0";
 function readEnv(name) {
   return typeof process !== "undefined" ? process.env?.[name] : void 0;
 }
@@ -267,12 +268,14 @@ var SMS_STATUSES = [
   "rejected",
   "failed"
 ];
+var SMS_PROVIDERS = ["sns", "mtn", "orange"];
 var WHATSAPP_STATUSES = ["queued", "sent", "delivered", "read", "failed"];
 export {
   Batch,
   EMAIL_STATUSES,
   Emails,
   Retransmit,
+  SMS_PROVIDERS,
   SMS_STATUSES,
   Sms,
   WHATSAPP_STATUSES,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "retransmit.dev",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Node.js SDK for the Retransmit email, SMS and WhatsApp APIs",
   "keywords": [
     "email",