@develemail/sdk 0.1.1 → 0.4.1

package/dist/index.cjs

@@ -22,53 +22,547 @@ var index_exports = {};
 __export(index_exports, {
   DevelEmail: () => DevelEmail,
   DevelEmailError: () => DevelEmailError,
+  EMAIL_EVENT_TYPES: () => EMAIL_EVENT_TYPES,
+  EMAIL_STATUSES: () => EMAIL_STATUSES,
+  SMS_STATUSES: () => SMS_STATUSES,
   verifyWebhookSignature: () => verifyWebhookSignature
 });
 module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
 var DevelEmailError = class extends Error {
-  constructor(status, message) {
+  constructor(status, message, code, details) {
     super(message);
     this.status = status;
+    this.code = code;
+    this.details = details;
     this.name = "DevelEmailError";
   }
   status;
+  code;
+  details;
 };
-var EmailsNamespace = class {
+
+// src/client.ts
+var DEFAULT_MAX_RETRIES = 3;
+var BASE_DELAY_MS = 500;
+var MAX_DELAY_MS = 3e4;
+var MAX_RETRY_AFTER_MS = 1e4;
+var CONFLICT_RETRY_DELAY_MS = 1e3;
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isRetryable(status) {
+  return status >= 500 || status === 429;
+}
+function isIdempotencyConflict(status, code) {
+  return status === 409 && code === "idempotency_conflict";
+}
+function parseRetryAfterMs(header) {
+  if (!header) return null;
+  const seconds = Number(header);
+  if (!Number.isFinite(seconds) || seconds < 0) return null;
+  return Math.min(seconds * 1e3, MAX_RETRY_AFTER_MS);
+}
+function parseErrorBody(body) {
+  if (typeof body === "object" && body !== null) {
+    const b = body;
+    const { message, error, statusCode, ...rest } = b;
+    const code = typeof b.code === "string" ? b.code : typeof error === "string" ? error : void 0;
+    return {
+      message: typeof message === "string" ? message : "Unknown error",
+      code,
+      details: Object.keys(rest).length > 0 ? rest : void 0
+    };
+  }
+  return { message: "Unknown error" };
+}
+var HttpClient = class {
+  baseUrl;
+  apiKey;
+  maxRetries;
   constructor(config) {
-    this.config = config;
+    this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+    this.apiKey = config.apiKey;
+    this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
   }
-  config;
-  async send(input) {
-    return this.request("POST", "/v1/emails", input);
+  async get(path) {
+    return this.request("GET", path);
   }
-  async get(id) {
-    return this.request("GET", `/v1/emails/${id}`);
+  async post(path, body, extraHeaders) {
+    return this.request("POST", path, body, extraHeaders);
+  }
+  async put(path, body, extraHeaders) {
+    return this.request("PUT", path, body, extraHeaders);
+  }
+  async patch(path, body, extraHeaders) {
+    return this.request("PATCH", path, body, extraHeaders);
+  }
+  async delete(path, extraHeaders) {
+    return this.request("DELETE", path, void 0, extraHeaders);
   }
-  async request(method, path, body) {
-    const res = await fetch(`${this.config.baseUrl}${path}`, {
+  async request(method, path, body, extraHeaders) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json",
+      ...extraHeaders
+    };
+    const init = {
       method,
-      headers: {
-        Authorization: `Bearer ${this.config.apiKey}`,
-        "Content-Type": "application/json"
-      },
+      headers,
       body: body !== void 0 ? JSON.stringify(body) : void 0
-    });
-    if (!res.ok) {
-      const data = await res.json().catch(() => ({}));
+    };
+    let lastError;
+    let retriedConflict = false;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      let res;
+      try {
+        res = await fetch(url, init);
+      } catch (err) {
+        lastError = err;
+        if (attempt < this.maxRetries) {
+          await sleep(this.backoff(attempt));
+          continue;
+        }
+        throw new DevelEmailError(
+          0,
+          err instanceof Error ? err.message : "Network error",
+          "network_error"
+        );
+      }
+      if (res.ok) {
+        if (res.status === 204) return void 0;
+        return res.json();
+      }
+      const errorBody = await res.json().catch(() => ({}));
+      const parsed = parseErrorBody(errorBody);
+      const conflictRetry = isIdempotencyConflict(res.status, parsed.code) && !retriedConflict;
+      if ((isRetryable(res.status) || conflictRetry) && attempt < this.maxRetries) {
+        if (conflictRetry) retriedConflict = true;
+        const retryAfterMs = parseRetryAfterMs(res.headers.get("Retry-After"));
+        const delay = retryAfterMs ?? (conflictRetry ? CONFLICT_RETRY_DELAY_MS : this.backoff(attempt));
+        await sleep(delay);
+        lastError = new DevelEmailError(
+          res.status,
+          parsed.message,
+          parsed.code,
+          parsed.details
+        );
+        continue;
+      }
       throw new DevelEmailError(
         res.status,
-        data.message ?? res.statusText
+        parsed.message,
+        parsed.code,
+        parsed.details
       );
     }
-    return res.json();
+    if (lastError instanceof DevelEmailError) throw lastError;
+    throw new DevelEmailError(
+      0,
+      lastError instanceof Error ? lastError.message : "Request failed",
+      "network_error"
+    );
+  }
+  backoff(attempt) {
+    const delay = BASE_DELAY_MS * 2 ** attempt;
+    const jitter = delay * 0.2 * Math.random();
+    return Math.min(delay + jitter, MAX_DELAY_MS);
   }
 };
-var DevelEmail = class {
-  emails;
-  constructor(config) {
-    this.emails = new EmailsNamespace(config);
+
+// ../core/src/reserved-domains.ts
+var RESERVED_DOMAINS = ["example.com", "example.net", "example.org"];
+var RESERVED_TLDS = [
+  "test",
+  "example",
+  "invalid",
+  "localhost",
+  "local"
+];
+function isReservedDomain(domain) {
+  const normalized = domain.trim().toLowerCase().replace(/\.$/, "");
+  if (!normalized) return false;
+  if (RESERVED_DOMAINS.includes(normalized)) return true;
+  const tld = normalized.split(".").pop() ?? "";
+  return RESERVED_TLDS.includes(tld);
+}
+
+// src/attachment-encoding.ts
+function encodeAttachmentContent(content) {
+  return typeof content === "string" ? content : Buffer.from(content).toString("base64");
+}
+function encodeAttachments(attachments) {
+  if (!attachments) return void 0;
+  return attachments.map((attachment) => ({
+    filename: attachment.filename,
+    contentType: attachment.contentType,
+    content: encodeAttachmentContent(attachment.content)
+  }));
+}
+
+// src/emails.ts
+function toWirePayload(input) {
+  return { ...input, attachments: encodeAttachments(input.attachments) };
+}
+function extractDomain(email) {
+  return email.split("@")[1] ?? "";
+}
+function reservedRecipientError(recipient) {
+  const domain = extractDomain(recipient);
+  return new DevelEmailError(
+    400,
+    `Recipient '${recipient}' uses reserved domain '${domain}', which cannot receive mail`,
+    "reserved_recipient_domain",
+    { recipient, domain }
+  );
+}
+function findReservedRecipient(input) {
+  const toAddresses = Array.isArray(input.to) ? input.to : [input.to];
+  return toAddresses.find((addr) => isReservedDomain(extractDomain(addr))) ?? null;
+}
+var Emails = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  async send(input, options) {
+    const reserved = findReservedRecipient(input);
+    if (reserved) throw reservedRecipientError(reserved);
+    const key = options?.idempotencyKey ?? crypto.randomUUID();
+    return this.http.post("/v1/emails", toWirePayload(input), {
+      "Idempotency-Key": key
+    });
+  }
+  // Rejects reserved recipients client-side but, matching the server's
+  // per-item batch semantics, does not fail the whole batch: deliverable
+  // items still go out, and each reserved item is named in `results` with
+  // an `error` instead of being silently dropped.
+  async batch(emails, options) {
+    const rejections = /* @__PURE__ */ new Map();
+    emails.forEach((email, index) => {
+      const reserved = findReservedRecipient(email);
+      if (reserved) {
+        rejections.set(index, {
+          index,
+          error: reservedRecipientError(reserved).message,
+          code: "reserved_recipient_domain"
+        });
+      }
+    });
+    const deliverable = emails.filter((_, index) => !rejections.has(index));
+    if (deliverable.length === 0) {
+      return {
+        results: emails.map((_, index) => rejections.get(index)),
+        created: 0,
+        errors: rejections.size
+      };
+    }
+    const key = options?.idempotencyKey ?? crypto.randomUUID();
+    const response = await this.http.post(
+      "/v1/emails/batch",
+      { emails: deliverable.map(toWirePayload) },
+      { "Idempotency-Key": key }
+    );
+    const results = [];
+    let sent = 0;
+    for (let index = 0; index < emails.length; index++) {
+      const rejection = rejections.get(index);
+      results.push(rejection ?? { ...response.results[sent++], index });
+    }
+    return {
+      results,
+      created: response.created,
+      errors: response.errors + rejections.size,
+      limitReached: response.limitReached
+    };
+  }
+  async get(id) {
+    return this.http.get(`/v1/emails/${encodeURIComponent(id)}`);
+  }
+};
+
+// src/domains.ts
+var Domains = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  async list() {
+    return this.http.get("/domains");
+  }
+  async get(id) {
+    return this.http.get(`/domains/${encodeURIComponent(id)}`);
+  }
+  async create(input) {
+    return this.http.post("/domains", input);
+  }
+  async delete(id) {
+    await this.http.delete(`/domains/${encodeURIComponent(id)}`);
+  }
+  async verify(id) {
+    return this.http.post(
+      `/domains/${encodeURIComponent(id)}/verify`,
+      void 0
+    );
+  }
+};
+
+// src/templates.ts
+var Templates = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  async list() {
+    return this.http.get("/templates");
+  }
+  async get(id) {
+    return this.http.get(`/templates/${encodeURIComponent(id)}`);
+  }
+  async create(input) {
+    return this.http.post("/templates", input);
+  }
+  async update(id, input) {
+    return this.http.put(
+      `/templates/${encodeURIComponent(id)}`,
+      input
+    );
+  }
+  async delete(id) {
+    await this.http.delete(`/templates/${encodeURIComponent(id)}`);
   }
 };
+
+// src/campaigns.ts
+function toQueryString(query) {
+  const params = new URLSearchParams();
+  params.set("projectId", query.projectId);
+  if (query.status) params.set("status", query.status);
+  if (query.limit !== void 0) params.set("limit", String(query.limit));
+  if (query.offset !== void 0) params.set("offset", String(query.offset));
+  return params.toString();
+}
+var Campaigns = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  async list(query) {
+    return this.http.get(`/campaigns?${toQueryString(query)}`);
+  }
+  async get(id) {
+    return this.http.get(`/campaigns/${encodeURIComponent(id)}`);
+  }
+  async create(input) {
+    return this.http.post("/campaigns", input);
+  }
+  async update(id, input) {
+    return this.http.patch(
+      `/campaigns/${encodeURIComponent(id)}`,
+      input
+    );
+  }
+  async send(id) {
+    return this.http.post(
+      `/campaigns/${encodeURIComponent(id)}/send`,
+      void 0
+    );
+  }
+  async pause(id) {
+    return this.http.post(
+      `/campaigns/${encodeURIComponent(id)}/pause`,
+      void 0
+    );
+  }
+  async resume(id) {
+    return this.http.post(
+      `/campaigns/${encodeURIComponent(id)}/resume`,
+      void 0
+    );
+  }
+  async cancel(id) {
+    return this.http.post(
+      `/campaigns/${encodeURIComponent(id)}/cancel`,
+      void 0
+    );
+  }
+  async duplicate(id) {
+    return this.http.post(
+      `/campaigns/${encodeURIComponent(id)}/duplicate`,
+      void 0
+    );
+  }
+  async delete(id) {
+    await this.http.delete(`/campaigns/${encodeURIComponent(id)}`);
+  }
+  async stats(id) {
+    return this.http.get(
+      `/campaigns/${encodeURIComponent(id)}/stats`
+    );
+  }
+  async providerStats(id) {
+    return this.http.get(
+      `/campaigns/${encodeURIComponent(id)}/provider-stats`
+    );
+  }
+};
+
+// src/contacts.ts
+function toQueryString2(query) {
+  const params = new URLSearchParams();
+  params.set("projectId", query.projectId);
+  if (query.search) params.set("search", query.search);
+  if (query.tags) {
+    const tags = query.tags.filter(Boolean);
+    if (tags.length > 0) params.set("tags", tags.join(","));
+  }
+  if (query.tagMode) params.set("tagMode", query.tagMode);
+  if (query.limit !== void 0) params.set("limit", String(query.limit));
+  if (query.offset !== void 0) params.set("offset", String(query.offset));
+  return params.toString();
+}
+var Contacts = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  async list(query) {
+    return this.http.get(
+      `/contacts?${toQueryString2(query)}`
+    );
+  }
+  async get(id) {
+    return this.http.get(`/contacts/${encodeURIComponent(id)}`);
+  }
+  async create(input) {
+    return this.http.post("/contacts", input);
+  }
+  async update(id, input) {
+    return this.http.patch(
+      `/contacts/${encodeURIComponent(id)}`,
+      input
+    );
+  }
+  async delete(id) {
+    await this.http.delete(`/contacts/${encodeURIComponent(id)}`);
+  }
+  async bulkCreate(input) {
+    return this.http.post("/contacts/bulk", input);
+  }
+  async tags(projectId) {
+    const params = new URLSearchParams();
+    params.set("projectId", projectId);
+    return this.http.get(`/contacts/tags?${params.toString()}`);
+  }
+  async lists(contactId) {
+    return this.http.get(
+      `/contacts/${encodeURIComponent(contactId)}/lists`
+    );
+  }
+  /** @deprecated Use `lists.addContacts` instead. */
+  async addToList(contactId, listId) {
+    await this.http.post(
+      `/lists/${encodeURIComponent(listId)}/contacts`,
+      { contactIds: [contactId] }
+    );
+  }
+  /** @deprecated Use `lists.removeContact` instead. */
+  async removeFromList(contactId, listId) {
+    await this.http.delete(
+      `/lists/${encodeURIComponent(listId)}/contacts/${encodeURIComponent(contactId)}`
+    );
+  }
+};
+
+// src/lists.ts
+function toQueryString3(query) {
+  const params = new URLSearchParams();
+  if (query.search) params.set("search", query.search);
+  if (query.limit !== void 0) params.set("limit", String(query.limit));
+  if (query.offset !== void 0) params.set("offset", String(query.offset));
+  return params.toString();
+}
+var Lists = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  async list(projectId) {
+    const params = new URLSearchParams();
+    params.set("projectId", projectId);
+    return this.http.get(`/lists?${params.toString()}`);
+  }
+  async get(id) {
+    return this.http.get(`/lists/${encodeURIComponent(id)}`);
+  }
+  async create(input) {
+    return this.http.post("/lists", input);
+  }
+  async update(id, input) {
+    return this.http.patch(`/lists/${encodeURIComponent(id)}`, input);
+  }
+  async delete(id) {
+    await this.http.delete(`/lists/${encodeURIComponent(id)}`);
+  }
+  async listContacts(id, query = {}) {
+    return this.http.get(
+      `/lists/${encodeURIComponent(id)}/contacts?${toQueryString3(query)}`
+    );
+  }
+  async addContacts(id, contactIds) {
+    return this.http.post(
+      `/lists/${encodeURIComponent(id)}/contacts`,
+      { contactIds }
+    );
+  }
+  async removeContact(id, contactId) {
+    await this.http.delete(
+      `/lists/${encodeURIComponent(id)}/contacts/${encodeURIComponent(contactId)}`
+    );
+  }
+};
+
+// src/sms.ts
+function toQueryString4(query) {
+  const params = new URLSearchParams();
+  if (query.status) params.set("status", query.status);
+  if (query.limit !== void 0) params.set("limit", String(query.limit));
+  if (query.cursor) params.set("cursor", query.cursor);
+  return params.toString();
+}
+var Sms = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  async send(input, options) {
+    const key = options?.idempotencyKey ?? crypto.randomUUID();
+    return this.http.post("/v1/sms", input, {
+      "Idempotency-Key": key
+    });
+  }
+  async sendBatch(messages, options) {
+    const key = options?.idempotencyKey ?? crypto.randomUUID();
+    return this.http.post(
+      "/v1/sms/batch",
+      { messages },
+      { "Idempotency-Key": key }
+    );
+  }
+  async get(id) {
+    return this.http.get(
+      `/v1/sms/${encodeURIComponent(id)}`
+    );
+  }
+  async list(query = {}) {
+    const qs = toQueryString4(query);
+    return this.http.get(`/v1/sms${qs ? `?${qs}` : ""}`);
+  }
+};
+
+// src/webhook.ts
 async function verifyWebhookSignature(payload, signature, secret) {
   const expected = signature.startsWith("sha256=") ? signature.slice(7) : signature;
   const enc = new TextEncoder();
@@ -79,7 +573,11 @@ async function verifyWebhookSignature(payload, signature, secret) {
     false,
     ["sign"]
   );
-  const mac = await globalThis.crypto.subtle.sign("HMAC", key, enc.encode(payload));
+  const mac = await globalThis.crypto.subtle.sign(
+    "HMAC",
+    key,
+    enc.encode(payload)
+  );
   const computed = Array.from(new Uint8Array(mac)).map((b) => b.toString(16).padStart(2, "0")).join("");
   if (computed.length !== expected.length) return false;
   let diff = 0;
@@ -88,10 +586,81 @@ async function verifyWebhookSignature(payload, signature, secret) {
   }
   return diff === 0;
 }
+
+// src/types/emails.ts
+var EMAIL_STATUSES = [
+  "queued",
+  "rendering",
+  "submitted_to_postfix",
+  "deferred",
+  "sent",
+  "delivered",
+  "bounced",
+  "rejected",
+  "failed",
+  "suppressed",
+  "cancelled",
+  "scheduled",
+  "quarantined",
+  "sandboxed"
+];
+var EMAIL_EVENT_TYPES = [
+  "queued",
+  "rendering_started",
+  "rendering_completed",
+  "submitted_to_postfix",
+  "deferred",
+  "sent",
+  "delivered",
+  "bounced",
+  "rejected",
+  "failed",
+  "suppressed",
+  "cancelled",
+  "retry_scheduled",
+  "open",
+  "click",
+  "quarantined"
+];
+
+// src/types/sms.ts
+var SMS_STATUSES = [
+  "queued",
+  "sending",
+  "sent",
+  "delivered",
+  "deferred",
+  "failed",
+  "suppressed"
+];
+
+// src/index.ts
+var DevelEmail = class {
+  emails;
+  domains;
+  templates;
+  campaigns;
+  contacts;
+  lists;
+  sms;
+  constructor(config) {
+    const http = new HttpClient(config);
+    this.emails = new Emails(http);
+    this.domains = new Domains(http);
+    this.templates = new Templates(http);
+    this.campaigns = new Campaigns(http);
+    this.contacts = new Contacts(http);
+    this.lists = new Lists(http);
+    this.sms = new Sms(http);
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DevelEmail,
   DevelEmailError,
+  EMAIL_EVENT_TYPES,
+  EMAIL_STATUSES,
+  SMS_STATUSES,
   verifyWebhookSignature
 });
 //# sourceMappingURL=index.cjs.map