@harleyl7/relay-email 0.3.0

package/README.md

@@ -0,0 +1,123 @@
+# @harleyl7/relay-email
+
+Server-side SDK for sending and inspecting transactional email through Relay.
+
+## Install
+
+```bash
+npm install @harleyl7/relay-email
+```
+
+## Usage
+
+```ts
+import { Relay } from "@harleyl7/relay-email";
+
+const relay = new Relay(process.env.RELAY_API_KEY!);
+
+const email = await relay.emails.send({
+  from: "noreply@client.com",
+  to: "user@example.com",
+  subject: "Welcome",
+  html: "<p>Welcome to the site.</p>",
+  text: "Welcome to the site.",
+});
+
+console.log(email.id, email.status, email.provider.messageId);
+```
+
+## Batch, List, and Retrieve
+
+```ts
+const batch = await relay.batch.send([
+  {
+    from: "noreply@client.com",
+    to: "one@example.com",
+    subject: "First message",
+    text: "Hello one",
+  },
+  {
+    from: "noreply@client.com",
+    to: "two@example.com",
+    subject: "Second message",
+    text: "Hello two",
+  },
+]);
+
+const page = await relay.emails.list({ limit: 20, status: "delivered" });
+const email = await relay.emails.get(batch.data[0].id);
+```
+
+Batch payloads are validated before sending and processed sequentially. If the email provider fails mid-request, earlier messages may already have been accepted. Use an idempotency key when retrying a batch.
+
+## Attachments
+
+```ts
+import { readFile } from "node:fs/promises";
+import { Relay } from "@harleyl7/relay-email";
+
+const relay = new Relay(process.env.RELAY_API_KEY!);
+const pdf = await readFile("./invoice.pdf");
+
+await relay.emails.send({
+  from: "billing@client.com",
+  to: "user@example.com",
+  subject: "Invoice",
+  text: "Attached is your invoice.",
+  attachments: [
+    {
+      filename: "invoice.pdf",
+      content: pdf,
+      contentType: "application/pdf",
+    },
+  ],
+});
+```
+
+## Options
+
+Relay uses `https://relay.vanillasky.dev` by default, so production sites only need `RELAY_API_KEY`. Override `baseUrl` for a preview or self-hosted Relay instance:
+
+```ts
+const relay = new Relay(process.env.RELAY_API_KEY!, {
+  baseUrl: "https://relay.vanillasky.dev",
+  timeoutMs: 30_000,
+});
+```
+
+## Error Handling
+
+```ts
+import { Relay, RelayError } from "@harleyl7/relay-email";
+
+const relay = new Relay(process.env.RELAY_API_KEY!);
+
+try {
+  await relay.emails.send({
+    from: "noreply@client.com",
+    to: "user@example.com",
+    subject: "Test",
+    text: "Hello",
+  });
+} catch (error) {
+  if (error instanceof RelayError) {
+    console.error(error.status, error.message, error.details);
+  }
+}
+```
+
+## Intended Use
+
+- server-side only
+- website backends, server actions, cron jobs, and worker processes
+- wraps Relay's send, batch, list, and retrieve endpoints
+
+## Publish
+
+This repo includes a GitHub Actions workflow to publish the public package to npm.
+
+After the workflow runs successfully, any project can install without an `.npmrc` file or registry token:
+
+```bash
+npm install @harleyl7/relay-email
+```

package/index.d.ts

@@ -0,0 +1,115 @@
+export type RelayAddress = string | string[];
+
+export type RelayAttachment = {
+  filename: string;
+  content: string | Blob | Buffer | Uint8Array | ArrayBuffer;
+  contentType?: string;
+};
+
+export type SendEmailRequest = {
+  from: string;
+  to: RelayAddress;
+  cc?: RelayAddress;
+  bcc?: RelayAddress;
+  replyTo?: RelayAddress;
+  subject: string;
+  html?: string;
+  text?: string;
+  headers?: Record<string, string>;
+  attachments?: RelayAttachment[];
+};
+
+export type SendEmailResponse = {
+  id: string;
+  object: "email";
+  createdAt: string;
+  sentAt: string | null;
+  from: string;
+  to: string[];
+  cc: string[];
+  bcc: string[];
+  replyTo: string[];
+  subject: string;
+  html: string | null;
+  text: string | null;
+  headers: Record<string, string>;
+  status: string;
+  provider: {
+    name: "ses";
+    messageId: string | null;
+  };
+};
+
+export type EmailEvent = {
+  id: string;
+  type: string;
+  createdAt: string;
+};
+
+export type EmailAttachment = {
+  id: string;
+  filename: string;
+  contentType: string;
+  sizeBytes: number;
+};
+
+export type GetEmailResponse = SendEmailResponse & {
+  events: EmailEvent[];
+  attachments: EmailAttachment[];
+};
+
+export type ListEmailsOptions = {
+  limit?: number;
+  cursor?: string;
+  status?: string;
+};
+
+export type ListEmailsResponse = {
+  object: "list";
+  data: SendEmailResponse[];
+  hasMore: boolean;
+  nextCursor: string | null;
+};
+
+export type BatchSendEmailResponse = {
+  object: "list";
+  data: SendEmailResponse[];
+};
+
+export type RelayRequestOptions = {
+  idempotencyKey?: string;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+};
+
+export type RelayOptions = {
+  baseUrl?: string;
+  timeoutMs?: number;
+  fetch?: typeof fetch;
+};
+
+export declare class RelayError extends Error {
+  status: number;
+  details: unknown;
+  constructor(message: string, options?: { status?: number; details?: unknown });
+}
+
+export declare class Relay {
+  constructor(apiKey: string, options?: RelayOptions);
+
+  emails: {
+    send: (payload: SendEmailRequest, options?: RelayRequestOptions) => Promise<SendEmailResponse>;
+    get: (id: string, options?: Omit<RelayRequestOptions, "idempotencyKey">) => Promise<GetEmailResponse>;
+    list: (
+      options?: ListEmailsOptions,
+      requestOptions?: Omit<RelayRequestOptions, "idempotencyKey">,
+    ) => Promise<ListEmailsResponse>;
+  };
+
+  batch: {
+    send: (
+      payloads: SendEmailRequest[],
+      options?: RelayRequestOptions,
+    ) => Promise<BatchSendEmailResponse>;
+  };
+}

package/index.js

@@ -0,0 +1,294 @@
+const DEFAULT_BASE_URL = "https://relay.vanillasky.dev";
+
+export class RelayError extends Error {
+  constructor(message, options = {}) {
+    super(message);
+    this.name = "RelayError";
+    this.status = options.status ?? 500;
+    this.details = options.details;
+  }
+}
+
+export class Relay {
+  constructor(apiKey, options = {}) {
+    if (!apiKey || typeof apiKey !== "string") {
+      throw new RelayError("A Relay API key is required.");
+    }
+
+    this.apiKey = apiKey;
+    this.baseUrl = normalizeBaseUrl(options.baseUrl ?? DEFAULT_BASE_URL);
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+    this.timeoutMs = options.timeoutMs ?? 30_000;
+
+    if (typeof this.fetchImpl !== "function") {
+      throw new RelayError("Global fetch is unavailable. Provide a custom fetch implementation.");
+    }
+
+    this.emails = {
+      send: (payload, requestOptions) => this.sendEmail(payload, requestOptions),
+      get: (id, requestOptions) => this.getEmail(id, requestOptions),
+      list: (options, requestOptions) => this.listEmails(options, requestOptions),
+    };
+    this.batch = {
+      send: (payloads, requestOptions) => this.sendBatch(payloads, requestOptions),
+    };
+  }
+
+  async sendEmail(payload, requestOptions = {}) {
+    validatePayload(payload);
+
+    const headers = new Headers({
+      Authorization: `Bearer ${this.apiKey}`,
+    });
+
+    let body;
+
+    if (payload.attachments?.length) {
+      body = buildMultipartBody(payload);
+    } else {
+      headers.set("Content-Type", "application/json");
+      body = JSON.stringify({
+        from: payload.from,
+        to: payload.to,
+        cc: payload.cc,
+        bcc: payload.bcc,
+        replyTo: payload.replyTo,
+        subject: payload.subject,
+        html: payload.html,
+        text: payload.text,
+        headers: payload.headers,
+      });
+    }
+
+    if (requestOptions.idempotencyKey) {
+      headers.set("Idempotency-Key", requestOptions.idempotencyKey);
+    }
+
+    return this.request("/api/emails", {
+      method: "POST",
+      headers,
+      body,
+      ...requestOptions,
+    });
+  }
+
+  async sendBatch(payloads, requestOptions = {}) {
+    if (!Array.isArray(payloads) || payloads.length === 0 || payloads.length > 100) {
+      throw new RelayError("Batch payload must contain between 1 and 100 emails.");
+    }
+
+    for (const payload of payloads) {
+      validatePayload(payload);
+      if (payload.attachments?.length) {
+        throw new RelayError("Batch sends do not support attachments. Send those emails individually.");
+      }
+    }
+
+    const headers = new Headers({
+      "Content-Type": "application/json",
+    });
+
+    if (requestOptions.idempotencyKey) {
+      headers.set("Idempotency-Key", requestOptions.idempotencyKey);
+    }
+
+    return this.request("/api/emails/batch", {
+      method: "POST",
+      headers,
+      body: JSON.stringify(payloads),
+      ...requestOptions,
+    });
+  }
+
+  async getEmail(id, requestOptions = {}) {
+    if (!id || typeof id !== "string") {
+      throw new RelayError("An email ID is required.");
+    }
+
+    return this.request(`/api/emails/${encodeURIComponent(id)}`, requestOptions);
+  }
+
+  async listEmails(options = {}, requestOptions = {}) {
+    const searchParams = new URLSearchParams();
+
+    if (options.limit !== undefined) {
+      searchParams.set("limit", String(options.limit));
+    }
+
+    if (options.cursor) {
+      searchParams.set("cursor", options.cursor);
+    }
+
+    if (options.status) {
+      searchParams.set("status", options.status);
+    }
+
+    const query = searchParams.size > 0 ? `?${searchParams.toString()}` : "";
+    return this.request(`/api/emails${query}`, requestOptions);
+  }
+
+  async request(path, options = {}) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? this.timeoutMs);
+    const headers = new Headers(options.headers);
+    headers.set("Authorization", `Bearer ${this.apiKey}`);
+
+    try {
+      const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        method: options.method ?? "GET",
+        headers,
+        body: options.body,
+        signal: options.signal ?? controller.signal,
+      });
+
+      const json = await parseJsonResponse(response);
+
+      if (!response.ok) {
+        throw new RelayError(getErrorMessage(json), {
+          status: response.status,
+          details: json,
+        });
+      }
+
+      return json;
+    } catch (error) {
+      if (error instanceof RelayError) {
+        throw error;
+      }
+
+      if (error?.name === "AbortError") {
+        throw new RelayError("Relay request timed out.", {
+          status: 408,
+        });
+      }
+
+      throw new RelayError(error instanceof Error ? error.message : "Unknown Relay error.");
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+}
+
+function getErrorMessage(response) {
+  if (typeof response?.error === "string") {
+    return response.error;
+  }
+
+  if (typeof response?.error?.message === "string") {
+    return response.error.message;
+  }
+
+  return "Relay request failed.";
+}
+
+function normalizeBaseUrl(baseUrl) {
+  return baseUrl.replace(/\/+$/, "");
+}
+
+function validatePayload(payload) {
+  if (!payload || typeof payload !== "object") {
+    throw new RelayError("Email payload must be an object.");
+  }
+
+  if (!payload.from || typeof payload.from !== "string") {
+    throw new RelayError("`from` is required.");
+  }
+
+  if (!payload.subject || typeof payload.subject !== "string") {
+    throw new RelayError("`subject` is required.");
+  }
+
+  if (!payload.html && !payload.text) {
+    throw new RelayError("Either `html` or `text` is required.");
+  }
+
+  if (
+    !payload.to ||
+    (typeof payload.to !== "string" && !Array.isArray(payload.to)) ||
+    (Array.isArray(payload.to) && payload.to.length === 0)
+  ) {
+    throw new RelayError("`to` must be a non-empty string or string array.");
+  }
+}
+
+function buildMultipartBody(payload) {
+  const formData = new FormData();
+
+  appendAddressField(formData, "from", payload.from);
+  appendAddressField(formData, "to", payload.to);
+  appendAddressField(formData, "cc", payload.cc);
+  appendAddressField(formData, "bcc", payload.bcc);
+  appendAddressField(formData, "replyTo", payload.replyTo);
+  formData.set("subject", payload.subject);
+
+  if (payload.html) {
+    formData.set("html", payload.html);
+  }
+
+  if (payload.text) {
+    formData.set("text", payload.text);
+  }
+
+  if (payload.headers) {
+    formData.set("headers", JSON.stringify(payload.headers));
+  }
+
+  for (const attachment of payload.attachments ?? []) {
+    const blob = toBlob(attachment.content, attachment.contentType);
+    formData.append("attachments", blob, attachment.filename);
+  }
+
+  return formData;
+}
+
+function appendAddressField(formData, key, value) {
+  if (!value) {
+    return;
+  }
+
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      formData.append(key, entry);
+    }
+    return;
+  }
+
+  formData.set(key, value);
+}
+
+function toBlob(content, contentType) {
+  if (content instanceof Blob) {
+    return content;
+  }
+
+  if (typeof content === "string") {
+    return new Blob([content], {
+      type: contentType ?? "text/plain",
+    });
+  }
+
+  if (content instanceof ArrayBuffer || ArrayBuffer.isView(content)) {
+    return new Blob([content], {
+      type: contentType ?? "application/octet-stream",
+    });
+  }
+
+  throw new RelayError("Unsupported attachment content. Use string, Blob, Buffer, Uint8Array, or ArrayBuffer.");
+}
+
+async function parseJsonResponse(response) {
+  const text = await response.text();
+
+  if (!text) {
+    return {};
+  }
+
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new RelayError("Relay returned a non-JSON response.", {
+      status: response.status,
+      details: text,
+    });
+  }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@harleyl7/relay-email",
+  "version": "0.3.0",
+  "description": "Server-side SDK for sending and inspecting transactional email through Relay.",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HarleyL7/relay.git",
+    "directory": "packages/relay-email"
+  },
+  "homepage": "https://github.com/HarleyL7/relay/tree/main/packages/relay-email",
+  "keywords": [
+    "relay",
+    "email",
+    "sdk",
+    "ses"
+  ]
+}