@suaveplan/email-processing - Universal MIME parsing and email processing: postal-mime + libmime wrappers, attachment processing with SHA-256 hashing + MIME-type allowlists, Content-ID resolution, structured data extraction (iCalendar, delivery tracking, receipts), DKIM/SPF/DMARC verification, spam scoring with pluggable rule sets, conversation threading, hook pipeline + OTel instrumentation

Universal MIME parsing and email processing for the Suaveplan . Wraps postal-mime and libmime with structured errors, OpenTelemetry instrumentation, a hook pipeline for transforming parsed messages, full attachment processing (SHA-256 hashing, MIME allowlists, CID resolution), structured-data extraction (iCalendar, delivery tracking, receipts), DKIM/SPF/DMARC verification, spam scoring, and conversation threading.

Documentation tree

attachment-processor — Normalises and validates EmailAttachment payloads emerging from parseEmail. Each attachment is decoded to bytes, va…
- attachment-processor — Normalises and validates EmailAttachment payloads emerging from parseEmail. Each attachment is decoded to bytes, va…
calendar-parser — Parses iCalendar (RFC 5545) / ICS payloads embedded in emails — these arrive either as text/calendar MIME parts or as…
- calendar-parser — Parses iCalendar (RFC 5545) / ICS payloads embedded in emails — these arrive either as text/calendar MIME parts or as…
cid-resolver — Resolves Content-ID references inside HTML email bodies. Email clients that send inline images embed them as MIME parts…
- cid-resolver — Resolves Content-ID references inside HTML email bodies. Email clients that send inline images embed them as MIME parts…
data-extractor — Extracts structured business signals — calendar events, parcel tracking numbers, and receipt / order data — from the fr…
- data-extractor — Extracts structured business signals — calendar events, parcel tracking numbers, and receipt / order data — from the fr…
dkim-canonicalize — Implements RFC 6376 canonicalisation primitives — the byte-exact text normalisation steps DKIM requires before hashing…
- dkim-canonicalize — Implements RFC 6376 canonicalisation primitives — the byte-exact text normalisation steps DKIM requires before hashing…
dkim-verifier — Implements DKIM (RFC 6376) signature verification — parses a DKIM-Signature header, looks up the signer's public key…
- dkim-verifier — Implements DKIM (RFC 6376) signature verification — parses a DKIM-Signature header, looks up the signer's public key…
dmarc-checker — Implements DMARC (RFC 7489) policy evaluation on top of an upstream SPF result and DKIM verification. Looks up the `_dm…
- dmarc-checker — Implements DMARC (RFC 7489) policy evaluation on top of an upstream SPF result and DKIM verification. Looks up the `_dm…
error-codes — Defines the stable error-code registry and typed error class for the @suaveplan/email-processing package. Every failu…
- error-codes — Defines the stable error-code registry and typed error class for the @suaveplan/email-processing package. Every failu…
hooks — Implements the package's email:processing hook pipeline: every parsed email passes through a sequence of handlers tha…
- hooks — Implements the package's email:processing hook pipeline: every parsed email passes through a sequence of handlers tha…
mime-utils — Wraps the libmime library with a strict, typed boundary so the rest of the package can call RFC 2047 / 2231 / 5322 en…
- mime-utils — Wraps the libmime library with a strict, typed boundary so the rest of the package can call RFC 2047 / 2231 / 5322 en…
parser — Wraps postal-mime with a strict input/option boundary, OTel instrumentation, structured error codes, and the `@suavep…
- parser — Wraps postal-mime with a strict input/option boundary, OTel instrumentation, structured error codes, and the `@suavep…
spam-scorer — Heuristic spam scorer with a pluggable rule set. The default rules cover the most common spam signals — missing headers…
- spam-scorer — Heuristic spam scorer with a pluggable rule set. The default rules cover the most common spam signals — missing headers…
spf-checker — Implements the SPF (RFC 7208) evaluation algorithm: parses the record, walks each mechanism in order, follows `include:…
- spf-checker — Implements the SPF (RFC 7208) evaluation algorithm: parses the record, walks each mechanism in order, follows `include:…
telemetry — Provides the shared OpenTelemetry meter and instrument set used by every public entry point of `@suaveplan/email-proces…
- telemetry — Provides the shared OpenTelemetry meter and instrument set used by every public entry point of `@suaveplan/email-proces…
thread-grouper — Groups a flat list of emails into conversation threads using In-Reply-To, References, and subject-line heuristics. Each…
- thread-grouper — Groups a flat list of emails into conversation threads using In-Reply-To, References, and subject-line heuristics. Each…

Layout

src/
  attachment-processor/    # SHA-256 hash + size + MIME allowlist validation
  calendar-parser/         # iCalendar VEVENT extraction
  cid-resolver/            # Content-ID resolution to data URIs / URL maps
  data-extractor/          # tracking numbers, receipts, calendar events
  dkim-canonicalize/       # RFC 6376 relaxed + simple canonicalisation
  dkim-verifier/           # Tag parsing, body-hash, RSASSA-PKCS1-v1_5 verify
  dmarc-checker/           # Policy + alignment over SPF + DKIM
  error-codes/             # EMAIL_PROCESSING_CODES + EmailProcessingError
  hooks/                   # email:processing pipeline + singleton bus
  mime-utils/              # libmime wrappers (encode/decode words, folding)
  parser/                  # parseEmail / parseEmailAddress / decodeEmailWords
  spam-scorer/             # 12 default rules + custom-rule merge
  spf-checker/             # RFC 7208 evaluator with include/redirect limits
  telemetry/               # Shared OTel meter + instruments
  thread-grouper/          # In-Reply-To + References + subject threading
  types/                   # Shared MIME / address / header type aliases
  index.ts                 # Package barrel

Quality

100% statement / branch / function / line coverage (Istanbul).
Real postal-mime parses against embedded RFC 822 fixtures — no mocks (rule 2).
Test runner imports go through @suaveplan/testing/runner only (rule 11).
Zod-validated option boundaries (parseEmail, processAttachment).
Two error codes: INVALID_INPUT, PARSE_FAILURE, INVALID_OPTIONS, ATTACHMENT_TOO_LARGE, ATTACHMENT_TYPE_REJECTED, HASH_FAILURE, DKIM_VERIFY_FAILURE, HOOK_FAILURE — every code is thrown by at least one production path under src/.

Quick start

import {
    parseEmail,
    processAttachments,
    onEmailProcessing,
} from "@suaveplan/email-processing";

onEmailProcessing((data) => ({
    ...data,
    parsed: {
        ...data.parsed,
        html: data.parsed.html?.replace(/<script[\s\S]*?<\/script>/gi, ""),
    },
}));

const parsed = await parseEmail(rawMimeBuffer);
const processed = await processAttachments(parsed.attachments, {
    maxSize: 10 * 1024 * 1024,
    allowedMimeTypes: ["image/*", "application/pdf"],
});

Subpath exports

./parser, ./mime-utils, ./hooks, ./attachments, ./cid-resolver, ./extraction, ./calendar, ./dkim, ./dmarc, ./spf, ./spam, ./threading, ./errors, ./otel.

Provenance

Migrated from packages/universal/email-processing on the /mnt/s/web/suaveplan main branch per the enterprise plan at /mnt/s/web/suaveplan/enterprise/email-processing.md. Hook infrastructure was rewritten locally because the foundation @suaveplan/events library does not yet ship a shared Hooks<T> substrate.

9.0 KiB Raw Permalink Blame History