retransmit.dev 0.1.2 → 0.2.0

package/README.md

@@ -1,12 +1,12 @@
 # retransmit.dev
 
-Node.js SDK for the [Retransmit](https://retransmit.dev) messaging API. Send email and SMS through one typed client; WhatsApp support is coming soon. Zero dependencies, works on Node 18+ and edge runtimes with `fetch`.
+Node.js SDK for the [Retransmit](https://retransmit.dev) messaging API. Send email, SMS, and WhatsApp through one typed client. Zero dependencies, works on Node 18+ and edge runtimes with `fetch`.
 
 | Channel | SDK namespace | Availability |
 | --- | --- | --- |
 | Email | `retransmit.emails` | Available |
 | SMS | `retransmit.sms` | Available |
-| WhatsApp | `retransmit.whatsapp` | Coming soon; not included in the current release |
+| WhatsApp | `retransmit.whatsapp` | Available |
 
 ## Install
 
@@ -93,10 +93,33 @@ console.log(progress?.processed, "/", progress?.total, progress?.counts);
 
 ## WhatsApp
 
-WhatsApp is the next planned channel. The intended SDK namespace is
-`retransmit.whatsapp`, but it is deliberately not exported yet because the
-production endpoint and request types are still being finalized. This keeps
-the current SDK honest while reserving a consistent channel-based API shape.
+Connect your WhatsApp Business number in the dashboard first. One recipient
+per request, in E.164 format. Start a conversation with an approved template;
+once the recipient replies you can send free-form text and media for 24 hours.
+
+```ts
+const { data, error } = await retransmit.whatsapp.send({
+  to: "+237670000000",
+  type: "template",
+  template: {
+    name: "verification_code",
+    language: "en_US",
+    components: [{ type: "body", parameters: [{ type: "text", text: "482913" }] }],
+  },
+});
+
+// Inside the 24-hour window:
+await retransmit.whatsapp.send({ to: "+237670000000", text: "Anything else we can help with?" });
+```
+
+Check the outcome, including `read` receipts:
+
+```ts
+const { data } = await retransmit.whatsapp.get("wa_xxxxxxxxxxxx");
+console.log(data?.status); // "sent" | "delivered" | "read" | "failed"
+```
+
+Replies from recipients reach you as `whatsapp.received` webhooks.
 
 ## Error handling
 

package/dist/index.cjs

@@ -25,7 +25,9 @@ __export(index_exports, {
   Emails: () => Emails,
   Retransmit: () => Retransmit,
   SMS_STATUSES: () => SMS_STATUSES,
-  Sms: () => Sms
+  Sms: () => Sms,
+  WHATSAPP_STATUSES: () => WHATSAPP_STATUSES,
+  Whatsapp: () => Whatsapp
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -96,6 +98,35 @@ var Sms = class {
   }
 };
 
+// src/whatsapp.ts
+var Whatsapp = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Queues a single WhatsApp message to one recipient. Poll `get(id)` or
+   * subscribe to webhooks for the outcome; replies arrive as
+   * `whatsapp.received` webhooks.
+   */
+  send(options) {
+    return this.client.request("POST", "/v1/whatsapp", {
+      from: options.from,
+      to: options.to,
+      type: options.type,
+      text: options.text,
+      preview_url: options.previewUrl,
+      template: options.template,
+      image: options.image,
+      document: options.document
+    });
+  }
+  /** Retrieves a WhatsApp message with its current status and event history. */
+  get(id) {
+    return this.client.request("GET", `/v1/whatsapp/${encodeURIComponent(id)}`);
+  }
+};
+
 // src/retransmit.ts
 var DEFAULT_BASE_URL = "https://api.retransmit.dev";
 var USER_AGENT = "retransmit.dev-node/0.1.0";
@@ -105,6 +136,7 @@ function readEnv(name) {
 var Retransmit = class {
   emails = new Emails(this);
   sms = new Sms(this);
+  whatsapp = new Whatsapp(this);
   batch = new Batch(this);
   apiKey;
   baseUrl;
@@ -187,6 +219,7 @@ var SMS_STATUSES = [
   "rejected",
   "failed"
 ];
+var WHATSAPP_STATUSES = ["queued", "sent", "delivered", "read", "failed"];
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Batch,
@@ -194,5 +227,7 @@ var SMS_STATUSES = [
   Emails,
   Retransmit,
   SMS_STATUSES,
-  Sms
+  Sms,
+  WHATSAPP_STATUSES,
+  Whatsapp
 });

package/dist/index.d.cts

@@ -106,6 +106,81 @@ interface GetSmsResponse {
     last_event_at: string | null;
     events: SmsEvent[];
 }
+declare const WHATSAPP_STATUSES: readonly ["queued", "sent", "delivered", "read", "failed"];
+type WhatsappStatus = (typeof WHATSAPP_STATUSES)[number];
+type WhatsappMessageType = "text" | "template" | "image" | "document";
+interface WhatsappTemplate {
+    /** Template name as approved in WhatsApp Manager. */
+    name: string;
+    /** Language code the template was approved for, e.g. `en_US`. */
+    language: string;
+    /** Meta `components` (header/body/button parameters), passed through verbatim. */
+    components?: Record<string, unknown>[];
+}
+interface WhatsappMedia {
+    /** Public HTTPS link fetched at send time. */
+    link: string;
+    caption?: string;
+}
+interface WhatsappDocument extends WhatsappMedia {
+    /** File name shown to the recipient. */
+    filename?: string;
+}
+interface SendWhatsappOptions {
+    /**
+     * Connected number to send from, in international format. Optional when
+     * your organization has a single WhatsApp number.
+     */
+    from?: string;
+    /** One recipient in international format (`+237670000000`). */
+    to: string;
+    /** Defaults to `text`. */
+    type?: WhatsappMessageType;
+    /** Body for `text` messages (up to 4,096 characters), or a media caption. */
+    text?: string;
+    /** Render a preview for the first link in a `text` message. */
+    previewUrl?: boolean;
+    /** Required for `type: "template"`. Needed to start a conversation outside the 24h window. */
+    template?: WhatsappTemplate;
+    /** Required for `type: "image"`. */
+    image?: WhatsappMedia;
+    /** Required for `type: "document"`. */
+    document?: WhatsappDocument;
+}
+interface SendWhatsappResponse {
+    id: string;
+    status: "queued";
+    type: WhatsappMessageType;
+    /** The connected number the message goes out from. */
+    from: string;
+    /** ISO 3166-1 alpha-2 destination country detected from the number prefix. */
+    country: string | null;
+    created_at: string;
+}
+interface WhatsappEvent {
+    type: string;
+    created_at: string;
+}
+interface GetWhatsappResponse {
+    id: string;
+    from: string;
+    to: string;
+    country: string | null;
+    type: WhatsappMessageType;
+    text: string | null;
+    preview_url: boolean;
+    template: WhatsappTemplate | null;
+    media: WhatsappDocument | null;
+    /** Upstream provider that carried the message, e.g. `meta`. */
+    provider: string | null;
+    /** Provider-side message id (`wamid.…` on Meta); inbound replies reference it. */
+    provider_message_id: string | null;
+    status: WhatsappStatus;
+    error: string | null;
+    created_at: string;
+    last_event_at: string | null;
+    events: WhatsappEvent[];
+}
 interface SendBatchResponse {
     id: string;
     total: number;
@@ -149,9 +224,23 @@ declare class Sms {
     get(id: string): Promise<Result<GetSmsResponse>>;
 }
 
+declare class Whatsapp {
+    private readonly client;
+    constructor(client: Retransmit);
+    /**
+     * Queues a single WhatsApp message to one recipient. Poll `get(id)` or
+     * subscribe to webhooks for the outcome; replies arrive as
+     * `whatsapp.received` webhooks.
+     */
+    send(options: SendWhatsappOptions): Promise<Result<SendWhatsappResponse>>;
+    /** Retrieves a WhatsApp message with its current status and event history. */
+    get(id: string): Promise<Result<GetWhatsappResponse>>;
+}
+
 declare class Retransmit {
     readonly emails: Emails;
     readonly sms: Sms;
+    readonly whatsapp: Whatsapp;
     readonly batch: Batch;
     private readonly apiKey;
     private readonly baseUrl;
@@ -160,4 +249,4 @@ declare class Retransmit {
     request<T>(method: "GET" | "POST", path: string, body?: unknown): Promise<Result<T>>;
 }
 
-export { Batch, EMAIL_STATUSES, type EmailEvent, type EmailStatus, Emails, type GetBatchResponse, type GetEmailResponse, type GetSmsResponse, type Result, Retransmit, type RetransmitError, type RetransmitOptions, SMS_STATUSES, type SendBatchResponse, type SendEmailOptions, type SendEmailResponse, type SendSmsOptions, type SendSmsResponse, Sms, type SmsEvent, type SmsStatus };
+export { Batch, EMAIL_STATUSES, type EmailEvent, type EmailStatus, Emails, type GetBatchResponse, type GetEmailResponse, type GetSmsResponse, type GetWhatsappResponse, 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 };

package/dist/index.d.ts

@@ -106,6 +106,81 @@ interface GetSmsResponse {
     last_event_at: string | null;
     events: SmsEvent[];
 }
+declare const WHATSAPP_STATUSES: readonly ["queued", "sent", "delivered", "read", "failed"];
+type WhatsappStatus = (typeof WHATSAPP_STATUSES)[number];
+type WhatsappMessageType = "text" | "template" | "image" | "document";
+interface WhatsappTemplate {
+    /** Template name as approved in WhatsApp Manager. */
+    name: string;
+    /** Language code the template was approved for, e.g. `en_US`. */
+    language: string;
+    /** Meta `components` (header/body/button parameters), passed through verbatim. */
+    components?: Record<string, unknown>[];
+}
+interface WhatsappMedia {
+    /** Public HTTPS link fetched at send time. */
+    link: string;
+    caption?: string;
+}
+interface WhatsappDocument extends WhatsappMedia {
+    /** File name shown to the recipient. */
+    filename?: string;
+}
+interface SendWhatsappOptions {
+    /**
+     * Connected number to send from, in international format. Optional when
+     * your organization has a single WhatsApp number.
+     */
+    from?: string;
+    /** One recipient in international format (`+237670000000`). */
+    to: string;
+    /** Defaults to `text`. */
+    type?: WhatsappMessageType;
+    /** Body for `text` messages (up to 4,096 characters), or a media caption. */
+    text?: string;
+    /** Render a preview for the first link in a `text` message. */
+    previewUrl?: boolean;
+    /** Required for `type: "template"`. Needed to start a conversation outside the 24h window. */
+    template?: WhatsappTemplate;
+    /** Required for `type: "image"`. */
+    image?: WhatsappMedia;
+    /** Required for `type: "document"`. */
+    document?: WhatsappDocument;
+}
+interface SendWhatsappResponse {
+    id: string;
+    status: "queued";
+    type: WhatsappMessageType;
+    /** The connected number the message goes out from. */
+    from: string;
+    /** ISO 3166-1 alpha-2 destination country detected from the number prefix. */
+    country: string | null;
+    created_at: string;
+}
+interface WhatsappEvent {
+    type: string;
+    created_at: string;
+}
+interface GetWhatsappResponse {
+    id: string;
+    from: string;
+    to: string;
+    country: string | null;
+    type: WhatsappMessageType;
+    text: string | null;
+    preview_url: boolean;
+    template: WhatsappTemplate | null;
+    media: WhatsappDocument | null;
+    /** Upstream provider that carried the message, e.g. `meta`. */
+    provider: string | null;
+    /** Provider-side message id (`wamid.…` on Meta); inbound replies reference it. */
+    provider_message_id: string | null;
+    status: WhatsappStatus;
+    error: string | null;
+    created_at: string;
+    last_event_at: string | null;
+    events: WhatsappEvent[];
+}
 interface SendBatchResponse {
     id: string;
     total: number;
@@ -149,9 +224,23 @@ declare class Sms {
     get(id: string): Promise<Result<GetSmsResponse>>;
 }
 
+declare class Whatsapp {
+    private readonly client;
+    constructor(client: Retransmit);
+    /**
+     * Queues a single WhatsApp message to one recipient. Poll `get(id)` or
+     * subscribe to webhooks for the outcome; replies arrive as
+     * `whatsapp.received` webhooks.
+     */
+    send(options: SendWhatsappOptions): Promise<Result<SendWhatsappResponse>>;
+    /** Retrieves a WhatsApp message with its current status and event history. */
+    get(id: string): Promise<Result<GetWhatsappResponse>>;
+}
+
 declare class Retransmit {
     readonly emails: Emails;
     readonly sms: Sms;
+    readonly whatsapp: Whatsapp;
     readonly batch: Batch;
     private readonly apiKey;
     private readonly baseUrl;
@@ -160,4 +249,4 @@ declare class Retransmit {
     request<T>(method: "GET" | "POST", path: string, body?: unknown): Promise<Result<T>>;
 }
 
-export { Batch, EMAIL_STATUSES, type EmailEvent, type EmailStatus, Emails, type GetBatchResponse, type GetEmailResponse, type GetSmsResponse, type Result, Retransmit, type RetransmitError, type RetransmitOptions, SMS_STATUSES, type SendBatchResponse, type SendEmailOptions, type SendEmailResponse, type SendSmsOptions, type SendSmsResponse, Sms, type SmsEvent, type SmsStatus };
+export { Batch, EMAIL_STATUSES, type EmailEvent, type EmailStatus, Emails, type GetBatchResponse, type GetEmailResponse, type GetSmsResponse, type GetWhatsappResponse, 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 };

package/dist/index.js

@@ -65,6 +65,35 @@ var Sms = class {
   }
 };
 
+// src/whatsapp.ts
+var Whatsapp = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Queues a single WhatsApp message to one recipient. Poll `get(id)` or
+   * subscribe to webhooks for the outcome; replies arrive as
+   * `whatsapp.received` webhooks.
+   */
+  send(options) {
+    return this.client.request("POST", "/v1/whatsapp", {
+      from: options.from,
+      to: options.to,
+      type: options.type,
+      text: options.text,
+      preview_url: options.previewUrl,
+      template: options.template,
+      image: options.image,
+      document: options.document
+    });
+  }
+  /** Retrieves a WhatsApp message with its current status and event history. */
+  get(id) {
+    return this.client.request("GET", `/v1/whatsapp/${encodeURIComponent(id)}`);
+  }
+};
+
 // src/retransmit.ts
 var DEFAULT_BASE_URL = "https://api.retransmit.dev";
 var USER_AGENT = "retransmit.dev-node/0.1.0";
@@ -74,6 +103,7 @@ function readEnv(name) {
 var Retransmit = class {
   emails = new Emails(this);
   sms = new Sms(this);
+  whatsapp = new Whatsapp(this);
   batch = new Batch(this);
   apiKey;
   baseUrl;
@@ -156,11 +186,14 @@ var SMS_STATUSES = [
   "rejected",
   "failed"
 ];
+var WHATSAPP_STATUSES = ["queued", "sent", "delivered", "read", "failed"];
 export {
   Batch,
   EMAIL_STATUSES,
   Emails,
   Retransmit,
   SMS_STATUSES,
-  Sms
+  Sms,
+  WHATSAPP_STATUSES,
+  Whatsapp
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "retransmit.dev",
-  "version": "0.1.2",
-  "description": "Node.js SDK for the Retransmit email and SMS APIs",
+  "version": "0.2.0",
+  "description": "Node.js SDK for the Retransmit email, SMS and WhatsApp APIs",
   "keywords": [
     "email",
     "sms",
@@ -9,7 +9,9 @@
     "retransmit",
     "ses",
     "transactional-email",
-    "transactional-sms"
+    "transactional-sms",
+    "whatsapp",
+    "whatsapp-cloud-api"
   ],
   "homepage": "https://docs.retransmit.dev",
   "repository": {