supersendtx 0.3.0 → 0.6.0

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+type ApiErrorCode = 'validation_error' | 'unauthorized' | 'forbidden' | 'not_found' | 'conflict' | 'plan_limit' | 'domain_limit' | 'idempotency_conflict' | 'rate_limited' | 'upstream_error' | 'not_configured' | 'internal_error';
 type SendEmailParams = {
     from: string | {
         email: string;
@@ -7,23 +8,63 @@ type SendEmailParams = {
     subject: string;
     html?: string;
     text?: string;
-    replyTo?: string;
-    reply_to?: string;
+    replyTo?: string | string[];
+    reply_to?: string | string[];
     cc?: string | string[];
     bcc?: string | string[];
+    tags?: Array<{
+        name: string;
+        value: string;
+    }> | Record<string, string>;
+    headers?: Record<string, string>;
+    tag?: string;
+    attachments?: Array<{
+        name: string;
+        content_type: string;
+        data: string;
+        content_id?: string;
+    }>;
+    scheduledAt?: string | Date;
+    scheduled_at?: string | Date;
+    /** Optional Idempotency-Key (24h TTL). */
+    idempotencyKey?: string;
 };
 type SendEmailResult = {
     id: string;
     status: string;
 };
+type BatchSendEmailResult = {
+    data: Array<{
+        index: number;
+        id?: string;
+        status?: string;
+        error?: {
+            message: string;
+            code?: string;
+            details?: unknown;
+            status_code?: number;
+        };
+    }>;
+};
+type UpdateEmailParams = {
+    scheduledAt?: string | Date;
+    scheduled_at?: string | Date;
+    cancel?: boolean;
+};
 type EmailListItem = {
     id: string;
     from: string;
     to: string[];
+    cc: string[];
+    bcc: string[];
+    reply_to: string[];
     subject: string;
     status: string;
     last_event: string | null;
     bounce_reason: string | null;
+    tags: unknown;
+    scheduled_at: string | null;
+    cancelled_at: string | null;
     created_at: string;
     sent_at: string | null;
     delivered_at: string | null;
@@ -31,8 +72,44 @@ type EmailListItem = {
 };
 type ListEmailsParams = {
     limit?: number;
+    cursor?: string;
+};
+type ListEmailsResult = {
+    emails: EmailListItem[];
+    has_more: boolean;
+    next_cursor: string | null;
+};
+type ApiKeyScope = 'full' | 'sending';
+type ApiKey = {
+    id: string;
+    name: string;
+    scope: ApiKeyScope;
+    prefix: string;
+    created_at: string;
+    last_used_at: string | null;
+};
+type ListApiKeysParams = {
+    limit?: number;
+    cursor?: string;
 };
-type WebhookEventType = 'email.delivered' | 'email.bounced';
+type ListApiKeysResult = {
+    data: ApiKey[];
+    has_more: boolean;
+    next_cursor: string | null;
+};
+type CreateApiKeyParams = {
+    name?: string;
+    scope?: ApiKeyScope;
+};
+type CreateApiKeyResult = {
+    id: string;
+    name: string;
+    scope: ApiKeyScope;
+    prefix: string;
+    token: string;
+    created_at: string;
+};
+type WebhookEventType = 'email.sent' | 'email.delivered' | 'email.delivery_delayed' | 'email.bounced' | 'email.complained' | 'email.opened' | 'email.clicked' | 'email.failed' | 'email.suppressed' | 'email.scheduled';
 type WebhookEndpoint = {
     id: string;
     url: string;
@@ -45,10 +122,37 @@ type CreateWebhookParams = {
     url: string;
     events?: WebhookEventType[];
 };
+type UpdateWebhookParams = {
+    url?: string;
+    events?: WebhookEventType[];
+    enabled?: boolean;
+};
 type WebhookEndpointWithSecret = {
     webhook: WebhookEndpoint;
     secret: string;
 };
+type Suppression = {
+    id: string;
+    email: string;
+    reason: string | null;
+    source: string;
+    created_at: string;
+    updated_at: string;
+};
+type ListSuppressionsParams = {
+    limit?: number;
+    cursor?: string;
+    email?: string;
+};
+type ListSuppressionsResult = {
+    data: Suppression[];
+    has_more: boolean;
+    next_cursor: string | null;
+};
+type CreateSuppressionParams = {
+    email: string;
+    reason?: string;
+};
 type SuperSendTXOptions = {
     baseUrl?: string;
     fetch?: typeof fetch;
@@ -60,6 +164,8 @@ type Domain = {
     status: DomainStatus | string;
     created_at: string;
     verified_at: string | null;
+    open_tracking?: boolean;
+    click_tracking?: boolean;
 };
 type DnsRecord = {
     type: string;
@@ -111,14 +217,21 @@ type ApiErrorBody = {
     error?: string | {
         message?: string;
         details?: unknown;
+        code?: string;
+        upgrade_url?: string;
     };
 };
 
 declare class DomainsResource {
     private readonly client;
     constructor(client: SuperSendTX);
-    list(): Promise<{
+    list(params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
         domains: Domain[];
+        has_more: boolean;
+        next_cursor: string | null;
     }>;
     get(idOrName: string): Promise<{
         domain: Domain;
@@ -146,22 +259,63 @@ declare class DomainsResource {
 declare class EmailsResource {
     private readonly client;
     constructor(client: SuperSendTX);
-    list(params?: ListEmailsParams): Promise<{
-        emails: EmailListItem[];
+    list(params?: ListEmailsParams): Promise<ListEmailsResult>;
+    get(id: string): Promise<{
+        email: EmailListItem;
     }>;
     send(params: SendEmailParams): Promise<SendEmailResult>;
+    batch(emails: SendEmailParams[]): Promise<BatchSendEmailResult>;
+    update(id: string, params: UpdateEmailParams): Promise<SendEmailResult>;
+    cancel(id: string): Promise<SendEmailResult>;
+    private serializeSendParams;
+}
+
+declare class KeysResource {
+    private readonly client;
+    constructor(client: SuperSendTX);
+    list(params?: ListApiKeysParams): Promise<ListApiKeysResult>;
+    create(params?: CreateApiKeyParams): Promise<CreateApiKeyResult>;
+    remove(id: string): Promise<{
+        ok: boolean;
+    }>;
+}
+
+declare class SuppressionsResource {
+    private readonly client;
+    constructor(client: SuperSendTX);
+    list(params?: ListSuppressionsParams): Promise<ListSuppressionsResult>;
+    create(params: CreateSuppressionParams): Promise<{
+        suppression: Suppression;
+    }>;
+    /** Remove by suppression id or email address. */
+    remove(idOrEmail: string): Promise<{
+        ok: boolean;
+    }>;
 }
 
 declare class WebhooksResource {
     private readonly client;
     constructor(client: SuperSendTX);
-    list(): Promise<{
+    list(params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
         webhooks: WebhookEndpoint[];
+        has_more: boolean;
+        next_cursor: string | null;
+    }>;
+    get(id: string): Promise<{
+        webhook: WebhookEndpoint;
     }>;
     create(params: CreateWebhookParams): Promise<WebhookEndpointWithSecret>;
+    update(id: string, params: UpdateWebhookParams): Promise<{
+        webhook: WebhookEndpoint;
+    }>;
     delete(id: string): Promise<{
         ok: boolean;
     }>;
+    /** Verify an incoming webhook signature (same as `verifyWebhookSignature`). */
+    verify(secret: string, payload: string, header: string | null | undefined, toleranceSec?: number): boolean;
 }
 
 declare const DEFAULT_API_BASE_URL = "https://api.supersendtx.com";
@@ -171,6 +325,8 @@ declare class SuperSendTX {
     readonly domains: DomainsResource;
     readonly emails: EmailsResource;
     readonly webhooks: WebhooksResource;
+    readonly apiKeys: KeysResource;
+    readonly suppressions: SuppressionsResource;
     constructor(apiKey: string, options?: SuperSendTXOptions);
     get baseUrl(): string;
     get fetchImpl(): typeof fetch;
@@ -180,10 +336,23 @@ declare class SuperSendTX {
 declare class SuperSendTXError extends Error {
     readonly status: number;
     readonly details?: unknown;
-    constructor(message: string, status: number, details?: unknown);
+    readonly code?: string;
+    readonly upgradeUrl?: string;
+    constructor(message: string, status: number, details?: unknown, options?: {
+        code?: string;
+        upgradeUrl?: string;
+    });
     static fromResponse(status: number, body: ApiErrorBody): SuperSendTXError;
 }
 
+declare function signWebhookPayload(secret: string, payload: string, timestamp: number): string;
+declare function buildSignatureHeader(secret: string, payload: string, timestamp?: number): string;
+/**
+ * Verify a SuperSend TX webhook signature header (`SuperSendTX-Signature`).
+ * Expects HMAC-SHA256 over `${timestamp}.${rawBody}` with the endpoint secret.
+ */
+declare function verifyWebhookSignature(secret: string, payload: string, header: string | null | undefined, toleranceSec?: number): boolean;
+
 /** Merge `include:host` into an existing SPF record (or create a minimal one). */
 declare function mergeSpfInclude(existing: string | null | undefined, includeHost: string): string;
 
@@ -214,4 +383,4 @@ declare function applyDnsRecords(input: {
     fetchImpl?: typeof fetch;
 }): Promise<ApplyDnsResult>;
 
-export { type ApplyDnsParams, type ApplyDnsRecordResult$1 as ApplyDnsRecordResult, type ApplyDnsResult$1 as ApplyDnsResult, type CreateDomainParams, type CreateDomainResult, type CreateWebhookParams, DEFAULT_API_BASE_URL, type DnsProviderName$1 as DnsProviderName, type DnsRecord, type Domain, type DomainStatus, type EmailListItem, type ListEmailsParams, type SendEmailParams, type SendEmailResult, SuperSendTX, SuperSendTXError, type SuperSendTXOptions, type VerifyDomainResult, type WebhookEndpoint, type WebhookEndpointWithSecret, type WebhookEventType, applyDnsRecords, mergeSpfInclude };
+export { type ApiErrorCode, type ApiKey, type ApiKeyScope, type ApplyDnsParams, type ApplyDnsRecordResult$1 as ApplyDnsRecordResult, type ApplyDnsResult$1 as ApplyDnsResult, type BatchSendEmailResult, type CreateApiKeyParams, type CreateApiKeyResult, type CreateDomainParams, type CreateDomainResult, type CreateSuppressionParams, type CreateWebhookParams, DEFAULT_API_BASE_URL, type DnsProviderName$1 as DnsProviderName, type DnsRecord, type Domain, type DomainStatus, type EmailListItem, type ListApiKeysParams, type ListApiKeysResult, type ListEmailsParams, type ListEmailsResult, type ListSuppressionsParams, type ListSuppressionsResult, type SendEmailParams, type SendEmailResult, SuperSendTX, SuperSendTXError, type SuperSendTXOptions, type Suppression, type UpdateEmailParams, type UpdateWebhookParams, type VerifyDomainResult, type WebhookEndpoint, type WebhookEndpointWithSecret, type WebhookEventType, applyDnsRecords, buildSignatureHeader, mergeSpfInclude, signWebhookPayload, verifyWebhookSignature };

package/dist/index.js

@@ -1,16 +1,20 @@
 // src/errors.ts
 var SuperSendTXError = class _SuperSendTXError extends Error {
-  constructor(message, status, details) {
+  constructor(message, status, details, options) {
     super(message);
     this.name = "SuperSendTXError";
     this.status = status;
     this.details = details;
+    this.code = options?.code;
+    this.upgradeUrl = options?.upgradeUrl;
   }
   static fromResponse(status, body) {
     const err = body.error;
     const message = typeof err === "string" ? err : err?.message || `Request failed with status ${status}`;
     const details = typeof err === "object" && err ? err.details : void 0;
-    return new _SuperSendTXError(message, status, details);
+    const code = typeof err === "object" && err && "code" in err ? String(err.code) : void 0;
+    const upgradeUrl = typeof err === "object" && err && "upgrade_url" in err ? String(err.upgrade_url) : void 0;
+    return new _SuperSendTXError(message, status, details, { code, upgradeUrl });
   }
 };
 
@@ -337,8 +341,12 @@ var DomainsResource = class {
   constructor(client) {
     this.client = client;
   }
-  async list() {
-    return this.client.request("/domains", { method: "GET" });
+  async list(params = {}) {
+    const search = new URLSearchParams();
+    if (params.limit != null) search.set("limit", String(params.limit));
+    if (params.cursor) search.set("cursor", params.cursor);
+    const query = search.toString();
+    return this.client.request(`/domains${query ? `?${query}` : ""}`, { method: "GET" });
   }
   async get(idOrName) {
     return this.client.request(`/domains/${encodeURIComponent(idOrName)}`, { method: "GET" });
@@ -400,8 +408,16 @@ var EmailsResource = class {
     this.client = client;
   }
   async list(params = {}) {
-    const query = params.limit ? `?limit=${params.limit}` : "";
-    return this.client.request(`/emails${query}`, {
+    const search = new URLSearchParams();
+    if (params.limit != null) search.set("limit", String(params.limit));
+    if (params.cursor) search.set("cursor", params.cursor);
+    const query = search.toString();
+    return this.client.request(`/emails${query ? `?${query}` : ""}`, {
+      method: "GET"
+    });
+  }
+  async get(id) {
+    return this.client.request(`/emails/${encodeURIComponent(id)}`, {
       method: "GET"
     });
   }
@@ -411,26 +427,181 @@ var EmailsResource = class {
       to: params.to,
       subject: params.subject
     };
-    if (params.html) payload.html = params.html;
-    if (params.text) payload.text = params.text;
+    if (params.html !== void 0) payload.html = params.html;
+    if (params.text !== void 0) payload.text = params.text;
     const replyTo = params.replyTo ?? params.reply_to;
-    if (replyTo) payload.reply_to = replyTo;
-    if (params.cc) payload.cc = params.cc;
-    if (params.bcc) payload.bcc = params.bcc;
+    if (replyTo !== void 0) payload.reply_to = replyTo;
+    if (params.cc !== void 0) payload.cc = params.cc;
+    if (params.bcc !== void 0) payload.bcc = params.bcc;
+    if (params.tags !== void 0) payload.tags = params.tags;
+    if (params.headers !== void 0) payload.headers = params.headers;
+    if (params.tag !== void 0) payload.tag = params.tag;
+    if (params.attachments !== void 0) payload.attachments = params.attachments;
+    const scheduledAt = params.scheduledAt ?? params.scheduled_at;
+    if (scheduledAt !== void 0) {
+      payload.scheduled_at = scheduledAt instanceof Date ? scheduledAt.toISOString() : scheduledAt;
+    }
+    const headers = {};
+    if (params.idempotencyKey) {
+      headers["Idempotency-Key"] = params.idempotencyKey;
+    }
     return this.client.request("/emails", {
       method: "POST",
+      headers,
       body: JSON.stringify(payload)
     });
   }
+  async batch(emails) {
+    return this.client.request("/emails/batch", {
+      method: "POST",
+      body: JSON.stringify({ emails: emails.map((email) => this.serializeSendParams(email)) })
+    });
+  }
+  async update(id, params) {
+    const payload = {};
+    if (params.cancel !== void 0) payload.cancel = params.cancel;
+    const scheduledAt = params.scheduledAt ?? params.scheduled_at;
+    if (scheduledAt !== void 0) {
+      payload.scheduled_at = scheduledAt instanceof Date ? scheduledAt.toISOString() : scheduledAt;
+    }
+    return this.client.request(`/emails/${encodeURIComponent(id)}`, {
+      method: "PATCH",
+      body: JSON.stringify(payload)
+    });
+  }
+  async cancel(id) {
+    return this.update(id, { cancel: true });
+  }
+  serializeSendParams(params) {
+    const payload = {
+      from: params.from,
+      to: params.to,
+      subject: params.subject
+    };
+    if (params.html !== void 0) payload.html = params.html;
+    if (params.text !== void 0) payload.text = params.text;
+    const replyTo = params.replyTo ?? params.reply_to;
+    if (replyTo !== void 0) payload.reply_to = replyTo;
+    if (params.cc !== void 0) payload.cc = params.cc;
+    if (params.bcc !== void 0) payload.bcc = params.bcc;
+    if (params.tags !== void 0) payload.tags = params.tags;
+    if (params.headers !== void 0) payload.headers = params.headers;
+    if (params.tag !== void 0) payload.tag = params.tag;
+    if (params.attachments !== void 0) payload.attachments = params.attachments;
+    const scheduledAt = params.scheduledAt ?? params.scheduled_at;
+    if (scheduledAt !== void 0) {
+      payload.scheduled_at = scheduledAt instanceof Date ? scheduledAt.toISOString() : scheduledAt;
+    }
+    return payload;
+  }
+};
+
+// src/keys.ts
+var KeysResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  async list(params = {}) {
+    const search = new URLSearchParams();
+    if (params.limit != null) search.set("limit", String(params.limit));
+    if (params.cursor) search.set("cursor", params.cursor);
+    const query = search.toString();
+    return this.client.request(`/api-keys${query ? `?${query}` : ""}`, {
+      method: "GET"
+    });
+  }
+  async create(params = {}) {
+    return this.client.request("/api-keys", {
+      method: "POST",
+      body: JSON.stringify({
+        ...params.name ? { name: params.name } : {},
+        ...params.scope ? { scope: params.scope } : {}
+      })
+    });
+  }
+  async remove(id) {
+    return this.client.request(`/api-keys/${encodeURIComponent(id)}`, {
+      method: "DELETE"
+    });
+  }
 };
 
-// src/webhooks.ts
+// src/suppressions.ts
+var SuppressionsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  async list(params = {}) {
+    const search = new URLSearchParams();
+    if (params.limit != null) search.set("limit", String(params.limit));
+    if (params.cursor) search.set("cursor", params.cursor);
+    if (params.email) search.set("email", params.email);
+    const query = search.toString();
+    return this.client.request(`/suppressions${query ? `?${query}` : ""}`, { method: "GET" });
+  }
+  async create(params) {
+    return this.client.request("/suppressions", {
+      method: "POST",
+      body: JSON.stringify(params)
+    });
+  }
+  /** Remove by suppression id or email address. */
+  async remove(idOrEmail) {
+    if (idOrEmail.includes("@")) {
+      return this.client.request(`/suppressions?email=${encodeURIComponent(idOrEmail)}`, {
+        method: "DELETE"
+      });
+    }
+    return this.client.request(`/suppressions/${encodeURIComponent(idOrEmail)}`, {
+      method: "DELETE"
+    });
+  }
+};
+
+// src/webhooks/verify.ts
+import { createHmac, timingSafeEqual } from "crypto";
+function signWebhookPayload(secret, payload, timestamp) {
+  const signed = `${timestamp}.${payload}`;
+  return createHmac("sha256", secret).update(signed).digest("hex");
+}
+function buildSignatureHeader(secret, payload, timestamp = Math.floor(Date.now() / 1e3)) {
+  const signature = signWebhookPayload(secret, payload, timestamp);
+  return `t=${timestamp},v1=${signature}`;
+}
+function verifyWebhookSignature(secret, payload, header, toleranceSec = 300) {
+  if (!header) return false;
+  const parts = Object.fromEntries(
+    header.split(",").map((part) => {
+      const [key, value] = part.trim().split("=");
+      return [key, value];
+    })
+  );
+  const timestamp = Number(parts.t);
+  const signature = parts.v1;
+  if (!timestamp || !signature) return false;
+  if (Math.abs(Math.floor(Date.now() / 1e3) - timestamp) > toleranceSec) return false;
+  const expected = signWebhookPayload(secret, payload, timestamp);
+  try {
+    return timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
+  } catch {
+    return false;
+  }
+}
+
+// src/webhooks/index.ts
 var WebhooksResource = class {
   constructor(client) {
     this.client = client;
   }
-  async list() {
-    return this.client.request("/webhooks", { method: "GET" });
+  async list(params = {}) {
+    const search = new URLSearchParams();
+    if (params.limit != null) search.set("limit", String(params.limit));
+    if (params.cursor) search.set("cursor", params.cursor);
+    const query = search.toString();
+    return this.client.request(`/webhooks${query ? `?${query}` : ""}`, { method: "GET" });
+  }
+  async get(id) {
+    return this.client.request(`/webhooks/${encodeURIComponent(id)}`, { method: "GET" });
   }
   async create(params) {
     return this.client.request("/webhooks", {
@@ -438,9 +609,19 @@ var WebhooksResource = class {
       body: JSON.stringify(params)
     });
   }
+  async update(id, params) {
+    return this.client.request(`/webhooks/${encodeURIComponent(id)}`, {
+      method: "PATCH",
+      body: JSON.stringify(params)
+    });
+  }
   async delete(id) {
     return this.client.request(`/webhooks/${id}`, { method: "DELETE" });
   }
+  /** Verify an incoming webhook signature (same as `verifyWebhookSignature`). */
+  verify(secret, payload, header, toleranceSec = 300) {
+    return verifyWebhookSignature(secret, payload, header, toleranceSec);
+  }
 };
 
 // src/client.ts
@@ -455,6 +636,8 @@ var SuperSendTX = class {
     this.domains = new DomainsResource(this);
     this.emails = new EmailsResource(this);
     this.webhooks = new WebhooksResource(this);
+    this.apiKeys = new KeysResource(this);
+    this.suppressions = new SuppressionsResource(this);
   }
   get baseUrl() {
     return (this.options.baseUrl || DEFAULT_API_BASE_URL).replace(/\/$/, "");
@@ -483,5 +666,8 @@ export {
   SuperSendTX,
   SuperSendTXError,
   applyDnsRecords,
-  mergeSpfInclude
+  buildSignatureHeader,
+  mergeSpfInclude,
+  signWebhookPayload,
+  verifyWebhookSignature
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supersendtx",
-  "version": "0.3.0",
+  "version": "0.6.0",
   "description": "SuperSend TX transactional email API client",
   "license": "MIT",
   "type": "module",