@visulima/email 1.0.0-alpha.9 → 1.0.0

package/dist/webhooks/index.d.ts

@@ -0,0 +1,231 @@
+/**
+* Result of verifying an inbound webhook signature.
+*/
+interface WebhookVerificationResult {
+  /**
+  * Machine-readable reason when {@link WebhookVerificationResult.valid} is `false`.
+  */
+  reason?: string;
+  /**
+  * Whether the signature (and, when applicable, the timestamp) is valid.
+  */
+  valid: boolean;
+}
+/**
+* Headers passed to a webhook verifier. Either a plain record or a `Headers` instance.
+*
+* Lookups are case-insensitive.
+*/
+type WebhookHeaders = Headers | Record<string, string | string[] | undefined>;
+/**
+* Shared options for verifiers that enforce a timestamp tolerance to guard against replay attacks.
+*/
+interface TimestampToleranceOptions {
+  /**
+  * Maximum allowed difference, in seconds, between the signed timestamp and the current time.
+  *
+  * Set to `0` to disable the replay-protection window.
+  * @default 300
+  */
+  tolerance?: number;
+}
+/**
+* Options for {@link verifyMailgunWebhook}.
+*
+* Mailgun nests these three fields under a `signature` object in the webhook JSON body.
+*/
+interface MailgunWebhookOptions extends TimestampToleranceOptions {
+  /**
+  * Override the current time (milliseconds) — primarily for testing.
+  */
+  now?: number;
+  /**
+  * The HMAC value from `signature.signature`.
+  */
+  signature: string;
+  /**
+  * Your Mailgun HTTP webhook signing key (Settings → Webhooks).
+  */
+  signingKey: string;
+  /**
+  * The timestamp from `signature.timestamp` (unix seconds, as a string or number).
+  */
+  timestamp: number | string;
+  /**
+  * The token from `signature.token`.
+  */
+  token: string;
+}
+/**
+* Verifies a [Mailgun](https://documentation.mailgun.com/docs/mailgun/user-manual/tracking-messages/#webhooks) webhook.
+*
+* Mailgun computes `HMAC-SHA256(key = signingKey, message = timestamp + token)` and sends the hex
+* digest as `signature.signature`.
+* @param options Verification inputs. See {@link MailgunWebhookOptions}.
+* @returns The verification result.
+*/
+declare const verifyMailgunWebhook: (options: MailgunWebhookOptions) => WebhookVerificationResult;
+/**
+* Options for {@link verifyPostmarkWebhook}.
+*
+* Postmark does not sign webhook payloads; instead it supports HTTP Basic Auth credentials embedded
+* in the webhook URL (and IP allow-listing). This verifier checks the Basic Auth credentials.
+*/
+interface PostmarkWebhookOptions {
+  /**
+  * The value of the incoming `Authorization` header (e.g. `Basic dXNlcjpwYXNz`).
+  */
+  authorization: string | undefined;
+  /**
+  * The password configured on the Postmark webhook URL.
+  */
+  password: string;
+  /**
+  * The username configured on the Postmark webhook URL.
+  */
+  username: string;
+}
+/**
+* Verifies a [Postmark](https://postmarkapp.com/support/article/1213-securing-inbound-and-open-webhooks)
+* webhook by validating its HTTP Basic Auth credentials.
+* @param options Verification inputs. See {@link PostmarkWebhookOptions}.
+* @returns The verification result.
+*/
+declare const verifyPostmarkWebhook: (options: PostmarkWebhookOptions) => WebhookVerificationResult;
+/**
+* Options for {@link verifySendGridWebhook}.
+*/
+interface SendGridWebhookOptions extends TimestampToleranceOptions {
+  /**
+  * Override the current time (milliseconds) — primarily for testing.
+  */
+  now?: number;
+  /**
+  * The raw, unparsed request body exactly as received.
+  */
+  payload: string;
+  /**
+  * The verification key from the SendGrid Event Webhook settings.
+  *
+  * Either the base64-encoded DER (SPKI) string SendGrid displays, or a full PEM block.
+  */
+  publicKey: string;
+  /**
+  * The value of the `X-Twilio-Email-Event-Webhook-Signature` header (base64 DER ECDSA signature).
+  */
+  signature: string;
+  /**
+  * The value of the `X-Twilio-Email-Event-Webhook-Timestamp` header (unix epoch seconds).
+  */
+  timestamp: string;
+}
+/**
+* Verifies a [SendGrid Event Webhook](https://www.twilio.com/docs/sendgrid/for-developers/tracking-events/getting-started-event-webhook-security-features)
+* using its ECDSA (prime256v1) signature, and rejects stale requests to prevent replay.
+*
+* The signed message is `timestamp + payload`. The signature header is the base64-encoded DER
+* ECDSA signature. The timestamp is unix epoch seconds and must fall within `tolerance` of now.
+* @param options Verification inputs. See {@link SendGridWebhookOptions}.
+* @returns The verification result.
+* @throws {EmailError} When the supplied public key cannot be parsed.
+*/
+declare const verifySendGridWebhook: (options: SendGridWebhookOptions) => WebhookVerificationResult;
+/**
+* The subset of an Amazon SNS message envelope relevant to signature verification.
+*
+* AWS SES delivers events (deliveries, bounces, complaints) wrapped in SNS notifications.
+*/
+interface SnsMessage {
+  [key: string]: unknown;
+  Message?: string;
+  MessageId?: string;
+  Signature?: string;
+  SignatureVersion?: string;
+  SigningCertURL?: string;
+  Subject?: string;
+  SubscribeURL?: string;
+  Timestamp?: string;
+  Token?: string;
+  TopicArn?: string;
+  Type?: string;
+}
+/**
+* Resolves a signing-certificate URL to its PEM contents. Injectable for testing and caching.
+*/
+type CertificateResolver = (url: string) => Promise<string> | string;
+/**
+* Options for {@link verifySnsMessage}.
+*/
+interface SnsVerifyOptions {
+  /**
+  * Override how the signing certificate is fetched. Defaults to a `fetch`-based resolver that
+  * only accepts `https://*.amazonaws.com` URLs.
+  */
+  certificateResolver?: CertificateResolver;
+}
+/**
+* Validates that a signing-certificate URL points at an AWS SNS signing host over HTTPS.
+* @param url The `SigningCertURL` from the SNS message.
+* @returns `true` when the URL is an acceptable AWS SNS certificate endpoint.
+*/
+declare const isValidSigningCertUrl: (url: string) => boolean;
+/**
+* Verifies the RSA signature on an Amazon SNS message (used to wrap AWS SES events).
+*
+* Signature version `1` uses SHA1, version `2` uses SHA256. The signing certificate is fetched from
+* `SigningCertURL` (validated to be an `sns.&lt;region>.amazonaws.com` HTTPS endpoint with no userinfo
+* or explicit port) unless a custom {@link CertificateResolver} is supplied.
+* @param message The parsed SNS message envelope.
+* @param options Optional overrides. See {@link SnsVerifyOptions}.
+* @returns The verification result.
+* @throws {EmailError} When the certificate cannot be resolved.
+*/
+declare const verifySnsMessage: (message: SnsMessage, options?: SnsVerifyOptions) => Promise<WebhookVerificationResult>;
+/**
+* Options for {@link verifyStandardWebhook}.
+*/
+interface StandardWebhookOptions extends TimestampToleranceOptions {
+  /**
+  * The request headers, or the three signature headers as a plain record.
+  *
+  * Recognized header names (case-insensitive): `webhook-id` / `svix-id`,
+  * `webhook-timestamp` / `svix-timestamp`, and `webhook-signature` / `svix-signature`.
+  */
+  headers: WebhookHeaders;
+  /**
+  * Override the current time (milliseconds) — primarily for testing.
+  */
+  now?: number;
+  /**
+  * The raw, unparsed request body exactly as received.
+  *
+  * Parsing and re-serializing the body changes the bytes and breaks verification.
+  */
+  payload: string;
+  /**
+  * The signing secret. Supports the `whsec_`-prefixed, base64-encoded form used by Svix/Resend,
+  * or a raw secret string.
+  */
+  secret: string;
+}
+/**
+* Verifies a webhook signed according to the [Standard Webhooks](https://www.standardwebhooks.com/) spec.
+*
+* This is the scheme used by Svix and, by extension, Resend. The signed content is
+* `${id}.${timestamp}.${payload}`, HMAC-SHA256'd with the (base64-decoded) secret and base64-encoded.
+* The `webhook-signature` header may contain multiple space-separated `v1,&lt;sig>` entries; a match
+* against any one of them passes.
+* @param options Verification inputs. See {@link StandardWebhookOptions}.
+* @returns The verification result.
+*/
+declare const verifyStandardWebhook: (options: StandardWebhookOptions) => WebhookVerificationResult;
+/**
+* Verifies a [Resend](https://resend.com/docs/dashboard/webhooks/verify-webhooks-requests) webhook.
+*
+* Resend uses Svix, so this is an alias for {@link verifyStandardWebhook} that accepts the
+* `svix-*` headers.
+* @param options Verification inputs. See {@link StandardWebhookOptions}.
+* @returns The verification result.
+*/
+declare const verifyResendWebhook: (options: StandardWebhookOptions) => WebhookVerificationResult;
+export { type CertificateResolver, type MailgunWebhookOptions, type PostmarkWebhookOptions, type SendGridWebhookOptions, type SnsMessage, type SnsVerifyOptions, type StandardWebhookOptions, type TimestampToleranceOptions, type WebhookHeaders, type WebhookVerificationResult, isValidSigningCertUrl, verifyMailgunWebhook, verifyPostmarkWebhook, verifyResendWebhook, verifySendGridWebhook, verifySnsMessage, verifyStandardWebhook };

package/dist/webhooks/index.js

@@ -0,0 +1 @@
+import{verifyMailgunWebhook as r}from"../packem_shared/verifyMailgunWebhook-Cwl0OD3P.js";import{verifyPostmarkWebhook as f}from"../packem_shared/verifyPostmarkWebhook-C72ZvbrG.js";import{verifySendGridWebhook as n}from"../packem_shared/verifySendGridWebhook-Dbwc1tfG.js";import{isValidSigningCertUrl as d,verifySnsMessage as k}from"../packem_shared/isValidSigningCertUrl-Bii1AMGC.js";import{verifyResendWebhook as s,verifyStandardWebhook as v}from"../packem_shared/verifyResendWebhook-YK2zNDXR.js";export{d as isValidSigningCertUrl,r as verifyMailgunWebhook,f as verifyPostmarkWebhook,s as verifyResendWebhook,n as verifySendGridWebhook,k as verifySnsMessage,v as verifyStandardWebhook};

package/package.json

@@ -1,57 +1,68 @@
 {
   "name": "@visulima/email",
-  "version": "1.0.0-alpha.9",
+  "version": "1.0.0",
   "description": "A comprehensive email library with multi-provider support, crypto utilities, and template engines",
   "keywords": [
-    "visulima",
-    "email",
-    "mail",
-    "better-mail",
-    "smtp",
-    "resend",
+    "ahasend",
+    "arc",
     "aws-ses",
-    "zeptomail",
-    "http",
+    "azure",
+    "batch",
+    "better-mail",
+    "brevo",
+    "crypto",
+    "deliverability",
+    "dkim",
+    "dmarc",
+    "email",
+    "encryption",
+    "i18n",
+    "inbound-email",
+    "jsx-email",
+    "liquid",
+    "list-unsubscribe",
+    "middleware",
+    "queue",
+    "webhook",
     "failover",
-    "roundrobin",
+    "handlebars",
+    "html-to-text",
+    "http",
+    "infobip",
+    "mail",
     "mailcrab",
-    "nodemailer",
-    "opentelemetry",
-    "plunk",
-    "mock",
-    "sendgrid",
+    "mailersend",
     "mailgun",
-    "postmark",
-    "brevo",
     "mailjet",
-    "mailersend",
+    "mailomat",
+    "mailpace",
+    "mailtrap",
     "mandrill",
+    "mjml",
+    "mock",
+    "netcore",
+    "nodemailer",
+    "opentelemetry",
+    "outlook365",
+    "plunk",
     "postal",
-    "mailtrap",
-    "mailpace",
-    "azure",
-    "infobip",
+    "postmark",
+    "sparkpost",
+    "react-email",
+    "resend",
+    "roundrobin",
     "scaleway",
-    "ahasend",
-    "mailomat",
-    "sweego",
-    "dkim",
-    "smime",
-    "encryption",
+    "sendgrid",
     "signing",
-    "crypto",
-    "disposable-email",
-    "disposable-email-domains",
-    "handlebars",
-    "mjml",
-    "react-email",
+    "smime",
+    "smtp",
+    "sweego",
+    "visulima",
     "vue-email",
-    "html-to-text"
+    "zeptomail"
   ],
   "homepage": "https://visulima.com/packages/email",
-  "bugs": {
-    "url": "https://github.com/visulima/visulima/issues"
-  },
+  "bugs": "https://github.com/visulima/visulima/issues",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/visulima/visulima.git",
@@ -99,6 +110,18 @@
       "types": "./dist/template-engines/html-to-text.d.ts",
       "default": "./dist/template-engines/html-to-text.js"
     },
+    "./template/liquid": {
+      "types": "./dist/template-engines/liquid.d.ts",
+      "default": "./dist/template-engines/liquid.js"
+    },
+    "./template/jsx-email": {
+      "types": "./dist/template-engines/jsx-email.d.ts",
+      "default": "./dist/template-engines/jsx-email.js"
+    },
+    "./template/i18n": {
+      "types": "./dist/template-engines/i18n.d.ts",
+      "default": "./dist/template-engines/i18n.js"
+    },
     "./providers/aws-ses": {
       "types": "./dist/providers/aws-ses/index.d.ts",
       "default": "./dist/providers/aws-ses/index.js"
@@ -151,6 +174,58 @@
       "types": "./dist/crypto/index.d.ts",
       "default": "./dist/crypto/index.js"
     },
+    "./render": {
+      "types": "./dist/render/index.d.ts",
+      "default": "./dist/render/index.js"
+    },
+    "./webhooks": {
+      "types": "./dist/webhooks/index.d.ts",
+      "default": "./dist/webhooks/index.js"
+    },
+    "./deliverability": {
+      "types": "./dist/deliverability/index.d.ts",
+      "default": "./dist/deliverability/index.js"
+    },
+    "./deliverability/dmarc-report": {
+      "types": "./dist/deliverability/dmarc-report.d.ts",
+      "default": "./dist/deliverability/dmarc-report.js"
+    },
+    "./inbound": {
+      "types": "./dist/inbound/index.d.ts",
+      "default": "./dist/inbound/index.js"
+    },
+    "./events": {
+      "types": "./dist/events/index.d.ts",
+      "default": "./dist/events/index.js"
+    },
+    "./middleware": {
+      "types": "./dist/middleware/index.d.ts",
+      "default": "./dist/middleware/index.js"
+    },
+    "./queue": {
+      "types": "./dist/queue/index.d.ts",
+      "default": "./dist/queue/index.js"
+    },
+    "./queue/unstorage": {
+      "types": "./dist/queue/unstorage-queue.d.ts",
+      "default": "./dist/queue/unstorage-queue.js"
+    },
+    "./queue/sqs": {
+      "types": "./dist/queue/sqs-queue.d.ts",
+      "default": "./dist/queue/sqs-queue.js"
+    },
+    "./queue/pg-boss": {
+      "types": "./dist/queue/pg-boss-queue.d.ts",
+      "default": "./dist/queue/pg-boss-queue.js"
+    },
+    "./queue/bullmq": {
+      "types": "./dist/queue/bullmq-queue.d.ts",
+      "default": "./dist/queue/bullmq-queue.js"
+    },
+    "./test": {
+      "types": "./dist/test/index.d.ts",
+      "default": "./dist/test/index.js"
+    },
     "./providers/sendgrid": {
       "types": "./dist/providers/sendgrid/index.d.ts",
       "default": "./dist/providers/sendgrid/index.js"
@@ -215,10 +290,42 @@
       "types": "./dist/providers/sweego/index.d.ts",
       "default": "./dist/providers/sweego/index.js"
     },
+    "./providers/mailchannels": {
+      "types": "./dist/providers/mailchannels/index.d.ts",
+      "default": "./dist/providers/mailchannels/index.js"
+    },
+    "./providers/cloudflare-email": {
+      "types": "./dist/providers/cloudflare-email/index.d.ts",
+      "default": "./dist/providers/cloudflare-email/index.js"
+    },
+    "./providers/loops": {
+      "types": "./dist/providers/loops/index.d.ts",
+      "default": "./dist/providers/loops/index.js"
+    },
+    "./providers/sparkpost": {
+      "types": "./dist/providers/sparkpost/index.d.ts",
+      "default": "./dist/providers/sparkpost/index.js"
+    },
+    "./providers/netcore": {
+      "types": "./dist/providers/netcore/index.d.ts",
+      "default": "./dist/providers/netcore/index.js"
+    },
+    "./providers/outlook365": {
+      "types": "./dist/providers/outlook365/index.d.ts",
+      "default": "./dist/providers/outlook365/index.js"
+    },
     "./utils/parse-address": {
       "types": "./dist/utils/parse-address.d.ts",
       "default": "./dist/utils/parse-address.js"
     },
+    "./utils/parse-eml": {
+      "types": "./dist/utils/parse-eml.d.ts",
+      "default": "./dist/utils/parse-eml.js"
+    },
+    "./utils/result": {
+      "types": "./dist/utils/result.d.ts",
+      "default": "./dist/utils/result.js"
+    },
     "./utils/format-email-address": {
       "types": "./dist/utils/format-email-address.d.ts",
       "default": "./dist/utils/format-email-address.js"
@@ -227,29 +334,13 @@
       "types": "./dist/utils/cache.d.ts",
       "default": "./dist/utils/cache.js"
     },
-    "./validation/disposable-email-domains": {
-      "types": "./dist/utils/validation/disposable-email-domains.d.ts",
-      "default": "./dist/utils/validation/disposable-email-domains.js"
-    },
     "./validation/validate-email": {
       "types": "./dist/utils/validation/validate-email.d.ts",
       "default": "./dist/utils/validation/validate-email.js"
     },
-    "./validation/check-mx-records": {
-      "types": "./dist/utils/validation/check-mx-records.d.ts",
-      "default": "./dist/utils/validation/check-mx-records.js"
-    },
-    "./validation/role-accounts": {
-      "types": "./dist/utils/validation/role-accounts.d.ts",
-      "default": "./dist/utils/validation/role-accounts.js"
-    },
-    "./validation/verify-smtp": {
-      "types": "./dist/utils/validation/verify-smtp.d.ts",
-      "default": "./dist/utils/validation/verify-smtp.js"
-    },
-    "./validation/verify-email": {
-      "types": "./dist/utils/validation/verify-email.d.ts",
-      "default": "./dist/utils/validation/verify-email.js"
+    "./validation/check-feature-support": {
+      "types": "./dist/utils/validation/check-feature-support.d.ts",
+      "default": "./dist/utils/validation/check-feature-support.js"
     },
     "./utils/normalize-email-aliases": {
       "types": "./dist/utils/normalize-email-aliases.d.ts",
@@ -263,21 +354,25 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@visulima/disposable-email-domains": "1.0.0-alpha.8",
-    "html-to-text": "^9.0.5",
-    "ical-generator": "^10.0.0",
-    "lru-cache": "^11.2.4",
+    "html-to-text": "^10.0.0",
+    "ical-generator": "11.0.0",
+    "lru-cache": "11.5.1",
     "mime": "^4.1.0"
   },
   "peerDependencies": {
     "@opentelemetry/api": "^1.0.0 || ^2.0.0",
-    "@react-email/render": "^2.0.0",
+    "@react-email/render": "^2.0.9",
     "@vue-email/render": "0.0.9",
-    "asn1js": "^3.0.0",
-    "handlebars": "^4.7.8",
-    "mjml": "^4.15.3",
+    "asn1js": ">=3.0.10",
+    "fast-xml-parser": "^4.5.0",
+    "handlebars": ">=4.7.9",
+    "jsx-email": "^2.0.0",
+    "juice": "^11.0.0",
+    "liquidjs": "^10.0.0",
+    "mjml": ">=5.3.0",
     "nodemailer": ">=7",
-    "pkijs": "^3.0.0"
+    "pkijs": ">=3.4.0",
+    "unstorage": "^1.13.0"
   },
   "peerDependenciesMeta": {
     "@opentelemetry/api": {
@@ -292,9 +387,21 @@
     "asn1js": {
       "optional": true
     },
+    "fast-xml-parser": {
+      "optional": true
+    },
     "handlebars": {
       "optional": true
     },
+    "jsx-email": {
+      "optional": true
+    },
+    "juice": {
+      "optional": true
+    },
+    "liquidjs": {
+      "optional": true
+    },
     "mjml": {
       "optional": true
     },
@@ -303,10 +410,13 @@
     },
     "pkijs": {
       "optional": true
+    },
+    "unstorage": {
+      "optional": true
     }
   },
   "engines": {
-    "node": ">=22.13 <=25.x"
+    "node": "^22.14.0 || >=24.10.0"
   },
   "publishConfig": {
     "access": "public",

package/dist/attachment-helpers.d.ts

@@ -1,64 +0,0 @@
-import type { Buffer } from "node:buffer";
-/**
- * Detects MIME type from filename using mime package.
- * Falls back to application/octet-stream if not found.
- * @param filename The filename or path.
- * @returns MIME type or application/octet-stream as fallback.
- */
-export declare const detectMimeType: (filename: string) => string;
-/**
- * Generates a Content-ID for inline attachments.
- * @param filename The filename to generate CID from.
- * @returns A unique Content-ID string.
- */
-export declare const generateContentId: (filename: string) => string;
-/**
- * Reads file and returns its content as Buffer.
- * @param filePath Path to the file.
- * @returns Buffer containing file content.
- */
-export declare const readFileAsBuffer: (filePath: string) => Promise<Buffer>;
-/**
- * Attachment options for helper methods
- */
-export interface AttachmentOptions {
-    /**
-     * Content-ID for inline attachments (used in HTML with cid:).
-     * If not provided and contentDisposition is 'inline', will be auto-generated.
-     */
-    cid?: string;
-    /**
-     * Content disposition type.
-     * 'attachment' (default) or 'inline'.
-     */
-    contentDisposition?: "attachment" | "inline";
-    /**
-     * MIME type of the attachment.
-     * If not provided, will be detected from filename.
-     */
-    contentType?: string;
-    /**
-     * Content transfer encoding.
-     * Examples: 'base64', '7bit', 'quoted-printable'.
-     */
-    encoding?: string;
-    /**
-     * Custom filename.
-     * Used when different from the file path.
-     */
-    filename?: string;
-    /**
-     * Custom headers for this attachment.
-     */
-    headers?: Record<string, string>;
-}
-/**
- * Attachment data options (for raw data attachments)
- */
-export interface AttachmentDataOptions extends AttachmentOptions {
-    /**
-     * Filename for the attachment.
-     * Required for raw data attachments.
-     */
-    filename: string;
-}

package/dist/crypto/dkim-signer.d.ts

@@ -1,48 +0,0 @@
-import type { EmailOptions } from "../types.d.ts";
-import type { DkimOptions, EmailSigner } from "./types.d.ts";
-/**
- * DKIM signer implementation
- */
-export declare class DkimSigner implements EmailSigner {
-    /**
-     * Sanitizes a display name for use in quoted email headers per RFC 5322.
-     * Removes/replaces CR, LF, tabs with space, escapes backslashes and quotes,
-     * and strips non-printable control characters.
-     * @param name The display name to sanitize.
-     * @returns The sanitized display name, or empty string if nothing remains.
-     */
-    private static sanitizeDisplayName;
-    /**
-     * Formats an email address for use in email headers.
-     * @param address The email address object to format.
-     * @param address.email The email address string.
-     * @param address.name Optional display name for the email address.
-     * @returns The formatted email address string in RFC 5322 format.
-     */
-    private static formatAddress;
-    /**
-     * Formats email addresses for headers.
-     * @param addresses The email address(es) to format (single or array).
-     * @returns The formatted email addresses string (comma-separated if multiple).
-     */
-    private static formatAddresses;
-    private readonly options;
-    /**
-     * Creates a new DKIM signer.
-     * @param options DKIM signing options.
-     */
-    constructor(options: DkimOptions);
-    /**
-     * Signs an email message with DKIM.
-     * @param email The email options to sign.
-     * @returns The email options with DKIM signature header added.
-     * @throws {Error} When signing fails (e.g., invalid private key).
-     */
-    sign(email: EmailOptions): Promise<EmailOptions>;
-}
-/**
- * Creates a DKIM signer instance.
- * @param options DKIM signing options.
- * @returns A new DkimSigner instance.
- */
-export declare const createDkimSigner: (options: DkimOptions) => DkimSigner;