@fias/arche-sdk 2.19.1 → 2.20.0

package/dist/hooks.test.js

@@ -110,9 +110,11 @@ jest.mock('react-dom', () => ({
 let mockSingletonBridge = null;
 jest.mock('./bridge', () => ({
     __esModule: true,
-    // Real exports the hooks module needs: only getBridge. resetBridge isn't
-    // referenced from hooks.ts.
+    // Real exports the hooks module needs: getBridge, plus the coded error
+    // class the hooks throw for refusals they can make without a round-trip.
+    // resetBridge isn't referenced from hooks.ts.
     getBridge: jest.fn(() => mockSingletonBridge),
+    FiasBridgeError: jest.requireActual('./bridge').FiasBridgeError,
     FiasBridge: jest.fn(),
     resetBridge: jest.fn(),
 }));
@@ -238,6 +240,24 @@ describe('SDK hooks', () => {
             });
         });
     });
+    describe('hook return identity', () => {
+        // These two returns MUST be memoized. The natural way to consume them is
+        // `useEffect(() => { void storage.readFile(...) }, [storage])`, and a
+        // fresh object literal every render turns that into an infinite loop —
+        // effect, setState, render, effect. It cost a live QA session to find.
+        //
+        // The react mock here stubs `useMemo` as a pass-through, so identity
+        // across renders cannot be asserted from this harness. What it CAN pin is
+        // that the return goes through `useMemo` at all, which is the thing a
+        // future edit would undo by reaching for an object literal again.
+        it.each([['useFiasStorage'], ['useFiasNavigation']])('%s memoizes its returned API object', (hookName) => {
+            const react = require('react');
+            react.useMemo.mockClear();
+            const hooks = require('./hooks');
+            hooks[hookName]();
+            expect(react.useMemo).toHaveBeenCalled();
+        });
+    });
     describe('useFiasStorage', () => {
         it('returns storage API methods that call bridge.request', async () => {
             const { useFiasStorage } = require('./hooks');
@@ -289,6 +309,115 @@ describe('SDK hooks', () => {
             expect(res.document.name).toBe('a.pdf');
         });
     });
+    describe('useVaultUserDocuments — edit access and in-place saves', () => {
+        const DOC = 'vdoc_0123456789abcdef0123456789abcdef';
+        const receipt = { documentId: DOC, sizeBytes: 5, updatedAt: 'now', revision: 'c:new' };
+        it('pick({ access }) forwards the access asked for; the default asks for nothing extra', async () => {
+            const { useVaultUserDocuments } = require('./hooks');
+            const docs = useVaultUserDocuments();
+            mockBridge.request.mockResolvedValue({ canceled: true });
+            await docs.pick({ maxDocuments: 3, access: 'write' });
+            await docs.pick();
+            expect(mockBridge.request).toHaveBeenNthCalledWith(1, 'vault_documents_pick', {
+                maxDocuments: 3,
+                access: 'write',
+            });
+            expect(mockBridge.request).toHaveBeenNthCalledWith(2, 'vault_documents_pick', {
+                maxDocuments: undefined,
+                access: undefined,
+            });
+        });
+        it('pick({ accept }) forwards the accepted types as a plain array', async () => {
+            const { useVaultUserDocuments } = require('./hooks');
+            mockBridge.request.mockResolvedValue({ canceled: true });
+            await useVaultUserDocuments().pick({ accept: ['image/*', '.pdf'] });
+            expect(mockBridge.request).toHaveBeenCalledWith('vault_documents_pick', {
+                maxDocuments: undefined,
+                access: undefined,
+                accept: ['image/*', '.pdf'],
+            });
+        });
+        it('requestEditAccess names ONE document and asks for write — through the same host-mediated op', async () => {
+            const { useVaultUserDocuments } = require('./hooks');
+            mockBridge.request.mockResolvedValue({ canceled: true });
+            await useVaultUserDocuments().requestEditAccess(DOC);
+            expect(mockBridge.request).toHaveBeenCalledWith('vault_documents_pick', {
+                maxDocuments: 1,
+                access: 'write',
+                documentId: DOC,
+            });
+        });
+        it('a small string saves over the entity lane with its expectedRevision', async () => {
+            const { useVaultUserDocuments } = require('./hooks');
+            mockBridge.request.mockResolvedValue(output(receipt));
+            const res = await useVaultUserDocuments().saveContent({
+                documentId: DOC,
+                content: 'hello',
+                expectedRevision: 'c:old',
+            });
+            expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.VAULT_USER_DOCUMENTS_ENTITY_ID, 'save_consented_document_content', {
+                documentId: DOC,
+                content: 'hello',
+                expectedRevision: 'c:old',
+            }));
+            expect(res.revision).toBe('c:new');
+        });
+        it.each([
+            ['bytes', new Uint8Array([1, 2, 3]), 'binary', Buffer.from([1, 2, 3]).toString('base64')],
+            ['a string past the bridge body', 'x'.repeat(200001), 'text', null],
+        ])('%s go to the host-orchestrated lane, aimed at the USER’S files and never able to create a document', async (_label, content, contentKind, expectedBase64) => {
+            const { useVaultUserDocuments } = require('./hooks');
+            mockBridge.request.mockResolvedValue(receipt);
+            await useVaultUserDocuments().saveContent({
+                documentId: DOC,
+                content,
+                expectedRevision: 'c:old',
+            });
+            expect(mockBridge.request).toHaveBeenCalledTimes(1);
+            const [type, payload] = mockBridge.request.mock.calls[0];
+            expect(type).toBe('vault_documents_upload');
+            expect(Object.keys(payload).sort()).toEqual([
+                'bytes',
+                'contentKind',
+                'expectedRevision',
+                'saveTarget',
+                'saveToDocumentId',
+            ]);
+            expect(payload).toMatchObject({
+                saveToDocumentId: DOC,
+                saveTarget: 'user',
+                contentKind,
+                expectedRevision: 'c:old',
+            });
+            if (expectedBase64)
+                expect(payload.bytes).toBe(expectedBase64);
+        });
+    });
+    describe('saveContent — refused locally past the 15 MB cap', () => {
+        const DOC = 'vdoc_0123456789abcdef0123456789abcdef';
+        it.each([
+            ['useVaultDocuments', 'useVaultDocuments'],
+            ['useVaultUserDocuments', 'useVaultUserDocuments'],
+        ])('%s: rejects with OWN_DOCUMENT_SAVE_TOO_LARGE before base64-encoding or sending anything', async (_label, hookName) => {
+            const hooks = require('./hooks');
+            const tooBig = new Uint8Array(15 * 1024 * 1024 + 1);
+            await expect(hooks[hookName]().saveContent({
+                documentId: DOC,
+                content: tooBig,
+                expectedRevision: 'c:old',
+            })).rejects.toMatchObject({ name: 'FiasBridgeError', code: 'OWN_DOCUMENT_SAVE_TOO_LARGE' });
+            expect(mockBridge.request).not.toHaveBeenCalled();
+        });
+        it('content exactly AT the cap is sent', async () => {
+            const { useVaultDocuments } = require('./hooks');
+            mockBridge.request.mockResolvedValue({ documentId: DOC, sizeBytes: 1, updatedAt: 'now' });
+            await useVaultDocuments().saveContent({
+                documentId: DOC,
+                content: new Uint8Array(15 * 1024 * 1024),
+            });
+            expect(mockBridge.request).toHaveBeenCalledTimes(1);
+        });
+    });
     describe('useVaultDocuments.readBytes (arche-owned binary reads)', () => {
         it('invokes get_own_document_bytes on the Vault Arche Documents entity and decodes byte-exact', async () => {
             const { useVaultDocuments } = require('./hooks');
@@ -341,6 +470,143 @@ describe('SDK hooks', () => {
                 updatedAt: '2026-09-10T00:00:00.000Z',
             });
         });
+        // ── one method, lane picked from the argument ────────────────────────────
+        const DOC_ID = 'vdoc_0123456789abcdef0123456789abcdef';
+        const receipt = { documentId: DOC_ID, sizeBytes: 1, updatedAt: 'x', revision: 'c:new' };
+        /**
+         * REGRESSION GUARD. The text lane was chosen on raw UTF-8 size alone, but
+         * the text travels as a JSON string inside a 256 KB request: quotes,
+         * backslashes and newlines double, other control characters become six
+         * bytes. 150 KB of newlines is 300 KB on the wire — an opaque 413.
+         */
+        it.each([
+            ['newlines (2 bytes each on the wire)', '\n'.repeat(150000)],
+            ['quotes', '"'.repeat(150000)],
+            ['control characters (6 bytes each)', '\u0001'.repeat(60000)],
+        ])('text under 200 KB that would NOT fit the request once JSON-escaped goes to the host lane: %s', async (_label, content) => {
+            const { useVaultDocuments } = require('./hooks');
+            mockBridge.request.mockResolvedValue(receipt);
+            expect(Buffer.byteLength(content, 'utf-8')).toBeLessThanOrEqual(200000);
+            await useVaultDocuments().saveContent({ documentId: DOC_ID, content });
+            const [type, payload] = mockBridge.request.mock.calls[0];
+            expect(type).toBe('vault_documents_upload');
+            expect(payload.contentKind).toBe('text');
+            expect(Buffer.from(payload.bytes, 'base64').toString('utf-8')).toBe(content);
+        });
+        it('the same amount of ORDINARY text still rides the small lane', async () => {
+            const { useVaultDocuments } = require('./hooks');
+            mockBridge.request.mockResolvedValue(output(receipt));
+            await useVaultDocuments().saveContent({ documentId: DOC_ID, content: 'x'.repeat(150000) });
+            expect(mockBridge.request.mock.calls[0][0]).toBe('entity_invoke');
+        });
+        it('write() has no second lane, so it refuses what cannot travel — by name, not as a 413', async () => {
+            const { useVaultDocuments } = require('./hooks');
+            const docs = useVaultDocuments();
+            await expect(docs.write({ name: 'a.txt', content: '\n'.repeat(150000) })).rejects.toMatchObject({
+                code: 'INVALID_PARAMS',
+                message: expect.stringMatching(/upload\(\)/),
+            });
+            await expect(docs.write({ name: 'a.txt', content: 'x'.repeat(200001) })).rejects.toMatchObject({
+                code: 'INVALID_PARAMS',
+            });
+            expect(mockBridge.request).not.toHaveBeenCalled();
+            mockBridge.request.mockResolvedValue({ documentId: DOC_ID });
+            await expect(docs.write({ name: 'a.txt', content: 'x'.repeat(150000) })).resolves.toEqual({
+                documentId: DOC_ID,
+            });
+        });
+        const decode = (b64) => Buffer.from(b64, 'base64');
+        /** The `[op, payload]` of the n-th bridge request, typed. */
+        const sent = (n = 0) => mockBridge.request.mock.calls[n];
+        it('sends small text with expectedRevision on the body lane', async () => {
+            const { useVaultDocuments } = require('./hooks');
+            mockBridge.request.mockResolvedValue(output(receipt));
+            const res = await useVaultDocuments().saveContent({
+                documentId: DOC_ID,
+                content: 'hello',
+                expectedRevision: 'c:old',
+            });
+            expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.VAULT_ARCHE_DOCUMENTS_ENTITY_ID, 'save_own_document_content', {
+                documentId: DOC_ID,
+                content: 'hello',
+                expectedRevision: 'c:old',
+            }));
+            expect(res.revision).toBe('c:new');
+        });
+        it.each([
+            ['Uint8Array', () => new Uint8Array([0x25, 0x50, 0x00, 0xff])],
+            ['ArrayBuffer', () => new Uint8Array([0x25, 0x50, 0x00, 0xff]).buffer],
+            ['Blob', () => new Blob([new Uint8Array([0x25, 0x50, 0x00, 0xff])])],
+        ])('routes %s content through the host-uploaded lane, byte-exact, as binary', async (_l, make) => {
+            const { useVaultDocuments } = require('./hooks');
+            mockBridge.request.mockResolvedValue(receipt);
+            const res = await useVaultDocuments().saveContent({
+                documentId: DOC_ID,
+                content: make(),
+                contentType: 'application/pdf',
+                expectedRevision: 'c:old',
+            });
+            expect(mockBridge.request).toHaveBeenCalledTimes(1);
+            const [op, payload] = sent();
+            expect(op).toBe('vault_documents_upload');
+            expect(payload).toEqual({
+                saveToDocumentId: DOC_ID,
+                bytes: expect.any(String),
+                mimeType: 'application/pdf',
+                contentKind: 'binary',
+                expectedRevision: 'c:old',
+            });
+            expect(Array.from(decode(payload.bytes))).toEqual([0x25, 0x50, 0x00, 0xff]);
+            // NOT unwrapped from `{ output }` — the host returns the receipt itself.
+            expect(res).toEqual(receipt);
+        });
+        /**
+         * REGRESSION GUARD. A host that predates in-place saves handles
+         * `vault_documents_upload` by CREATING a document, and requires `name` to
+         * do it. Sending no `name` makes such a host refuse the message; sending
+         * one would make it silently fork a new document on every save — the
+         * exact behaviour this lane exists to remove.
+         */
+        it('never sends create-path fields on the save lane, so an older host fails closed instead of forking a document', async () => {
+            const { useVaultDocuments } = require('./hooks');
+            mockBridge.request.mockResolvedValue(receipt);
+            await useVaultDocuments().saveContent({ documentId: DOC_ID, content: new Uint8Array([1]) });
+            const payload = mockBridge.request.mock.calls[0][1];
+            for (const key of [
+                'name',
+                'tags',
+                'folderPath',
+                'sensitivity',
+                'replacesDocumentId',
+                'userVisible',
+            ]) {
+                expect(payload).not.toHaveProperty(key);
+            }
+        });
+        it('auto-routes text past the 200 KB body ceiling through the host lane AS TEXT, rather than failing', async () => {
+            const { useVaultDocuments } = require('./hooks');
+            mockBridge.request.mockResolvedValue(receipt);
+            const big = 'a'.repeat(200001);
+            await useVaultDocuments().saveContent({ documentId: DOC_ID, content: big });
+            const [op, payload] = sent();
+            expect(op).toBe('vault_documents_upload');
+            // 'text' keeps the must-be-a-text-type rule in force at any size.
+            expect(payload.contentKind).toBe('text');
+            expect(decode(payload.bytes).toString('utf-8')).toBe(big);
+        });
+        it('measures the ENCODED size: multi-byte text under 200k chars but over 200 KB takes the host lane', async () => {
+            const { useVaultDocuments } = require('./hooks');
+            mockBridge.request.mockResolvedValue(receipt);
+            const content = '€'.repeat(70000); // 210 000 bytes, 70 000 chars
+            await useVaultDocuments().saveContent({ documentId: DOC_ID, content });
+            expect(mockBridge.request.mock.calls[0][0]).toBe('vault_documents_upload');
+        });
+        it('keeps text at exactly the ceiling on the body lane', async () => {
+            const { useVaultDocuments } = require('./hooks');
+            mockBridge.request.mockResolvedValue(output(receipt));
+            await useVaultDocuments().saveContent({ documentId: DOC_ID, content: 'a'.repeat(200000) });
+            expect(mockBridge.request.mock.calls[0][0]).toBe('entity_invoke');
+        });
     });
     describe('useEntityInvocation', () => {
         it('returns invoke function and initial state', () => {
@@ -535,6 +801,19 @@ describe('SDK hooks', () => {
             await Promise.resolve();
             expect(mockSetState).toHaveBeenCalledWith(42);
         });
+        it('keeps a value set before the mount read resolves (the read must not revert it)', async () => {
+            let resolveRead;
+            mockBridge.request.mockImplementationOnce(() => new Promise((r) => (resolveRead = r)));
+            const { usePersistentState } = require('./hooks');
+            const [, setValue] = usePersistentState('choice', 'a');
+            setValue('b'); // the user acts while the read is still in flight
+            mockSetState.mockClear();
+            resolveRead(output({ content: JSON.stringify('stored'), exists: true }));
+            await Promise.resolve();
+            await Promise.resolve();
+            await Promise.resolve();
+            expect(mockSetState).not.toHaveBeenCalledWith('stored');
+        });
         it('falls back to the initial value when the mount storage_read is denied/fails', async () => {
             // e.g. the plugin didn't declare `storage:sandbox`. Must not become a
             // silent unhandled rejection, and must not clobber the initial value.
@@ -715,6 +994,39 @@ describe('SDK hooks', () => {
                 documentId: 'vdoc_2',
             });
         });
+        it("upload({ destination: 'documents' }) asks the host for its Save dialog", async () => {
+            const { useVaultDocuments } = freshHooks();
+            const api = useVaultDocuments();
+            const saved = {
+                documentId: 'vdoc_s',
+                status: 'uploaded',
+                name: 'Report (2).pdf',
+                access: 'read',
+            };
+            mockBridge.request.mockResolvedValueOnce(saved);
+            const res = await api.upload(new Uint8Array([1, 2]), {
+                name: 'Report.pdf',
+                mimeType: 'application/pdf',
+                destination: 'documents',
+            });
+            expect(res).toEqual(saved);
+            expect(mockBridge.request).toHaveBeenCalledWith('vault_documents_upload', expect.objectContaining({ name: 'Report.pdf', destination: 'documents' }));
+        });
+        it('saveCopy rides the update op with only the saveCopy options', async () => {
+            const { useVaultDocuments } = freshHooks();
+            const api = useVaultDocuments();
+            mockBridge.request.mockResolvedValue({ documentId: 'vdoc_c', status: 'uploaded' });
+            await api.saveCopy('vdoc_own', { suggestedName: 'Final.png' });
+            expect(mockBridge.request).toHaveBeenLastCalledWith('vault_documents_update', {
+                documentId: 'vdoc_own',
+                saveCopy: { suggestedName: 'Final.png' },
+            });
+            await api.saveCopy('vdoc_own');
+            expect(mockBridge.request).toHaveBeenLastCalledWith('vault_documents_update', {
+                documentId: 'vdoc_own',
+                saveCopy: {},
+            });
+        });
         it('getDownloadUrl caches a still-valid presigned URL', async () => {
             const { useVaultDocuments } = freshHooks();
             const api = useVaultDocuments();
@@ -1405,6 +1717,106 @@ describe('SDK hooks', () => {
             expect(asset.assetId).toBe('aset_1');
         });
     });
+    describe('useFiasContent (content packs, ADR-021)', () => {
+        const ENTITY = 'ent_intg_plugin_content_00000000';
+        const load = () => {
+            const { useFiasContent, FiasContentError } = require('./hooks');
+            return { content: useFiasContent(), FiasContentError };
+        };
+        it('lists through the generic client_entity_invoke op, verb in the input', async () => {
+            const { content } = load();
+            const files = [{ path: 'lessons/01.md', sizeBytes: 5, mimeType: 'text/markdown' }];
+            mockBridge.request.mockResolvedValueOnce({ files });
+            expect(await content.list('lessons/')).toEqual(files);
+            expect(mockBridge.request).toHaveBeenCalledWith('client_entity_invoke', { entityId: ENTITY, input: { verb: 'list', prefix: 'lessons/' } }, 120000);
+        });
+        it('reads text and parses JSON', async () => {
+            const { content } = load();
+            mockBridge.request.mockResolvedValueOnce({
+                results: { 'a.md': { text: '# A', mimeType: 'text/markdown' } },
+            });
+            expect(await content.getText('a.md')).toBe('# A');
+            mockBridge.request.mockResolvedValueOnce({
+                results: { 'c.json': { text: '{"n":1}', mimeType: 'application/json' } },
+            });
+            expect(await content.getJson('c.json')).toEqual({ n: 1 });
+        });
+        it('throws a coded FiasContentError for a per-file and a whole-call failure', async () => {
+            const { content, FiasContentError } = load();
+            mockBridge.request.mockResolvedValueOnce({
+                results: { 'x.md': { error: { code: 'CONTENT_NOT_FOUND', message: 'not in pack' } } },
+            });
+            const perFile = await content.getText('x.md').catch((e) => e);
+            expect(perFile).toBeInstanceOf(FiasContentError);
+            expect(perFile).toMatchObject({ code: 'CONTENT_NOT_FOUND', path: 'x.md' });
+            mockBridge.request.mockResolvedValueOnce({
+                error: { code: 'CONTENT_UNAVAILABLE_IN_PREVIEW', message: 'preview' },
+            });
+            await expect(content.list()).rejects.toMatchObject({
+                code: 'CONTENT_UNAVAILABLE_IN_PREVIEW',
+            });
+        });
+        it.each([
+            ['Permission denied: entities:client_invoke', undefined, 'PERMISSION_DENIED'],
+            ['Rate limit exceeded for client_entity_invoke', undefined, 'RATE_LIMIT'],
+            ['Bridge request timed out', 'TIMEOUT', 'CONTENT_UNAVAILABLE'],
+        ])('maps a bridge failure (%s, code %s) to %s', async (message, code, expected) => {
+            const { content } = load();
+            mockBridge.request.mockRejectedValueOnce(Object.assign(new Error(message), { code }));
+            await expect(content.list()).rejects.toMatchObject({ code: expected });
+        });
+        it('reads bytes, and batches with per-file errors', async () => {
+            const { content, FiasContentError } = load();
+            const bytes = new Uint8Array([1, 2]).buffer;
+            mockBridge.request.mockResolvedValueOnce({
+                results: { 'a.bin': { bytes, mimeType: 'application/octet-stream' } },
+            });
+            expect(await content.getBytes('a.bin')).toBe(bytes);
+            mockBridge.request.mockResolvedValueOnce({
+                results: {
+                    'a.md': { text: '# A', mimeType: 'text/markdown' },
+                    'b.png': { error: { code: 'CONTENT_NOT_TEXT', message: 'image/png, not text' } },
+                },
+            });
+            const many = await content.getMany(['a.md', 'b.png', 'gone.md'], 'text');
+            expect(many['a.md']).toBe('# A');
+            expect(many['b.png']).toMatchObject({ code: 'CONTENT_NOT_TEXT', path: 'b.png' });
+            expect(many['gone.md']).toBeInstanceOf(FiasContentError);
+        });
+        it('builds one typed blob: URL per path from host-cached bytes', async () => {
+            const { content } = load();
+            const created = [];
+            const original = URL.createObjectURL;
+            URL.createObjectURL = jest.fn((blob) => {
+                created.push(blob);
+                return 'blob:plugin/1';
+            });
+            try {
+                mockBridge.request.mockResolvedValueOnce({
+                    results: {
+                        'img/cover-unique.webp': { bytes: new ArrayBuffer(3), mimeType: 'image/webp' },
+                    },
+                });
+                expect(await content.getObjectUrl('img/cover-unique.webp')).toBe('blob:plugin/1');
+                expect(await content.getObjectUrl('img/cover-unique.webp')).toBe('blob:plugin/1');
+                expect(created).toHaveLength(1);
+                expect(created[0].type).toBe('image/webp');
+            }
+            finally {
+                URL.createObjectURL = original;
+            }
+        });
+        it('returns a signed streaming URL with its expiry', async () => {
+            const { content } = load();
+            mockBridge.request.mockResolvedValueOnce({
+                results: { 'a.ogg': { url: 'https://cdn/x?sig', expiresAt: '2026-09-24T00:00:00Z' } },
+            });
+            expect(await content.getUrl('a.ogg')).toEqual({
+                url: 'https://cdn/x?sig',
+                expiresAt: '2026-09-24T00:00:00Z',
+            });
+        });
+    });
 });
 describe('useDataSubscription (ADR-012 Phase M4)', () => {
     const flush = async () => {