@fias/arche-sdk 2.27.0 → 2.29.0

package/dist/hooks.test.js

@@ -68,6 +68,8 @@ function createMockBridge() {
         getCurrentPath: jest.fn().mockReturnValue('/'),
         getTextModels: jest.fn().mockReturnValue(null),
         onTextModelsUpdate: jest.fn().mockReturnValue(() => { }),
+        getHolder: jest.fn().mockReturnValue(null),
+        onHolderReady: jest.fn().mockReturnValue(() => { }),
         onThemeUpdate: jest.fn().mockReturnValue(() => { }),
         onNavigationUpdate: jest.fn().mockReturnValue(() => { }),
         onStepNavigationUpdate: jest.fn().mockReturnValue(() => { }),
@@ -763,6 +765,167 @@ describe('SDK hooks', () => {
             expect(useTextModels()).toEqual([]);
         });
     });
+    describe('useFiasHolder', () => {
+        it('returns the init-payload workspace and subscribes for its arrival', () => {
+            const { useFiasHolder } = require('./hooks');
+            const holder = { type: 'org', role: 'member' };
+            mockBridge.getHolder.mockReturnValue(holder);
+            expect(useFiasHolder()).toEqual(holder);
+            expect(mockBridge.onHolderReady).toHaveBeenCalled();
+        });
+        it('returns null before init', () => {
+            const { useFiasHolder } = require('./hooks');
+            mockBridge.getHolder.mockReturnValue(null);
+            expect(useFiasHolder()).toBeNull();
+        });
+    });
+    describe('useFiasWorkspaces().openForWorkspace', () => {
+        it('asks for the acting workspace by flag, never by id', async () => {
+            const { useFiasWorkspaces } = require('./hooks');
+            const ws = { workspaceId: 'ws_1', displayName: 'Acme', role: 'member', holderBacked: true };
+            mockBridge.request.mockResolvedValue(output({ workspace: ws }));
+            await expect(useFiasWorkspaces().openForWorkspace()).resolves.toEqual(ws);
+            expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.PLUGIN_WORKSPACES_ENTITY_ID, 'create', { forActingHolder: true }));
+        });
+    });
+    describe('useFiasConnections', () => {
+        it('lists through the connections entity', async () => {
+            const { useFiasConnections } = require('./hooks');
+            const accounts = [{ connectionId: 'conn_1', provider: 'x', status: 'active' }];
+            mockBridge.request.mockResolvedValue(output({ connections: accounts }));
+            await expect(useFiasConnections().list()).resolves.toEqual(accounts);
+            expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.CONNECTIONS_ENTITY_ID, 'list'));
+        });
+        it('connects through the client-side entity, waiting on the person', async () => {
+            const { useFiasConnections } = require('./hooks');
+            mockBridge.request.mockResolvedValue({ connectionId: 'conn_1', provider: 'x' });
+            await expect(useFiasConnections().connect('x')).resolves.toEqual({
+                connectionId: 'conn_1',
+                provider: 'x',
+            });
+            const [op, payload, timeout] = mockBridge.request.mock.calls[0];
+            expect(op).toBe('client_entity_invoke');
+            expect(payload).toEqual({
+                entityId: entity_ops_1.CONNECTIONS_CONNECT_ENTITY_ID,
+                input: { provider: 'x' },
+            });
+            expect(timeout).toBeGreaterThanOrEqual(5 * 60 * 1000);
+        });
+        it('turns a refusal result into a typed error', async () => {
+            const { useFiasConnections } = require('./hooks');
+            mockBridge.request.mockResolvedValue({
+                error: { code: 'PERMISSION_DENIED', message: 'no connections:use' },
+            });
+            await expect(useFiasConnections().connect('x')).rejects.toMatchObject({
+                code: 'PERMISSION_DENIED',
+            });
+        });
+        it('releases its own access', async () => {
+            const { useFiasConnections } = require('./hooks');
+            mockBridge.request.mockResolvedValue(output({ released: true }));
+            await useFiasConnections().release('conn_1');
+            expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.CONNECTIONS_ENTITY_ID, 'release', { connectionId: 'conn_1' }));
+        });
+    });
+    describe('the outward guard round-trip (ADR-029 §4)', () => {
+        const PACT = `pact_${'a'.repeat(32)}`;
+        const publish = { connectionId: 'conn_1', posts: [{ text: 'Hi' }] };
+        it('a confirmation answer asks the host, then re-sends the identical call naming the approval', async () => {
+            const { useFiasX } = require('./hooks');
+            mockBridge.request
+                .mockResolvedValueOnce({ output: null, confirmationRequired: { pendingActionId: PACT } })
+                .mockResolvedValueOnce({ approved: true })
+                .mockResolvedValueOnce(output({ posts: [{ postId: '1', url: 'u' }], complete: true }));
+            await expect(useFiasX().publishPost(publish)).resolves.toEqual({
+                posts: [{ postId: '1', url: 'u' }],
+                complete: true,
+            });
+            const [first, confirm, resend] = mockBridge.request.mock.calls;
+            expect(first).toEqual(entityOp(entity_ops_1.X_ENTITY_ID, 'publish_post', publish));
+            expect(confirm[0]).toBe('client_entity_invoke');
+            expect(confirm[1]).toEqual({
+                entityId: entity_ops_1.ACTION_CONFIRMATION_ENTITY_ID,
+                input: { pendingActionId: PACT },
+            });
+            expect(confirm[2]).toBeGreaterThanOrEqual(5 * 60 * 1000);
+            expect(resend[0]).toBe('entity_invoke');
+            expect(resend[1]).toEqual({
+                entityId: entity_ops_1.X_ENTITY_ID,
+                payload: { op: 'publish_post', ...publish },
+                pendingActionId: PACT,
+            });
+            // The approved call acts outside Fias and may take a while; it is not cut at the default.
+            expect(resend[2]).toBeGreaterThanOrEqual(60 * 1000);
+        });
+        it('a decline rejects with USER_DECLINED and sends nothing more', async () => {
+            const { useFiasX } = require('./hooks');
+            mockBridge.request
+                .mockResolvedValueOnce({ output: null, confirmationRequired: { pendingActionId: PACT } })
+                .mockResolvedValueOnce({ approved: false });
+            await expect(useFiasX().publishPost(publish)).rejects.toMatchObject({
+                code: 'USER_DECLINED',
+            });
+            expect(mockBridge.request).toHaveBeenCalledTimes(2);
+        });
+        it("the host's refusal is a typed error", async () => {
+            const { useFiasLinkedIn } = require('./hooks');
+            mockBridge.request
+                .mockResolvedValueOnce({ output: null, confirmationRequired: { pendingActionId: PACT } })
+                .mockResolvedValueOnce({ error: { code: 'CONFIRM_UNAVAILABLE', message: 'no host' } });
+            await expect(useFiasLinkedIn().publishPost({ connectionId: 'conn_1', text: 'Hi' })).rejects.toMatchObject({ code: 'CONFIRM_UNAVAILABLE' });
+        });
+    });
+    describe('useFiasSchedules (ADR-029 §5)', () => {
+        it('schedules one call, approved first, and lists and cancels its own', async () => {
+            const { useFiasSchedules } = require('./hooks');
+            const PACT = `pact_${'b'.repeat(32)}`;
+            const fireAt = new Date('2030-01-01T09:00:00Z');
+            const payload = { connectionId: 'conn_1', posts: [{ text: 'Later' }] };
+            mockBridge.request
+                .mockResolvedValueOnce({ output: null, confirmationRequired: { pendingActionId: PACT } })
+                .mockResolvedValueOnce({ approved: true })
+                .mockResolvedValueOnce(output({ scheduleId: 's1', fireAt: fireAt.toISOString() }));
+            await expect(useFiasSchedules().schedule({
+                entityId: entity_ops_1.X_ENTITY_ID,
+                verb: 'publish_post',
+                payload,
+                fireAt,
+            })).resolves.toEqual({ scheduleId: 's1', fireAt: fireAt.toISOString() });
+            // The Date is sent as ISO, and the re-send names the approval.
+            expect(mockBridge.request.mock.calls[0]).toEqual(entityOp(entity_ops_1.SCHEDULED_INVOCATIONS_ENTITY_ID, 'schedule', {
+                entityId: entity_ops_1.X_ENTITY_ID,
+                verb: 'publish_post',
+                payload,
+                fireAt: fireAt.toISOString(),
+            }));
+            expect(mockBridge.request.mock.calls[2][1]).toMatchObject({ pendingActionId: PACT });
+            mockBridge.request.mockResolvedValueOnce(output({ schedules: [{ scheduleId: 's1' }] }));
+            await expect(useFiasSchedules().list()).resolves.toEqual([{ scheduleId: 's1' }]);
+            expect(mockBridge.request).toHaveBeenLastCalledWith(...entityOp(entity_ops_1.SCHEDULED_INVOCATIONS_ENTITY_ID, 'list', {}));
+            mockBridge.request.mockResolvedValueOnce(output({ schedules: [] }));
+            await useFiasSchedules().list({ limit: 100, scheduleIds: ['s1'] });
+            expect(mockBridge.request).toHaveBeenLastCalledWith(...entityOp(entity_ops_1.SCHEDULED_INVOCATIONS_ENTITY_ID, 'list', { limit: 100, scheduleIds: ['s1'] }));
+            mockBridge.request.mockResolvedValueOnce(output({ cancelled: true }));
+            await useFiasSchedules().cancel('s1');
+            expect(mockBridge.request).toHaveBeenLastCalledWith(...entityOp(entity_ops_1.SCHEDULED_INVOCATIONS_ENTITY_ID, 'cancel', { scheduleId: 's1' }));
+        });
+    });
+    describe('useFiasX / useFiasLinkedIn reads', () => {
+        it('unwrap each read through its entity verb', async () => {
+            const { useFiasX, useFiasLinkedIn } = require('./hooks');
+            mockBridge.request.mockResolvedValueOnce(output({ users: [{ id: '1' }] }));
+            await expect(useFiasX().searchUsers('conn_1', 'acme')).resolves.toEqual([{ id: '1' }]);
+            expect(mockBridge.request).toHaveBeenLastCalledWith(...entityOp(entity_ops_1.X_ENTITY_ID, 'search_users', { connectionId: 'conn_1', query: 'acme' }));
+            mockBridge.request.mockResolvedValueOnce(output({ organizations: [{ id: '2' }] }));
+            await expect(useFiasLinkedIn().searchOrganizations('conn_1', 'acme')).resolves.toEqual([
+                { id: '2' },
+            ]);
+            expect(mockBridge.request).toHaveBeenLastCalledWith(...entityOp(entity_ops_1.LINKEDIN_ENTITY_ID, 'search_organizations', {
+                connectionId: 'conn_1',
+                query: 'acme',
+            }));
+        });
+    });
     describe('NLLB translation entity', () => {
         it('exposes the NLLB_LANGUAGES picker list keyed by FLORES code', () => {
             const { NLLB_LANGUAGES } = require('./hooks');
@@ -1798,7 +1961,231 @@ describe('SDK hooks', () => {
             api.setCurrentStep('step-b');
         });
     });
+    describe('useArcheAssetBytes', () => {
+        const SIGNED = '/v1/arches/arc_1/assets/aset_1?m=mfst_1&u=usr_1&exp=1&sig=x';
+        const inFiveMinutes = () => Math.floor(Date.now() / 1000) + 300;
+        const entry = (assetId, expiresAt = inFiveMinutes()) => ({
+            assetId,
+            signedUrl: SIGNED.replace('aset_1', assetId),
+            expiresAt,
+        });
+        const bytesResult = (size = 1) => ({
+            contentType: 'audio/mpeg',
+            bytes: new ArrayBuffer(size),
+            sizeBytes: size,
+        });
+        /** The `signedUrls` of the nth bridge call (0-based). */
+        const urlsOfCall = (n) => mockBridge.request.mock.calls[n][1].input.signedUrls;
+        const readCalls = () => mockBridge.request.mock.calls.filter(([type]) => type === 'client_entity_invoke');
+        it('mints a signed URL, then has the host read it through the asset-bytes entity', async () => {
+            const { useArcheAssetBytes, ARCHE_ASSET_BYTES_ENTITY_ID } = require('./hooks');
+            const bytes = new Uint8Array([1, 2]).buffer;
+            mockBridge.request
+                .mockResolvedValueOnce({ assetId: 'aset_1', signedUrl: SIGNED, expiresAt: inFiveMinutes() })
+                .mockResolvedValueOnce({ results: [{ contentType: 'audio/mpeg', bytes, sizeBytes: 2 }] });
+            const result = await useArcheAssetBytes().getBytes('aset_1');
+            expect(mockBridge.request).toHaveBeenNthCalledWith(1, 'arche_assets_get_url', {
+                assetId: 'aset_1',
+            });
+            expect(mockBridge.request).toHaveBeenNthCalledWith(2, 'client_entity_invoke', {
+                entityId: ARCHE_ASSET_BYTES_ENTITY_ID,
+                input: { verb: 'read', signedUrls: [SIGNED] },
+            }, expect.any(Number));
+            expect(result).toEqual({ contentType: 'audio/mpeg', bytes, sizeBytes: 2 });
+        });
+        it("reuses a listed entry's signed URL — one round trip, no get_url", async () => {
+            const { useArcheAssetBytes } = require('./hooks');
+            mockBridge.request.mockResolvedValueOnce({ results: [bytesResult()] });
+            await useArcheAssetBytes().getBytes(entry('aset_1'));
+            expect(mockBridge.request).toHaveBeenCalledTimes(1);
+            expect(urlsOfCall(0)).toEqual([SIGNED]);
+        });
+        it('mints a fresh URL for an entry whose URL is about to expire', async () => {
+            const { useArcheAssetBytes } = require('./hooks');
+            const fresh = SIGNED.replace('exp=1', 'exp=2');
+            mockBridge.request
+                .mockResolvedValueOnce({ assetId: 'aset_1', signedUrl: fresh })
+                .mockResolvedValueOnce({ results: [bytesResult()] });
+            await useArcheAssetBytes().getBytes(entry('aset_1', Math.floor(Date.now() / 1000) + 5));
+            expect(mockBridge.request).toHaveBeenNthCalledWith(1, 'arche_assets_get_url', {
+                assetId: 'aset_1',
+            });
+            expect(urlsOfCall(1)).toEqual([fresh]);
+        });
+        it('retries once with a fresh URL when a reused one has lapsed', async () => {
+            const { useArcheAssetBytes } = require('./hooks');
+            const fresh = SIGNED.replace('exp=1', 'exp=2');
+            mockBridge.request
+                .mockResolvedValueOnce({
+                results: [{ error: { code: 'ASSET_URL_EXPIRED', message: 'expired' } }],
+            })
+                .mockResolvedValueOnce({ assetId: 'aset_1', signedUrl: fresh })
+                .mockResolvedValueOnce({ results: [bytesResult()] });
+            const result = await useArcheAssetBytes().getBytes(entry('aset_1'));
+            expect(result.sizeBytes).toBe(1);
+            expect(mockBridge.request).toHaveBeenCalledTimes(3);
+            expect(urlsOfCall(2)).toEqual([fresh]);
+        });
+        it('turns a refused call into a typed ArcheAssetError', async () => {
+            const { useArcheAssetBytes, ArcheAssetError } = require('./hooks');
+            mockBridge.request.mockResolvedValueOnce({
+                error: { code: 'ASSETS_UNAVAILABLE_IN_PREVIEW', message: 'not in preview' },
+            });
+            const err = await useArcheAssetBytes()
+                .getBytes(entry('aset_1'))
+                .catch((e) => e);
+            expect(err).toBeInstanceOf(ArcheAssetError);
+            expect(err).toMatchObject({
+                code: 'ASSETS_UNAVAILABLE_IN_PREVIEW',
+                message: 'not in preview',
+            });
+        });
+        it("turns one URL's error result into a typed ArcheAssetError", async () => {
+            const { useArcheAssetBytes } = require('./hooks');
+            mockBridge.request.mockResolvedValueOnce({
+                results: [{ error: { code: 'ASSET_URL_FORBIDDEN', message: 'not this arche' } }],
+            });
+            await expect(useArcheAssetBytes().getBytes(entry('aset_1'))).rejects.toMatchObject({
+                code: 'ASSET_URL_FORBIDDEN',
+                message: 'not this arche',
+            });
+        });
+        it('names both permissions when the bridge denies one', async () => {
+            const { useArcheAssetBytes } = require('./hooks');
+            mockBridge.request.mockRejectedValueOnce(new Error('Permission denied: entities:client_invoke not granted'));
+            const err = await useArcheAssetBytes()
+                .getBytes('aset_1')
+                .catch((e) => e);
+            expect(err).toMatchObject({ code: 'PERMISSION_DENIED' });
+            expect(err.message).toMatch(/assets:read.*entities:client_invoke/);
+        });
+        it('maps a rate-limit rejection to RATE_LIMIT and anything else to ASSET_UNAVAILABLE', async () => {
+            const { useArcheAssetBytes } = require('./hooks');
+            mockBridge.request.mockRejectedValueOnce(new Error('Rate limit exceeded'));
+            await expect(useArcheAssetBytes().getBytes('a')).rejects.toMatchObject({
+                code: 'RATE_LIMIT',
+            });
+            mockBridge.request.mockRejectedValueOnce(new Error('Asset not found: a'));
+            await expect(useArcheAssetBytes().getBytes('a')).rejects.toMatchObject({
+                code: 'ASSET_UNAVAILABLE',
+            });
+        });
+        it("maps the bridge's runaway-loop block to RATE_LIMIT and points at getMany", async () => {
+            const { useArcheAssetBytes } = require('./hooks');
+            mockBridge.request.mockRejectedValueOnce(new Error('Bridge call "client_entity_invoke" (entity: x) temporarily blocked — rapid-fire loop detected.'));
+            const err = await useArcheAssetBytes()
+                .getBytes(entry('aset_1'))
+                .catch((e) => e);
+            expect(err).toMatchObject({ code: 'RATE_LIMIT' });
+            expect(err.message).toMatch(/getMany/);
+        });
+        it('sends getBytes calls made together as one host call', async () => {
+            const { useArcheAssetBytes } = require('./hooks');
+            mockBridge.request.mockResolvedValueOnce({
+                results: [bytesResult(1), bytesResult(2), bytesResult(3)],
+            });
+            const { getBytes } = useArcheAssetBytes();
+            const results = await Promise.all(['a1', 'a2', 'a3'].map((id) => getBytes(entry(id))));
+            expect(readCalls()).toHaveLength(1);
+            expect(urlsOfCall(0)).toHaveLength(3);
+            expect(results.map((r) => r.sizeBytes)).toEqual([1, 2, 3]);
+        });
+        it('gives each caller of the same asset its own buffer (decodeAudioData detaches it)', async () => {
+            const { useArcheAssetBytes } = require('./hooks');
+            mockBridge.request.mockResolvedValueOnce({ results: [bytesResult(4)] });
+            const { getBytes } = useArcheAssetBytes();
+            const [first, second] = await Promise.all([getBytes(entry('a1')), getBytes(entry('a1'))]);
+            expect(urlsOfCall(0)).toHaveLength(1);
+            expect(first.bytes).not.toBe(second.bytes);
+            expect(second.bytes.byteLength).toBe(4);
+        });
+        describe('getMany', () => {
+            it('reads 150 sounds in two calls — never one per sound', async () => {
+                const { useArcheAssetBytes } = require('./hooks');
+                mockBridge.request.mockImplementation(async (_type, payload) => ({
+                    results: payload.input.signedUrls.map(() => bytesResult()),
+                }));
+                const entries = Array.from({ length: 150 }, (_, i) => entry(`a${i}`));
+                const loaded = await useArcheAssetBytes().getMany(entries);
+                expect(readCalls()).toHaveLength(2);
+                expect(urlsOfCall(0)).toHaveLength(100);
+                expect(urlsOfCall(1)).toHaveLength(50);
+                expect(Object.keys(loaded)).toHaveLength(150);
+                expect(loaded.a149).toMatchObject({ sizeBytes: 1 });
+            });
+            it('returns a failed asset as its ArcheAssetError without failing the rest', async () => {
+                const { useArcheAssetBytes, ArcheAssetError } = require('./hooks');
+                mockBridge.request.mockResolvedValueOnce({
+                    results: [
+                        bytesResult(),
+                        { error: { code: 'ASSET_UNAVAILABLE', message: 'the asset could not be read (404)' } },
+                    ],
+                });
+                const loaded = await useArcheAssetBytes().getMany([entry('a1'), entry('a2')]);
+                expect(loaded.a1).toMatchObject({ sizeBytes: 1 });
+                expect(loaded.a2).toBeInstanceOf(ArcheAssetError);
+                expect(loaded.a2).toMatchObject({ code: 'ASSET_UNAVAILABLE' });
+            });
+            it('rejects when the read is refused as a whole', async () => {
+                const { useArcheAssetBytes } = require('./hooks');
+                mockBridge.request.mockResolvedValueOnce({
+                    error: { code: 'ASSETS_UNAVAILABLE_IN_PREVIEW', message: 'not in preview' },
+                });
+                await expect(useArcheAssetBytes().getMany([entry('a1')])).rejects.toMatchObject({
+                    code: 'ASSETS_UNAVAILABLE_IN_PREVIEW',
+                });
+            });
+            it('reads again, together, the assets that did not fit the call byte budget', async () => {
+                const { useArcheAssetBytes } = require('./hooks');
+                const overBudget = { error: { code: 'ASSET_TOO_LARGE', message: 'read it on its own' } };
+                mockBridge.request
+                    .mockResolvedValueOnce({ results: [bytesResult(), overBudget, overBudget] })
+                    .mockResolvedValueOnce({ results: [bytesResult(), overBudget] })
+                    .mockResolvedValueOnce({ results: [bytesResult()] });
+                const loaded = await useArcheAssetBytes().getMany([entry('a1'), entry('a2'), entry('a3')]);
+                expect(urlsOfCall(1)).toHaveLength(2);
+                expect(urlsOfCall(2)).toHaveLength(1);
+                expect(Object.values(loaded).every((r) => !(r instanceof Error))).toBe(true);
+            });
+            it('refreshes at most 10 lapsed URLs per call and asks for a fresh list past that', async () => {
+                const { useArcheAssetBytes } = require('./hooks');
+                mockBridge.request.mockImplementation(async (type, payload) => type === 'arche_assets_get_url'
+                    ? { assetId: payload.assetId, signedUrl: SIGNED }
+                    : {
+                        results: payload.input.signedUrls.map(() => bytesResult()),
+                    });
+                const lapsed = Math.floor(Date.now() / 1000) - 1;
+                const entries = Array.from({ length: 15 }, (_, i) => entry(`a${i}`, lapsed));
+                const loaded = await useArcheAssetBytes().getMany(entries);
+                const minted = mockBridge.request.mock.calls.filter(([type]) => type === 'arche_assets_get_url');
+                expect(minted).toHaveLength(10);
+                const expired = Object.values(loaded).filter((r) => r instanceof Error && r.code === 'ASSET_URL_EXPIRED');
+                expect(expired).toHaveLength(5);
+                expect(expired[0].message).toMatch(/list the assets again/);
+            });
+        });
+    });
     describe('useArcheAssets', () => {
+        // Compile-time only (`pnpm typecheck:tests` fails if these drift): code
+        // written before the library held sounds keeps its image types.
+        function listingTypes(api) {
+            return async () => {
+                const images = await api.list({ limit: 10 });
+                const width = images.entries[0].width;
+                const refreshed = await api.getUrl('aset_1');
+                const height = refreshed.height;
+                const mixed = await api.list({ kinds: ['image', 'audio'] });
+                // @ts-expect-error a listing with kinds may hold sounds, which have no width
+                const unchecked = mixed.entries[0].width;
+                const first = mixed.entries[0];
+                const narrowed = first.contentType.startsWith('image/') && first.width !== null ? first.width : undefined;
+                const sound = await api.getUrl('aset_2');
+                return [width, height, unchecked, narrowed, sound];
+            };
+        }
+        it('keeps an images-only listing typed as images', () => {
+            expect(typeof listingTypes).toBe('function');
+        });
         it('list forwards to arche_assets_list with the cursor/limit options', async () => {
             const { useArcheAssets } = require('./hooks');
             mockBridge.request.mockResolvedValueOnce({ entries: [], nextCursor: null });
@@ -1821,6 +2208,17 @@ describe('SDK hooks', () => {
                 tags: ['category:background'],
             });
         });
+        it('list and index forward the kinds filter', async () => {
+            const { useArcheAssets } = require('./hooks');
+            mockBridge.request
+                .mockResolvedValueOnce({ entries: [], nextCursor: null })
+                .mockResolvedValueOnce({ groups: [] });
+            const api = useArcheAssets();
+            await api.list({ kinds: ['audio'] });
+            await api.index({ kinds: ['image', 'audio'] });
+            expect(mockBridge.request).toHaveBeenNthCalledWith(1, 'arche_assets_list', expect.objectContaining({ kinds: ['audio'] }));
+            expect(mockBridge.request).toHaveBeenNthCalledWith(2, 'arche_assets_index', expect.objectContaining({ kinds: ['image', 'audio'] }));
+        });
         it('index forwards to arche_assets_index with tags + groupBy', async () => {
             const { useArcheAssets } = require('./hooks');
             mockBridge.request.mockResolvedValueOnce({ groups: [] });
@@ -1846,6 +2244,100 @@ describe('SDK hooks', () => {
             expect(asset.assetId).toBe('aset_1');
         });
     });
+    describe('useLocalStore (ADR-031)', () => {
+        const ENTITY = 'ent_intg_plugin_local_store_0000';
+        const load = () => {
+            const { useLocalStore, FiasLocalStoreError } = require('./hooks');
+            return { store: useLocalStore(), FiasLocalStoreError };
+        };
+        it('puts through the generic client_entity_invoke op, verb in the input', async () => {
+            const { store } = load();
+            mockBridge.request.mockResolvedValueOnce({ sizeBytes: 7 });
+            expect(await store.put('session/1', { a: 1 })).toEqual({ sizeBytes: 7 });
+            expect(mockBridge.request).toHaveBeenCalledWith('client_entity_invoke', { entityId: ENTITY, input: { verb: 'put', key: 'session/1', value: { a: 1 } } }, 120000);
+        });
+        it('reads each kind back through the typed getters, and null for a missing key', async () => {
+            const { store } = load();
+            const meta = { key: 'k', sizeBytes: 1, updatedAt: '2026-10-13T00:00:00.000Z' };
+            mockBridge.request.mockResolvedValueOnce({ entry: { ...meta, value: 'hi' } });
+            expect(await store.getText('k')).toBe('hi');
+            const bytes = new Uint8Array([1, 2]).buffer;
+            mockBridge.request.mockResolvedValueOnce({ entry: { ...meta, value: bytes } });
+            expect(await store.getBytes('k')).toBe(bytes);
+            mockBridge.request.mockResolvedValueOnce({ entry: { ...meta, value: { n: 1 } } });
+            expect(await store.getJson('k')).toEqual({ n: 1 });
+            mockBridge.request.mockResolvedValueOnce({ entry: null });
+            expect(await store.getJson('k')).toBeNull();
+            mockBridge.request.mockResolvedValueOnce({ entry: { ...meta, value: 'raw' } });
+            expect(await store.get('k')).toEqual({ ...meta, value: 'raw' });
+        });
+        it('getJson parses a text entry, so put(JSON.stringify(x)) reads back like put(x)', async () => {
+            const { store, FiasLocalStoreError } = load();
+            const meta = { key: 'k', sizeBytes: 7, updatedAt: '2026-10-13T00:00:00.000Z' };
+            mockBridge.request.mockResolvedValueOnce({ entry: { ...meta, value: '{"n":1}' } });
+            expect(await store.getJson('k')).toEqual({ n: 1 });
+            mockBridge.request.mockResolvedValueOnce({ entry: { ...meta, value: 'not json' } });
+            const err = await store.getJson('k').catch((e) => e);
+            expect(err).toBeInstanceOf(FiasLocalStoreError);
+            expect(err).toMatchObject({ code: 'LOCAL_STORE_WRONG_KIND' });
+        });
+        it('the typed getters refuse the wrong kind with LOCAL_STORE_WRONG_KIND', async () => {
+            const { store } = load();
+            const meta = { key: 'k', sizeBytes: 2, updatedAt: '2026-10-13T00:00:00.000Z' };
+            mockBridge.request.mockResolvedValueOnce({ entry: { ...meta, value: { n: 1 } } });
+            await expect(store.getText('k')).rejects.toMatchObject({ code: 'LOCAL_STORE_WRONG_KIND' });
+            mockBridge.request.mockResolvedValueOnce({ entry: { ...meta, value: 'text' } });
+            await expect(store.getBytes('k')).rejects.toMatchObject({ code: 'LOCAL_STORE_WRONG_KIND' });
+            mockBridge.request.mockResolvedValueOnce({ entry: { ...meta, value: new ArrayBuffer(1) } });
+            await expect(store.getJson('k')).rejects.toMatchObject({ code: 'LOCAL_STORE_WRONG_KIND' });
+        });
+        it('throws a coded FiasLocalStoreError when the host returns { error }', async () => {
+            const { store, FiasLocalStoreError } = load();
+            mockBridge.request.mockResolvedValueOnce({
+                error: { code: 'LOCAL_STORE_QUOTA_EXCEEDED', message: 'over budget' },
+            });
+            const err = await store.put('k', 'v').catch((e) => e);
+            expect(err).toBeInstanceOf(FiasLocalStoreError);
+            expect(err).toMatchObject({ code: 'LOCAL_STORE_QUOTA_EXCEEDED', message: 'over budget' });
+        });
+        it.each([
+            ['Permission denied: storage:local not granted', undefined, 'PERMISSION_DENIED'],
+            ['refused', 'PERMISSION_DENIED', 'PERMISSION_DENIED'],
+            ['Rate limit exceeded for ent_intg_plugin_local_store_0000', undefined, 'RATE_LIMIT'],
+            ['slow down', 'RATE_LIMIT', 'RATE_LIMIT'],
+            ['Bridge request timed out', 'TIMEOUT', 'LOCAL_STORE_UNAVAILABLE'],
+        ])('maps a bridge failure (%s, code %s) to %s', async (message, code, expected) => {
+            const { store } = load();
+            mockBridge.request.mockRejectedValueOnce(Object.assign(new Error(message), { code }));
+            await expect(store.list()).rejects.toMatchObject({ code: expected });
+        });
+        it('lists, deletes, clears and estimates with the documented shapes', async () => {
+            const { store } = load();
+            const entries = [{ key: 'a', sizeBytes: 1, updatedAt: '2026-10-13T00:00:00.000Z' }];
+            mockBridge.request.mockResolvedValueOnce({ entries });
+            expect(await store.list('a')).toEqual(entries);
+            expect(mockBridge.request).toHaveBeenLastCalledWith('client_entity_invoke', { entityId: ENTITY, input: { verb: 'list', prefix: 'a' } }, 120000);
+            mockBridge.request.mockResolvedValueOnce({});
+            await expect(store.delete('a')).resolves.toBeUndefined();
+            mockBridge.request.mockResolvedValueOnce({ deleted: 3 });
+            expect(await store.clear()).toEqual({ deleted: 3 });
+            mockBridge.request.mockResolvedValueOnce({ usedBytes: 10, budgetBytes: 100 });
+            expect(await store.estimate()).toEqual({ usedBytes: 10, budgetBytes: 100 });
+        });
+        it('getMany reads several entries in one call, in order, null for a missing key', async () => {
+            const { store } = load();
+            const a = { key: 'a', value: 'x', sizeBytes: 1, updatedAt: '2026-10-14T00:00:00.000Z' };
+            mockBridge.request.mockResolvedValueOnce({ entries: [a, null] });
+            expect(await store.getMany(['a', 'gone'])).toEqual([a, null]);
+            expect(mockBridge.request).toHaveBeenLastCalledWith('client_entity_invoke', { entityId: ENTITY, input: { verb: 'get_many', keys: ['a', 'gone'] } }, 120000);
+            mockBridge.request.mockResolvedValueOnce({
+                error: { code: 'LOCAL_STORE_VALUE_TOO_LARGE', message: 'read fewer keys at a time' },
+            });
+            await expect(store.getMany(['a', 'b'])).rejects.toMatchObject({
+                code: 'LOCAL_STORE_VALUE_TOO_LARGE',
+            });
+        });
+    });
     describe('useFiasContent (content packs, ADR-021)', () => {
         const ENTITY = 'ent_intg_plugin_content_00000000';
         const load = () => {