@easybits.cloud/mailmask 0.2.2 → 0.3.1

package/README.md

@@ -38,6 +38,29 @@ await mm.send.send(domainId, {
 const aliases = await mm.aliases.list(domainId);
 ```
 
+## More
+
+```ts
+// Attachments, copies, threading, idempotency
+const pdf = await mm.attachments.upload(domainId, { filename: "invoice.pdf", contentType: "application/pdf", data: bytes });
+await mm.send.send(domainId, {
+  from: "billing", to: "client@example.com", cc: ["cfo@example.com"],
+  subject: "Re: Invoice 42", markdown: "Attached.", attachments: [pdf],
+  inReplyTo: "<abc@mail.example.com>", references: "<abc@mail.example.com>",
+}, { idempotencyKey: `invoice-42` });
+
+// Suppression list (hard bounces / complaints)
+await mm.suppressions.list(domainId);
+await mm.suppressions.remove(domainId, "fixed@example.com");
+
+// Webhooks (Developer plan) — secret is shown once
+const wh = await mm.webhooks.create(domainId, { url: "https://app.example.com/hooks/mailmask", events: ["email.received", "email.delivered", "email.bounced"] });
+
+// On your server: verify the signature with the raw body
+import { verifyWebhookSignature } from "@easybits.cloud/mailmask";
+const ok = await verifyWebhookSignature(secret, { signature: req.headers["x-mailmask-signature"], timestamp: req.headers["x-mailmask-timestamp"] }, rawBody);
+```
+
 ## Docs
 
 Full API reference and examples: https://mailmask.studio/docs

package/dist/index.cjs

@@ -21,7 +21,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   MailMask: () => MailMask,
-  MailMaskError: () => MailMaskError
+  MailMaskError: () => MailMaskError,
+  verifyWebhookSignature: () => verifyWebhookSignature
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -34,14 +35,9 @@ var MailMaskError = class extends Error {
   }
 };
 async function request(baseUrl, apiKey, path, opts, doFetch = fetch) {
-  const res = await doFetch(`${baseUrl}${path}`, {
-    ...opts,
-    headers: {
-      "Authorization": `Bearer ${apiKey}`,
-      "Content-Type": "application/json",
-      ...opts?.headers
-    }
-  });
+  const headers = { "Authorization": `Bearer ${apiKey}`, ...opts?.headers };
+  if (!(opts?.body instanceof FormData) && !("Content-Type" in headers)) headers["Content-Type"] = "application/json";
+  const res = await doFetch(`${baseUrl}${path}`, { ...opts, headers });
   if (!res.ok) {
     const body = await res.json().catch(() => ({ error: res.statusText }));
     throw new MailMaskError(res.status, body.error || res.statusText);
@@ -59,6 +55,9 @@ var MailMask = class {
     this.rules = new RulesResource(req);
     this.logs = new LogsResource(req);
     this.send = new SendResource(req);
+    this.attachments = new AttachmentsResource(req);
+    this.suppressions = new SuppressionsResource(req);
+    this.webhooks = new WebhooksResource(req);
     this.smtp = new SmtpResource(req);
     this.apiKeys = new ApiKeysResource(req);
   }
@@ -134,8 +133,10 @@ var SendResource = class {
   constructor(req) {
     this.req = req;
   }
-  send(domainId, input) {
-    return this.req(`/api/domains/${domainId}/send`, { method: "POST", body: JSON.stringify(input) });
+  send(domainId, input, opts) {
+    const headers = {};
+    if (opts?.idempotencyKey) headers["Idempotency-Key"] = opts.idempotencyKey;
+    return this.req(`/api/domains/${domainId}/send`, { method: "POST", body: JSON.stringify(input), headers });
   }
   bulkSend(domainId, input) {
     return this.req(`/api/domains/${domainId}/send-bulk`, { method: "POST", body: JSON.stringify(input) });
@@ -144,6 +145,56 @@ var SendResource = class {
     return this.req(`/api/domains/${domainId}/bulk/${jobId}`);
   }
 };
+var AttachmentsResource = class {
+  constructor(req) {
+    this.req = req;
+  }
+  /** Máx. 5 MB. Ejecutables bloqueados (415). La llave vale hasta que se envía. */
+  upload(domainId, input) {
+    const form = new FormData();
+    const blob = input.data instanceof Blob ? input.data : new Blob([input.data], { type: input.contentType });
+    form.append("file", blob, input.filename);
+    return this.req(`/api/domains/${domainId}/attachments`, { method: "POST", body: form });
+  }
+};
+var SuppressionsResource = class {
+  constructor(req) {
+    this.req = req;
+  }
+  list(domainId) {
+    return this.req(`/api/domains/${domainId}/suppressions`);
+  }
+  add(domainId, email) {
+    return this.req(`/api/domains/${domainId}/suppressions`, { method: "POST", body: JSON.stringify({ email }) });
+  }
+  remove(domainId, email) {
+    return this.req(`/api/domains/${domainId}/suppressions/${encodeURIComponent(email)}`, { method: "DELETE" });
+  }
+};
+var WebhooksResource = class {
+  constructor(req) {
+    this.req = req;
+  }
+  list(domainId) {
+    return this.req(`/api/domains/${domainId}/webhooks`);
+  }
+  create(domainId, input) {
+    return this.req(`/api/domains/${domainId}/webhooks`, { method: "POST", body: JSON.stringify(input) });
+  }
+  update(domainId, webhookId, input) {
+    return this.req(`/api/domains/${domainId}/webhooks/${webhookId}`, { method: "PUT", body: JSON.stringify(input) });
+  }
+  delete(domainId, webhookId) {
+    return this.req(`/api/domains/${domainId}/webhooks/${webhookId}`, { method: "DELETE" });
+  }
+  /** Encola un `ping`; llega en el siguiente minuto. */
+  test(domainId, webhookId) {
+    return this.req(`/api/domains/${domainId}/webhooks/${webhookId}/test`, { method: "POST" });
+  }
+  deliveries(domainId, webhookId) {
+    return this.req(`/api/domains/${domainId}/webhooks/${webhookId}/deliveries`);
+  }
+};
 var SmtpResource = class {
   constructor(req) {
     this.req = req;
@@ -172,8 +223,28 @@ var ApiKeysResource = class {
     return this.req(`/api/api-keys/${id}`, { method: "DELETE" });
   }
 };
+
+// src/verify.ts
+function hex(buf) {
+  return Array.from(new Uint8Array(buf)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function constantTimeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+async function verifyWebhookSignature(secret, headers, rawBody, toleranceMs = 5 * 6e4) {
+  const ts = Number(headers.timestamp);
+  if (!Number.isFinite(ts) || Math.abs(Date.now() - ts) > toleranceMs) return false;
+  const enc = new TextEncoder();
+  const key = await crypto.subtle.importKey("raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const mac = await crypto.subtle.sign("HMAC", key, enc.encode(`${headers.timestamp}.${rawBody}`));
+  return constantTimeEqual(`sha256=${hex(mac)}`, headers.signature);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   MailMask,
-  MailMaskError
+  MailMaskError,
+  verifyWebhookSignature
 });

package/dist/index.d.cts

@@ -111,6 +111,87 @@ interface SendEmailInput {
     from?: string;
     /** Nombre visible del remitente: `Libretas <hola@tudominio.com>`. */
     fromName?: string;
+    /** Copias visibles. Máx. 20; también pasan por la lista de supresión. */
+    cc?: string[];
+    /** Copias ocultas. Máx. 20. */
+    bcc?: string[];
+    /** `Message-ID` del correo al que se responde, para que el cliente lo enhebre. */
+    inReplyTo?: string;
+    /** Cadena `References` del hilo. */
+    references?: string;
+    /** Archivos subidos antes con `attachments.upload`. Se borran de S3 al enviarse. */
+    attachments?: AttachmentRef[];
+}
+/** Lo que devuelve `attachments.upload`; se pasa tal cual en `SendEmailInput.attachments`. */
+interface AttachmentRef {
+    key: string;
+    filename: string;
+    contentType?: string;
+}
+interface UploadAttachmentInput {
+    filename: string;
+    contentType: string;
+    data: Uint8Array | Blob;
+}
+interface UploadedAttachment {
+    ok: boolean;
+    key: string;
+    filename: string;
+    size: number;
+}
+interface SendOptions {
+    /**
+     * Reintentar con la misma clave (máx. 128 caracteres) devuelve la respuesta
+     * original sin volver a enviar ni consumir cuota, durante 24 h.
+     */
+    idempotencyKey?: string;
+}
+interface Suppression {
+    email: string;
+    /** `bounce:Permanent`, `complaint` o `manual`. */
+    reason: string;
+    createdAt: string;
+}
+type WebhookEvent = "email.received" | "email.sent" | "email.delivered" | "email.bounced" | "email.complained";
+interface Webhook {
+    id: string;
+    domainId: string;
+    url: string;
+    events: WebhookEvent[];
+    enabled: boolean;
+    createdAt: string;
+}
+/** Lo que devuelve `webhooks.create`. El `secret` se muestra una sola vez. */
+interface WebhookCreated extends Webhook {
+    secret: string;
+}
+interface CreateWebhookInput {
+    /** Debe ser https y pública. */
+    url: string;
+    events: WebhookEvent[];
+}
+interface UpdateWebhookInput {
+    url?: string;
+    events?: WebhookEvent[];
+    enabled?: boolean;
+}
+interface WebhookDelivery {
+    id: string;
+    webhookId: string;
+    event: WebhookEvent | "ping";
+    attempts: number;
+    status: "pending" | "delivered" | "failed";
+    nextAt: string;
+    lastError: string | null;
+    lastStatusCode: number | null;
+    createdAt: string;
+}
+/** Cuerpo que recibe tu endpoint. `data` depende del evento. */
+interface WebhookPayload<T = Record<string, unknown>> {
+    event: WebhookEvent | "ping";
+    domainId: string;
+    timestamp: string;
+    data: T;
 }
 interface BulkSendInput {
     recipients: string[];
@@ -184,6 +265,9 @@ declare class MailMask {
     rules: RulesResource;
     logs: LogsResource;
     send: SendResource;
+    attachments: AttachmentsResource;
+    suppressions: SuppressionsResource;
+    webhooks: WebhooksResource;
     smtp: SmtpResource;
     apiKeys: ApiKeysResource;
     constructor(config: MailMaskConfig);
@@ -234,13 +318,44 @@ declare class LogsResource {
 declare class SendResource {
     private req;
     constructor(req: Req);
-    send(domainId: string, input: SendEmailInput): Promise<{
+    send(domainId: string, input: SendEmailInput, opts?: SendOptions): Promise<{
         ok: boolean;
         messageId: string;
     }>;
     bulkSend(domainId: string, input: BulkSendInput): Promise<BulkJobCreated>;
     bulkStatus(domainId: string, jobId: string): Promise<BulkJob>;
 }
+declare class AttachmentsResource {
+    private req;
+    constructor(req: Req);
+    /** Máx. 5 MB. Ejecutables bloqueados (415). La llave vale hasta que se envía. */
+    upload(domainId: string, input: UploadAttachmentInput): Promise<UploadedAttachment>;
+}
+declare class SuppressionsResource {
+    private req;
+    constructor(req: Req);
+    list(domainId: string): Promise<Suppression[]>;
+    add(domainId: string, email: string): Promise<Suppression>;
+    remove(domainId: string, email: string): Promise<{
+        ok: boolean;
+    }>;
+}
+declare class WebhooksResource {
+    private req;
+    constructor(req: Req);
+    list(domainId: string): Promise<Webhook[]>;
+    create(domainId: string, input: CreateWebhookInput): Promise<WebhookCreated>;
+    update(domainId: string, webhookId: string, input: UpdateWebhookInput): Promise<Webhook>;
+    delete(domainId: string, webhookId: string): Promise<{
+        ok: boolean;
+    }>;
+    /** Encola un `ping`; llega en el siguiente minuto. */
+    test(domainId: string, webhookId: string): Promise<{
+        ok: boolean;
+        deliveryId: string;
+    }>;
+    deliveries(domainId: string, webhookId: string): Promise<WebhookDelivery[]>;
+}
 declare class SmtpResource {
     private req;
     constructor(req: Req);
@@ -262,4 +377,17 @@ declare class ApiKeysResource {
     }>;
 }
 
-export { type Alias, type ApiKey, type BulkJob, type BulkJobCreated, type BulkSendInput, type CreateAliasInput, type CreateRuleInput, type Domain, type DomainVerification, type EmailLog, MailMask, type MailMaskConfig, MailMaskError, type Rule, type RuleAction, type RuleField, type RuleMatch, type SendEmailInput, type SmtpCredential, type SmtpCredentialCreated, type UpdateAliasInput, type UpdateRuleInput };
+interface WebhookSignatureHeaders {
+    /** Header `X-MailMask-Signature`, con forma `sha256=<hex>`. */
+    signature: string;
+    /** Header `X-MailMask-Timestamp`, milisegundos Unix. */
+    timestamp: string;
+}
+/**
+ * Comprueba que `rawBody` (el cuerpo tal cual llegó, sin parsear) fue firmado
+ * con `secret`. Rechaza timestamps con más de `toleranceMs` de diferencia para
+ * frenar repeticiones.
+ */
+declare function verifyWebhookSignature(secret: string, headers: WebhookSignatureHeaders, rawBody: string, toleranceMs?: number): Promise<boolean>;
+
+export { type Alias, type ApiKey, type AttachmentRef, type BulkJob, type BulkJobCreated, type BulkSendInput, type CreateAliasInput, type CreateRuleInput, type CreateWebhookInput, type Domain, type DomainVerification, type EmailLog, MailMask, type MailMaskConfig, MailMaskError, type Rule, type RuleAction, type RuleField, type RuleMatch, type SendEmailInput, type SendOptions, type SmtpCredential, type SmtpCredentialCreated, type Suppression, type UpdateAliasInput, type UpdateRuleInput, type UpdateWebhookInput, type UploadAttachmentInput, type UploadedAttachment, type Webhook, type WebhookCreated, type WebhookDelivery, type WebhookEvent, type WebhookPayload, type WebhookSignatureHeaders, verifyWebhookSignature };

package/dist/index.d.ts

@@ -111,6 +111,87 @@ interface SendEmailInput {
     from?: string;
     /** Nombre visible del remitente: `Libretas <hola@tudominio.com>`. */
     fromName?: string;
+    /** Copias visibles. Máx. 20; también pasan por la lista de supresión. */
+    cc?: string[];
+    /** Copias ocultas. Máx. 20. */
+    bcc?: string[];
+    /** `Message-ID` del correo al que se responde, para que el cliente lo enhebre. */
+    inReplyTo?: string;
+    /** Cadena `References` del hilo. */
+    references?: string;
+    /** Archivos subidos antes con `attachments.upload`. Se borran de S3 al enviarse. */
+    attachments?: AttachmentRef[];
+}
+/** Lo que devuelve `attachments.upload`; se pasa tal cual en `SendEmailInput.attachments`. */
+interface AttachmentRef {
+    key: string;
+    filename: string;
+    contentType?: string;
+}
+interface UploadAttachmentInput {
+    filename: string;
+    contentType: string;
+    data: Uint8Array | Blob;
+}
+interface UploadedAttachment {
+    ok: boolean;
+    key: string;
+    filename: string;
+    size: number;
+}
+interface SendOptions {
+    /**
+     * Reintentar con la misma clave (máx. 128 caracteres) devuelve la respuesta
+     * original sin volver a enviar ni consumir cuota, durante 24 h.
+     */
+    idempotencyKey?: string;
+}
+interface Suppression {
+    email: string;
+    /** `bounce:Permanent`, `complaint` o `manual`. */
+    reason: string;
+    createdAt: string;
+}
+type WebhookEvent = "email.received" | "email.sent" | "email.delivered" | "email.bounced" | "email.complained";
+interface Webhook {
+    id: string;
+    domainId: string;
+    url: string;
+    events: WebhookEvent[];
+    enabled: boolean;
+    createdAt: string;
+}
+/** Lo que devuelve `webhooks.create`. El `secret` se muestra una sola vez. */
+interface WebhookCreated extends Webhook {
+    secret: string;
+}
+interface CreateWebhookInput {
+    /** Debe ser https y pública. */
+    url: string;
+    events: WebhookEvent[];
+}
+interface UpdateWebhookInput {
+    url?: string;
+    events?: WebhookEvent[];
+    enabled?: boolean;
+}
+interface WebhookDelivery {
+    id: string;
+    webhookId: string;
+    event: WebhookEvent | "ping";
+    attempts: number;
+    status: "pending" | "delivered" | "failed";
+    nextAt: string;
+    lastError: string | null;
+    lastStatusCode: number | null;
+    createdAt: string;
+}
+/** Cuerpo que recibe tu endpoint. `data` depende del evento. */
+interface WebhookPayload<T = Record<string, unknown>> {
+    event: WebhookEvent | "ping";
+    domainId: string;
+    timestamp: string;
+    data: T;
 }
 interface BulkSendInput {
     recipients: string[];
@@ -184,6 +265,9 @@ declare class MailMask {
     rules: RulesResource;
     logs: LogsResource;
     send: SendResource;
+    attachments: AttachmentsResource;
+    suppressions: SuppressionsResource;
+    webhooks: WebhooksResource;
     smtp: SmtpResource;
     apiKeys: ApiKeysResource;
     constructor(config: MailMaskConfig);
@@ -234,13 +318,44 @@ declare class LogsResource {
 declare class SendResource {
     private req;
     constructor(req: Req);
-    send(domainId: string, input: SendEmailInput): Promise<{
+    send(domainId: string, input: SendEmailInput, opts?: SendOptions): Promise<{
         ok: boolean;
         messageId: string;
     }>;
     bulkSend(domainId: string, input: BulkSendInput): Promise<BulkJobCreated>;
     bulkStatus(domainId: string, jobId: string): Promise<BulkJob>;
 }
+declare class AttachmentsResource {
+    private req;
+    constructor(req: Req);
+    /** Máx. 5 MB. Ejecutables bloqueados (415). La llave vale hasta que se envía. */
+    upload(domainId: string, input: UploadAttachmentInput): Promise<UploadedAttachment>;
+}
+declare class SuppressionsResource {
+    private req;
+    constructor(req: Req);
+    list(domainId: string): Promise<Suppression[]>;
+    add(domainId: string, email: string): Promise<Suppression>;
+    remove(domainId: string, email: string): Promise<{
+        ok: boolean;
+    }>;
+}
+declare class WebhooksResource {
+    private req;
+    constructor(req: Req);
+    list(domainId: string): Promise<Webhook[]>;
+    create(domainId: string, input: CreateWebhookInput): Promise<WebhookCreated>;
+    update(domainId: string, webhookId: string, input: UpdateWebhookInput): Promise<Webhook>;
+    delete(domainId: string, webhookId: string): Promise<{
+        ok: boolean;
+    }>;
+    /** Encola un `ping`; llega en el siguiente minuto. */
+    test(domainId: string, webhookId: string): Promise<{
+        ok: boolean;
+        deliveryId: string;
+    }>;
+    deliveries(domainId: string, webhookId: string): Promise<WebhookDelivery[]>;
+}
 declare class SmtpResource {
     private req;
     constructor(req: Req);
@@ -262,4 +377,17 @@ declare class ApiKeysResource {
     }>;
 }
 
-export { type Alias, type ApiKey, type BulkJob, type BulkJobCreated, type BulkSendInput, type CreateAliasInput, type CreateRuleInput, type Domain, type DomainVerification, type EmailLog, MailMask, type MailMaskConfig, MailMaskError, type Rule, type RuleAction, type RuleField, type RuleMatch, type SendEmailInput, type SmtpCredential, type SmtpCredentialCreated, type UpdateAliasInput, type UpdateRuleInput };
+interface WebhookSignatureHeaders {
+    /** Header `X-MailMask-Signature`, con forma `sha256=<hex>`. */
+    signature: string;
+    /** Header `X-MailMask-Timestamp`, milisegundos Unix. */
+    timestamp: string;
+}
+/**
+ * Comprueba que `rawBody` (el cuerpo tal cual llegó, sin parsear) fue firmado
+ * con `secret`. Rechaza timestamps con más de `toleranceMs` de diferencia para
+ * frenar repeticiones.
+ */
+declare function verifyWebhookSignature(secret: string, headers: WebhookSignatureHeaders, rawBody: string, toleranceMs?: number): Promise<boolean>;
+
+export { type Alias, type ApiKey, type AttachmentRef, type BulkJob, type BulkJobCreated, type BulkSendInput, type CreateAliasInput, type CreateRuleInput, type CreateWebhookInput, type Domain, type DomainVerification, type EmailLog, MailMask, type MailMaskConfig, MailMaskError, type Rule, type RuleAction, type RuleField, type RuleMatch, type SendEmailInput, type SendOptions, type SmtpCredential, type SmtpCredentialCreated, type Suppression, type UpdateAliasInput, type UpdateRuleInput, type UpdateWebhookInput, type UploadAttachmentInput, type UploadedAttachment, type Webhook, type WebhookCreated, type WebhookDelivery, type WebhookEvent, type WebhookPayload, type WebhookSignatureHeaders, verifyWebhookSignature };

package/dist/index.js

@@ -7,14 +7,9 @@ var MailMaskError = class extends Error {
   }
 };
 async function request(baseUrl, apiKey, path, opts, doFetch = fetch) {
-  const res = await doFetch(`${baseUrl}${path}`, {
-    ...opts,
-    headers: {
-      "Authorization": `Bearer ${apiKey}`,
-      "Content-Type": "application/json",
-      ...opts?.headers
-    }
-  });
+  const headers = { "Authorization": `Bearer ${apiKey}`, ...opts?.headers };
+  if (!(opts?.body instanceof FormData) && !("Content-Type" in headers)) headers["Content-Type"] = "application/json";
+  const res = await doFetch(`${baseUrl}${path}`, { ...opts, headers });
   if (!res.ok) {
     const body = await res.json().catch(() => ({ error: res.statusText }));
     throw new MailMaskError(res.status, body.error || res.statusText);
@@ -32,6 +27,9 @@ var MailMask = class {
     this.rules = new RulesResource(req);
     this.logs = new LogsResource(req);
     this.send = new SendResource(req);
+    this.attachments = new AttachmentsResource(req);
+    this.suppressions = new SuppressionsResource(req);
+    this.webhooks = new WebhooksResource(req);
     this.smtp = new SmtpResource(req);
     this.apiKeys = new ApiKeysResource(req);
   }
@@ -107,8 +105,10 @@ var SendResource = class {
   constructor(req) {
     this.req = req;
   }
-  send(domainId, input) {
-    return this.req(`/api/domains/${domainId}/send`, { method: "POST", body: JSON.stringify(input) });
+  send(domainId, input, opts) {
+    const headers = {};
+    if (opts?.idempotencyKey) headers["Idempotency-Key"] = opts.idempotencyKey;
+    return this.req(`/api/domains/${domainId}/send`, { method: "POST", body: JSON.stringify(input), headers });
   }
   bulkSend(domainId, input) {
     return this.req(`/api/domains/${domainId}/send-bulk`, { method: "POST", body: JSON.stringify(input) });
@@ -117,6 +117,56 @@ var SendResource = class {
     return this.req(`/api/domains/${domainId}/bulk/${jobId}`);
   }
 };
+var AttachmentsResource = class {
+  constructor(req) {
+    this.req = req;
+  }
+  /** Máx. 5 MB. Ejecutables bloqueados (415). La llave vale hasta que se envía. */
+  upload(domainId, input) {
+    const form = new FormData();
+    const blob = input.data instanceof Blob ? input.data : new Blob([input.data], { type: input.contentType });
+    form.append("file", blob, input.filename);
+    return this.req(`/api/domains/${domainId}/attachments`, { method: "POST", body: form });
+  }
+};
+var SuppressionsResource = class {
+  constructor(req) {
+    this.req = req;
+  }
+  list(domainId) {
+    return this.req(`/api/domains/${domainId}/suppressions`);
+  }
+  add(domainId, email) {
+    return this.req(`/api/domains/${domainId}/suppressions`, { method: "POST", body: JSON.stringify({ email }) });
+  }
+  remove(domainId, email) {
+    return this.req(`/api/domains/${domainId}/suppressions/${encodeURIComponent(email)}`, { method: "DELETE" });
+  }
+};
+var WebhooksResource = class {
+  constructor(req) {
+    this.req = req;
+  }
+  list(domainId) {
+    return this.req(`/api/domains/${domainId}/webhooks`);
+  }
+  create(domainId, input) {
+    return this.req(`/api/domains/${domainId}/webhooks`, { method: "POST", body: JSON.stringify(input) });
+  }
+  update(domainId, webhookId, input) {
+    return this.req(`/api/domains/${domainId}/webhooks/${webhookId}`, { method: "PUT", body: JSON.stringify(input) });
+  }
+  delete(domainId, webhookId) {
+    return this.req(`/api/domains/${domainId}/webhooks/${webhookId}`, { method: "DELETE" });
+  }
+  /** Encola un `ping`; llega en el siguiente minuto. */
+  test(domainId, webhookId) {
+    return this.req(`/api/domains/${domainId}/webhooks/${webhookId}/test`, { method: "POST" });
+  }
+  deliveries(domainId, webhookId) {
+    return this.req(`/api/domains/${domainId}/webhooks/${webhookId}/deliveries`);
+  }
+};
 var SmtpResource = class {
   constructor(req) {
     this.req = req;
@@ -145,7 +195,27 @@ var ApiKeysResource = class {
     return this.req(`/api/api-keys/${id}`, { method: "DELETE" });
   }
 };
+
+// src/verify.ts
+function hex(buf) {
+  return Array.from(new Uint8Array(buf)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function constantTimeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+async function verifyWebhookSignature(secret, headers, rawBody, toleranceMs = 5 * 6e4) {
+  const ts = Number(headers.timestamp);
+  if (!Number.isFinite(ts) || Math.abs(Date.now() - ts) > toleranceMs) return false;
+  const enc = new TextEncoder();
+  const key = await crypto.subtle.importKey("raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const mac = await crypto.subtle.sign("HMAC", key, enc.encode(`${headers.timestamp}.${rawBody}`));
+  return constantTimeEqual(`sha256=${hex(mac)}`, headers.signature);
+}
 export {
   MailMask,
-  MailMaskError
+  MailMaskError,
+  verifyWebhookSignature
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@easybits.cloud/mailmask",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Official SDK for the MailMask email alias/forwarding API",
   "type": "module",
   "main": "./dist/index.cjs",