@marlinjai/mail-sdk 0.2.0

package/dist/index.mjs

@@ -0,0 +1,724 @@
+// src/client.ts
+import { HEALTH_PATH, SUBJECT_HEADER, WORKSPACE_HEADER } from "@marlinjai/mail-contract";
+
+// src/core.ts
+import {
+  AUTHORIZATION_HEADER,
+  BEARER_PREFIX,
+  ErrorBody,
+  IDEMPOTENCY_KEY_HEADER,
+  REQUEST_ID_HEADER,
+  RETRY_AFTER_HEADER,
+  USAGE_WARNING_HEADER,
+  parseUsageWarningHeader,
+  EXPORT_WARNINGS_HEADER,
+  EXPORT_WARNING_COUNT_HEADER,
+  parseExportWarningsHeader,
+  acceptsIdempotencyKey,
+  isRetryableError,
+  buildPath,
+  routes
+} from "@marlinjai/mail-contract";
+
+// src/errors.ts
+var MailApiError = class extends Error {
+  code;
+  status;
+  details;
+  requestId;
+  constructor(input) {
+    super(input.message);
+    this.name = "MailApiError";
+    this.code = input.code;
+    this.status = input.status;
+    this.details = input.details;
+    this.requestId = input.requestId ?? null;
+  }
+};
+var MailNetworkError = class extends Error {
+  cause;
+  constructor(message, cause) {
+    super(message);
+    this.name = "MailNetworkError";
+    this.cause = cause;
+  }
+};
+var MailTimeoutError = class extends Error {
+  timeoutMs;
+  constructor(timeoutMs) {
+    super(`mail service request timed out after ${timeoutMs}ms`);
+    this.name = "MailTimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+};
+var MailResponseValidationError = class extends Error {
+  operationId;
+  issues;
+  constructor(operationId, issues) {
+    super(`response for "${operationId}" did not match the mail-contract schema`);
+    this.name = "MailResponseValidationError";
+    this.operationId = operationId;
+    this.issues = issues;
+  }
+};
+
+// src/runtime.ts
+function webCrypto() {
+  const c = globalThis.crypto;
+  if (!c?.randomUUID) {
+    throw new Error(
+      "globalThis.crypto.randomUUID is not available in this runtime (Node 18 needs --experimental-global-webcrypto or Node 19+); @marlinjai/mail-sdk needs Web Crypto to mint idempotency keys"
+    );
+  }
+  return c;
+}
+function generateIdempotencyKey() {
+  return webCrypto().randomUUID();
+}
+function defaultSleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason);
+      return;
+    }
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        reject(signal.reason);
+      },
+      { once: true }
+    );
+  });
+}
+function backoffDelayMs(attempt, baseMs, maxDelayMs, random = Math.random) {
+  const exp = Math.min(maxDelayMs, baseMs * 2 ** attempt);
+  return Math.floor(random() * exp);
+}
+var MAX_RETRY_DELAY_MS = 6e4;
+function parseRetryAfterMs(header, now = Date.now) {
+  if (!header) return null;
+  const trimmed = header.trim();
+  if (/^\d+$/.test(trimmed)) {
+    return Math.min(MAX_RETRY_DELAY_MS, Number(trimmed) * 1e3);
+  }
+  const at = Date.parse(trimmed);
+  if (Number.isNaN(at)) return null;
+  const delta = at - now();
+  if (delta <= 0) return 0;
+  return Math.min(MAX_RETRY_DELAY_MS, delta);
+}
+
+// src/core.ts
+function responseMeta(response, requestId) {
+  return {
+    status: response.status,
+    requestId,
+    headers: response.headers,
+    usageWarnings: parseUsageWarningHeader(response.headers.get(USAGE_WARNING_HEADER))
+  };
+}
+var RETRY_BASE_MS = 250;
+var RETRY_MAX_MS = 8e3;
+var MAX_ERROR_TEXT_LENGTH = 2e3;
+function toQueryString(query) {
+  if (!query) return "";
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value === void 0 || value === null) continue;
+    params.set(key, String(value));
+  }
+  const s = params.toString();
+  return s.length > 0 ? `?${s}` : "";
+}
+function isCallerAbort(err, callerSignal) {
+  return callerSignal?.aborted === true && err instanceof Error && err.name === "AbortError";
+}
+async function parseErrorBody(status, text) {
+  if (text.length > 0) {
+    try {
+      const json = JSON.parse(text);
+      const parsed = ErrorBody.safeParse(json);
+      if (parsed.success) return parsed.data.error;
+    } catch {
+    }
+  }
+  const raw = text.slice(0, MAX_ERROR_TEXT_LENGTH);
+  const code = status >= 500 ? "internal_error" : "invalid_request";
+  return {
+    code,
+    message: `mail service returned ${status} with an unparseable body`,
+    details: raw.length > 0 ? { raw } : void 0
+  };
+}
+async function send(config, operationId, args, opts, accept) {
+  const route = routes[operationId];
+  const sleep = config.sleep ?? defaultSleep;
+  const path = buildPath(route.path, args.params ?? {});
+  const url = `${config.baseUrl.replace(/\/+$/, "")}${path}${toQueryString(args.query)}`;
+  const hasJsonBody = route.body !== void 0;
+  const bodyText = hasJsonBody ? JSON.stringify(args.body ?? {}) : void 0;
+  const idempotencyKey = acceptsIdempotencyKey(route) ? opts.idempotencyKey ?? generateIdempotencyKey() : void 0;
+  let lastError;
+  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
+    const timeoutController = new AbortController();
+    const timeout = setTimeout(() => timeoutController.abort(), config.timeoutMs);
+    const onCallerAbort = () => timeoutController.abort(opts.signal?.reason);
+    opts.signal?.addEventListener("abort", onCallerAbort, { once: true });
+    try {
+      const headers = {
+        ...config.authHeaders(),
+        accept
+      };
+      if (hasJsonBody) headers["content-type"] = "application/json";
+      if (idempotencyKey) headers[IDEMPOTENCY_KEY_HEADER] = idempotencyKey;
+      if (config.userAgent) headers["user-agent"] = config.userAgent;
+      let response;
+      try {
+        response = await config.fetch(url, {
+          method: route.method,
+          headers,
+          body: bodyText,
+          signal: timeoutController.signal
+        });
+      } catch (err) {
+        if (isCallerAbort(err, opts.signal)) throw err;
+        if (err instanceof Error && err.name === "AbortError") {
+          lastError = new MailTimeoutError(config.timeoutMs);
+        } else {
+          lastError = new MailNetworkError("mail service request failed before a response was received", err);
+        }
+        if (attempt < config.maxRetries) {
+          await sleep(backoffDelayMs(attempt, RETRY_BASE_MS, RETRY_MAX_MS, config.random), opts.signal);
+          continue;
+        }
+        throw lastError;
+      }
+      const requestId = response.headers.get(REQUEST_ID_HEADER);
+      if (response.status >= 200 && response.status < 300) return { response, requestId };
+      const text = await response.text();
+      const errorBody = await parseErrorBody(response.status, text);
+      const apiError = new MailApiError({
+        code: errorBody.code,
+        status: response.status,
+        message: errorBody.message,
+        details: errorBody.details,
+        requestId
+      });
+      lastError = apiError;
+      const retryable = isRetryableError(errorBody.code, errorBody.details);
+      if (retryable && attempt < config.maxRetries) {
+        const retryAfterMs = parseRetryAfterMs(response.headers.get(RETRY_AFTER_HEADER));
+        const delay = retryAfterMs ?? backoffDelayMs(attempt, RETRY_BASE_MS, RETRY_MAX_MS, config.random);
+        await sleep(delay, opts.signal);
+        continue;
+      }
+      throw apiError;
+    } finally {
+      clearTimeout(timeout);
+      opts.signal?.removeEventListener("abort", onCallerAbort);
+    }
+  }
+  throw lastError instanceof Error ? lastError : new Error("mail service request failed");
+}
+async function execute(config, operationId, args = {}, opts = {}) {
+  const route = routes[operationId];
+  if (route.responseType === "text") {
+    const file = await executeFile(config, operationId, args, opts);
+    return file.content;
+  }
+  const { response, requestId } = await send(config, operationId, args, opts, "application/json");
+  const text = await response.text();
+  const json = text.length > 0 ? JSON.parse(text) : void 0;
+  let data;
+  if (!config.validateResponses) data = json;
+  else {
+    const parsed = route.response.safeParse(json);
+    if (!parsed.success) throw new MailResponseValidationError(operationId, parsed.error.issues);
+    data = parsed.data;
+  }
+  opts.onResponse?.(responseMeta(response, requestId));
+  return data;
+}
+function dispositionFilename(value) {
+  if (!value) return null;
+  const extended = /filename\*\s*=\s*UTF-8''([^;]+)/i.exec(value);
+  if (extended) {
+    try {
+      return decodeURIComponent(extended[1].trim());
+    } catch {
+    }
+  }
+  const plain = /filename\s*=\s*"([^"]*)"|filename\s*=\s*([^;\s]+)/i.exec(value);
+  return plain ? plain[1] ?? plain[2] ?? null : null;
+}
+async function executeFile(config, operationId, args = {}, opts = {}) {
+  const route = routes[operationId];
+  if (route.responseType !== "text") throw new Error(`"${operationId}" answers with JSON: use execute`);
+  const { response, requestId } = await send(config, operationId, args, opts, "text/html, text/plain, */*");
+  const content = await response.text();
+  const warnings = parseExportWarningsHeader(response.headers.get(EXPORT_WARNINGS_HEADER));
+  const count = Number(response.headers.get(EXPORT_WARNING_COUNT_HEADER));
+  const file = {
+    content,
+    contentType: response.headers.get("content-type") ?? "application/octet-stream",
+    filename: dispositionFilename(response.headers.get("content-disposition")) ?? "export",
+    warnings,
+    warningCount: Number.isInteger(count) && count >= warnings.length ? count : warnings.length,
+    requestId
+  };
+  opts.onResponse?.(responseMeta(response, requestId));
+  return file;
+}
+async function executeMultipart(config, operationId, args, opts = {}) {
+  const route = routes[operationId];
+  if (!route.multipart) throw new Error(`"${operationId}" is not a multipart route`);
+  const sleep = config.sleep ?? defaultSleep;
+  const path = buildPath(route.path, args.params ?? {});
+  const url = `${config.baseUrl.replace(/\/+$/, "")}${path}`;
+  const idempotencyKey = acceptsIdempotencyKey(route) ? opts.idempotencyKey ?? generateIdempotencyKey() : void 0;
+  let lastError;
+  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
+    const timeoutController = new AbortController();
+    const timeout = setTimeout(() => timeoutController.abort(), config.timeoutMs);
+    const onCallerAbort = () => timeoutController.abort(opts.signal?.reason);
+    opts.signal?.addEventListener("abort", onCallerAbort, { once: true });
+    try {
+      const form = new FormData();
+      form.set(route.multipart.fileField, args.file, args.filename);
+      if (route.multipart.jsonField) {
+        form.set(route.multipart.jsonField, JSON.stringify(args.json ?? {}));
+      }
+      const headers = { ...config.authHeaders(), accept: "application/json" };
+      if (idempotencyKey) headers[IDEMPOTENCY_KEY_HEADER] = idempotencyKey;
+      if (config.userAgent) headers["user-agent"] = config.userAgent;
+      let response;
+      try {
+        response = await config.fetch(url, { method: route.method, headers, body: form, signal: timeoutController.signal });
+      } catch (err) {
+        if (isCallerAbort(err, opts.signal)) throw err;
+        if (err instanceof Error && err.name === "AbortError") {
+          lastError = new MailTimeoutError(config.timeoutMs);
+        } else {
+          lastError = new MailNetworkError("mail service request failed before a response was received", err);
+        }
+        if (attempt < config.maxRetries) {
+          await sleep(backoffDelayMs(attempt, RETRY_BASE_MS, RETRY_MAX_MS, config.random), opts.signal);
+          continue;
+        }
+        throw lastError;
+      }
+      const requestId = response.headers.get(REQUEST_ID_HEADER);
+      if (response.status >= 200 && response.status < 300) {
+        const text2 = await response.text();
+        const json = text2.length > 0 ? JSON.parse(text2) : void 0;
+        let data;
+        if (!config.validateResponses) data = json;
+        else {
+          const parsed = route.response.safeParse(json);
+          if (!parsed.success) throw new MailResponseValidationError(operationId, parsed.error.issues);
+          data = parsed.data;
+        }
+        opts.onResponse?.(responseMeta(response, requestId));
+        return data;
+      }
+      const text = await response.text();
+      const errorBody = await parseErrorBody(response.status, text);
+      const apiError = new MailApiError({
+        code: errorBody.code,
+        status: response.status,
+        message: errorBody.message,
+        details: errorBody.details,
+        requestId
+      });
+      lastError = apiError;
+      const retryable = isRetryableError(errorBody.code, errorBody.details);
+      if (retryable && attempt < config.maxRetries) {
+        const retryAfterMs = parseRetryAfterMs(response.headers.get(RETRY_AFTER_HEADER));
+        const delay = retryAfterMs ?? backoffDelayMs(attempt, RETRY_BASE_MS, RETRY_MAX_MS, config.random);
+        await sleep(delay, opts.signal);
+        continue;
+      }
+      throw apiError;
+    } finally {
+      clearTimeout(timeout);
+      opts.signal?.removeEventListener("abort", onCallerAbort);
+    }
+  }
+  throw lastError instanceof Error ? lastError : new Error("mail service request failed");
+}
+function buildAuthorizationHeader(token) {
+  return { [AUTHORIZATION_HEADER]: `${BEARER_PREFIX}${token}` };
+}
+
+// src/namespaces.ts
+function createNamespaces(config) {
+  return {
+    /**
+     * `workspaces` (plural) is the dashboard-only pair for a person with no
+     * workspace context yet: creating one, and listing the ones they belong to.
+     * `workspace` (singular, below) is the ordinary per-workspace read/update,
+     * reachable with a workspace API key or a dashboard call already bound to one.
+     */
+    workspaces: {
+      create: (body, opts) => execute(config, "workspaces.create", { body }, opts),
+      list: (query, opts) => execute(config, "workspaces.list", { query }, opts)
+    },
+    workspace: {
+      get: (opts) => execute(config, "workspace.get", {}, opts),
+      update: (body, opts) => execute(config, "workspace.update", { body }, opts),
+      /**
+       * Hands the workspace to another auth-brain company (owner only, and a
+       * workspace API key is refused outright). What changes is whose erasure
+       * takes the workspace with it, nothing about billing or who may sign in.
+       */
+      move: (body, opts) => execute(config, "workspace.move", { body }, opts)
+    },
+    members: {
+      list: (query, opts) => execute(config, "members.list", { query }, opts),
+      /**
+       * The service binds people by auth-brain subject only (it never sees a
+       * login), so the caller resolves the person first and sends the subject
+       * with their email and name.
+       */
+      add: (body, opts) => execute(config, "members.add", { body }, opts),
+      update: (id, body, opts) => execute(config, "members.update", { params: { id }, body }, opts),
+      remove: (id, opts) => execute(config, "members.remove", { params: { id } }, opts)
+    },
+    /**
+     * Invitations: an admin invites an address with a role (the token is in
+     * the create response only); the invited person accepts through the
+     * dashboard (`accept` is dashboard-only and names the signed-in person).
+     */
+    invites: {
+      create: (body, opts) => execute(config, "invites.create", { body }, opts),
+      list: (query, opts) => execute(config, "invites.list", { query }, opts),
+      revoke: (id, opts) => execute(config, "invites.revoke", { params: { id } }, opts),
+      accept: (body, opts) => execute(config, "invites.accept", { body }, opts)
+    },
+    apiKeys: {
+      list: (query, opts) => execute(config, "apiKeys.list", { query }, opts),
+      create: (body, opts) => execute(config, "apiKeys.create", { body }, opts),
+      revoke: (id, opts) => execute(config, "apiKeys.revoke", { params: { id } }, opts)
+    },
+    auditLog: {
+      list: (query, opts) => execute(config, "audit.list", { query }, opts)
+    },
+    templates: {
+      list: (query, opts) => execute(config, "templates.list", { query }, opts),
+      create: (body, opts) => execute(config, "templates.create", { body }, opts),
+      get: (id, opts) => execute(config, "templates.get", { params: { id } }, opts),
+      update: (id, body, opts) => execute(config, "templates.update", { params: { id }, body }, opts),
+      delete: (id, opts) => execute(config, "templates.delete", { params: { id } }, opts),
+      versions: (id, query, opts) => execute(config, "templates.versions", { params: { id }, query }, opts),
+      version: (id, version, opts) => execute(config, "templates.version", { params: { id, version } }, opts),
+      compile: (id, body = {}, opts) => execute(config, "templates.compile", { params: { id }, body }, opts),
+      /**
+       * Creates a template (version 1) from MJML. What the editor cannot hold
+       * as a block is kept as compiled HTML and reported in `warnings`; broken
+       * MJML is `invalid_mjml` with the line and column in `details`.
+       */
+      import: (body, opts) => execute(config, "templates.import", { body }, opts),
+      /** What `import` would create, compiled, without saving anything. */
+      importPreview: (body, opts) => execute(config, "templates.importPreview", { body }, opts),
+      /**
+       * The template (or a past `version`) as an `.mjml` or `.html` file, asset
+       * addresses absolute. Never refused for the asset policy: see `warnings`.
+       */
+      export: (id, query, opts) => executeFile(config, "templates.export", { params: { id }, query }, opts)
+    },
+    /**
+     * Saved sections: one section of a document kept under a name, so a footer
+     * built once can be dropped into any other template of the workspace.
+     *
+     * A stamp, not a live partial: inserting copies, and `update` overwriting
+     * the saved copy leaves every template that already holds one untouched.
+     * A workspace keeps at most `MAX_SAVED_SECTIONS` of them, and a name is
+     * unique within it, so a duplicate is `already_exists` rather than a
+     * silent overwrite.
+     */
+    savedSections: {
+      list: (query, opts) => execute(config, "savedSections.list", { query }, opts),
+      create: (body, opts) => execute(config, "savedSections.create", { body }, opts),
+      update: (id, body, opts) => execute(config, "savedSections.update", { params: { id }, body }, opts),
+      delete: (id, opts) => execute(config, "savedSections.delete", { params: { id } }, opts)
+    },
+    /** Compiles an unsaved document (the editor's live preview), not a saved template. */
+    compile: (body, opts) => execute(config, "compile", { body }, opts),
+    assets: {
+      /** `file` must be a `Blob` (edge-safe): wrap a Node `Buffer` with `new Blob([buffer])`. */
+      upload: (file, filename, opts) => executeMultipart(config, "assets.upload", { file, filename }, opts),
+      /**
+       * Copies a remote image into the workspace's assets and answers with the
+       * new asset, whose `url` is the service's own. The workspace setting
+       * `asset_policy: 'service_only'` accepts only such addresses in a mail.
+       */
+      import: (body, opts) => execute(config, "assets.import", { body }, opts),
+      get: (id, opts) => execute(config, "assets.get", { params: { id } }, opts)
+    },
+    providers: {
+      list: (query, opts) => execute(config, "providers.list", { query }, opts),
+      create: (body, opts) => execute(config, "providers.create", { body }, opts),
+      get: (id, opts) => execute(config, "providers.get", { params: { id } }, opts),
+      update: (id, body, opts) => execute(config, "providers.update", { params: { id }, body }, opts),
+      delete: (id, opts) => execute(config, "providers.delete", { params: { id } }, opts),
+      verify: (id, opts) => execute(config, "providers.verify", { params: { id } }, opts),
+      usage: (id, opts) => execute(config, "providers.usage", { params: { id } }, opts),
+      /** Clears the provider's bounce anomaly, reopening bounce blocking, test sends and mailing starts. */
+      clearAnomaly: (id, opts) => execute(config, "providers.clearAnomaly", { params: { id } }, opts),
+      /** Stores the signing secret of a Resend webhook registered by hand, so bounces and complaints are accepted. */
+      setEventsSecret: (id, body, opts) => execute(config, "providers.setEventsSecret", { params: { id }, body }, opts)
+    },
+    topics: {
+      list: (query, opts) => execute(config, "topics.list", { query }, opts),
+      create: (body, opts) => execute(config, "topics.create", { body }, opts),
+      update: (id, body, opts) => execute(config, "topics.update", { params: { id }, body }, opts)
+    },
+    contacts: {
+      upsert: (body, opts) => execute(config, "contacts.upsert", { body }, opts),
+      list: (query, opts) => execute(config, "contacts.list", { query }, opts),
+      get: (id, opts) => execute(config, "contacts.get", { params: { id } }, opts),
+      erase: (id, opts) => execute(config, "contacts.erase", { params: { id } }, opts),
+      messages: (id, query, opts) => execute(config, "contacts.messages", { params: { id }, query }, opts),
+      /** Every automation this person has been through, for the contact's own page. */
+      automations: (id, query, opts) => execute(config, "contacts.automations", { params: { id }, query }, opts)
+    },
+    suppressions: {
+      list: (query, opts) => execute(config, "suppressions.list", { query }, opts),
+      create: (body, opts) => execute(config, "suppressions.create", { body }, opts),
+      delete: (id, opts) => execute(config, "suppressions.delete", { params: { id } }, opts)
+    },
+    mailings: {
+      list: (query, opts) => execute(config, "mailings.list", { query }, opts),
+      create: (body, opts) => execute(config, "mailings.create", { body }, opts),
+      get: (id, opts) => execute(config, "mailings.get", { params: { id } }, opts),
+      /** The mailing's content snapshot as an `.mjml` or `.html` file, like `templates.export`. */
+      export: (id, query, opts) => executeFile(config, "mailings.export", { params: { id }, query }, opts),
+      update: (id, body, opts) => execute(config, "mailings.update", { params: { id }, body }, opts),
+      addRecipients: (id, body, opts) => execute(config, "mailings.addRecipients", { params: { id }, body }, opts),
+      listRecipients: (id, query, opts) => execute(config, "mailings.listRecipients", { params: { id }, query }, opts),
+      test: (id, body, opts) => execute(config, "mailings.test", { params: { id }, body }, opts),
+      send: (id, opts) => execute(config, "mailings.send", { params: { id }, body: {} }, opts),
+      pause: (id, opts) => execute(config, "mailings.pause", { params: { id }, body: {} }, opts),
+      resume: (id, opts) => execute(config, "mailings.resume", { params: { id }, body: {} }, opts),
+      cancel: (id, opts) => execute(config, "mailings.cancel", { params: { id }, body: {} }, opts),
+      retryFailed: (id, body = {}, opts) => execute(config, "mailings.retryFailed", { params: { id }, body }, opts),
+      duplicate: (id, opts) => execute(config, "mailings.duplicate", { params: { id }, body: {} }, opts),
+      // S4: scheduling, segments and A/B testing
+      addSegment: (id, body, opts) => execute(config, "mailings.addSegment", { params: { id }, body }, opts),
+      schedule: (id, body, opts) => execute(config, "mailings.schedule", { params: { id }, body }, opts),
+      unschedule: (id, opts) => execute(config, "mailings.unschedule", { params: { id }, body: {} }, opts),
+      setAbTest: (id, body, opts) => execute(config, "mailings.setAbTest", { params: { id }, body }, opts),
+      clearAbTest: (id, opts) => execute(config, "mailings.clearAbTest", { params: { id } }, opts),
+      pickAbWinner: (id, body, opts) => execute(config, "mailings.pickAbWinner", { params: { id }, body }, opts),
+      analytics: (id, opts) => execute(config, "mailings.analytics", { params: { id } }, opts)
+    },
+    messages: {
+      list: (query, opts) => execute(config, "messages.list", { query }, opts),
+      get: (id, opts) => execute(config, "messages.get", { params: { id } }, opts)
+    },
+    webhooks: {
+      list: (query, opts) => execute(config, "webhooks.list", { query }, opts),
+      create: (body, opts) => execute(config, "webhooks.create", { body }, opts),
+      get: (id, opts) => execute(config, "webhooks.get", { params: { id } }, opts),
+      update: (id, body, opts) => execute(config, "webhooks.update", { params: { id }, body }, opts),
+      delete: (id, opts) => execute(config, "webhooks.delete", { params: { id } }, opts),
+      rotateSecret: (id, opts) => execute(config, "webhooks.rotateSecret", { params: { id } }, opts),
+      deliveries: (id, query, opts) => execute(config, "webhooks.deliveries", { params: { id }, query }, opts),
+      redeliver: (id, deliveryId, opts) => execute(config, "webhooks.redeliver", { params: { id, delivery_id: deliveryId } }, opts)
+    },
+    // S4: the platform features.
+    tags: {
+      list: (query, opts) => execute(config, "tags.list", { query }, opts),
+      create: (body, opts) => execute(config, "tags.create", { body }, opts),
+      delete: (id, opts) => execute(config, "tags.delete", { params: { id } }, opts),
+      assign: (id, body, opts) => execute(config, "tags.assign", { params: { id }, body }, opts),
+      unassign: (id, body, opts) => execute(config, "tags.unassign", { params: { id }, body }, opts)
+    },
+    segments: {
+      list: (query, opts) => execute(config, "segments.list", { query }, opts),
+      create: (body, opts) => execute(config, "segments.create", { body }, opts),
+      /** Counts what a filter matches, without saving it. */
+      preview: (body, opts) => execute(config, "segments.preview", { body }, opts),
+      get: (id, opts) => execute(config, "segments.get", { params: { id } }, opts),
+      update: (id, body, opts) => execute(config, "segments.update", { params: { id }, body }, opts),
+      delete: (id, opts) => execute(config, "segments.delete", { params: { id } }, opts)
+    },
+    signupForms: {
+      list: (query, opts) => execute(config, "signupForms.list", { query }, opts),
+      create: (body, opts) => execute(config, "signupForms.create", { body }, opts),
+      get: (id, opts) => execute(config, "signupForms.get", { params: { id } }, opts),
+      embed: (id, opts) => execute(config, "signupForms.embed", { params: { id } }, opts),
+      update: (id, body, opts) => execute(config, "signupForms.update", { params: { id }, body }, opts),
+      delete: (id, opts) => execute(config, "signupForms.delete", { params: { id } }, opts),
+      /** The public submission route: usable without a workspace key in a browser form handler. */
+      submit: (id, body, opts) => execute(config, "signupForms.submit", { params: { id }, body }, opts)
+    },
+    imports: {
+      /** Step 1: upload the CSV. The answer carries its columns, a sample and a suggested mapping. */
+      create: (file, filename, opts) => executeMultipart(config, "imports.create", { file, filename }, opts),
+      list: (query, opts) => execute(config, "imports.list", { query }, opts),
+      get: (id, opts) => execute(config, "imports.get", { params: { id } }, opts),
+      /** Step 2: set (or revise) the mapping; the dry run starts, and any earlier one is discarded. */
+      setMapping: (id, body, opts) => execute(config, "imports.setMapping", { params: { id }, body }, opts),
+      /** Step 3: commit the dry run of `mapping_version`. */
+      commit: (id, body, opts) => execute(config, "imports.commit", { params: { id }, body }, opts),
+      cancel: (id, opts) => execute(config, "imports.cancel", { params: { id }, body: {} }, opts),
+      rows: (id, query, opts) => execute(config, "imports.rows", { params: { id }, query }, opts)
+    },
+    tracking: {
+      get: (opts) => execute(config, "tracking.get", {}, opts),
+      update: (body, opts) => execute(config, "tracking.update", { body }, opts)
+    },
+    contactProperties: {
+      list: (opts) => execute(config, "contactProperties.list", {}, opts),
+      create: (body, opts) => execute(config, "contactProperties.create", { body }, opts),
+      delete: (key, opts) => execute(config, "contactProperties.delete", { params: { key } }, opts)
+    },
+    // S5: billing.
+    billing: {
+      plans: (opts) => execute(config, "billing.plans", {}, opts),
+      subscription: (opts) => execute(config, "billing.subscription", {}, opts),
+      usage: (opts) => execute(config, "billing.usage", {}, opts),
+      checkout: (body, opts) => execute(config, "billing.checkout", { body }, opts),
+      portal: (body, opts) => execute(config, "billing.portal", { body }, opts)
+    },
+    // A1: automations.
+    automations: {
+      list: (query, opts) => execute(config, "automations.list", { query }, opts),
+      create: (body, opts) => execute(config, "automations.create", { body }, opts),
+      get: (id, opts) => execute(config, "automations.get", { params: { id } }, opts),
+      /** Saves the draft. `base_version` is the draft version you loaded; a stale one is `conflict` (409). */
+      update: (id, body, opts) => execute(config, "automations.update", { params: { id }, body }, opts),
+      delete: (id, opts) => execute(config, "automations.delete", { params: { id } }, opts),
+      /** Every problem that stops the draft from being published, with nothing saved. */
+      validate: (id, body, opts) => execute(config, "automations.validate", { params: { id }, body: body ?? {} }, opts),
+      /**
+       * Publishes the draft. On a live automation the first call answers
+       * `published: false` with the people who would have to move; call again
+       * with `confirm: true` to go ahead.
+       */
+      publish: (id, body, opts) => execute(config, "automations.publish", { params: { id }, body: body ?? {} }, opts),
+      pause: (id, opts) => execute(config, "automations.pause", { params: { id }, body: {} }, opts),
+      resume: (id, opts) => execute(config, "automations.resume", { params: { id }, body: {} }, opts),
+      archive: (id, opts) => execute(config, "automations.archive", { params: { id }, body: {} }, opts),
+      duplicate: (id, body, opts) => execute(config, "automations.duplicate", { params: { id }, body: body ?? {} }, opts),
+      /** Enters people by hand; each answer says entered, or refused with the reason. */
+      enroll: (id, body, opts) => execute(config, "automations.enroll", { params: { id }, body }, opts),
+      testEmail: (id, stepId, body, opts) => execute(config, "automations.testEmail", { params: { id, step_id: stepId }, body }, opts),
+      runs: (id, query, opts) => execute(config, "automations.runs", { params: { id }, query }, opts),
+      /** One person's journey, step by step. */
+      run: (id, runId, opts) => execute(config, "automations.run", { params: { id, run_id: runId } }, opts),
+      exitRun: (id, runId, body, opts) => execute(config, "automations.exitRun", { params: { id, run_id: runId }, body: body ?? {} }, opts),
+      report: (id, opts) => execute(config, "automations.report", { params: { id } }, opts)
+    },
+    events: {
+      /** Tells the service something happened, so the automations waiting for it enter this person. */
+      create: (body, opts) => execute(config, "events.create", { body }, opts),
+      list: (query, opts) => execute(config, "events.list", { query }, opts)
+    }
+  };
+}
+
+// src/pagination.ts
+async function* paginate(config, operationId, args = {}, opts = {}) {
+  let cursor = args.query?.cursor;
+  const seenCursors = /* @__PURE__ */ new Set();
+  for (; ; ) {
+    const query = { ...args.query, cursor };
+    const result = await execute(config, operationId, { params: args.params, query }, opts);
+    const page = result;
+    for (const item of page.data) yield item;
+    if (page.next_cursor === null) return;
+    if (seenCursors.has(page.next_cursor)) {
+      throw new Error(`mail service returned a repeated pagination cursor for "${operationId}"`);
+    }
+    seenCursors.add(page.next_cursor);
+    cursor = page.next_cursor;
+  }
+}
+
+// src/client.ts
+var DEFAULT_TIMEOUT_MS = 1e4;
+var DEFAULT_MAX_RETRIES = 3;
+function resolveFetch(provided) {
+  const impl = provided ?? (typeof fetch === "function" ? fetch : void 0);
+  if (!impl) {
+    throw new Error(
+      "@marlinjai/mail-sdk needs a `fetch` implementation: none was given and none is global in this runtime (Node 18+ and every edge runtime provide one; pass `fetch` explicitly otherwise)"
+    );
+  }
+  return impl.bind(globalThis);
+}
+function buildConfig(options, authHeaders) {
+  if (options.baseUrl.trim().length === 0) throw new Error("createMailClient requires a non-empty baseUrl");
+  return {
+    baseUrl: options.baseUrl,
+    authHeaders,
+    fetch: resolveFetch(options.fetch),
+    timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    maxRetries: options.maxRetries ?? DEFAULT_MAX_RETRIES,
+    userAgent: options.userAgent,
+    validateResponses: options.validateResponses ?? true,
+    sleep: options.__sleep,
+    random: options.__random
+  };
+}
+async function checkHealth(config, opts) {
+  try {
+    const response = await config.fetch(`${config.baseUrl.replace(/\/+$/, "")}${HEALTH_PATH}`, {
+      method: "GET",
+      signal: opts?.signal
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+function buildClient(config) {
+  return {
+    ...createNamespaces(config),
+    request: (operationId, args, opts) => execute(config, operationId, args ?? {}, opts),
+    paginate: (operationId, args, opts) => paginate(config, operationId, args ?? {}, opts),
+    health: (opts) => checkHealth(config, opts)
+  };
+}
+function createMailClient(options) {
+  const config = buildConfig(options, () => buildAuthorizationHeader(options.apiKey));
+  return buildClient(config);
+}
+function assertServerSide() {
+  const hasWindow = typeof globalThis === "object" && "window" in globalThis && globalThis.window !== void 0;
+  if (hasWindow) {
+    throw new Error(
+      "createDashboardMailClient must never run in a browser: its service token authenticates as the whole dashboard, not one signed-in person, and a browser bundle would ship it to every visitor. Call it only from server-side code (a Next.js server action, route handler or server component) and pass the signed-in person to forUser() per request."
+    );
+  }
+}
+function createDashboardMailClient(options) {
+  assertServerSide();
+  return {
+    forUser(user) {
+      const config = buildConfig(options, () => ({
+        ...buildAuthorizationHeader(options.serviceToken),
+        [SUBJECT_HEADER]: user.subject,
+        ...user.workspaceId ? { [WORKSPACE_HEADER]: user.workspaceId } : {}
+      }));
+      return buildClient(config);
+    }
+  };
+}
+
+// src/index.ts
+export * from "@marlinjai/mail-contract";
+export {
+  MailApiError,
+  MailNetworkError,
+  MailResponseValidationError,
+  MailTimeoutError,
+  createDashboardMailClient,
+  createMailClient,
+  dispositionFilename,
+  generateIdempotencyKey
+};