@easybits.cloud/mailmask 0.2.1 → 0.3.0

package/README.md

@@ -31,13 +31,36 @@ await mm.send.send(domainId, {
   fromName: "Acme",           // optional display name: Acme <hello@yourdomain.com>
   to: "client@example.com",
   subject: "Welcome!",
-  html: "<p>Thanks for signing up.</p>",
+  html: "<p>Thanks for signing up.</p>", // or `body` (plain text) / `markdown`
 });
 
 // List aliases for a domain
 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.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);
   }
@@ -124,16 +123,20 @@ var LogsResource = class {
   constructor(req) {
     this.req = req;
   }
-  list(domainId) {
-    return this.req(`/api/domains/${domainId}/logs`);
+  /** `limit` por omisión 50, máximo 100. */
+  list(domainId, opts) {
+    const qs = opts?.limit ? `?limit=${encodeURIComponent(opts.limit)}` : "";
+    return this.req(`/api/domains/${domainId}/logs${qs}`);
   }
 };
 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) });
@@ -142,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;
@@ -170,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

@@ -13,7 +13,12 @@ interface Domain {
     domain: string;
     verified: boolean;
     mxConfigured: boolean;
+    registeredViaMailmask: boolean;
     createdAt: string;
+    /** Sólo en `domains.list`: reenvíos del mes en curso. */
+    monthlyForwards?: number;
+    /** Sólo en `domains.list`: tope de reenvíos por hora del plan. */
+    forwardPerHour?: number;
 }
 /** Respuesta de `domains.verify`. */
 interface DomainVerification {
@@ -30,6 +35,8 @@ interface Alias {
     destinations: string[];
     enabled: boolean;
     forwardCount: number;
+    lastFrom?: string | null;
+    lastAt?: string | null;
     createdAt: string;
 }
 interface CreateAliasInput {
@@ -41,31 +48,38 @@ interface UpdateAliasInput {
     enabled?: boolean;
     destinations?: string[];
 }
+type RuleField = "to" | "from" | "subject";
+type RuleMatch = "contains" | "equals" | "regex";
+/** `forward` y `webhook` requieren `target`; `discard` no. */
+type RuleAction = "forward" | "webhook" | "discard";
 interface Rule {
     id: string;
     domainId: string;
-    field: "to" | "from" | "subject";
-    match: string;
+    field: RuleField;
+    match: RuleMatch;
     value: string;
-    action: string;
+    action: RuleAction;
     target: string;
     priority: number;
     enabled: boolean;
     createdAt: string;
 }
 interface CreateRuleInput {
-    field: "to" | "from" | "subject";
-    match: string;
+    field: RuleField;
+    /** Los patrones `regex` se validan al guardar: uno peligroso responde 400. */
+    match: RuleMatch;
     value: string;
-    action: string;
-    target: string;
+    action: RuleAction;
+    /** Destino del `forward` o URL del `webhook`. Se ignora con `discard`. */
+    target?: string;
     priority?: number;
+    enabled?: boolean;
 }
 interface UpdateRuleInput {
-    field?: "to" | "from" | "subject";
-    match?: string;
+    field?: RuleField;
+    match?: RuleMatch;
     value?: string;
-    action?: string;
+    action?: RuleAction;
     target?: string;
     priority?: number;
     enabled?: boolean;
@@ -79,14 +93,16 @@ interface EmailLog {
     subject: string;
     status: string;
     forwardedTo: string;
+    sizeBytes: number;
     error?: string;
 }
 interface SendEmailInput {
     to: string;
     subject: string;
-    /** Al menos uno de `html` o `body`. Con los dos se manda multipart. */
+    /** Al menos uno de `html`, `body` o `markdown`. Con html y body se manda multipart. HTML máx. 100 KB. */
     html?: string;
     body?: string;
+    markdown?: string;
     replyTo?: string;
     /**
      * Parte local de un alias **activo** del dominio. Sin esto el correo sale
@@ -95,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.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[];
@@ -150,6 +247,8 @@ interface SmtpCredentialCreated {
 interface ApiKey {
     id: string;
     name: string;
+    /** Primeros caracteres de la llave, para identificarla en listados. */
+    keyPrefix: string;
     lastUsedAt?: string;
     createdAt: string;
 }
@@ -166,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);
@@ -208,17 +310,52 @@ declare class RulesResource {
 declare class LogsResource {
     private req;
     constructor(req: Req);
-    list(domainId: string): Promise<EmailLog[]>;
+    /** `limit` por omisión 50, máximo 100. */
+    list(domainId: string, opts?: {
+        limit?: number;
+    }): Promise<EmailLog[]>;
 }
 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);
@@ -240,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 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

@@ -13,7 +13,12 @@ interface Domain {
     domain: string;
     verified: boolean;
     mxConfigured: boolean;
+    registeredViaMailmask: boolean;
     createdAt: string;
+    /** Sólo en `domains.list`: reenvíos del mes en curso. */
+    monthlyForwards?: number;
+    /** Sólo en `domains.list`: tope de reenvíos por hora del plan. */
+    forwardPerHour?: number;
 }
 /** Respuesta de `domains.verify`. */
 interface DomainVerification {
@@ -30,6 +35,8 @@ interface Alias {
     destinations: string[];
     enabled: boolean;
     forwardCount: number;
+    lastFrom?: string | null;
+    lastAt?: string | null;
     createdAt: string;
 }
 interface CreateAliasInput {
@@ -41,31 +48,38 @@ interface UpdateAliasInput {
     enabled?: boolean;
     destinations?: string[];
 }
+type RuleField = "to" | "from" | "subject";
+type RuleMatch = "contains" | "equals" | "regex";
+/** `forward` y `webhook` requieren `target`; `discard` no. */
+type RuleAction = "forward" | "webhook" | "discard";
 interface Rule {
     id: string;
     domainId: string;
-    field: "to" | "from" | "subject";
-    match: string;
+    field: RuleField;
+    match: RuleMatch;
     value: string;
-    action: string;
+    action: RuleAction;
     target: string;
     priority: number;
     enabled: boolean;
     createdAt: string;
 }
 interface CreateRuleInput {
-    field: "to" | "from" | "subject";
-    match: string;
+    field: RuleField;
+    /** Los patrones `regex` se validan al guardar: uno peligroso responde 400. */
+    match: RuleMatch;
     value: string;
-    action: string;
-    target: string;
+    action: RuleAction;
+    /** Destino del `forward` o URL del `webhook`. Se ignora con `discard`. */
+    target?: string;
     priority?: number;
+    enabled?: boolean;
 }
 interface UpdateRuleInput {
-    field?: "to" | "from" | "subject";
-    match?: string;
+    field?: RuleField;
+    match?: RuleMatch;
     value?: string;
-    action?: string;
+    action?: RuleAction;
     target?: string;
     priority?: number;
     enabled?: boolean;
@@ -79,14 +93,16 @@ interface EmailLog {
     subject: string;
     status: string;
     forwardedTo: string;
+    sizeBytes: number;
     error?: string;
 }
 interface SendEmailInput {
     to: string;
     subject: string;
-    /** Al menos uno de `html` o `body`. Con los dos se manda multipart. */
+    /** Al menos uno de `html`, `body` o `markdown`. Con html y body se manda multipart. HTML máx. 100 KB. */
     html?: string;
     body?: string;
+    markdown?: string;
     replyTo?: string;
     /**
      * Parte local de un alias **activo** del dominio. Sin esto el correo sale
@@ -95,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.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[];
@@ -150,6 +247,8 @@ interface SmtpCredentialCreated {
 interface ApiKey {
     id: string;
     name: string;
+    /** Primeros caracteres de la llave, para identificarla en listados. */
+    keyPrefix: string;
     lastUsedAt?: string;
     createdAt: string;
 }
@@ -166,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);
@@ -208,17 +310,52 @@ declare class RulesResource {
 declare class LogsResource {
     private req;
     constructor(req: Req);
-    list(domainId: string): Promise<EmailLog[]>;
+    /** `limit` por omisión 50, máximo 100. */
+    list(domainId: string, opts?: {
+        limit?: number;
+    }): Promise<EmailLog[]>;
 }
 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);
@@ -240,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 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);
   }
@@ -97,16 +95,20 @@ var LogsResource = class {
   constructor(req) {
     this.req = req;
   }
-  list(domainId) {
-    return this.req(`/api/domains/${domainId}/logs`);
+  /** `limit` por omisión 50, máximo 100. */
+  list(domainId, opts) {
+    const qs = opts?.limit ? `?limit=${encodeURIComponent(opts.limit)}` : "";
+    return this.req(`/api/domains/${domainId}/logs${qs}`);
   }
 };
 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) });
@@ -115,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;
@@ -143,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.1",
+  "version": "0.3.0",
   "description": "Official SDK for the MailMask email alias/forwarding API",
   "type": "module",
   "main": "./dist/index.cjs",