retransmit.dev 0.1.0

package/README.md

@@ -0,0 +1,80 @@
+# retransmit.dev
+
+Node.js SDK for the [Retransmit](https://retransmit.dev) email API. Zero dependencies, works on Node 18+ and edge runtimes with `fetch`.
+
+## Install
+
+```bash
+npm install retransmit.dev
+# or
+pnpm add retransmit.dev
+```
+
+## Usage
+
+Grab an API key from your Retransmit dashboard, then:
+
+```ts
+import { Retransmit } from "retransmit.dev";
+
+const retransmit = new Retransmit("rt_xxxxxxxxxxxx");
+// or set RETRANSMIT_API_KEY and call `new Retransmit()`
+
+const { data, error } = await retransmit.emails.send({
+  from: "Acme <hello@yourdomain.com>",
+  to: "user@example.com",
+  subject: "Hello from Retransmit",
+  html: "<p>It works!</p>",
+});
+
+if (error) {
+  console.error(error.code, error.message);
+} else {
+  console.log(data.id); // em_xxxxxxxxxxxx
+}
+```
+
+Emails are queued and sent asynchronously. Check the outcome later:
+
+```ts
+const { data } = await retransmit.emails.get("em_xxxxxxxxxxxx");
+console.log(data?.status); // "delivered"
+```
+
+### 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: progress } = await retransmit.batch.get(batch!.id);
+console.log(progress?.processed, "/", progress?.total, progress?.counts);
+```
+
+## Error handling
+
+Methods never throw on API errors — they return `{ data, error }`:
+
+```ts
+const { data, error } = await retransmit.emails.send(/* ... */);
+if (error) {
+  // error.code: "validation_error" | "domain_not_verified" | "unauthorized" | ...
+}
+```
+
+Only constructing the client without an API key throws.
+
+## Configuration
+
+| Option | Env var | Default |
+| --- | --- | --- |
+| `apiKey` (first argument) | `RETRANSMIT_API_KEY` | — (required) |
+| `baseUrl` | `RETRANSMIT_BASE_URL` | `https://api.retransmit.dev` |
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,163 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Batch: () => Batch,
+  EMAIL_STATUSES: () => EMAIL_STATUSES,
+  Emails: () => Emails,
+  Retransmit: () => Retransmit
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/emails.ts
+function toWirePayload(options) {
+  return {
+    from: options.from,
+    to: options.to,
+    cc: options.cc,
+    bcc: options.bcc,
+    reply_to: options.replyTo,
+    subject: options.subject,
+    html: options.html,
+    text: options.text
+  };
+}
+var Emails = class {
+  constructor(client) {
+    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));
+  }
+  /** Retrieves an email with its current status and event history. */
+  get(id) {
+    return this.client.request("GET", `/v1/emails/${encodeURIComponent(id)}`);
+  }
+};
+
+// src/batch.ts
+var Batch = class {
+  constructor(client) {
+    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)
+    });
+  }
+  /** Batch progress: how many emails are in each status so far. */
+  get(id) {
+    return this.client.request("GET", `/v1/emails/batch/${encodeURIComponent(id)}`);
+  }
+};
+
+// src/retransmit.ts
+var DEFAULT_BASE_URL = "https://api.retransmit.dev";
+var USER_AGENT = "retransmit.dev-node/0.1.0";
+function readEnv(name) {
+  return typeof process !== "undefined" ? process.env?.[name] : void 0;
+}
+var Retransmit = class {
+  emails = new Emails(this);
+  batch = new Batch(this);
+  apiKey;
+  baseUrl;
+  constructor(apiKey, options = {}) {
+    const key = apiKey ?? readEnv("RETRANSMIT_API_KEY");
+    if (!key) {
+      throw new Error(
+        'Missing API key. Pass it to `new Retransmit("rt_...")` or set the RETRANSMIT_API_KEY environment variable.'
+      );
+    }
+    this.apiKey = key;
+    this.baseUrl = (options.baseUrl ?? readEnv("RETRANSMIT_BASE_URL") ?? DEFAULT_BASE_URL).replace(
+      /\/+$/,
+      ""
+    );
+  }
+  /** Internal transport shared by the resource classes. API failures are returned, never thrown. */
+  async request(method, path, body) {
+    let response;
+    try {
+      response = await fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json",
+          "User-Agent": USER_AGENT
+        },
+        body: body === void 0 ? void 0 : JSON.stringify(body)
+      });
+    } catch (cause) {
+      return {
+        data: null,
+        error: {
+          code: "network_error",
+          message: cause instanceof Error ? cause.message : "Unable to reach the Retransmit API"
+        }
+      };
+    }
+    let json = null;
+    try {
+      json = await response.json();
+    } catch {
+    }
+    if (!response.ok) {
+      const error = json?.error;
+      return {
+        data: null,
+        error: error ?? {
+          code: "internal_error",
+          message: `Request failed with status ${response.status}`
+        }
+      };
+    }
+    return { data: json, error: null };
+  }
+};
+
+// src/types.ts
+var EMAIL_STATUSES = [
+  "queued",
+  "scheduled",
+  "sent",
+  "delivery_delayed",
+  "delivered",
+  "opened",
+  "clicked",
+  "bounced",
+  "complained",
+  "suppressed",
+  "canceled",
+  "rejected",
+  "failed"
+];
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Batch,
+  EMAIL_STATUSES,
+  Emails,
+  Retransmit
+});

package/dist/index.d.cts

@@ -0,0 +1,105 @@
+/**
+ * Response and payload types mirror the public API wire format
+ * (snake_case fields, ISO 8601 timestamps). Kept standalone on purpose:
+ * this package is published to npm and cannot import workspace packages.
+ */
+declare const EMAIL_STATUSES: readonly ["queued", "scheduled", "sent", "delivery_delayed", "delivered", "opened", "clicked", "bounced", "complained", "suppressed", "canceled", "rejected", "failed"];
+type EmailStatus = (typeof EMAIL_STATUSES)[number];
+interface RetransmitError {
+    code: string;
+    message: string;
+}
+type Result<T> = {
+    data: T;
+    error: null;
+} | {
+    data: null;
+    error: RetransmitError;
+};
+interface RetransmitOptions {
+    /** Override the API origin. Defaults to `https://api.retransmit.dev` (or `RETRANSMIT_BASE_URL`). */
+    baseUrl?: string;
+}
+interface SendEmailOptions {
+    /** Sender, as `address@domain.com` or `Name <address@domain.com>`. The domain must be verified on your account. */
+    from: string;
+    /** One recipient or up to 50. */
+    to: string | string[];
+    cc?: string | string[];
+    bcc?: string | string[];
+    replyTo?: string | string[];
+    subject: string;
+    /** HTML body. At least one of `html` or `text` is required. */
+    html?: string;
+    /** Plain-text body. At least one of `html` or `text` is required. */
+    text?: string;
+}
+interface SendEmailResponse {
+    id: string;
+    status: "queued";
+    created_at: string;
+}
+interface EmailEvent {
+    type: string;
+    created_at: string;
+}
+interface GetEmailResponse {
+    id: string;
+    batch_id: string | null;
+    from: string;
+    to: string[];
+    cc: string[] | null;
+    bcc: string[] | null;
+    reply_to: string[] | null;
+    subject: string;
+    status: EmailStatus;
+    error: string | null;
+    created_at: string;
+    last_event_at: string | null;
+    events: EmailEvent[];
+}
+interface SendBatchResponse {
+    id: string;
+    total: number;
+    status: "queued";
+    created_at: string;
+}
+interface GetBatchResponse {
+    id: string;
+    total: number;
+    /** Emails that have left the queue (any status other than `queued`/`scheduled`). */
+    processed: number;
+    /** Email count per status, e.g. `{ queued: 4, delivered: 96 }`. */
+    counts: Partial<Record<EmailStatus, number>>;
+    created_at: string;
+}
+
+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>>;
+    /** Batch progress: how many emails are in each status so far. */
+    get(id: string): Promise<Result<GetBatchResponse>>;
+}
+
+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>>;
+    /** Retrieves an email with its current status and event history. */
+    get(id: string): Promise<Result<GetEmailResponse>>;
+}
+
+declare class Retransmit {
+    readonly emails: Emails;
+    readonly batch: Batch;
+    private readonly apiKey;
+    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): Promise<Result<T>>;
+}
+
+export { Batch, EMAIL_STATUSES, type EmailEvent, type EmailStatus, Emails, type GetBatchResponse, type GetEmailResponse, type Result, Retransmit, type RetransmitError, type RetransmitOptions, type SendBatchResponse, type SendEmailOptions, type SendEmailResponse };

package/dist/index.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Response and payload types mirror the public API wire format
+ * (snake_case fields, ISO 8601 timestamps). Kept standalone on purpose:
+ * this package is published to npm and cannot import workspace packages.
+ */
+declare const EMAIL_STATUSES: readonly ["queued", "scheduled", "sent", "delivery_delayed", "delivered", "opened", "clicked", "bounced", "complained", "suppressed", "canceled", "rejected", "failed"];
+type EmailStatus = (typeof EMAIL_STATUSES)[number];
+interface RetransmitError {
+    code: string;
+    message: string;
+}
+type Result<T> = {
+    data: T;
+    error: null;
+} | {
+    data: null;
+    error: RetransmitError;
+};
+interface RetransmitOptions {
+    /** Override the API origin. Defaults to `https://api.retransmit.dev` (or `RETRANSMIT_BASE_URL`). */
+    baseUrl?: string;
+}
+interface SendEmailOptions {
+    /** Sender, as `address@domain.com` or `Name <address@domain.com>`. The domain must be verified on your account. */
+    from: string;
+    /** One recipient or up to 50. */
+    to: string | string[];
+    cc?: string | string[];
+    bcc?: string | string[];
+    replyTo?: string | string[];
+    subject: string;
+    /** HTML body. At least one of `html` or `text` is required. */
+    html?: string;
+    /** Plain-text body. At least one of `html` or `text` is required. */
+    text?: string;
+}
+interface SendEmailResponse {
+    id: string;
+    status: "queued";
+    created_at: string;
+}
+interface EmailEvent {
+    type: string;
+    created_at: string;
+}
+interface GetEmailResponse {
+    id: string;
+    batch_id: string | null;
+    from: string;
+    to: string[];
+    cc: string[] | null;
+    bcc: string[] | null;
+    reply_to: string[] | null;
+    subject: string;
+    status: EmailStatus;
+    error: string | null;
+    created_at: string;
+    last_event_at: string | null;
+    events: EmailEvent[];
+}
+interface SendBatchResponse {
+    id: string;
+    total: number;
+    status: "queued";
+    created_at: string;
+}
+interface GetBatchResponse {
+    id: string;
+    total: number;
+    /** Emails that have left the queue (any status other than `queued`/`scheduled`). */
+    processed: number;
+    /** Email count per status, e.g. `{ queued: 4, delivered: 96 }`. */
+    counts: Partial<Record<EmailStatus, number>>;
+    created_at: string;
+}
+
+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>>;
+    /** Batch progress: how many emails are in each status so far. */
+    get(id: string): Promise<Result<GetBatchResponse>>;
+}
+
+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>>;
+    /** Retrieves an email with its current status and event history. */
+    get(id: string): Promise<Result<GetEmailResponse>>;
+}
+
+declare class Retransmit {
+    readonly emails: Emails;
+    readonly batch: Batch;
+    private readonly apiKey;
+    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): Promise<Result<T>>;
+}
+
+export { Batch, EMAIL_STATUSES, type EmailEvent, type EmailStatus, Emails, type GetBatchResponse, type GetEmailResponse, type Result, Retransmit, type RetransmitError, type RetransmitOptions, type SendBatchResponse, type SendEmailOptions, type SendEmailResponse };

package/dist/index.js

@@ -0,0 +1,133 @@
+// src/emails.ts
+function toWirePayload(options) {
+  return {
+    from: options.from,
+    to: options.to,
+    cc: options.cc,
+    bcc: options.bcc,
+    reply_to: options.replyTo,
+    subject: options.subject,
+    html: options.html,
+    text: options.text
+  };
+}
+var Emails = class {
+  constructor(client) {
+    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));
+  }
+  /** Retrieves an email with its current status and event history. */
+  get(id) {
+    return this.client.request("GET", `/v1/emails/${encodeURIComponent(id)}`);
+  }
+};
+
+// src/batch.ts
+var Batch = class {
+  constructor(client) {
+    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)
+    });
+  }
+  /** Batch progress: how many emails are in each status so far. */
+  get(id) {
+    return this.client.request("GET", `/v1/emails/batch/${encodeURIComponent(id)}`);
+  }
+};
+
+// src/retransmit.ts
+var DEFAULT_BASE_URL = "https://api.retransmit.dev";
+var USER_AGENT = "retransmit.dev-node/0.1.0";
+function readEnv(name) {
+  return typeof process !== "undefined" ? process.env?.[name] : void 0;
+}
+var Retransmit = class {
+  emails = new Emails(this);
+  batch = new Batch(this);
+  apiKey;
+  baseUrl;
+  constructor(apiKey, options = {}) {
+    const key = apiKey ?? readEnv("RETRANSMIT_API_KEY");
+    if (!key) {
+      throw new Error(
+        'Missing API key. Pass it to `new Retransmit("rt_...")` or set the RETRANSMIT_API_KEY environment variable.'
+      );
+    }
+    this.apiKey = key;
+    this.baseUrl = (options.baseUrl ?? readEnv("RETRANSMIT_BASE_URL") ?? DEFAULT_BASE_URL).replace(
+      /\/+$/,
+      ""
+    );
+  }
+  /** Internal transport shared by the resource classes. API failures are returned, never thrown. */
+  async request(method, path, body) {
+    let response;
+    try {
+      response = await fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json",
+          "User-Agent": USER_AGENT
+        },
+        body: body === void 0 ? void 0 : JSON.stringify(body)
+      });
+    } catch (cause) {
+      return {
+        data: null,
+        error: {
+          code: "network_error",
+          message: cause instanceof Error ? cause.message : "Unable to reach the Retransmit API"
+        }
+      };
+    }
+    let json = null;
+    try {
+      json = await response.json();
+    } catch {
+    }
+    if (!response.ok) {
+      const error = json?.error;
+      return {
+        data: null,
+        error: error ?? {
+          code: "internal_error",
+          message: `Request failed with status ${response.status}`
+        }
+      };
+    }
+    return { data: json, error: null };
+  }
+};
+
+// src/types.ts
+var EMAIL_STATUSES = [
+  "queued",
+  "scheduled",
+  "sent",
+  "delivery_delayed",
+  "delivered",
+  "opened",
+  "clicked",
+  "bounced",
+  "complained",
+  "suppressed",
+  "canceled",
+  "rejected",
+  "failed"
+];
+export {
+  Batch,
+  EMAIL_STATUSES,
+  Emails,
+  Retransmit
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "retransmit.dev",
+  "version": "0.1.0",
+  "description": "Node.js SDK for the Retransmit email API",
+  "keywords": [
+    "email",
+    "retransmit",
+    "ses",
+    "transactional-email"
+  ],
+  "homepage": "https://retransmit.dev/docs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jpainam/retransmit.git",
+    "directory": "packages/sdk"
+  },
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "tsup": "^8.5.0",
+    "typescript": "^6.0.3",
+    "@retransmit/config": "0.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "check-types": "tsc --noEmit"
+  }
+}