docs(js-sdk): document resumeUpload, recoveryToken, and FileState for cross-restart upload resume

[dobby-coder]

The @e4a/pg-js SDK gained a new public surface for resuming an in-flight upload across page refreshes, tab crashes, or process restarts. The behaviour is partly covered on the cryptify side (docs/repos/cryptify.md mentions recovery_token and X-Recovery-Token), but the JS SDK reference does not document the new exports.

Source PR

encryption4all/postguard-js#66 — feat(api): capture recovery_token and add resumeUpload for cross-restart resume (merged 2026-05-13).

What needs documenting in docs/sdk/js-encryption.md

1. FileState.recoveryToken — initUpload now reads the snake-case recovery_token from the server response and returns it on FileState as recoveryToken. Consumers are expected to persist { uuid, recoveryToken } in their own storage (roamingSettings / browser.storage / IndexedDB).
2. resumeUpload(cryptifyUrl, uuid, recoveryToken, signal?) — new export. Calls GET /fileupload/{uuid}/status with the X-Recovery-Token header. Returns { state: FileState; uploaded: number }:
   • cryptify_token from the response is mapped to state.token
   • prev_token is mapped to state.prevToken (omitted before the first committed chunk)
   • uploaded is the byte offset to resume from; feed the returned state into the existing storeChunkWithRetry flow
3. UploadSessionExpiredError is already documented in docs/sdk/js-errors.md, but the JS encryption page should cross-link it from the new resume section, noting that a 404 upload_session_not_found is surfaced as this error and that cryptify deliberately collapses unknown UUID and wrong recovery token into the same response — callers should treat both as "start a new upload".

A small flow example in the JS SDK page (init → persist → resume after restart → continue with storeChunkWithRetry) would mirror the level of detail already present for the regular upload path.

Verification

• Cross-check against src/api/cryptify.ts and src/index.ts in postguard-js at the merge commit of PR#66 for the exact signature and re-exports.
• Run npx vitepress build docs and confirm no broken links.
• Keep style aligned with postguard-docs/CLAUDE.md (no em dashes, minimal bold, no banned words).

[dobby-coder]

/dobby

[dobby-coder]

Dobby is here! Dobby sees the task — document resumeUpload, recoveryToken, and FileState on the JS SDK page. Dobby will cross-check against postguard-js PR #66 at the merge commit, draft the new section in docs/sdk/js-encryption.md, verify the build, and report back with a plan before editing.

[dobby-coder]

Plan

Verified against postguard-js@6205fc309aaf954e82937beae723912812604f2e (merge commit of #66).

What is actually re-exported from @e4a/pg-js after #66

From src/index.ts:

• resumeUpload(cryptifyUrl, uuid, recoveryToken, signal?) — function
• FileState — type
• UploadSessionExpiredError — already exported pre-chore: bump @e4a/pg-js to 1.6.0 #66, already documented on js-errors.md

Not exported (kept internal): initUpload, storeChunkWithRetry, finalizeUpload, createUploadStream.

Gap to flag

The high-level sealed.upload() returns UploadResult = { uuid: string } only — recoveryToken is captured internally by createUploadStream but never surfaced to the caller. Consumers who only use the public pg.encrypt(...).upload() path cannot currently obtain the recoveryToken they would need to call resumeUpload. The issue body suggests a flow init -> persist -> resume -> storeChunkWithRetry, but initUpload and storeChunkWithRetry are not part of the public surface, so that flow is not buildable against @e4a/pg-js today.

This is a real gap. Two options for the docs PR:

1. Document resumeUpload and FileState as the new exports, link them to the existing UploadSessionExpiredError reference, and explicitly note that the high-level sealed.upload() does not yet surface recoveryToken (so resume is not yet usable from the public API). Open a follow-up issue on postguard-js to plumb recoveryToken through UploadResult (and/or expose a session-init callback on UploadOptions).
2. Block the docs PR until postguard-js exposes a path for capturing recoveryToken, then document the full flow at once.

This bot recommends option 1 — the exports exist in the published package surface and should be reference-documented, and the gap is worth tracking as a separate postguard-js issue rather than leaving the new exports undocumented.

Files to change (option 1)

• docs/sdk/js-encryption.md: add a new ## Resume an interrupted upload section after ## Encrypt and upload, covering:
  • FileState shape (token, prevToken, uuid, recoveryToken) — pin source link to commit 6205fc30.
  • resumeUpload(cryptifyUrl, uuid, recoveryToken, signal?) signature and return type { state, uploaded }.
  • Behaviour: GET /fileupload/{uuid}/status with X-Recovery-Token header; cryptify_token -> state.token, prev_token -> state.prevToken; uploaded is byte offset to resume from.
  • 404 with upload_session_not_found surfaces as UploadSessionExpiredError; cryptify collapses unknown UUID and wrong token into the same response, so callers treat both as "start a new upload".
  • Cross-link to /sdk/js-errors#uploadsessionexpirederror.
  • Honest note about the sealed.upload() gap, with a link to the follow-up issue.
• docs/sdk/js-errors.md: amend the line "there is no resume path once a session is gone" to clarify scope — this applies once the session has expired; an in-flight session can be resumed via resumeUpload. Cross-link the new encryption section.
• (Separate) open encryption4all/postguard-js issue: "Surface recoveryToken on UploadResult (or via an onInit callback) so the new resumeUpload export is reachable from the public API." Link it from the docs PR.

Verification

• npm install && npm run docs:build — confirm clean build.
• curl -sI the new postguard-js source links at commit 6205fc30 and confirm HTTP 200.
• Style check pass per postguard-docs/CLAUDE.md (no banned words, no em dashes, minimal bold).

Risks / open questions

• This bot assumes option 1. If the maintainer wants option 2 instead, this bot will hold the docs PR and only open the postguard-js follow-up.
• This bot will not invent a code example that calls non-exported internals.

Proceeding with option 1 unless redirected.

[dobby-coder]

Draft is now live as #88 (CI green, opened ready for review). The new section in docs/sdk/js-encryption.md covers FileState, resumeUpload, and the failure mode, with source links pinned to postguard-js merge commit 6205fc309a. The js-errors page now cross-links to it.

One gap to flag: pg.encrypt(...).upload() does not yet surface recoveryToken on UploadResult, so the public API path to use resumeUpload is not complete. That is tracked at encryption4all/postguard-js#68; the new docs section calls it out explicitly so readers are not misled.