shipmail 0.1.5 → 0.1.20

package/README.md

@@ -1,6 +1,6 @@
 # ShipMail TypeScript SDK
 
-Official TypeScript SDK for the [ShipMail](https://shipmail.to) API. Zero runtime dependencies. Works with Node.js 20+, Bun, and Deno.
+Official TypeScript SDK for the [ShipMail](https://shipmail.to) API. Zero runtime dependencies. Works with Node.js 18+, Bun, and Deno.
 
 ## Installation
 
@@ -38,7 +38,7 @@ import { ShipMailClient } from "shipmail";
 
 const client = new ShipMailClient({
   apiKey: "sm_live_...",
-  baseUrl: "https://api.shipmail.to/v1", // default
+  baseUrl: "https://shipmail.to/api/v1", // default
   maxRetries: 2, // default, retries on 5xx and 429
   timeout: 30_000, // default, in milliseconds
 });
@@ -69,10 +69,6 @@ const mailboxes = await client.mailboxes.list({ domain_id: "dom_..." });
 const mailbox = await client.mailboxes.get("mbx_...");
 const updated = await client.mailboxes.update("mbx_...", { display_name: "New Name" });
 await client.mailboxes.delete("mbx_...");
-
-// Avatar
-const avatar = await client.mailboxes.uploadAvatar("mbx_...", imageBuffer, "image/png");
-await client.mailboxes.deleteAvatar("mbx_...");
 ```
 
 ### Messages
@@ -161,7 +157,7 @@ Verify incoming webhook signatures without instantiating a client:
 import { verifyWebhook, WebhookVerificationError } from "shipmail";
 
 try {
-  const event = verifyWebhook(rawBody, request.headers, webhookSecret);
+  const event = await verifyWebhook(rawBody, request.headers, webhookSecret);
   console.log(event.event_type); // e.g., "message.received"
   console.log(event.data);
 } catch (err) {

package/dist/index.cjs

@@ -2,8 +2,6 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var crypto = require('crypto');
-
 // src/errors.ts
 var ShipMailError = class extends Error {
   constructor(message, options) {
@@ -39,6 +37,12 @@ var ValidationError = class extends ShipMailError {
     this.details = options?.details;
   }
 };
+var QuotaExceededError = class extends ShipMailError {
+  constructor(message, requestId) {
+    super(message, { status: 403, type: "quota_exceeded", requestId, retryable: false });
+    this.name = "QuotaExceededError";
+  }
+};
 var NotFoundError = class extends ShipMailError {
   constructor(message, requestId) {
     super(message, { status: 404, type: "not_found", requestId, retryable: false });
@@ -89,6 +93,8 @@ function mapErrorFromResponse(status, body, requestId) {
       return new AuthenticationError(error.message, rid);
     case "authorization_error":
       return new AuthorizationError(error.message, rid);
+    case "quota_exceeded":
+      return new QuotaExceededError(error.message, rid);
     case "validation_error":
       return new ValidationError(error.message, { requestId: rid, details: error.details });
     case "not_found":
@@ -142,21 +148,23 @@ var ApiResource = class {
 
 // src/resources/domains.ts
 var Domains = class extends ApiResource {
-  create(params) {
+  create(params, options) {
     return this.client.request({
       method: "POST",
       path: "/domains",
-      body: params
+      body: params,
+      methodOptions: options
     });
   }
-  list(params) {
+  list(params, options) {
     return this.client.request({
       method: "GET",
       path: "/domains",
       query: {
         cursor: params?.cursor,
         limit: params?.limit
-      }
+      },
+      methodOptions: options
     });
   }
   listAutoPaginating(params) {
@@ -164,43 +172,64 @@ var Domains = class extends ApiResource {
       limit: params?.limit
     });
   }
-  get(id) {
+  get(id, options) {
     return this.client.request({
       method: "GET",
-      path: `/domains/${id}`
+      path: `/domains/${encodeURIComponent(id)}`,
+      methodOptions: options
     });
   }
-  update(id, params) {
+  update(id, params, options) {
     return this.client.request({
       method: "PATCH",
-      path: `/domains/${id}`,
-      body: params
+      path: `/domains/${encodeURIComponent(id)}`,
+      body: params,
+      methodOptions: options
     });
   }
-  delete(id) {
+  delete(id, options) {
     return this.client.request({
       method: "DELETE",
-      path: `/domains/${id}`
+      path: `/domains/${encodeURIComponent(id)}`,
+      methodOptions: options
+    });
+  }
+  verify(id, options) {
+    return this.client.request({
+      method: "POST",
+      path: `/domains/${encodeURIComponent(id)}/verification`,
+      methodOptions: options
     });
   }
-  verify(id) {
+  search(params, options) {
     return this.client.request({
       method: "POST",
-      path: `/domains/${id}/verification`
+      path: "/domains/search",
+      body: params,
+      methodOptions: options
+    });
+  }
+  register(params, options) {
+    return this.client.request({
+      method: "POST",
+      path: "/domains/register",
+      body: params,
+      methodOptions: options
     });
   }
 };
 
 // src/resources/mailboxes.ts
 var Mailboxes = class extends ApiResource {
-  create(params) {
+  create(params, options) {
     return this.client.request({
       method: "POST",
       path: "/mailboxes",
-      body: params
+      body: params,
+      methodOptions: options
     });
   }
-  list(params) {
+  list(params, options) {
     return this.client.request({
       method: "GET",
       path: "/mailboxes",
@@ -208,7 +237,8 @@ var Mailboxes = class extends ApiResource {
         domain_id: params?.domain_id,
         cursor: params?.cursor,
         limit: params?.limit
-      }
+      },
+      methodOptions: options
     });
   }
   listAutoPaginating(params) {
@@ -217,71 +247,124 @@ var Mailboxes = class extends ApiResource {
       limit: params?.limit
     });
   }
-  get(id) {
+  get(id, options) {
     return this.client.request({
       method: "GET",
-      path: `/mailboxes/${id}`
+      path: `/mailboxes/${encodeURIComponent(id)}`,
+      methodOptions: options
     });
   }
-  update(id, params) {
+  update(id, params, options) {
     return this.client.request({
       method: "PATCH",
-      path: `/mailboxes/${id}`,
-      body: params
+      path: `/mailboxes/${encodeURIComponent(id)}`,
+      body: params,
+      methodOptions: options
     });
   }
-  delete(id) {
+  delete(id, options) {
     return this.client.request({
       method: "DELETE",
-      path: `/mailboxes/${id}`
-    });
-  }
-  uploadAvatar(id, data, contentType) {
-    return this.client.request({
-      method: "PUT",
-      path: `/mailboxes/${id}/avatar`,
-      rawBody: data,
-      contentType
+      path: `/mailboxes/${encodeURIComponent(id)}`,
+      methodOptions: options
     });
   }
-  deleteAvatar(id) {
+  updateAutoReply(id, params, options) {
     return this.client.request({
-      method: "DELETE",
-      path: `/mailboxes/${id}/avatar`
+      method: "PATCH",
+      path: `/mailboxes/${encodeURIComponent(id)}/auto-reply`,
+      body: params,
+      methodOptions: options
     });
   }
 };
 
 // src/resources/messages.ts
 var Messages = class extends ApiResource {
-  send(params) {
+  send(params, options) {
     return this.client.request({
       method: "POST",
       path: "/messages",
-      body: params
+      body: params,
+      methodOptions: options
     });
   }
-  get(id) {
+  list(params, options) {
     return this.client.request({
       method: "GET",
-      path: `/messages/${id}`
+      path: "/messages",
+      query: {
+        mailbox_id: params.mailbox_id,
+        cursor: params.cursor,
+        limit: params.limit
+      },
+      methodOptions: options
+    });
+  }
+  listAutoPaginating(params) {
+    return new Page(this.client, "/messages", {
+      mailbox_id: params.mailbox_id,
+      limit: params.limit
+    });
+  }
+  get(id, options) {
+    return this.client.request({
+      method: "GET",
+      path: `/messages/${encodeURIComponent(id)}`,
+      methodOptions: options
+    });
+  }
+  reply(id, params, options) {
+    return this.client.request({
+      method: "POST",
+      path: `/messages/${encodeURIComponent(id)}/reply`,
+      body: params,
+      methodOptions: options
     });
   }
 };
 
 // src/resources/status.ts
 var Status = class extends ApiResource {
-  get() {
+  get(options) {
+    return this.client.request({
+      method: "GET",
+      path: "/status",
+      methodOptions: options
+    });
+  }
+};
+
+// src/resources/suppressions.ts
+var Suppressions = class extends ApiResource {
+  list(params, options) {
     return this.client.request({
       method: "GET",
-      path: "/status"
+      path: "/suppressions",
+      query: {
+        cursor: params?.cursor,
+        limit: params?.limit
+      },
+      methodOptions: options
+    });
+  }
+  listAutoPaginating(params) {
+    return new Page(this.client, "/suppressions", {
+      limit: params?.limit
+    });
+  }
+  remove(email, options) {
+    return this.client.request({
+      method: "DELETE",
+      path: `/suppressions/${encodeURIComponent(email)}`,
+      methodOptions: options
     });
   }
 };
 
 // src/resources/threads.ts
 var Threads = class extends ApiResource {
-  list(params) {
+  list(params, options) {
     return this.client.request({
       method: "GET",
       path: "/threads",
@@ -289,7 +372,8 @@ var Threads = class extends ApiResource {
         mailbox_id: params.mailbox_id,
         cursor: params.cursor,
         limit: params.limit
-      }
+      },
+      methodOptions: options
     });
   }
   listAutoPaginating(params) {
@@ -298,42 +382,46 @@ var Threads = class extends ApiResource {
       limit: params.limit
     });
   }
-  get(id, params) {
+  get(id, params, options) {
     return this.client.request({
       method: "GET",
-      path: `/threads/${id}`,
+      path: `/threads/${encodeURIComponent(id)}`,
       query: {
         cursor: params?.cursor,
         limit: params?.limit
-      }
+      },
+      methodOptions: options
     });
   }
-  reply(id, params) {
+  reply(id, params, options) {
     return this.client.request({
       method: "POST",
-      path: `/threads/${id}/reply`,
-      body: params
+      path: `/threads/${encodeURIComponent(id)}/reply`,
+      body: params,
+      methodOptions: options
     });
   }
 };
 
 // src/resources/webhooks.ts
 var Webhooks = class extends ApiResource {
-  create(params) {
+  create(params, options) {
     return this.client.request({
       method: "POST",
       path: "/webhooks",
-      body: params
+      body: params,
+      methodOptions: options
     });
   }
-  list(params) {
+  list(params, options) {
     return this.client.request({
       method: "GET",
       path: "/webhooks",
       query: {
         cursor: params?.cursor,
         limit: params?.limit
-      }
+      },
+      methodOptions: options
     });
   }
   listAutoPaginating(params) {
@@ -341,69 +429,82 @@ var Webhooks = class extends ApiResource {
       limit: params?.limit
     });
   }
-  get(id) {
+  get(id, options) {
     return this.client.request({
       method: "GET",
-      path: `/webhooks/${id}`
+      path: `/webhooks/${encodeURIComponent(id)}`,
+      methodOptions: options
     });
   }
-  update(id, params) {
+  update(id, params, options) {
     return this.client.request({
       method: "PATCH",
-      path: `/webhooks/${id}`,
-      body: params
+      path: `/webhooks/${encodeURIComponent(id)}`,
+      body: params,
+      methodOptions: options
     });
   }
-  delete(id) {
+  delete(id, options) {
     return this.client.request({
       method: "DELETE",
-      path: `/webhooks/${id}`
+      path: `/webhooks/${encodeURIComponent(id)}`,
+      methodOptions: options
     });
   }
-  rotateSecret(id) {
+  rotateSecret(id, options) {
     return this.client.request({
       method: "POST",
-      path: `/webhooks/${id}/rotate-secret`
+      path: `/webhooks/${encodeURIComponent(id)}/rotate-secret`,
+      methodOptions: options
     });
   }
-  test(id) {
+  test(id, options) {
     return this.client.request({
       method: "POST",
-      path: `/webhooks/${id}/test`
+      path: `/webhooks/${encodeURIComponent(id)}/test`,
+      methodOptions: options
     });
   }
-  listDeliveries(id, params) {
+  listDeliveries(id, params, options) {
     return this.client.request({
       method: "GET",
-      path: `/webhooks/${id}/deliveries`,
+      path: `/webhooks/${encodeURIComponent(id)}/deliveries`,
       query: {
         status: params?.status,
         event_type: params?.event_type,
         cursor: params?.cursor,
         limit: params?.limit
-      }
+      },
+      methodOptions: options
     });
   }
   listDeliveriesAutoPaginating(id, params) {
-    return new Page(this.client, `/webhooks/${id}/deliveries`, {
-      status: params?.status,
-      event_type: params?.event_type,
-      limit: params?.limit
-    });
+    return new Page(
+      this.client,
+      `/webhooks/${encodeURIComponent(id)}/deliveries`,
+      {
+        status: params?.status,
+        event_type: params?.event_type,
+        limit: params?.limit
+      }
+    );
   }
 };
 
 // src/version.ts
-var VERSION = "0.1.5";
+var VERSION = "0.1.20";
 
 // src/client.ts
-var DEFAULT_BASE_URL = "https://api.shipmail.to/v1";
+var DEFAULT_BASE_URL = "https://shipmail.to/api/v1";
 var DEFAULT_MAX_RETRIES = 2;
 var DEFAULT_TIMEOUT = 3e4;
 function isRetryableStatus(status) {
   return status === 429 || status >= 500;
 }
-function calculateBackoff(attempt) {
+function calculateBackoff(attempt, retryAfterMs) {
+  if (retryAfterMs !== void 0 && retryAfterMs > 0) {
+    return retryAfterMs;
+  }
   const base = Math.min(2 ** attempt * 500, 8e3);
   const jitter = Math.random() * base * 0.5;
   return base + jitter;
@@ -416,6 +517,10 @@ function isApiErrorBody(value) {
   return typeof error["type"] === "string" && typeof error["message"] === "string";
 }
 var ShipMailClient = class {
+  /**
+   * Create a new ShipMail client.
+   * @param config - API key string or full configuration object.
+   */
   constructor(config) {
     if (typeof config === "string") {
       this.apiKey = config;
@@ -423,16 +528,19 @@ var ShipMailClient = class {
       this.maxRetries = DEFAULT_MAX_RETRIES;
       this.timeout = DEFAULT_TIMEOUT;
       this.fetchFn = globalThis.fetch;
+      this.defaultHeaders = {};
     } else {
       this.apiKey = config.apiKey;
       this.baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
       this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
       this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
       this.fetchFn = config.fetch ?? globalThis.fetch;
+      this.defaultHeaders = config.defaultHeaders ? { ...config.defaultHeaders } : {};
     }
     this.domains = new Domains(this);
     this.mailboxes = new Mailboxes(this);
     this.messages = new Messages(this);
+    this.suppressions = new Suppressions(this);
     this.threads = new Threads(this);
     this.webhooks = new Webhooks(this);
     this.status = new Status(this);
@@ -440,18 +548,25 @@ var ShipMailClient = class {
   async request(options) {
     const url = this.buildUrl(options.path, options.query);
     let lastError;
+    const methodOpts = options.methodOptions;
     for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
       if (attempt > 0) {
-        const delay = calculateBackoff(attempt - 1);
+        const retryAfterMs = lastError instanceof RateLimitError && lastError.retryAfter !== void 0 ? lastError.retryAfter * 1e3 : void 0;
+        const delay = calculateBackoff(attempt - 1, retryAfterMs);
         await new Promise((resolve) => setTimeout(resolve, delay));
       }
       let response;
       try {
         const headers = {
+          ...this.defaultHeaders,
           Authorization: `Bearer ${this.apiKey}`,
           "User-Agent": `shipmail-node/${VERSION}`,
-          Accept: "application/json"
+          Accept: "application/json",
+          ...methodOpts?.headers
         };
+        if (methodOpts?.idempotencyKey) {
+          headers["Idempotency-Key"] = methodOpts.idempotencyKey;
+        }
         let body = null;
         if (options.rawBody !== void 0) {
           headers["Content-Type"] = options.contentType ?? "application/octet-stream";
@@ -460,11 +575,12 @@ var ShipMailClient = class {
           headers["Content-Type"] = "application/json";
           body = JSON.stringify(options.body);
         }
+        const effectiveTimeout = methodOpts?.timeout ?? this.timeout;
         response = await this.fetchFn(url, {
           method: options.method,
           headers,
           body,
-          signal: AbortSignal.timeout(this.timeout)
+          signal: methodOpts?.signal ?? AbortSignal.timeout(effectiveTimeout)
         });
       } catch (err) {
         lastError = new ConnectionError(err instanceof Error ? err.message : "Request failed");
@@ -513,15 +629,31 @@ var ShipMailClient = class {
 // src/types/common.ts
 var WEBHOOK_EVENT_TYPES = [
   "message.received",
-  "message.queued",
   "message.sent",
   "message.delivered",
   "message.bounced",
   "message.complained",
   "domain.verified",
   "domain.verification_failed",
-  "domain.degraded"
+  "domain.degraded",
+  "org.reputation_warning",
+  "org.sending_throttled",
+  "org.sending_suspended",
+  "org.reputation_recovered"
 ];
+var DOMAIN_STATUSES = ["pending", "verifying", "verified", "degraded", "failed"];
+var MESSAGE_STATUSES = [
+  "queued",
+  "sent",
+  "delivered",
+  "bounced",
+  "complained",
+  "failed"
+];
+var MESSAGE_SOURCES = ["api", "dashboard", "inbound", "smtp"];
+var WEBHOOK_DELIVERY_STATUSES = ["pending", "delivered", "failed"];
+
+// src/webhook-verification.ts
 var DEFAULT_TOLERANCE_SECONDS = 300;
 function getHeader(headers, name) {
   if (headers instanceof Headers) {
@@ -529,12 +661,13 @@ function getHeader(headers, name) {
   }
   return headers[name] ?? headers[name.toLowerCase()];
 }
-function signPayload(secret, timestamp, body) {
+async function signPayload(secret, timestamp, body) {
+  const { createHmac } = await import('crypto');
   const payload = `v1=${timestamp}
 ${body}`;
-  return crypto.createHmac("sha256", secret).update(payload).digest("hex");
+  return createHmac("sha256", secret).update(payload).digest("hex");
 }
-function verifyWebhook(body, headers, secret, options) {
+async function verifyWebhook(body, headers, secret, options) {
   const signature = getHeader(headers, "x-shipmail-signature");
   const timestampStr = getHeader(headers, "x-shipmail-timestamp");
   if (!signature) {
@@ -552,10 +685,11 @@ function verifyWebhook(body, headers, secret, options) {
   if (Math.abs(now - timestamp) > tolerance) {
     throw new WebhookVerificationError("Webhook timestamp is outside tolerance window");
   }
-  const expected = signPayload(secret, timestamp, body);
+  const expected = await signPayload(secret, timestamp, body);
+  const { timingSafeEqual } = await import('crypto');
   const sigBuffer = Buffer.from(signature, "hex");
   const expectedBuffer = Buffer.from(expected, "hex");
-  if (sigBuffer.length !== expectedBuffer.length || !crypto.timingSafeEqual(sigBuffer, expectedBuffer)) {
+  if (sigBuffer.length !== expectedBuffer.length || !timingSafeEqual(sigBuffer, expectedBuffer)) {
     throw new WebhookVerificationError("Webhook signature verification failed");
   }
   let parsed;
@@ -571,13 +705,18 @@ exports.AuthenticationError = AuthenticationError;
 exports.AuthorizationError = AuthorizationError;
 exports.ConflictError = ConflictError;
 exports.ConnectionError = ConnectionError;
+exports.DOMAIN_STATUSES = DOMAIN_STATUSES;
 exports.InternalServerError = InternalServerError;
+exports.MESSAGE_SOURCES = MESSAGE_SOURCES;
+exports.MESSAGE_STATUSES = MESSAGE_STATUSES;
 exports.NotFoundError = NotFoundError;
 exports.Page = Page;
+exports.QuotaExceededError = QuotaExceededError;
 exports.RateLimitError = RateLimitError;
 exports.ShipMailClient = ShipMailClient;
 exports.ShipMailError = ShipMailError;
 exports.ValidationError = ValidationError;
+exports.WEBHOOK_DELIVERY_STATUSES = WEBHOOK_DELIVERY_STATUSES;
 exports.WEBHOOK_EVENT_TYPES = WEBHOOK_EVENT_TYPES;
 exports.WebhookVerificationError = WebhookVerificationError;
 exports.default = ShipMailClient;