@rozenite/storage-plugin 2.1.0 → 2.3.0

package/dist/react-native/src/react-native/useStorageAgentTools.js

@@ -0,0 +1,223 @@
+import { useRozenitePluginAgentTool } from '@rozenite/agent-bridge';
+import { DEFAULT_PAGE_LIMIT, MAX_PAGE_LIMIT } from '@rozenite/agent-shared';
+import { STORAGE_AGENT_PLUGIN_ID, storageToolDefinitions, } from '../shared/agent-tools';
+const parseValueForType = (type, value) => {
+    if (type === 'string') {
+        if (typeof value !== 'string') {
+            throw new Error('Expected string value for type=string');
+        }
+        return value;
+    }
+    if (type === 'number') {
+        if (typeof value !== 'number' || Number.isNaN(value)) {
+            throw new Error('Expected number value for type=number');
+        }
+        return value;
+    }
+    if (type === 'boolean') {
+        if (typeof value !== 'boolean') {
+            throw new Error('Expected boolean value for type=boolean');
+        }
+        return value;
+    }
+    if (!Array.isArray(value) || !value.every((item) => Number.isInteger(item))) {
+        throw new Error('Expected number[] value for type=buffer');
+    }
+    return value;
+};
+const formatViewRef = (view) => `${view.target.adapterId}/${view.target.storageId}`;
+const isSameTarget = (left, right) => left.adapterId === right.adapterId && left.storageId === right.storageId;
+const encodeCursor = (cursor) => btoa(encodeURIComponent(JSON.stringify(cursor)));
+const decodeCursor = (value) => {
+    try {
+        const cursor = JSON.parse(decodeURIComponent(atob(value)));
+        if (typeof cursor !== 'object' ||
+            cursor == null ||
+            Array.isArray(cursor) ||
+            cursor.version !== 1 ||
+            typeof cursor.target?.adapterId !== 'string' ||
+            typeof cursor.target?.storageId !== 'string' ||
+            !Number.isSafeInteger(cursor.offset) ||
+            cursor.offset < 0) {
+            throw new Error('Invalid cursor');
+        }
+        return cursor;
+    }
+    catch {
+        throw new Error('Invalid cursor. Run list-entries again without a cursor to restart pagination.');
+    }
+};
+const sanitizeLimit = (limit) => {
+    if (typeof limit !== 'number' ||
+        !Number.isFinite(limit) ||
+        !Number.isInteger(limit) ||
+        limit < 1) {
+        return DEFAULT_PAGE_LIMIT;
+    }
+    return Math.min(limit, MAX_PAGE_LIMIT);
+};
+const sanitizeOffset = (offset) => {
+    if (typeof offset !== 'number' ||
+        !Number.isFinite(offset) ||
+        !Number.isSafeInteger(offset) ||
+        offset < 0) {
+        return 0;
+    }
+    return offset;
+};
+const resolveStorage = (views, adapterId, storageId) => {
+    if (views.length === 0) {
+        throw new Error('No storages are registered.');
+    }
+    if (adapterId !== undefined || storageId !== undefined) {
+        const matches = views.filter((view) => (adapterId === undefined || view.target.adapterId === adapterId) &&
+            (storageId === undefined || view.target.storageId === storageId));
+        const qualifier = [
+            adapterId !== undefined && `adapterId="${adapterId}"`,
+            storageId !== undefined && `storageId="${storageId}"`,
+        ]
+            .filter(Boolean)
+            .join(', ');
+        if (matches.length === 0) {
+            throw new Error(`No storage matched ${qualifier}. Available: ${views.map(formatViewRef).join(', ')}`);
+        }
+        if (matches.length > 1) {
+            throw new Error(`Multiple storages matched ${qualifier}. Provide both adapterId and storageId. Available: ${matches.map(formatViewRef).join(', ')}`);
+        }
+        return matches[0];
+    }
+    if (views.length > 1) {
+        throw new Error(`Multiple storages detected. Provide adapterId and/or storageId. Available: ${views.map(formatViewRef).join(', ')}`);
+    }
+    return views[0];
+};
+const listStorageKeys = async (view, input) => {
+    const limit = sanitizeLimit(input.limit);
+    if (input.cursor !== undefined && input.offset !== undefined) {
+        throw new Error('Provide either cursor or offset, not both.');
+    }
+    const cursor = input.cursor === undefined ? undefined : decodeCursor(input.cursor);
+    if (cursor && !isSameTarget(cursor.target, view.target)) {
+        throw new Error('Cursor does not match the requested storage. Run list-entries again without a cursor to restart pagination.');
+    }
+    const allKeys = await view.getAllKeys();
+    const offset = cursor?.offset ?? sanitizeOffset(input.offset);
+    const end = Math.min(offset + limit, allKeys.length);
+    return {
+        adapterId: view.target.adapterId,
+        storageId: view.target.storageId,
+        total: allKeys.length,
+        items: allKeys.slice(offset, end).map((key) => ({ key })),
+        page: {
+            limit,
+            hasMore: end < allKeys.length,
+            ...(end < allKeys.length
+                ? {
+                    nextCursor: encodeCursor({
+                        version: 1,
+                        target: view.target,
+                        offset: end,
+                    }),
+                }
+                : {}),
+        },
+    };
+};
+export const createStorageAgentHandlers = (views) => ({
+    listStorages: async () => ({
+        storages: views.map((view) => ({
+            adapterId: view.target.adapterId,
+            storageId: view.target.storageId,
+            adapterName: view.adapterName,
+            storageName: view.storageName,
+            supportedTypes: view.capabilities.supportedTypes,
+        })),
+    }),
+    listEntries: async (input) => {
+        const view = resolveStorage(views, input.adapterId, input.storageId);
+        return listStorageKeys(view, input);
+    },
+    readEntry: async ({ adapterId, storageId, key, }) => {
+        const view = resolveStorage(views, adapterId, storageId);
+        const entry = await view.get(key);
+        if (!entry) {
+            throw new Error(`Key "${key}" not found in storage "${formatViewRef(view)}".`);
+        }
+        return {
+            adapterId: view.target.adapterId,
+            storageId: view.target.storageId,
+            entry,
+        };
+    },
+});
+export const useStorageAgentTools = (views) => {
+    const handlers = createStorageAgentHandlers(views);
+    useRozenitePluginAgentTool({
+        pluginId: STORAGE_AGENT_PLUGIN_ID,
+        tool: storageToolDefinitions.listStorages,
+        handler: handlers.listStorages,
+    });
+    useRozenitePluginAgentTool({
+        pluginId: STORAGE_AGENT_PLUGIN_ID,
+        tool: storageToolDefinitions.listEntries,
+        handler: handlers.listEntries,
+    });
+    useRozenitePluginAgentTool({
+        pluginId: STORAGE_AGENT_PLUGIN_ID,
+        tool: storageToolDefinitions.readEntry,
+        handler: handlers.readEntry,
+    });
+    useRozenitePluginAgentTool({
+        pluginId: STORAGE_AGENT_PLUGIN_ID,
+        tool: storageToolDefinitions.createEntry,
+        handler: async ({ adapterId, storageId, key, type, value }) => {
+            const view = resolveStorage(views, adapterId, storageId);
+            const existing = await view.get(key);
+            if (existing) {
+                throw new Error(`Key "${key}" already exists in storage "${formatViewRef(view)}". Use edit-entry instead.`);
+            }
+            const parsedValue = parseValueForType(type, value);
+            await view.set({ key, type, value: parsedValue });
+            return {
+                adapterId: view.target.adapterId,
+                storageId: view.target.storageId,
+                created: true,
+                key,
+            };
+        },
+    });
+    useRozenitePluginAgentTool({
+        pluginId: STORAGE_AGENT_PLUGIN_ID,
+        tool: storageToolDefinitions.editEntry,
+        handler: async ({ adapterId, storageId, key, type, value }) => {
+            const view = resolveStorage(views, adapterId, storageId);
+            const existing = await view.get(key);
+            if (!existing) {
+                throw new Error(`Key "${key}" not found in storage "${formatViewRef(view)}". Use create-entry instead.`);
+            }
+            const parsedValue = parseValueForType(type, value);
+            await view.set({ key, type, value: parsedValue });
+            return {
+                adapterId: view.target.adapterId,
+                storageId: view.target.storageId,
+                edited: true,
+                key,
+            };
+        },
+    });
+    useRozenitePluginAgentTool({
+        pluginId: STORAGE_AGENT_PLUGIN_ID,
+        tool: storageToolDefinitions.removeEntry,
+        handler: async ({ adapterId, storageId, key }) => {
+            const view = resolveStorage(views, adapterId, storageId);
+            const existed = !!(await view.get(key));
+            await view.delete(key);
+            return {
+                adapterId: view.target.adapterId,
+                storageId: view.target.storageId,
+                removed: existed,
+                key,
+            };
+        },
+    });
+};

package/dist/react-native/src/shared/agent-tools.d.ts

@@ -0,0 +1,76 @@
+import { type AgentToolContract } from '@rozenite/agent-shared';
+import type { StorageEntry, StorageEntryType, StorageTarget } from './types';
+type StorageSelection = Partial<StorageTarget>;
+export declare const STORAGE_AGENT_PLUGIN_ID = "@rozenite/storage-plugin";
+export declare const STORAGE_AGENT_ENTRY_TYPES: readonly ["string", "number", "boolean", "buffer"];
+export type StorageListStoragesArgs = undefined;
+export type StorageListStoragesItem = {
+    adapterId: string;
+    storageId: string;
+    adapterName: string;
+    storageName: string;
+    supportedTypes: StorageEntryType[];
+};
+export type StorageListStoragesResult = {
+    storages: StorageListStoragesItem[];
+};
+export type StorageListEntriesArgs = StorageSelection & {
+    limit?: number;
+    cursor?: string;
+    /** @deprecated Use the opaque cursor returned by a previous page. */
+    offset?: number;
+};
+export type StorageListEntriesResult = {
+    adapterId: string;
+    storageId: string;
+    total: number;
+    items: Array<{
+        key: string;
+    }>;
+    page: {
+        limit: number;
+        hasMore: boolean;
+        nextCursor?: string;
+    };
+};
+export type StorageReadEntryArgs = StorageSelection & {
+    key: string;
+};
+export type StorageReadEntryResult = {
+    adapterId: string;
+    storageId: string;
+    entry: StorageEntry;
+};
+export type StorageWriteEntryArgs = StorageSelection & StorageEntry;
+export type StorageCreateEntryArgs = StorageWriteEntryArgs;
+export type StorageCreateEntryResult = {
+    adapterId: string;
+    storageId: string;
+    created: true;
+    key: string;
+};
+export type StorageEditEntryArgs = StorageWriteEntryArgs;
+export type StorageEditEntryResult = {
+    adapterId: string;
+    storageId: string;
+    edited: true;
+    key: string;
+};
+export type StorageRemoveEntryArgs = StorageSelection & {
+    key: string;
+};
+export type StorageRemoveEntryResult = {
+    adapterId: string;
+    storageId: string;
+    removed: boolean;
+    key: string;
+};
+export declare const storageToolDefinitions: {
+    readonly listStorages: AgentToolContract<undefined, StorageListStoragesResult>;
+    readonly listEntries: AgentToolContract<StorageListEntriesArgs, StorageListEntriesResult>;
+    readonly readEntry: AgentToolContract<StorageReadEntryArgs, StorageReadEntryResult>;
+    readonly createEntry: AgentToolContract<StorageWriteEntryArgs, StorageCreateEntryResult>;
+    readonly editEntry: AgentToolContract<StorageWriteEntryArgs, StorageEditEntryResult>;
+    readonly removeEntry: AgentToolContract<StorageRemoveEntryArgs, StorageRemoveEntryResult>;
+};
+export {};

package/dist/react-native/src/shared/agent-tools.js

@@ -0,0 +1,116 @@
+import { defineAgentToolContract, definePaginatedAgentToolContract, } from '@rozenite/agent-shared';
+const sharedStorageProperties = {
+    adapterId: {
+        type: 'string',
+        description: 'Storage adapter ID. Required when multiple adapters are configured.',
+    },
+    storageId: {
+        type: 'string',
+        description: 'Storage node ID within the adapter. Required when multiple storages are configured.',
+    },
+};
+export const STORAGE_AGENT_PLUGIN_ID = '@rozenite/storage-plugin';
+export const STORAGE_AGENT_ENTRY_TYPES = [
+    'string',
+    'number',
+    'boolean',
+    'buffer',
+];
+export const storageToolDefinitions = {
+    listStorages: defineAgentToolContract({
+        name: 'list-storages',
+        description: 'List all storage adapters and their storage nodes currently available on the device, including supported entry types. Entry counts are omitted to avoid enumerating every storage.',
+        inputSchema: { type: 'object', properties: {} },
+    }),
+    listEntries: definePaginatedAgentToolContract({
+        name: 'list-entries',
+        description: 'List keys in a storage. This call intentionally does not return entry values to keep responses token-efficient.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                ...sharedStorageProperties,
+                limit: {
+                    type: 'number',
+                    description: 'Pagination size. Defaults to 20 and is capped at 100.',
+                },
+                cursor: {
+                    type: 'string',
+                    description: 'Opaque pagination cursor from a previous list-entries call.',
+                },
+                offset: {
+                    type: 'number',
+                    description: 'Deprecated initial pagination offset. Must be a non-negative integer and cannot be combined with cursor.',
+                },
+            },
+        },
+        pagination: {
+            kind: 'cursor',
+            fields: ['key'],
+            defaultFields: ['key'],
+        },
+    }),
+    readEntry: defineAgentToolContract({
+        name: 'read-entry',
+        description: 'Read a single storage entry value by key.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                ...sharedStorageProperties,
+                key: { type: 'string', description: 'Entry key.' },
+            },
+            required: ['key'],
+        },
+    }),
+    createEntry: defineAgentToolContract({
+        name: 'create-entry',
+        description: 'Create a new storage entry. Fails if the key already exists.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                ...sharedStorageProperties,
+                key: { type: 'string', description: 'Entry key.' },
+                type: {
+                    type: 'string',
+                    enum: [...STORAGE_AGENT_ENTRY_TYPES],
+                    description: 'Entry value type. Must be one of the supported types for the target storage (see list-storages).',
+                },
+                value: {
+                    description: 'Entry value matching the provided type.',
+                },
+            },
+            required: ['key', 'type', 'value'],
+        },
+    }),
+    editEntry: defineAgentToolContract({
+        name: 'edit-entry',
+        description: 'Edit an existing storage entry. Fails if the key does not exist.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                ...sharedStorageProperties,
+                key: { type: 'string', description: 'Entry key.' },
+                type: {
+                    type: 'string',
+                    enum: [...STORAGE_AGENT_ENTRY_TYPES],
+                    description: 'Entry value type. Must be one of the supported types for the target storage (see list-storages).',
+                },
+                value: {
+                    description: 'Entry value matching the provided type.',
+                },
+            },
+            required: ['key', 'type', 'value'],
+        },
+    }),
+    removeEntry: defineAgentToolContract({
+        name: 'remove-entry',
+        description: 'Remove a storage entry by key.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                ...sharedStorageProperties,
+                key: { type: 'string', description: 'Entry key.' },
+            },
+            required: ['key'],
+        },
+    }),
+};

package/dist/react-native/src/shared/entry-preview.d.ts

@@ -0,0 +1,4 @@
+import type { StorageEntry, StorageEntryPreview } from './types';
+export declare const MAX_STRING_PREVIEW_CODE_POINTS = 256;
+export declare const MAX_BUFFER_PREVIEW_BYTES = 16;
+export declare const toStorageEntryPreview: (entry: StorageEntry) => StorageEntryPreview;

package/dist/react-native/src/shared/entry-preview.js

@@ -0,0 +1,44 @@
+export const MAX_STRING_PREVIEW_CODE_POINTS = 256;
+export const MAX_BUFFER_PREVIEW_BYTES = 16;
+const toHexPair = (byte) => byte.toString(16).toUpperCase().padStart(2, '0');
+const truncateString = (value) => {
+    let preview = '';
+    let codePointCount = 0;
+    for (const codePoint of value) {
+        if (codePointCount === MAX_STRING_PREVIEW_CODE_POINTS) {
+            return { preview, isTruncated: true };
+        }
+        preview += codePoint;
+        codePointCount += 1;
+    }
+    return { preview, isTruncated: false };
+};
+export const toStorageEntryPreview = (entry) => {
+    if (entry.type === 'string') {
+        return {
+            key: entry.key,
+            type: entry.type,
+            ...truncateString(entry.value),
+            // JavaScript strings expose their length in UTF-16 code units.
+            valueSize: entry.value.length,
+        };
+    }
+    if (entry.type === 'buffer') {
+        const shownBytes = entry.value.slice(0, MAX_BUFFER_PREVIEW_BYTES);
+        return {
+            key: entry.key,
+            type: entry.type,
+            preview: shownBytes.map(toHexPair).join(' '),
+            valueSize: entry.value.length,
+            isTruncated: entry.value.length > MAX_BUFFER_PREVIEW_BYTES,
+        };
+    }
+    const preview = String(entry.value);
+    return {
+        key: entry.key,
+        type: entry.type,
+        preview,
+        valueSize: preview.length,
+        isTruncated: false,
+    };
+};

package/dist/react-native/src/shared/messaging.d.ts

@@ -0,0 +1,134 @@
+import type { StorageDescriptor, StorageEntry, StorageEntryPreview, StorageTarget } from './types';
+import type { ImportPreview, StorageSnapshotV1 } from './snapshot';
+export type StorageSetEntryEvent = {
+    type: 'set-entry';
+    target: StorageTarget;
+    entry: StorageEntry;
+};
+export type StorageDeleteEntryEvent = {
+    type: 'delete-entry';
+    target: StorageTarget;
+    key: string;
+};
+export type StoragePurgeEvent = {
+    type: 'purge-storage';
+    target: StorageTarget;
+};
+export type StorageInvalidationOperation = 'set' | 'delete' | 'import' | 'purge';
+export type StorageInvalidatedEvent = {
+    type: 'storage-invalidated';
+    target: StorageTarget;
+    /** Native subscriptions only expose a key, not the operation. */
+    key?: string;
+    operation?: StorageInvalidationOperation;
+    /** Updated entry count for the storage after the invalidation. */
+    entryCount: number;
+};
+/**
+ * Announced by the device once it is listening for panel requests. The panel is
+ * recreated on every app reload and asks for storages immediately, which can
+ * land before the app's React tree has mounted the plugin; this lets the panel
+ * ask again instead of waiting forever on a dropped request.
+ */
+export type StorageDeviceReadyEvent = {
+    type: 'device-ready';
+};
+export type StorageDiscoverStoragesRequestEvent = {
+    type: 'discover-storages';
+    requestId: string;
+};
+export type StorageDiscoverStoragesResponseEvent = {
+    type: 'storage-descriptors';
+    requestId: string;
+    storages: StorageDescriptor[];
+};
+export type StorageListEntryPreviewsRequestEvent = {
+    type: 'list-entry-previews';
+    requestId: string;
+    target: StorageTarget;
+    search?: string;
+    keySortDirection?: 'ascending' | 'descending';
+    cursor?: string;
+    limit: number;
+};
+export type StorageListEntryPreviewsResponseEvent = {
+    type: 'entry-previews';
+    requestId: string;
+    target: StorageTarget;
+    items: StorageEntryPreview[];
+    nextCursor?: string;
+    previousCursor?: string;
+};
+export type StorageGetEntryRequestEvent = {
+    type: 'get-entry';
+    requestId: string;
+    target: StorageTarget;
+    key: string;
+};
+export type StorageGetEntryResponseEvent = {
+    type: 'entry';
+    requestId: string;
+    target: StorageTarget;
+    entry: StorageEntry;
+};
+export type StorageExportSnapshotRequestEvent = {
+    type: 'export-snapshot';
+    requestId: string;
+    target: StorageTarget;
+};
+export type StorageExportSnapshotResponseEvent = {
+    type: 'export-snapshot-result';
+    requestId: string;
+    target: StorageTarget;
+    snapshot: StorageSnapshotV1;
+};
+export type StorageImportPreviewRequestEvent = {
+    type: 'preview-import';
+    requestId: string;
+    target: StorageTarget;
+    snapshot: StorageSnapshotV1;
+};
+export type StorageImportPreviewResponseEvent = {
+    type: 'import-preview';
+    requestId: string;
+    target: StorageTarget;
+    preview: ImportPreview;
+};
+export type StorageRequestError = {
+    requestId: string;
+    code: 'TARGET_NOT_FOUND' | 'ENTRY_NOT_FOUND' | 'INVALID_CURSOR' | 'INVALID_REQUEST' | 'READ_FAILED' | 'WRITE_FAILED';
+    message: string;
+    resetPagination?: boolean;
+};
+export type StorageRequestErrorEvent = StorageRequestError & {
+    type: 'storage-request-error';
+};
+export type StorageImportEntriesEvent = {
+    type: 'import-entries';
+    requestId: string;
+    target: StorageTarget;
+    entries: StorageEntry[];
+};
+export type StorageImportProgressEvent = {
+    type: 'import-progress';
+    requestId: string;
+    target: StorageTarget;
+    written: number;
+    total: number;
+};
+export type StorageImportResultEvent = {
+    type: 'import-result';
+    requestId: string;
+    target: StorageTarget;
+    ok: boolean;
+    written: number;
+    total: number;
+    failedKey?: string;
+    error?: string;
+};
+export type StorageEvent = StorageSetEntryEvent | StorageDeleteEntryEvent | StoragePurgeEvent | StorageInvalidatedEvent | StorageDeviceReadyEvent | StorageDiscoverStoragesRequestEvent | StorageDiscoverStoragesResponseEvent | StorageListEntryPreviewsRequestEvent | StorageListEntryPreviewsResponseEvent | StorageGetEntryRequestEvent | StorageGetEntryResponseEvent | StorageExportSnapshotRequestEvent | StorageExportSnapshotResponseEvent | StorageImportPreviewRequestEvent | StorageImportPreviewResponseEvent | StorageRequestErrorEvent | StorageImportEntriesEvent | StorageImportProgressEvent | StorageImportResultEvent;
+export type StorageEventMap = {
+    [K in StorageEvent['type']]: Extract<StorageEvent, {
+        type: K;
+    }>;
+};

package/dist/react-native/src/shared/messaging.js

@@ -0,0 +1 @@
+export {};

package/dist/react-native/src/shared/snapshot.d.ts

@@ -0,0 +1,53 @@
+import { type StorageCapabilities, type StorageEntry, type StorageEntryType, type StorageTarget } from './types';
+export type StorageSnapshotV1 = {
+    version: 1;
+    plugin: string;
+    createdAt: string;
+    storage: {
+        adapterId: string;
+        storageId: string;
+        adapterName: string;
+        storageName: string;
+        capabilities: StorageCapabilities;
+    };
+    entries: StorageEntry[];
+};
+export type ParseError = {
+    path: string;
+    message: string;
+};
+export type ParseResult = {
+    ok: true;
+    snapshot: StorageSnapshotV1;
+} | {
+    ok: false;
+    error: ParseError;
+};
+export declare const parseSnapshot: (raw: unknown) => ParseResult;
+export declare const buildSnapshot: (args: {
+    target: StorageTarget;
+    adapterName: string;
+    storageName: string;
+    capabilities: StorageCapabilities;
+    entries: StorageEntry[];
+}) => StorageSnapshotV1;
+export type ImportPreview = {
+    newKeys: string[];
+    overwriteKeys: string[];
+    skippedKeys: {
+        key: string;
+        reason: 'blacklist';
+    }[];
+    unsupportedTypes: {
+        key: string;
+        type: StorageEntryType;
+    }[];
+    acceptedEntryIndexes: number[];
+    metadataMismatch: boolean;
+};
+export declare const computePreview: (snapshot: StorageSnapshotV1, current: {
+    target: StorageTarget;
+    capabilities: StorageCapabilities;
+    entryKeys: Set<string>;
+    isBlacklisted: (key: string) => boolean;
+}) => ImportPreview;