@fias/create-fias-plugin 1.5.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fias/create-fias-plugin",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "publishConfig": {
     "access": "public"
   },

package/templates/default/AGENTS.md

@@ -744,6 +744,7 @@ if ('canceled' in picked) {
 const granted = await userDocs.list(); // all granted docs
 const { document, content } = await userDocs.get(id, { includeContent: true }); // text docs
 const { url } = await userDocs.getDownloadUrl(id); // binary docs (images, PDFs)
+const { bytes } = await userDocs.getBytes(id); // raw bytes for PROCESSING binary docs
 ```
 
 **The consent model (what to tell your users):**
@@ -752,7 +753,9 @@ const { url } = await userDocs.getDownloadUrl(id); // binary docs (images, PDFs)
 - After revocation, `get`/`getDownloadUrl` reject with `DOCUMENT_NOT_FOUND` — handle that path gracefully (drop the document from your UI; do not retry in a loop).
 - `proprietary`-sensitivity documents are never grantable (they don't even appear in the picker).
 - Every read is audited by the platform; a new document _version_ is a new documentId, so a re-pick is needed after the user replaces a document.
-- Not available in the builder preview or the dev harness — `pick()` resolves `{ canceled: true }` there. Test the flow in the published plugin with your own documents.
+- `getDownloadUrl` is for DISPLAY (`<img src>`); your iframe cannot fetch the URL (CSP). To process binary content (parse a PDF, transform an image), use `getBytes(id)` — size-capped at 15 MB (`CONSENTED_DOCUMENT_TOO_LARGE` names the cap; ask the user to open the file manually instead). `getBytes` has a tighter per-minute budget than the rest of the family because it can move megabytes: read sequentially, and surface a rate-limit error rather than retrying in a loop.
+- Revocation behaves differently per method: `getBytes` and `get` re-check the grant on every call, so they start failing immediately. A URL already handed out by `getDownloadUrl` keeps working until it expires (1 hour) — that is the documented contract, not a bug.
+- **Testable in the dev harness (mock mode).** `pick()` grants a small fixture set — a text file, a real PDF, and one deliberately over the 15 MB cap — and `list` / `get` / `getDownloadUrl` / `getBytes` all resolve against it, including the refusals (`BINARY_DOCUMENT` on a text read of a PDF, `CONSENTED_DOCUMENT_TOO_LARGE`, `DOCUMENT_NOT_FOUND`). Run the harness with `FIAS_HARNESS_VAULT_PICK=canceled` to exercise the cancel branch. Not available in the builder preview — `pick()` resolves `{ canceled: true }` there.
 
 ### `useFiasAIActions()` — Let the platform's Fias AI assistant operate your plugin
 

package/templates/default/CLAUDE.md

@@ -744,6 +744,7 @@ if ('canceled' in picked) {
 const granted = await userDocs.list(); // all granted docs
 const { document, content } = await userDocs.get(id, { includeContent: true }); // text docs
 const { url } = await userDocs.getDownloadUrl(id); // binary docs (images, PDFs)
+const { bytes } = await userDocs.getBytes(id); // raw bytes for PROCESSING binary docs
 ```
 
 **The consent model (what to tell your users):**
@@ -752,7 +753,9 @@ const { url } = await userDocs.getDownloadUrl(id); // binary docs (images, PDFs)
 - After revocation, `get`/`getDownloadUrl` reject with `DOCUMENT_NOT_FOUND` — handle that path gracefully (drop the document from your UI; do not retry in a loop).
 - `proprietary`-sensitivity documents are never grantable (they don't even appear in the picker).
 - Every read is audited by the platform; a new document _version_ is a new documentId, so a re-pick is needed after the user replaces a document.
-- Not available in the builder preview or the dev harness — `pick()` resolves `{ canceled: true }` there. Test the flow in the published plugin with your own documents.
+- `getDownloadUrl` is for DISPLAY (`<img src>`); your iframe cannot fetch the URL (CSP). To process binary content (parse a PDF, transform an image), use `getBytes(id)` — size-capped at 15 MB (`CONSENTED_DOCUMENT_TOO_LARGE` names the cap; ask the user to open the file manually instead). `getBytes` has a tighter per-minute budget than the rest of the family because it can move megabytes: read sequentially, and surface a rate-limit error rather than retrying in a loop.
+- Revocation behaves differently per method: `getBytes` and `get` re-check the grant on every call, so they start failing immediately. A URL already handed out by `getDownloadUrl` keeps working until it expires (1 hour) — that is the documented contract, not a bug.
+- **Testable in the dev harness (mock mode).** `pick()` grants a small fixture set — a text file, a real PDF, and one deliberately over the 15 MB cap — and `list` / `get` / `getDownloadUrl` / `getBytes` all resolve against it, including the refusals (`BINARY_DOCUMENT` on a text read of a PDF, `CONSENTED_DOCUMENT_TOO_LARGE`, `DOCUMENT_NOT_FOUND`). Run the harness with `FIAS_HARNESS_VAULT_PICK=canceled` to exercise the cancel branch. Not available in the builder preview — `pick()` resolves `{ canceled: true }` there.
 
 ### `useFiasAIActions()` — Let the platform's Fias AI assistant operate your plugin