@visulima/email 1.0.0-alpha.8 → 1.0.0

package/dist/inbound/index.d.ts

@@ -0,0 +1,375 @@
+import { M as MaybePromise } from "../packem_shared/types.d-ejzh-xBP.js";
+import 'node:buffer';
+/**
+* A parsed address from an inbound message.
+*/
+interface InboundAddress {
+  /**
+  * The email address.
+  */
+  email: string;
+  /**
+  * The display name, when present.
+  */
+  name?: string;
+}
+/**
+* An attachment on an inbound message.
+*/
+interface InboundAttachment {
+  /**
+  * The Content-ID, for inline attachments.
+  */
+  cid?: string;
+  /**
+  * Base64-encoded content, when the provider includes it inline.
+  */
+  content?: string;
+  /**
+  * The MIME type.
+  */
+  contentType?: string;
+  /**
+  * The filename.
+  */
+  filename: string;
+  /**
+  * The size in bytes, when reported.
+  */
+  size?: number;
+}
+/**
+* A normalized inbound email, produced from any provider's inbound webhook/event payload.
+*
+* This is the common shape every `parse*Inbound` adapter maps onto, so downstream code is
+* provider-agnostic.
+*/
+interface InboundEmail {
+  /**
+  * Attachments included on the message.
+  */
+  attachments: InboundAttachment[];
+  /**
+  * Blind carbon-copy recipients.
+  */
+  bcc: InboundAddress[];
+  /**
+  * Carbon-copy recipients.
+  */
+  cc: InboundAddress[];
+  /**
+  * The sender.
+  */
+  from?: InboundAddress;
+  /**
+  * All headers, keyed by lower-cased name.
+  */
+  headers: Record<string, string>;
+  /**
+  * The HTML body, when present.
+  */
+  html?: string;
+  /**
+  * The `In-Reply-To` header value (a Message-ID), when present.
+  */
+  inReplyTo?: string;
+  /**
+  * The canonical `Message-ID` of this message, when present.
+  */
+  messageId?: string;
+  /**
+  * The provider this message was parsed from.
+  */
+  provider: string;
+  /**
+  * The raw payload the adapter received, for provider-specific fields.
+  */
+  raw?: unknown;
+  /**
+  * Message-IDs from the `References` header, oldest first.
+  */
+  references: string[];
+  /**
+  * The `Reply-To` address, when present.
+  */
+  replyTo?: InboundAddress;
+  /**
+  * The subject line.
+  */
+  subject?: string;
+  /**
+  * The plain-text body, when present.
+  */
+  text?: string;
+  /**
+  * Primary (`To`) recipients.
+  */
+  to: InboundAddress[];
+}
+/**
+* The inbound providers {@link parseInbound} can normalize.
+*/
+type InboundProvider = "cloudflare" | "mailgun" | "postmark" | "sendgrid" | "ses";
+/**
+* Normalizes a provider-specific inbound webhook payload into the common {@link InboundEmail} shape.
+* @param provider The provider the payload came from.
+* @param payload The raw (already JSON/form-decoded) payload.
+* @returns The normalized inbound email.
+*/
+declare const parseInbound: (provider: InboundProvider, payload: unknown) => InboundEmail;
+/**
+* Options for {@link defineInboundHandler}.
+*/
+interface InboundHandlerOptions {
+  /**
+  * Invoked when a payload fails to parse or `onMessage` throws. When omitted, the error propagates.
+  * @param error The thrown error.
+  * @param provider The provider being handled.
+  * @param payload The offending payload.
+  */
+  onError?: (error: unknown, provider: InboundProvider, payload: unknown) => MaybePromise<void>;
+  /**
+  * Invoked with each normalized inbound message.
+  * @param email The normalized inbound email.
+  */
+  onMessage: (email: InboundEmail) => MaybePromise<void>;
+  /**
+  * Strip quoted history from the plain-text body (via {@link extractReply}) before `onMessage`.
+  * @default false
+  */
+  stripReply?: boolean;
+}
+/**
+* A unified inbound handler created by {@link defineInboundHandler}.
+*/
+interface InboundHandler {
+  /**
+  * Parses a provider payload, optionally strips quoted history, and dispatches it to `onMessage`.
+  * @param provider The provider the payload came from.
+  * @param payload The raw payload.
+  * @returns The normalized email, or `undefined` when an error was handled by `onError`.
+  */
+  handle: (provider: InboundProvider, payload: unknown) => Promise<InboundEmail | undefined>;
+}
+/**
+* Creates a single inbound entry point over the five provider parsers — parse, optionally strip the
+* reply quote, then dispatch to your `onMessage` callback.
+* @param options Handler options. See {@link InboundHandlerOptions}.
+* @returns The handler. See {@link InboundHandler}.
+* @example
+* ```ts
+* const handler = defineInboundHandler({ stripReply: true, onMessage: (email) => saveReply(email) });
+*
+* app.post("/inbound/postmark", async (req) => { await handler.handle("postmark", req.body); });
+* ```
+*/
+declare const defineInboundHandler: (options: InboundHandlerOptions) => InboundHandler;
+/**
+* The shape of a Cloudflare Email Workers message, narrowed to what the parser reads.
+*
+* Cloudflare delivers a `ForwardableEmailMessage` with `from`, `to`, and a `Headers` object; the body
+* arrives as a raw stream you must parse yourself, so pass the decoded `text`/`html` alongside it.
+*/
+interface CloudflareEmailLike {
+  from?: string;
+  headers?: Headers | Record<string, string>;
+  html?: string;
+  text?: string;
+  to?: string;
+}
+/**
+* Parses a [Cloudflare Email Workers](https://developers.cloudflare.com/email-routing/email-workers/)
+* message into the normalized {@link InboundEmail} shape.
+*
+* Because Cloudflare exposes the body only as a raw stream, decode it first and pass the result via
+* `text`/`html`.
+* @param message The Cloudflare email message (plus optionally the decoded body).
+* @returns The normalized inbound email.
+*/
+declare const parseCloudflareInbound: (message: CloudflareEmailLike) => InboundEmail;
+interface MailgunInboundPayload {
+  [key: string]: unknown;
+  "body-html"?: string;
+  "body-plain"?: string;
+  cc?: string;
+  from?: string;
+  "message-headers"?: [string, string][] | string;
+  "Message-Id"?: string;
+  recipient?: string;
+  sender?: string;
+  "stripped-html"?: string;
+  "stripped-text"?: string;
+  subject?: string;
+  To?: string;
+}
+/**
+* Parses a [Mailgun inbound](https://documentation.mailgun.com/docs/mailgun/user-manual/receive-forward-store/)
+* route payload into the normalized {@link InboundEmail} shape.
+* @param payload The parsed form fields of the Mailgun inbound request.
+* @returns The normalized inbound email.
+*/
+declare const parseMailgunInbound: (payload: MailgunInboundPayload) => InboundEmail;
+interface PostmarkFullAddress {
+  Email?: string;
+  Name?: string;
+}
+interface PostmarkInboundPayload {
+  [key: string]: unknown;
+  Attachments?: {
+    Content?: string;
+    ContentID?: string;
+    ContentLength?: number;
+    ContentType?: string;
+    Name?: string;
+  }[];
+  BccFull?: PostmarkFullAddress[];
+  CcFull?: PostmarkFullAddress[];
+  FromFull?: PostmarkFullAddress;
+  Headers?: {
+    Name?: string;
+    Value?: string;
+  }[];
+  HtmlBody?: string;
+  MessageID?: string;
+  ReplyTo?: string;
+  Subject?: string;
+  TextBody?: string;
+  ToFull?: PostmarkFullAddress[];
+}
+/**
+* Parses a [Postmark inbound](https://postmarkapp.com/developer/webhooks/inbound-webhook) webhook
+* payload into the normalized {@link InboundEmail} shape.
+* @param payload The parsed JSON body of the Postmark inbound webhook.
+* @returns The normalized inbound email.
+*/
+declare const parsePostmarkInbound: (payload: PostmarkInboundPayload) => InboundEmail;
+interface SendGridInboundPayload {
+  [key: string]: unknown;
+  cc?: string;
+  from?: string;
+  headers?: string;
+  html?: string;
+  subject?: string;
+  text?: string;
+  to?: string;
+}
+/**
+* Parses a [SendGrid Inbound Parse](https://www.twilio.com/docs/sendgrid/for-developers/parsing-email/setting-up-the-inbound-parse-webhook)
+* payload (the multipart fields, already decoded into an object) into the normalized
+* {@link InboundEmail} shape.
+* @param payload The decoded Inbound Parse fields.
+* @returns The normalized inbound email.
+*/
+declare const parseSendGridInbound: (payload: SendGridInboundPayload) => InboundEmail;
+interface SesCommonHeaders {
+  cc?: string[];
+  from?: string[];
+  messageId?: string;
+  replyTo?: string[];
+  subject?: string;
+  to?: string[];
+}
+interface SesMail {
+  commonHeaders?: SesCommonHeaders;
+  headers?: {
+    name?: string;
+    value?: string;
+  }[];
+  messageId?: string;
+  source?: string;
+}
+interface SesInboundPayload {
+  [key: string]: unknown;
+  content?: string;
+  html?: string;
+  mail?: SesMail;
+  text?: string;
+}
+/**
+* Parses an [Amazon SES inbound](https://docs.aws.amazon.com/ses/latest/dg/receiving-email-action-lambda.html)
+* notification (the `mail` object, typically delivered via SNS/Lambda) into the normalized
+* {@link InboundEmail} shape.
+*
+* SES does not include the decoded body in the notification — fetch it from S3 (or pass it directly)
+* and supply it via `text`/`html`.
+* @param payload The SES notification, with optional decoded body.
+* @returns The normalized inbound email.
+*/
+declare const parseSesInbound: (payload: SesInboundPayload) => InboundEmail;
+/**
+* Options for {@link extractReply}.
+*/
+interface ExtractReplyOptions {
+  /**
+  * Also strip a trailing signature block (everything after a `-- ` delimiter line).
+  * @default true
+  */
+  stripSignature?: boolean;
+}
+/**
+* Extracts the new reply text from a plain-text email body, stripping quoted history and (optionally)
+* the trailing signature.
+*
+* Uses the same heuristics email clients use: quote markers (`>`), localized attribution lines
+* (EN/DE/FR/ES/TR), Outlook/`Original Message` separators, and the RFC 3676 `-- ` signature delimiter.
+* @param text The plain-text body.
+* @param options Extraction options. See {@link ExtractReplyOptions}.
+* @returns The trimmed reply text with quoted history removed.
+*/
+declare const extractReply: (text: string, options?: ExtractReplyOptions) => string;
+/**
+* A group of inbound messages belonging to the same conversation.
+*/
+interface EmailThread {
+  /**
+  * A stable identifier for the thread: the union-find root, which is a normalized root Message-ID
+  * or a synthetic `__index_&lt;n>` key when a message has no Message-ID.
+  */
+  id: string;
+  /**
+  * The messages in the thread. Order reflects input order (callers can sort by date if needed).
+  */
+  messages: InboundEmail[];
+}
+/**
+* Strips angle brackets and surrounding whitespace from a Message-ID for consistent matching.
+* @param id A raw Message-ID, optionally wrapped in angle brackets.
+* @returns The bare Message-ID.
+*/
+declare const normalizeMessageId: (id: string) => string;
+/**
+* Normalizes a subject for fallback threading: strips leading `Re:`/`Fwd:`/`Aw:`/`Wg:` prefixes and
+* collapses whitespace. Uses a linear loop rather than a backtracking regex.
+* @param subject The raw subject.
+* @returns The normalized subject key.
+*/
+declare const normalizeSubject: (subject: string) => string;
+/**
+* Groups inbound messages into conversation threads.
+*
+* Messages are linked via their `In-Reply-To` and `References` Message-IDs (RFC 5322 threading).
+* Messages that share no references but have an identical normalized subject are stitched together as
+* a fallback, matching how mail clients group conversations.
+* @param messages The inbound messages to thread.
+* @returns The detected threads. See {@link EmailThread}.
+*/
+declare const stitchThreads: (messages: InboundEmail[]) => EmailThread[];
+/**
+* Parses a single RFC 5322 address such as `John Doe &lt;john@example.com>` or `john@example.com`.
+* @param value The address string.
+* @returns The parsed address, or `undefined` when empty.
+*/
+declare const parseAddress: (value: string | undefined | null) => InboundAddress | undefined;
+/**
+* Splits and parses a comma-separated address list, respecting commas inside quoted display names.
+* @param value The address-list string.
+* @returns The parsed addresses (empty when none).
+*/
+declare const parseAddressList: (value: string | undefined | null) => InboundAddress[];
+/**
+* Splits a `References` header value into individual Message-IDs.
+* @param value The raw `References` header.
+* @returns The Message-IDs in document order (oldest first).
+*/
+declare const parseReferences: (value: string | undefined | null) => string[];
+export { type CloudflareEmailLike, type EmailThread, type ExtractReplyOptions, type InboundAddress, type InboundAttachment, type InboundEmail, type InboundHandler, type InboundHandlerOptions, type InboundProvider, defineInboundHandler, extractReply, normalizeMessageId, normalizeSubject, parseAddress, parseAddressList, parseCloudflareInbound, parseInbound, parseMailgunInbound, parsePostmarkInbound, parseReferences, parseSendGridInbound, parseSesInbound, stitchThreads };

package/dist/inbound/index.js

@@ -0,0 +1 @@
+import{defineInboundHandler as o,parseInbound as a}from"../packem_shared/defineInboundHandler-CnL2BzlL.js";import{default as d}from"../packem_shared/parseCloudflareInbound-C__j-oNa.js";import{default as t}from"../packem_shared/parseMailgunInbound-BpC6uPNe.js";import{default as f}from"../packem_shared/parsePostmarkInbound-Co3_c6-9.js";import{default as l}from"../packem_shared/parseSendGridInbound-DsALoijO.js";import{default as x}from"../packem_shared/parseSesInbound-CH5tHIjp.js";import{extractReply as I}from"../packem_shared/extractReply-BUjIBt9A.js";import{normalizeMessageId as c,normalizeSubject as S,stitchThreads as g}from"../packem_shared/normalizeMessageId-DAx2pGe2.js";import{parseAddress as z,parseAddressList as A,parseReferences as M}from"../packem_shared/parseAddress-DdbViBAJ.js";export{o as defineInboundHandler,I as extractReply,c as normalizeMessageId,S as normalizeSubject,z as parseAddress,A as parseAddressList,d as parseCloudflareInbound,a as parseInbound,t as parseMailgunInbound,f as parsePostmarkInbound,M as parseReferences,l as parseSendGridInbound,x as parseSesInbound,g as stitchThreads};

package/dist/index.d.ts

@@ -1,9 +1,94 @@
-export { type AttachmentDataOptions, type AttachmentOptions, detectMimeType, generateContentId, readFileAsBuffer } from "./attachment-helpers.d.ts";
-export { default as EmailError } from "./errors/email-error.d.ts";
-export { default as RequiredOptionError } from "./errors/required-option-error.d.ts";
-export { createMail, Mail, type MailGlobalConfig, type SendableMessage } from "./mail.d.ts";
-export { default as MailMessage } from "./mail-message.d.ts";
-export type { Provider, ProviderFactory } from "./providers/provider.d.ts";
-export { defineProvider } from "./providers/provider.d.ts";
-export type { TemplateRenderer } from "./template-engines/types.d.ts";
-export type { Attachment, BaseConfig, CalendarEventOptions, EmailAddress, EmailHeaders, EmailOptions, EmailResult, EmailTag, FeatureFlags, ImmutableHeaders, MaybePromise, Priority, Receipt, Result, } from "./types.d.ts";
+export { type A as AttachmentDataOptions, type a as AttachmentOptions, type B as BatchBase, type b as BatchRenderer, D as DraftMailMessage, type F as FeatureCheckMode, M as Mail, type c as MailGlobalConfig, d as MailMessage, type e as MailOptions, type P as Personalization, type S as SendBatchOptions, type f as SendableMessage, g as createMail, h as detectMimeType, i as generateContentId, r as readFileAsBuffer } from "./packem_shared/mail.d-B9SSqyy0.js";
+export type { M as Middleware, S as SendFunction } from "./packem_shared/types.d-Mpu0HZoG.js";
+export { type a as Provider, type P as ProviderFactory, d as defineProvider } from "./packem_shared/provider.d-J-y6iogK.js";
+export type { T as TemplateRenderer } from "./packem_shared/types.d-nyR1ty1Q.js";
+export type { A as Attachment, B as BaseConfig, C as CalendarEventOptions, c as EmailAddress, e as EmailHeaders, E as EmailOptions, a as EmailResult, d as EmailTag, F as FeatureFlags, I as ImmutableHeaders, M as MaybePromise, P as Priority, b as Receipt, R as Result } from "./packem_shared/types.d-ejzh-xBP.js";
+export { default as parseEml } from "./utils/parse-eml.js";
+export { type OkResult, isErr, isOk, mapOk, tryAsync, unwrap, unwrapOr } from "./utils/result.js";
+export { type FeatureSupportResult, type FeatureViolation, default as checkFeatureSupport } from "./utils/validation/check-feature-support.js";
+import 'ical-generator';
+import 'node:buffer';
+import 'node:crypto';
+import "./packem_shared/types.d-BId55FW2.js";
+interface ErrorProperties {
+  cause?: unknown;
+  hint?: ErrorHint;
+  location?: ErrorLocation;
+  message?: string;
+  name: string;
+  stack?: string;
+  title?: string;
+}
+interface ErrorLocation {
+  column?: number;
+  file?: string;
+  line?: number;
+}
+/**
+* A message that explains to the user how they can fix the error.
+* @example
+* ```ts
+* const error = new VisulimaError({
+*    hint: "Try running `npm install` to install missing dependencies.",
+*    location: {
+*    file: "src/index.ts",
+*    line: 1,
+*    column: 1,
+*    },
+*    message: "Cannot find module 'react'",
+*    name: "ModuleNotFoundError",
+* });
+* ```
+*
+* For more complex hints, you can pass an array of strings or a single string in markdown format.
+*/
+type ErrorHint = string[] | string;
+declare class VisulimaError extends Error {
+  loc: ErrorLocation | undefined;
+  title: string | undefined;
+  /**
+  * A message that explains to the user how they can fix the error.
+  */
+  hint: ErrorHint | undefined;
+  type: string;
+  constructor({
+    cause,
+    hint,
+    location,
+    message,
+    name,
+    stack,
+    title
+  }: ErrorProperties);
+  setLocation(location: ErrorLocation): void;
+  setName(name: string): void;
+  setMessage(message: string): void;
+  setHint(hint: ErrorHint): void;
+}
+/**
+* Will return an array of all causes in the error in the order they occurred.
+*/
+/**
+* Base error class for email package operations.
+* @param component The component name where the error occurred.
+* @param message The error message describing what went wrong.
+* @param options Optional error options including cause, code, and hint.
+*/
+declare class EmailError extends VisulimaError {
+  readonly component: string;
+  readonly code?: string;
+  constructor(component: string, message: string, options?: {
+    cause?: Error | unknown;
+    code?: string;
+    hint?: string | string[];
+  });
+}
+/**
+* Error for missing required options
+* @param component The component name where the error occurred
+* @param name The name(s) of the missing required option(s)
+*/
+declare class RequiredOptionError extends EmailError {
+  constructor(component: string, name: string | string[]);
+}
+export { EmailError, RequiredOptionError };

package/dist/index.js

@@ -1 +1 @@
-import{detectMimeType as o,generateContentId as t,readFileAsBuffer as a}from"./packem_shared/detectMimeType-S8WRsNtY.js";import{default as i}from"./packem_shared/EmailError-zm2ffVav.js";import{default as m}from"./packem_shared/RequiredOptionError-CevW3u2K.js";import{Mail as l,createMail as x}from"./packem_shared/Mail-6Bltpy_p.js";import{MailMessage as s}from"./packem_shared/MailMessage-B76GPBBA.js";import{defineProvider as u}from"./packem_shared/defineProvider-B9rSklAJ.js";export{i as EmailError,l as Mail,s as MailMessage,m as RequiredOptionError,x as createMail,u as defineProvider,o as detectMimeType,t as generateContentId,a as readFileAsBuffer};
+import{detectMimeType as a,generateContentId as t,readFileAsBuffer as o}from"./packem_shared/detectMimeType-Dxv4MjZ7.js";import{default as p}from"./packem_shared/DraftMailMessage-BxqGSLMN.js";import{default as m}from"./packem_shared/EmailError-B-sEf3bp.js";import{default as l}from"./packem_shared/RequiredOptionError-DuNNY_a5.js";import{Mail as u,createMail as x}from"./packem_shared/Mail-BEuzrB00.js";import{default as M}from"./packem_shared/MailMessage-D9k5gYrd.js";import{defineProvider as E}from"./packem_shared/defineProvider-C9q-7iwt.js";import{default as g}from"./utils/parse-eml.js";import{isErr as y,isOk as w,mapOk as A,tryAsync as F,unwrap as h,unwrapOr as q}from"./utils/result.js";import{default as B}from"./utils/validation/check-feature-support.js";export{p as DraftMailMessage,m as EmailError,u as Mail,M as MailMessage,l as RequiredOptionError,B as checkFeatureSupport,x as createMail,E as defineProvider,a as detectMimeType,t as generateContentId,y as isErr,w as isOk,A as mapOk,g as parseEml,o as readFileAsBuffer,F as tryAsync,h as unwrap,q as unwrapOr};