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