@fias/arche-sdk 2.27.0 → 2.28.0

package/dist/hooks.test.js

@@ -1798,7 +1798,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 +2045,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 +2081,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 = () => {