docs(postguard-js): document retry config, onRetry hook, resumable downloads, UploadSessionExpiredError

[dobby-coder]

The postguard-js SDK shipped two large user-facing features in v1.4–1.6 that have no coverage in the SDK reference pages.

What needs documenting

1. PostGuardConfig.retry and the onRetry hook (postguard-js#47)

Cryptify chunk PUTs and downloads now retry transient failures automatically. The retry budget, delays, and per-phase timeouts are configurable. Add a "Retries and timeouts" subsection to docs/sdk/js-encryption.md (and link from docs/sdk/js-decryption.md for the download side) covering:

• retry: RetryOptions on PostGuardConfig — defaults: 5 attempts, 500 ms initial delay, 30 s cap, 2× multiplier, full jitter
• Per-phase timeouts: chunkTimeoutMs (60 s default), finalizeTimeoutMs (120 s default), downloadTimeoutMs (off by default — bounded by retry budget)
• Retry classification: 5xx / network errors / internal-timeout AbortError → retry; 4xx / UploadSessionExpiredError / caller abort → fail
• onRetry: (event: RetryEvent) => void hook for surfacing "retrying… (attempt N of M)" in the UI
• initUpload and finalizeUpload are deliberately not retried

Source PR: encryption4all/postguard-js#47

2. Resumable downloads via Range header (postguard-js#52)

downloadFileWithRetry now resumes mid-stream failures using a Range header. Briefly document the new behaviour in docs/sdk/js-decryption.md:

• Mid-stream errors trigger a resume from the current offset
• Resume requires 206 Partial Content with a matching Content-Range; a 200 reply on resume is treated as fail-not-retry (silent-rewind protection)
• A flapping connection that delivers some bytes per attempt still exhausts the shared retry budget — does not loop forever
• The function now returns the ReadableStream synchronously (stream-level errors surface on the consumer's first read(), not via a function-level rejection). This is a behaviour change for callers that did await downloadFileWithRetry(...).

Source PR: encryption4all/postguard-js#52

3. New UploadSessionExpiredError (postguard-js#47)

Add a row to docs/sdk/js-errors.md. Subclass of NetworkError, parsed from cryptify's structured 404 body (upload_session_not_found). Distinct from NetworkError so retry policies short-circuit. Surfaced from both chunk and finalize paths.

Verification

• Confirm symbols exist on main of encryption4all/postguard-js (don't trust the PR description alone — verify against current source).
• Pin source links to a full commit hash. curl -sI each link before merging.
• npm run docs:build must succeed.

Cross-link

The cryptify-side counterpart docs are tracked in a separate issue on this repo; the SDK retry contract relies on that wire behaviour.

[dobby-coder]

/dobby

[dobby-coder]

Dobby sees the request! This agent will document the retry config, onRetry hook, resumable downloads, and UploadSessionExpiredError. Verifying symbols against postguard-js main first, then drafting a PR. Dobby reports back with a link.

[dobby-coder]

Done — opened #70 (ready for review, @rubenhensen assigned).

What landed

• docs/sdk/js-encryption.md: "Retry options" section for PostGuardConfig.retry — defaults, per-phase timeouts, retry classification, onRetry hook, and the note that initUpload/finalizeUpload are not retried.
• docs/sdk/js-decryption.md: "Retries and resumable downloads" section — Range-based resume, 206/Content-Range requirement, silent-rewind protection on a 200 reply, shared retry budget, and the v1.6 sync-stream behaviour change.
• docs/sdk/js-errors.md: new UploadSessionExpiredError entry with properties and a usage example.

Verification

• All symbols confirmed against encryption4all/postguard-js@a60716e (current main).
• Source links pinned to that hash; curl -sI checked — all 200.
• npm run docs:build clean.