supersendtx 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -8,10 +8,24 @@ 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;
 };
@@ -19,14 +33,38 @@ 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;
@@ -71,7 +109,7 @@ type CreateApiKeyResult = {
     token: string;
     created_at: string;
 };
-type WebhookEventType = 'email.delivered' | 'email.bounced';
+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;
@@ -84,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;
@@ -99,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;
@@ -197,6 +264,10 @@ declare class EmailsResource {
         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 {
@@ -209,6 +280,19 @@ declare class KeysResource {
     }>;
 }
 
+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);
@@ -220,10 +304,18 @@ declare class WebhooksResource {
         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";
@@ -234,6 +326,7 @@ declare class SuperSendTX {
     readonly emails: EmailsResource;
     readonly webhooks: WebhooksResource;
     readonly apiKeys: KeysResource;
+    readonly suppressions: SuppressionsResource;
     constructor(apiKey: string, options?: SuperSendTXOptions);
     get baseUrl(): string;
     get fetchImpl(): typeof fetch;
@@ -252,6 +345,14 @@ declare class SuperSendTXError extends Error {
     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;
 
@@ -282,4 +383,4 @@ declare function applyDnsRecords(input: {
     fetchImpl?: typeof fetch;
 }): Promise<ApplyDnsResult>;
 
-export { type ApiErrorCode, type ApiKey, type ApiKeyScope, type ApplyDnsParams, type ApplyDnsRecordResult$1 as ApplyDnsRecordResult, type ApplyDnsResult$1 as ApplyDnsResult, type CreateApiKeyParams, type CreateApiKeyResult, type CreateDomainParams, type CreateDomainResult, 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 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

@@ -427,12 +427,20 @@ 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;
@@ -443,6 +451,49 @@ var EmailsResource = class {
       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
@@ -475,7 +526,69 @@ var KeysResource = class {
   }
 };
 
-// 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;
@@ -487,15 +600,28 @@ var WebhooksResource = class {
     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", {
       method: "POST",
       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
@@ -511,6 +637,7 @@ var SuperSendTX = class {
     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(/\/$/, "");
@@ -539,5 +666,8 @@ export {
   SuperSendTX,
   SuperSendTXError,
   applyDnsRecords,
-  mergeSpfInclude
+  buildSignatureHeader,
+  mergeSpfInclude,
+  signWebhookPayload,
+  verifyWebhookSignature
 };

package/package.json

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