docs(js-sdk): document onUploadInit callback on UploadOptions / CreateEnvelopeOptions

[dobby-coder]

The onUploadInit callback added in postguard-js#71 is not yet covered in the SDK docs.

What changed in pg-js 1.7.0/1.7.1

PR #71 added onUploadInit?: (info: { uuid: string; recoveryToken: string }) => void to:

• UploadOptions (consumed by Sealed.upload)
• CreateEnvelopeOptions (consumed by createEnvelope)

It fires once, synchronously, after upload_init resolves and before the first chunk PUT. This is the missing piece called out in docs/sdk/js-encryption.md at the bottom of the "Resume an interrupted upload" section, which currently says:

resumeUpload and FileState are exported by @e4a/pg-js, but the high-level pg.encrypt(...).upload() does not yet surface recoveryToken on its UploadResult. Capturing the token from the public API requires a follow-up on postguard-js to plumb it through. Track at encryption4all/postguard-js#68.

postguard-js#68 is now resolved by #71, so that limitation paragraph is stale.

Suggested docs changes

In docs/sdk/js-encryption.md:

1. Remove or rewrite the trailing limitation paragraph that points at postguard-js#68.
2. Add a short subsection under "Resume an interrupted upload" describing onUploadInit on UploadOptions and CreateEnvelopeOptions. Include:
   • Signature: (info: { uuid: string; recoveryToken: string }) => void
   • When it fires: once, synchronously, after upload_init resolves, before the first chunk PUT.
   • Intended use: persist {uuid, recoveryToken} to durable storage so a later resumeUpload call can rehydrate after a process restart.
   • Caveat from the PR JSDoc: callback runs inside the WritableStream start handler; a throw errors the stream. Keep the body short (a chrome.storage.local.set is fine).
3. A minimal example showing pg.encrypt(...).upload(file, sink, { onUploadInit: ({ uuid, recoveryToken }) => storage.set({ uuid, recoveryToken }) }).

Verify against the actual exports in pg-js dist/index.d.mts (not just the PR body) and ensure naming matches the SDK source.

Verification

Run npx vitepress build docs and confirm dist/sdk/js-encryption.html builds and the new anchor links resolve.

Source PR: encryption4all/postguard-js#71

[dobby-coder]

/dobby

[dobby-coder]

This agent sees the request! Reading postguard-js#71 to confirm the exported types, then drafting the docs update for docs/sdk/js-encryption.md (new onUploadInit subsection + removing the stale postguard-js#68 limitation paragraph). Will follow up with a plan shortly.

[dobby-coder]

Plan

Source verified against postguard-js merge commit dcdd6591f58976364f8220f4cedbe86d0e2bce3b:

• UploadOptions.onUploadInit defined at src/types.ts#L107-L112
• CreateEnvelopeOptions.onUploadInit defined at src/types.ts#L246-L250 (typed as UploadOptions['onUploadInit'])
• Wired through in src/sealed.ts#L101 and src/email/envelope.ts#L36,L62

File

docs/sdk/js-encryption.md

Changes

Replace the existing `### Current limitation` block (the paragraph that points at postguard-js#68) with a new subsection under "Resume an interrupted upload":

• Title: `### Capture `recoveryToken` via `onUploadInit``
• Document the callback on both `UploadOptions` (consumed by `Sealed.upload`) and `CreateEnvelopeOptions` (consumed by `createEnvelope`).
• Signature: `(info: { uuid: string; recoveryToken: string }) => void`.
• When: once, synchronously, after `upload_init` resolves and before the first chunk PUT.
• Use: persist `{uuid, recoveryToken}` so a later `resumeUpload` can rehydrate after a process restart.
• Caveat: runs inside the WritableStream `start` handler; a throw errors the upload stream. Keep the body short.
• Minimal example using `pg.encrypt(...).upload(...)` with an `onUploadInit` writing to storage.
• Pinned source link at the new commit hash.

Verification

• `npx vitepress build docs` succeeds.
• `dist/sdk/js-encryption.html` contains the new section and the `#capture-recoverytoken-via-onuploadinit` anchor resolves.
• Style: writing rules (no banned words, em-dash budget, minimal bold).

PR will close issue #94 and reference encryption4all/postguard-js#71.