docs(sdk/js): document tier-based envelope strategy and EnvelopeResult.attachment breaking change

[dobby-coder]

Source PR: encryption4all/postguard-js#34 — feat(email): tier-based envelope strategy, drop in-body armor (merged 2026-05-01).

What changed in pg-js

pg.email.createEnvelope now picks one of three tiers based on payload size:

	base64 ≤ PG_MAX_URL_FRAGMENT_SIZE	bytes ≤ PG_MAX_ATTACHMENT_SIZE	bytes > PG_MAX_ATTACHMENT_SIZE
Tier	1	2	3
Local attachment	yes	yes	no
Cryptify upload	no	yes (opt-out via uploadToCryptify: false)	always
Body fallback link	/decrypt#<base64>	/decrypt?uuid=... (data) / /download?uuid=... (files)	/decrypt?uuid=... (data) / /download?uuid=... (files)

Breaking API change: EnvelopeResult.attachment is now File | null (was always File). Tier 3 yields null because Exchange tenants typically refuse delivery for >10 MB local attachments, so the recipient gets only the body fallback link.

The hidden <div id=\"postguard-armor\"> ciphertext block in htmlBody has been removed. The Outlook add-in's stripping workaround is now obsolete.

Docs that need updating

1. docs/sdk/js-email-helpers.md — section on createEnvelope. Currently says "may upload to Cryptify if the payload is too large" without specifying the tier model, the relevant size knobs, or the uploadToCryptify opt-out. Add the table above and document PG_MAX_URL_FRAGMENT_SIZE / PG_MAX_ATTACHMENT_SIZE constants and the uploadToCryptify option.
2. docs/repos/postguard-js.md — line ~208 says envelope.attachment → File(\"postguard.encrypted\"). Update to File | null and explain when it is null (tier 3).
3. docs/repos/postguard-tb-addon.md — line ~161 dereferences envelope.attachment.arrayBuffer() unconditionally. Update example to null-check, or add a note that the addon should fall back to the body link when attachment === null.
4. Note that the in-body armor div has been dropped — any consumer doc that mentioned stripping #postguard-armor should be removed.

Verification

The new constants and behavior are in src/email/envelope.ts, src/types.ts, and src/sealed.ts of postguard-js as of the merge commit on PR #34. Read those files before drafting prose so the parameter names match the source.

Reviewer

Assign @rubenhensen.

[rubenhensen]

/dobby

[dobby-coder]

Dobby sees the request, master rubenhensen! Dobby will read pg-js PR #34 source files at the merge commit, then update js-email-helpers.md, repos/postguard-js.md, and repos/postguard-tb-addon.md as described. A draft PR is on its way.

[dobby-coder]

Draft PR opened: #39. It documents the three-tier envelope model, the new uploadToCryptify opt-out, the attachment: File | null / tier / uploadUuid result fields, and removes the in-body armor reference from extractCiphertext. The Thunderbird addon snippet keeps its current shape (it matches the pinned commit) but now carries a warning that it needs a null branch for tier 3. npm run docs:build is green.