docs(js-sdk): Opened.decrypt({uuid}) may now return DecryptDataResult when payload was uploaded via {data}

[dobby-coder]

What changed

postguard-js#67 (merged 2026-05-13) changes the return shape of Opened.decrypt({ uuid }).

Previously, Opened.decrypt({ uuid }) always returned DecryptFileResult ({ files, sender, blob, download() }). After the fix, the SDK inspects the inner zip central directory: if the entries are exactly ['data.bin'] (the shape produced by Sealed.upload({ data })), the entry is unwrapped and the call returns DecryptDataResult ({ plaintext, sender }). Otherwise behaviour is unchanged.

This makes the round-trip pg.encrypt({ data }).upload() → pg.open({ uuid }).decrypt() actually yield plaintext as the encrypt-side API implies.

Docs that need updating

docs/sdk/js-decryption.md:

• The section "Decrypt from Cryptify UUID" currently states the result is DecryptFileResult. That is only true when the payload was uploaded with Sealed.upload({ files }). When uploaded with Sealed.upload({ data }) the result is now DecryptDataResult.
• The two-input table at the top ({ uuid } vs { data }) should note that { uuid } mirrors whichever mode produced the upload.
• A short note (or TypeScript union) explaining how to discriminate between the two result shapes (e.g. 'plaintext' in result) would be useful for consumers writing if/else over the result.

docs/repos/postguard-js.md snippets that show opened.decrypt({ uuid }) returning a blob should keep the file-upload framing but acknowledge the data-mode alternative.

Source

• Code: src/opened.ts, src/util/zip.ts (new extractZipEntry).
• PR body has the exact discriminator rule ("entries are exactly ['data.bin']").

Verify against the SDK source before writing — the PR description is accurate but the published API types are the binding reference.

[dobby-coder]

/dobby

[dobby-coder]

Dobby sees the request! Dobby will update the JS SDK decryption docs to reflect the new DecryptDataResult return shape from postguard-js#67. Dobby is most eager to help!

[dobby-coder]

Plan

Verified the SDK source at the merge commit (146a7ab70):

• src/opened.ts#L99-L121: when 'uuid' in options, the central directory is read; if entries are exactly ['data.bin'], the entry is unwrapped and the call returns DecryptDataResult ({ plaintext, sender }). Otherwise it returns DecryptFileResult unchanged.
• src/types.ts#L140-L155: DecryptResult = DecryptFileResult | DecryptDataResult is the published union.

Files to update

docs/sdk/js-decryption.md

• Two-input table: note that { uuid } mirrors the upload mode (files → DecryptFileResult, data → DecryptDataResult).
• Rewrite the "Decrypt from Cryptify UUID" section: return type is DecryptResult (union); explain the 'data.bin' discriminator briefly; show a narrowing snippet using 'plaintext' in result.
• Add a source link pinned to commit 146a7ab70 for the unwrap behaviour.

docs/repos/postguard-js.md

• Quick-start "Decrypt from Cryptify UUID" snippet keeps the file-upload framing, but a one-line note acknowledges the data-mode round-trip and points at the SDK page.

Verification

• npm run docs:build (baseline already green).
• Source-link self-check via curl -sI on the new pinned URLs.
• Lint the prose against the writing rules (banned words, em dashes, no AI tells).

Out of scope

No code changes to the SDK; this issue is documentation-only.