retransmit.dev 0.4.0 → 0.6.0

package/README.md

@@ -101,6 +101,80 @@ like `From`, `To`, `Subject`, `Date` or `Message-ID`, are rejected with a
 headers even if you pass your own. Headers come back on `emails.get`, and
 batch emails accept the same field.
 
+### Attachments
+
+Attach up to 20 files, 30 MB in total. Pass the bytes as `content` (a
+`Buffer`, `Uint8Array` or base64 string), or a public URL as `path` and
+Retransmit fetches it while the request runs. Either way the file travels
+inside the email.
+
+```ts
+import { readFile } from "node:fs/promises";
+
+await retransmit.emails.send({
+  from: "Acme <billing@yourdomain.com>",
+  to: "user@example.com",
+  subject: "Your invoice",
+  html: "<p>Your invoice is attached.</p>",
+  attachments: [
+    { filename: "invoice.pdf", content: await readFile("./invoice.pdf") },
+    { filename: "terms.pdf", path: "https://yourdomain.com/terms.pdf" },
+  ],
+});
+```
+
+To embed an image in the HTML, give it a `contentId` and reference it as
+`cid:`:
+
+```ts
+await retransmit.emails.send({
+  from: "Acme <hello@yourdomain.com>",
+  to: "user@example.com",
+  subject: "Welcome",
+  html: '<p><img src="cid:logo" alt="Acme" /> Glad to have you.</p>',
+  attachments: [{ filename: "logo.png", path: "https://yourdomain.com/logo.png", contentId: "logo" }],
+});
+```
+
+Executables, scripts and installers are rejected with `invalid_attachment`,
+and `batch.send` does not accept attachments. Files are kept for 30 days so
+you can see what went out:
+
+```ts
+const { data } = await retransmit.emails.attachments("em_xxxxxxxxxxxx");
+// data.attachments: [{ id, filename, content_type, size, download_url, expires_at, ... }]
+```
+
+`download_url` is signed and valid for one hour; it is `null` once the file
+has expired.
+
+### Idempotency
+
+A send can succeed on the server and still fail on your side, through a
+timeout or a dropped connection. Retrying it blindly sends the email twice.
+Pass an `idempotencyKey` and retries become safe: for 24 hours the same key
+with the same payload returns the original response, `id` included, and
+nothing is queued again.
+
+```ts
+await retransmit.emails.send(
+  {
+    from: "Acme <hello@yourdomain.com>",
+    to: "user@example.com",
+    subject: "Welcome to Acme",
+    html: "<p>Glad to have you.</p>",
+  },
+  { idempotencyKey: "welcome-user/123" },
+);
+```
+
+Use a value that identifies that exact email, such as a UUID or
+`<event>/<entity-id>`. Keys are 1 to 256 characters and are shared by every
+API key in your organization. The same key with a different payload returns
+`invalid_idempotent_request`; a retry that overlaps the first request returns
+`concurrent_idempotent_requests`, so wait a moment and try again. Batches
+accept the same option with one key for the whole batch.
+
 ### List and filter emails
 
 `emails.list` returns your emails newest first. Every tag you pass must match.
@@ -155,15 +229,59 @@ 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:
 
 ```ts
-const { data: batch } = await retransmit.batch.send([
-  { from: "Acme <hello@yourdomain.com>", to: "a@example.com", subject: "Hi", text: "Hello A" },
-  { from: "Acme <hello@yourdomain.com>", to: "b@example.com", subject: "Hi", text: "Hello B" },
-]);
+const { data: batch } = await retransmit.batch.send(
+  [
+    { from: "Acme <hello@yourdomain.com>", to: "a@example.com", subject: "Hi", text: "Hello A" },
+    { from: "Acme <hello@yourdomain.com>", to: "b@example.com", subject: "Hi", text: "Hello B" },
+  ],
+  { idempotencyKey: "weekly-digest/2026-09-07" },
+);
 
 const { data: progress } = await retransmit.batch.get(batch!.id);
 console.log(progress?.processed, "/", progress?.total, progress?.counts);

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,
@@ -32,6 +33,24 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/emails.ts
+function toBase64(bytes) {
+  if (typeof Buffer !== "undefined") return Buffer.from(bytes).toString("base64");
+  let binary = "";
+  const CHUNK = 32768;
+  for (let i = 0; i < bytes.length; i += CHUNK) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+  }
+  return btoa(binary);
+}
+function toWireAttachment(attachment) {
+  return {
+    filename: attachment.filename,
+    content: attachment.content === void 0 || typeof attachment.content === "string" ? attachment.content : toBase64(attachment.content),
+    path: attachment.path,
+    content_type: attachment.contentType,
+    content_id: attachment.contentId
+  };
+}
 function toWirePayload(options) {
   return {
     from: options.from,
@@ -44,7 +63,8 @@ function toWirePayload(options) {
     text: options.text,
     marketing: options.marketing,
     tags: options.tags,
-    headers: options.headers
+    headers: options.headers,
+    attachments: options.attachments?.map(toWireAttachment)
   };
 }
 var Emails = class {
@@ -52,9 +72,18 @@ var Emails = class {
     this.client = client;
   }
   client;
-  /** Queues a single email. Poll `get(id)` or subscribe to webhooks for the outcome. */
-  send(options) {
-    return this.client.request("POST", "/v1/emails", toWirePayload(options));
+  /**
+   * Queues a single email. Poll `get(id)` or subscribe to webhooks for the
+   * outcome. Pass `{ idempotencyKey }` to make the call safe to retry.
+   */
+  send(options, requestOptions) {
+    return this.client.request(
+      "POST",
+      "/v1/emails",
+      toWirePayload(options),
+      void 0,
+      requestOptions
+    );
   }
   /** Retrieves an email with its current status and event history. */
   get(id) {
@@ -77,6 +106,21 @@ var Emails = class {
   tags() {
     return this.client.request("GET", "/v1/emails/tags");
   }
+  /**
+   * The attachments of an email, each with a signed `download_url` valid for
+   * one hour. Files are kept for 30 days after the send; after that the link
+   * is `null` and only the metadata remains.
+   */
+  attachments(emailId) {
+    return this.client.request("GET", `/v1/emails/${encodeURIComponent(emailId)}/attachments`);
+  }
+  /** One attachment of an email with a signed download link. */
+  getAttachment(emailId, attachmentId) {
+    return this.client.request(
+      "GET",
+      `/v1/emails/${encodeURIComponent(emailId)}/attachments/${encodeURIComponent(attachmentId)}`
+    );
+  }
 };
 
 // src/batch.ts
@@ -85,11 +129,19 @@ var Batch = class {
     this.client = client;
   }
   client;
-  /** Queues up to 10,000 emails in one request. Track progress with `get(id)`. */
-  send(emails) {
-    return this.client.request("POST", "/v1/emails/batch", {
-      emails: emails.map(toWirePayload)
-    });
+  /**
+   * Queues up to 10,000 emails in one request. Track progress with `get(id)`.
+   * Pass `{ idempotencyKey }` covering the whole batch to make the call safe
+   * to retry.
+   */
+  send(emails, requestOptions) {
+    return this.client.request(
+      "POST",
+      "/v1/emails/batch",
+      { emails: emails.map(toWirePayload) },
+      void 0,
+      requestOptions
+    );
   }
   /** Batch progress: how many emails are in each status so far. */
   get(id) {
@@ -108,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. */
@@ -148,7 +201,7 @@ var Whatsapp = class {
 
 // src/retransmit.ts
 var DEFAULT_BASE_URL = "https://api.retransmit.dev";
-var USER_AGENT = "retransmit.dev-node/0.4.0";
+var USER_AGENT = "retransmit.dev-node/0.6.0";
 function readEnv(name) {
   return typeof process !== "undefined" ? process.env?.[name] : void 0;
 }
@@ -173,7 +226,7 @@ var Retransmit = class {
     );
   }
   /** Internal transport shared by the resource classes. API failures are returned, never thrown. */
-  async request(method, path, body, query) {
+  async request(method, path, body, query, options = {}) {
     const params = new URLSearchParams();
     for (const [key, value] of Object.entries(query ?? {})) {
       if (value === void 0) continue;
@@ -181,15 +234,19 @@ var Retransmit = class {
     }
     const encoded = params.toString();
     const search = encoded ? `?${encoded}` : "";
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json",
+      "User-Agent": USER_AGENT
+    };
+    if (options.idempotencyKey !== void 0) {
+      headers["Idempotency-Key"] = options.idempotencyKey;
+    }
     let response;
     try {
       response = await fetch(`${this.baseUrl}${path}${search}`, {
         method,
-        headers: {
-          Authorization: `Bearer ${this.apiKey}`,
-          "Content-Type": "application/json",
-          "User-Agent": USER_AGENT
-        },
+        headers,
         body: body === void 0 ? void 0 : JSON.stringify(body)
       });
     } catch (cause) {
@@ -245,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 = {
@@ -252,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

@@ -20,6 +20,18 @@ interface RetransmitOptions {
     /** Override the API origin. Defaults to `https://api.retransmit.dev` (or `RETRANSMIT_BASE_URL`). */
     baseUrl?: string;
 }
+/** Per-request options, passed as the second argument of `emails.send` and `batch.send`. */
+interface RequestOptions {
+    /**
+     * Makes the request safe to retry. Sent as the `Idempotency-Key` header.
+     * For 24 hours, a retry with the same key and payload returns the original
+     * response instead of queuing the email again. 1 to 256 characters; a UUID
+     * or `<event>/<entity-id>` such as `welcome-user/123` works well. A retry
+     * with a different payload fails with `invalid_idempotent_request`, and one
+     * that overlaps the first request fails with `concurrent_idempotent_requests`.
+     */
+    idempotencyKey?: string;
+}
 interface SendEmailOptions {
     /** Sender, as `address@domain.com` or `Name <address@domain.com>`. The domain must be verified on your account. */
     from: string;
@@ -58,8 +70,58 @@ interface SendEmailOptions {
      * List-Unsubscribe headers take precedence over yours.
      */
     headers?: EmailHeaders;
+    /**
+     * Files to attach, up to 20 per email and 30 MB in total. Each needs a
+     * `filename` and either `content` (the bytes) or `path` (a public URL
+     * fetched when you call `send`). Add `contentId` to embed an image inline.
+     * Not accepted by `batch.send`.
+     */
+    attachments?: Attachment[];
 }
 type EmailHeaders = Record<string, string>;
+/** A file to attach. Provide exactly one of `content` and `path`. */
+interface Attachment {
+    /**
+     * Name the recipient sees, up to 255 characters, no path separators. Its
+     * extension sets the content type when `contentType` is omitted.
+     */
+    filename: string;
+    /** The file: a `Buffer`, a `Uint8Array`, or an already base64 encoded string. */
+    content?: string | Uint8Array;
+    /**
+     * Public http(s) URL the file is fetched from while the request runs, with
+     * a 15 second budget. Private and internal hosts are refused.
+     */
+    path?: string;
+    /** MIME type such as `application/pdf`. Inferred from the filename when omitted. */
+    contentType?: string;
+    /**
+     * Embeds the file inline and sets its Content-ID. Reference it in `html`
+     * as `<img src="cid:the-id">`. Letters, digits, `.`, `_`, `@` and `-`, up
+     * to 128 characters, unique per email.
+     */
+    contentId?: string;
+}
+/** An attachment as it was sent, without a download link. */
+interface EmailAttachment {
+    id: string;
+    filename: string;
+    content_type: string;
+    /** Size in bytes of the decoded file. */
+    size: number;
+    content_id: string | null;
+    /** True for images embedded via `contentId`. */
+    inline: boolean;
+}
+interface EmailAttachmentWithDownload extends EmailAttachment {
+    /** When the stored file is deleted, 30 days after the send. */
+    expires_at: string;
+    /** Signed link to download the file, valid for one hour. `null` once the file has expired. */
+    download_url: string | null;
+}
+interface ListEmailAttachmentsResponse {
+    attachments: EmailAttachmentWithDownload[];
+}
 interface EmailTag {
     name: string;
     value: string;
@@ -91,6 +153,8 @@ interface GetEmailResponse {
     created_at: string;
     last_event_at: string | null;
     events: EmailEvent[];
+    /** Attachments given at send time, without download links. See `emails.attachments`. */
+    attachments: EmailAttachment[];
 }
 interface ListEmailsOptions {
     /**
@@ -136,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;
@@ -167,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;
@@ -269,8 +361,12 @@ interface GetBatchResponse {
 declare class Batch {
     private readonly client;
     constructor(client: Retransmit);
-    /** Queues up to 10,000 emails in one request. Track progress with `get(id)`. */
-    send(emails: SendEmailOptions[]): Promise<Result<SendBatchResponse>>;
+    /**
+     * Queues up to 10,000 emails in one request. Track progress with `get(id)`.
+     * Pass `{ idempotencyKey }` covering the whole batch to make the call safe
+     * to retry.
+     */
+    send(emails: SendEmailOptions[], requestOptions?: RequestOptions): Promise<Result<SendBatchResponse>>;
     /** Batch progress: how many emails are in each status so far. */
     get(id: string): Promise<Result<GetBatchResponse>>;
 }
@@ -278,8 +374,11 @@ declare class Batch {
 declare class Emails {
     private readonly client;
     constructor(client: Retransmit);
-    /** Queues a single email. Poll `get(id)` or subscribe to webhooks for the outcome. */
-    send(options: SendEmailOptions): Promise<Result<SendEmailResponse>>;
+    /**
+     * Queues a single email. Poll `get(id)` or subscribe to webhooks for the
+     * outcome. Pass `{ idempotencyKey }` to make the call safe to retry.
+     */
+    send(options: SendEmailOptions, requestOptions?: RequestOptions): Promise<Result<SendEmailResponse>>;
     /** Retrieves an email with its current status and event history. */
     get(id: string): Promise<Result<GetEmailResponse>>;
     /**
@@ -289,6 +388,14 @@ declare class Emails {
     list(options?: ListEmailsOptions): Promise<Result<ListEmailsResponse>>;
     /** Every distinct tag on your emails, with a count of emails carrying it. */
     tags(): Promise<Result<ListEmailTagsResponse>>;
+    /**
+     * The attachments of an email, each with a signed `download_url` valid for
+     * one hour. Files are kept for 30 days after the send; after that the link
+     * is `null` and only the metadata remains.
+     */
+    attachments(emailId: string): Promise<Result<ListEmailAttachmentsResponse>>;
+    /** One attachment of an email with a signed download link. */
+    getAttachment(emailId: string, attachmentId: string): Promise<Result<EmailAttachmentWithDownload>>;
 }
 
 declare class Sms {
@@ -322,7 +429,7 @@ declare class Retransmit {
     private readonly baseUrl;
     constructor(apiKey?: string, options?: RetransmitOptions);
     /** Internal transport shared by the resource classes. API failures are returned, never thrown. */
-    request<T>(method: "GET" | "POST", path: string, body?: unknown, query?: Record<string, string | number | string[] | undefined>): Promise<Result<T>>;
+    request<T>(method: "GET" | "POST", path: string, body?: unknown, query?: Record<string, string | number | string[] | undefined>, options?: RequestOptions): Promise<Result<T>>;
 }
 
-export { Batch, EMAIL_STATUSES, type EmailEvent, type EmailStatus, type EmailSummary, type EmailTag, type EmailTagCount, Emails, type GetBatchResponse, type GetEmailResponse, type GetSmsResponse, type GetWhatsappResponse, type ListEmailTagsResponse, type ListEmailsOptions, type ListEmailsResponse, 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

@@ -20,6 +20,18 @@ interface RetransmitOptions {
     /** Override the API origin. Defaults to `https://api.retransmit.dev` (or `RETRANSMIT_BASE_URL`). */
     baseUrl?: string;
 }
+/** Per-request options, passed as the second argument of `emails.send` and `batch.send`. */
+interface RequestOptions {
+    /**
+     * Makes the request safe to retry. Sent as the `Idempotency-Key` header.
+     * For 24 hours, a retry with the same key and payload returns the original
+     * response instead of queuing the email again. 1 to 256 characters; a UUID
+     * or `<event>/<entity-id>` such as `welcome-user/123` works well. A retry
+     * with a different payload fails with `invalid_idempotent_request`, and one
+     * that overlaps the first request fails with `concurrent_idempotent_requests`.
+     */
+    idempotencyKey?: string;
+}
 interface SendEmailOptions {
     /** Sender, as `address@domain.com` or `Name <address@domain.com>`. The domain must be verified on your account. */
     from: string;
@@ -58,8 +70,58 @@ interface SendEmailOptions {
      * List-Unsubscribe headers take precedence over yours.
      */
     headers?: EmailHeaders;
+    /**
+     * Files to attach, up to 20 per email and 30 MB in total. Each needs a
+     * `filename` and either `content` (the bytes) or `path` (a public URL
+     * fetched when you call `send`). Add `contentId` to embed an image inline.
+     * Not accepted by `batch.send`.
+     */
+    attachments?: Attachment[];
 }
 type EmailHeaders = Record<string, string>;
+/** A file to attach. Provide exactly one of `content` and `path`. */
+interface Attachment {
+    /**
+     * Name the recipient sees, up to 255 characters, no path separators. Its
+     * extension sets the content type when `contentType` is omitted.
+     */
+    filename: string;
+    /** The file: a `Buffer`, a `Uint8Array`, or an already base64 encoded string. */
+    content?: string | Uint8Array;
+    /**
+     * Public http(s) URL the file is fetched from while the request runs, with
+     * a 15 second budget. Private and internal hosts are refused.
+     */
+    path?: string;
+    /** MIME type such as `application/pdf`. Inferred from the filename when omitted. */
+    contentType?: string;
+    /**
+     * Embeds the file inline and sets its Content-ID. Reference it in `html`
+     * as `<img src="cid:the-id">`. Letters, digits, `.`, `_`, `@` and `-`, up
+     * to 128 characters, unique per email.
+     */
+    contentId?: string;
+}
+/** An attachment as it was sent, without a download link. */
+interface EmailAttachment {
+    id: string;
+    filename: string;
+    content_type: string;
+    /** Size in bytes of the decoded file. */
+    size: number;
+    content_id: string | null;
+    /** True for images embedded via `contentId`. */
+    inline: boolean;
+}
+interface EmailAttachmentWithDownload extends EmailAttachment {
+    /** When the stored file is deleted, 30 days after the send. */
+    expires_at: string;
+    /** Signed link to download the file, valid for one hour. `null` once the file has expired. */
+    download_url: string | null;
+}
+interface ListEmailAttachmentsResponse {
+    attachments: EmailAttachmentWithDownload[];
+}
 interface EmailTag {
     name: string;
     value: string;
@@ -91,6 +153,8 @@ interface GetEmailResponse {
     created_at: string;
     last_event_at: string | null;
     events: EmailEvent[];
+    /** Attachments given at send time, without download links. See `emails.attachments`. */
+    attachments: EmailAttachment[];
 }
 interface ListEmailsOptions {
     /**
@@ -136,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;
@@ -167,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;
@@ -269,8 +361,12 @@ interface GetBatchResponse {
 declare class Batch {
     private readonly client;
     constructor(client: Retransmit);
-    /** Queues up to 10,000 emails in one request. Track progress with `get(id)`. */
-    send(emails: SendEmailOptions[]): Promise<Result<SendBatchResponse>>;
+    /**
+     * Queues up to 10,000 emails in one request. Track progress with `get(id)`.
+     * Pass `{ idempotencyKey }` covering the whole batch to make the call safe
+     * to retry.
+     */
+    send(emails: SendEmailOptions[], requestOptions?: RequestOptions): Promise<Result<SendBatchResponse>>;
     /** Batch progress: how many emails are in each status so far. */
     get(id: string): Promise<Result<GetBatchResponse>>;
 }
@@ -278,8 +374,11 @@ declare class Batch {
 declare class Emails {
     private readonly client;
     constructor(client: Retransmit);
-    /** Queues a single email. Poll `get(id)` or subscribe to webhooks for the outcome. */
-    send(options: SendEmailOptions): Promise<Result<SendEmailResponse>>;
+    /**
+     * Queues a single email. Poll `get(id)` or subscribe to webhooks for the
+     * outcome. Pass `{ idempotencyKey }` to make the call safe to retry.
+     */
+    send(options: SendEmailOptions, requestOptions?: RequestOptions): Promise<Result<SendEmailResponse>>;
     /** Retrieves an email with its current status and event history. */
     get(id: string): Promise<Result<GetEmailResponse>>;
     /**
@@ -289,6 +388,14 @@ declare class Emails {
     list(options?: ListEmailsOptions): Promise<Result<ListEmailsResponse>>;
     /** Every distinct tag on your emails, with a count of emails carrying it. */
     tags(): Promise<Result<ListEmailTagsResponse>>;
+    /**
+     * The attachments of an email, each with a signed `download_url` valid for
+     * one hour. Files are kept for 30 days after the send; after that the link
+     * is `null` and only the metadata remains.
+     */
+    attachments(emailId: string): Promise<Result<ListEmailAttachmentsResponse>>;
+    /** One attachment of an email with a signed download link. */
+    getAttachment(emailId: string, attachmentId: string): Promise<Result<EmailAttachmentWithDownload>>;
 }
 
 declare class Sms {
@@ -322,7 +429,7 @@ declare class Retransmit {
     private readonly baseUrl;
     constructor(apiKey?: string, options?: RetransmitOptions);
     /** Internal transport shared by the resource classes. API failures are returned, never thrown. */
-    request<T>(method: "GET" | "POST", path: string, body?: unknown, query?: Record<string, string | number | string[] | undefined>): Promise<Result<T>>;
+    request<T>(method: "GET" | "POST", path: string, body?: unknown, query?: Record<string, string | number | string[] | undefined>, options?: RequestOptions): Promise<Result<T>>;
 }
 
-export { Batch, EMAIL_STATUSES, type EmailEvent, type EmailStatus, type EmailSummary, type EmailTag, type EmailTagCount, Emails, type GetBatchResponse, type GetEmailResponse, type GetSmsResponse, type GetWhatsappResponse, type ListEmailTagsResponse, type ListEmailsOptions, type ListEmailsResponse, 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

@@ -1,4 +1,22 @@
 // src/emails.ts
+function toBase64(bytes) {
+  if (typeof Buffer !== "undefined") return Buffer.from(bytes).toString("base64");
+  let binary = "";
+  const CHUNK = 32768;
+  for (let i = 0; i < bytes.length; i += CHUNK) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+  }
+  return btoa(binary);
+}
+function toWireAttachment(attachment) {
+  return {
+    filename: attachment.filename,
+    content: attachment.content === void 0 || typeof attachment.content === "string" ? attachment.content : toBase64(attachment.content),
+    path: attachment.path,
+    content_type: attachment.contentType,
+    content_id: attachment.contentId
+  };
+}
 function toWirePayload(options) {
   return {
     from: options.from,
@@ -11,7 +29,8 @@ function toWirePayload(options) {
     text: options.text,
     marketing: options.marketing,
     tags: options.tags,
-    headers: options.headers
+    headers: options.headers,
+    attachments: options.attachments?.map(toWireAttachment)
   };
 }
 var Emails = class {
@@ -19,9 +38,18 @@ var Emails = class {
     this.client = client;
   }
   client;
-  /** Queues a single email. Poll `get(id)` or subscribe to webhooks for the outcome. */
-  send(options) {
-    return this.client.request("POST", "/v1/emails", toWirePayload(options));
+  /**
+   * Queues a single email. Poll `get(id)` or subscribe to webhooks for the
+   * outcome. Pass `{ idempotencyKey }` to make the call safe to retry.
+   */
+  send(options, requestOptions) {
+    return this.client.request(
+      "POST",
+      "/v1/emails",
+      toWirePayload(options),
+      void 0,
+      requestOptions
+    );
   }
   /** Retrieves an email with its current status and event history. */
   get(id) {
@@ -44,6 +72,21 @@ var Emails = class {
   tags() {
     return this.client.request("GET", "/v1/emails/tags");
   }
+  /**
+   * The attachments of an email, each with a signed `download_url` valid for
+   * one hour. Files are kept for 30 days after the send; after that the link
+   * is `null` and only the metadata remains.
+   */
+  attachments(emailId) {
+    return this.client.request("GET", `/v1/emails/${encodeURIComponent(emailId)}/attachments`);
+  }
+  /** One attachment of an email with a signed download link. */
+  getAttachment(emailId, attachmentId) {
+    return this.client.request(
+      "GET",
+      `/v1/emails/${encodeURIComponent(emailId)}/attachments/${encodeURIComponent(attachmentId)}`
+    );
+  }
 };
 
 // src/batch.ts
@@ -52,11 +95,19 @@ var Batch = class {
     this.client = client;
   }
   client;
-  /** Queues up to 10,000 emails in one request. Track progress with `get(id)`. */
-  send(emails) {
-    return this.client.request("POST", "/v1/emails/batch", {
-      emails: emails.map(toWirePayload)
-    });
+  /**
+   * Queues up to 10,000 emails in one request. Track progress with `get(id)`.
+   * Pass `{ idempotencyKey }` covering the whole batch to make the call safe
+   * to retry.
+   */
+  send(emails, requestOptions) {
+    return this.client.request(
+      "POST",
+      "/v1/emails/batch",
+      { emails: emails.map(toWirePayload) },
+      void 0,
+      requestOptions
+    );
   }
   /** Batch progress: how many emails are in each status so far. */
   get(id) {
@@ -75,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. */
@@ -115,7 +167,7 @@ var Whatsapp = class {
 
 // src/retransmit.ts
 var DEFAULT_BASE_URL = "https://api.retransmit.dev";
-var USER_AGENT = "retransmit.dev-node/0.4.0";
+var USER_AGENT = "retransmit.dev-node/0.6.0";
 function readEnv(name) {
   return typeof process !== "undefined" ? process.env?.[name] : void 0;
 }
@@ -140,7 +192,7 @@ var Retransmit = class {
     );
   }
   /** Internal transport shared by the resource classes. API failures are returned, never thrown. */
-  async request(method, path, body, query) {
+  async request(method, path, body, query, options = {}) {
     const params = new URLSearchParams();
     for (const [key, value] of Object.entries(query ?? {})) {
       if (value === void 0) continue;
@@ -148,15 +200,19 @@ var Retransmit = class {
     }
     const encoded = params.toString();
     const search = encoded ? `?${encoded}` : "";
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json",
+      "User-Agent": USER_AGENT
+    };
+    if (options.idempotencyKey !== void 0) {
+      headers["Idempotency-Key"] = options.idempotencyKey;
+    }
     let response;
     try {
       response = await fetch(`${this.baseUrl}${path}${search}`, {
         method,
-        headers: {
-          Authorization: `Bearer ${this.apiKey}`,
-          "Content-Type": "application/json",
-          "User-Agent": USER_AGENT
-        },
+        headers,
         body: body === void 0 ? void 0 : JSON.stringify(body)
       });
     } catch (cause) {
@@ -212,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.4.0",
+  "version": "0.6.0",
   "description": "Node.js SDK for the Retransmit email, SMS and WhatsApp APIs",
   "keywords": [
     "email",