@rozenite/storage-plugin 1.12.0 → 2.0.0

package/src/react-native/useRozeniteStoragePlugin.ts

@@ -2,13 +2,23 @@ import { useRozeniteDevToolsClient } from '@rozenite/plugin-bridge';
 import { useEffect, useMemo } from 'react';
 import type {
   StorageDeleteEntryEvent,
+  StorageDiscoverStoragesRequestEvent,
   StorageEventMap,
-  StorageGetSnapshotEvent,
+  StorageExportSnapshotRequestEvent,
+  StorageGetEntryRequestEvent,
   StorageImportEntriesEvent,
+  StorageImportPreviewRequestEvent,
+  StorageInvalidationOperation,
+  StorageListEntryPreviewsRequestEvent,
   StorageSetEntryEvent,
+  StoragePurgeEvent,
 } from '../shared/messaging';
 import type { StorageAdapter } from '../shared/types';
-import { handleImportEntries } from './import';
+import { handleImportEntries, handleImportPreviewRequest } from './import';
+import { handleStorageDiscoveryRequest } from './storage-discovery';
+import { handleListEntryPreviewsRequest } from './entry-preview-pagination';
+import { handleFullEntryRequest } from './full-entry-request';
+import { handleExportSnapshotRequest } from './export-snapshot';
 import { createStorageViews } from './storage-view';
 import { useStorageAgentTools } from './useStorageAgentTools';
 
@@ -32,73 +42,50 @@ export const useRozeniteStoragePlugin = ({
       return;
     }
 
-    const pushSnapshot = async (viewId?: string) => {
-      const selectedViews = viewId
-        ? views.filter((view) => view.id === viewId)
-        : views;
-
-      for (const view of selectedViews) {
-        try {
-          const entries = await view.getAllEntries();
-          client.send('snapshot', {
-            type: 'snapshot',
-            target: view.target,
-            adapterName: view.adapterName,
-            storageName: view.storageName,
-            capabilities: view.capabilities,
-            blacklist: view.blacklist
-              ? { source: view.blacklist.source, flags: view.blacklist.flags }
-              : undefined,
-            entries,
-          });
-        } catch (error) {
-          console.warn(
-            `[Rozenite] Storage Plugin: Failed to snapshot ${view.target.adapterId}/${view.target.storageId}.`,
-            error,
-          );
-        }
-      }
-    };
-
-    void pushSnapshot();
-
     const viewSubscriptions: { remove: () => void }[] = [];
     let disposed = false;
 
+    const sendInvalidation = (
+      target: StorageSetEntryEvent['target'],
+      key?: string,
+      operation?: StorageInvalidationOperation,
+    ) => {
+      client.send('storage-invalidated', {
+        type: 'storage-invalidated',
+        target,
+        key,
+        operation,
+      });
+    };
+
     // Prevent one storage watcher failure from breaking the whole plugin.
     void Promise.all(
-      views.map(async (view) => {
-        try {
-          const subscription = await view.watch({
-            onSet: (entry) => {
-              client.send('set-entry', {
-                type: 'set-entry',
-                target: view.target,
-                entry,
-              });
-            },
-            onDelete: (key) => {
-              client.send('delete-entry', {
-                type: 'delete-entry',
-                target: view.target,
-                key,
-              });
-            },
-          });
+      views
+        .filter((view) => view.supportsSubscriptions && view.watch)
+        .map(async (view) => {
+          try {
+            const watch = view.watch;
+            if (!watch) {
+              return;
+            }
 
-          if (disposed) {
-            subscription.remove();
-            return;
-          }
+            const subscription = await watch((key) => {
+              sendInvalidation(view.target, key);
+            });
 
-          viewSubscriptions.push(subscription);
-        } catch (error) {
-          console.warn(
-            `[Rozenite] Storage Plugin: Failed to attach watcher for ${view.target.adapterId}/${view.target.storageId}.`,
-            error,
-          );
-        }
-      }),
+            if (disposed) {
+              subscription.remove();
+              return;
+            }
+
+            viewSubscriptions.push(subscription);
+          } catch (error) {
+            console.warn(
+              `[Rozenite] Storage Plugin: Failed to attach watcher for ${view.target.adapterId}/${view.target.storageId}.`,
+              error,
+            );
+          }
+        }),
     );
 
     const messageSubscriptions = [
@@ -120,6 +107,7 @@ export const useRozeniteStoragePlugin = ({
 
           try {
             await view.set(entry);
+            sendInvalidation(view.target, entry.key, 'set');
           } catch (error) {
             console.warn(
               `[Rozenite] Storage Plugin: Failed to set entry in ${target.adapterId}/${target.storageId}.`,
@@ -146,6 +134,7 @@ export const useRozeniteStoragePlugin = ({
 
           try {
             await view.delete(key);
+            sendInvalidation(view.target, key, 'delete');
           } catch (error) {
             console.warn(
               `[Rozenite] Storage Plugin: Failed to delete entry in ${target.adapterId}/${target.storageId}.`,
@@ -155,25 +144,72 @@ export const useRozeniteStoragePlugin = ({
         },
       ),
       client.onMessage(
-        'get-snapshot',
-        async ({ target }: StorageGetSnapshotEvent) => {
-          if (target === 'all') {
-            await pushSnapshot();
+        'purge-storage',
+        async ({ target }: StoragePurgeEvent) => {
+          const view = views.find(
+            (candidate) =>
+              candidate.target.adapterId === target.adapterId &&
+              candidate.target.storageId === target.storageId,
+          );
+
+          if (!view) {
+            console.warn(
+              `[Rozenite] Storage Plugin: Storage target not found for ${target.adapterId}/${target.storageId}`,
+            );
             return;
           }
 
-          await pushSnapshot(`${target.adapterId}:${target.storageId}`);
+          try {
+            await view.purge();
+            sendInvalidation(view.target, undefined, 'purge');
+          } catch (error) {
+            console.warn(
+              `[Rozenite] Storage Plugin: Failed to purge storage in ${target.adapterId}/${target.storageId}.`,
+              error,
+            );
+          }
+        },
+      ),
+      client.onMessage(
+        'discover-storages',
+        async (event: StorageDiscoverStoragesRequestEvent) => {
+          const response = await handleStorageDiscoveryRequest(views, event);
+          client.send(response.type, response);
+        },
+      ),
+      client.onMessage(
+        'list-entry-previews',
+        async (event: StorageListEntryPreviewsRequestEvent) => {
+          const response = await handleListEntryPreviewsRequest(views, event);
+          client.send(response.type, response);
+        },
+      ),
+      client.onMessage(
+        'get-entry',
+        async (event: StorageGetEntryRequestEvent) => {
+          const response = await handleFullEntryRequest(views, event);
+          client.send(response.type, response);
+        },
+      ),
+      client.onMessage(
+        'export-snapshot',
+        async (event: StorageExportSnapshotRequestEvent) => {
+          const response = await handleExportSnapshotRequest(views, event);
+          client.send(response.type, response);
+        },
+      ),
+      client.onMessage(
+        'preview-import',
+        async (event: StorageImportPreviewRequestEvent) => {
+          const response = await handleImportPreviewRequest(views, event);
+          client.send(response.type, response);
         },
       ),
       client.onMessage(
         'import-entries',
         async (event: StorageImportEntriesEvent) => {
           await handleImportEntries(views, event, (out) => {
-            if (out.type === 'set-entry') {
-              client.send('set-entry', out);
-            } else {
-              client.send('import-result', out);
-            }
+            client.send(out.type, out);
           });
         },
       ),

package/src/react-native/useStorageAgentTools.ts

@@ -1,15 +1,21 @@
-import { useCallback } from 'react';
 import { useRozenitePluginAgentTool } from '@rozenite/agent-bridge';
+import { DEFAULT_PAGE_LIMIT, MAX_PAGE_LIMIT } from '@rozenite/agent-shared';
 import {
   STORAGE_AGENT_PLUGIN_ID,
   storageToolDefinitions,
+  type StorageListEntriesArgs,
 } from '../shared/agent-tools';
-import type { StorageEntry, StorageEntryType, StorageEntryValue } from '../shared/types';
+import type {
+  StorageEntry,
+  StorageEntryType,
+  StorageEntryValue,
+  StorageTarget,
+} from '../shared/types';
 import type { StorageView } from './storage-view';
 
 const parseValueForType = (
   type: StorageEntryType,
-  value: unknown
+  value: unknown,
 ): StorageEntryValue => {
   if (type === 'string') {
     if (typeof value !== 'string') {
@@ -42,115 +48,230 @@ const parseValueForType = (
 const formatViewRef = (view: StorageView) =>
   `${view.target.adapterId}/${view.target.storageId}`;
 
-export const useStorageAgentTools = (views: StorageView[]) => {
-  const resolveStorage = useCallback(
-    (adapterId?: string, storageId?: string) => {
-      if (views.length === 0) {
-        throw new Error('No storages are registered.');
-      }
+const isSameTarget = (left: StorageTarget, right: StorageTarget) =>
+  left.adapterId === right.adapterId && left.storageId === right.storageId;
 
-      if (adapterId !== undefined || storageId !== undefined) {
-        const selected = views.find(
-          (view) =>
-            (adapterId === undefined || view.target.adapterId === adapterId) &&
-            (storageId === undefined || view.target.storageId === storageId)
-        );
+type ListEntriesCursor = {
+  version: 1;
+  target: StorageTarget;
+  offset: number;
+};
 
-        if (!selected) {
-          const qualifier = [
-            adapterId && `adapterId="${adapterId}"`,
-            storageId && `storageId="${storageId}"`,
-          ]
-            .filter(Boolean)
-            .join(', ');
-          throw new Error(
-            `No storage matched ${qualifier}. Available: ${views.map(formatViewRef).join(', ')}`
-          );
-        }
-
-        return selected;
-      }
+const encodeCursor = (cursor: ListEntriesCursor) =>
+  btoa(encodeURIComponent(JSON.stringify(cursor)));
 
-      if (views.length > 1) {
-        throw new Error(
-          `Multiple storages detected. Provide adapterId and/or storageId. Available: ${views.map(formatViewRef).join(', ')}`
-        );
-      }
+const decodeCursor = (value: string): ListEntriesCursor => {
+  try {
+    const cursor: unknown = JSON.parse(decodeURIComponent(atob(value)));
+    if (
+      typeof cursor !== 'object' ||
+      cursor == null ||
+      Array.isArray(cursor) ||
+      (cursor as { version?: unknown }).version !== 1 ||
+      typeof (cursor as { target?: { adapterId?: unknown } }).target
+        ?.adapterId !== 'string' ||
+      typeof (cursor as { target?: { storageId?: unknown } }).target
+        ?.storageId !== 'string' ||
+      !Number.isSafeInteger((cursor as { offset?: unknown }).offset) ||
+      (cursor as { offset: number }).offset < 0
+    ) {
+      throw new Error('Invalid cursor');
+    }
+
+    return cursor as ListEntriesCursor;
+  } catch {
+    throw new Error(
+      'Invalid cursor. Run list-entries again without a cursor to restart pagination.',
+    );
+  }
+};
+
+const sanitizeLimit = (limit: number | undefined) => {
+  if (
+    typeof limit !== 'number' ||
+    !Number.isFinite(limit) ||
+    !Number.isInteger(limit) ||
+    limit < 1
+  ) {
+    return DEFAULT_PAGE_LIMIT;
+  }
+
+  return Math.min(limit, MAX_PAGE_LIMIT);
+};
 
-      return views[0];
+const sanitizeOffset = (offset: number | undefined) => {
+  if (
+    typeof offset !== 'number' ||
+    !Number.isFinite(offset) ||
+    !Number.isSafeInteger(offset) ||
+    offset < 0
+  ) {
+    return 0;
+  }
+
+  return offset;
+};
+
+const resolveStorage = (
+  views: readonly StorageView[],
+  adapterId?: string,
+  storageId?: string,
+) => {
+  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: StorageView,
+  input: StorageListEntriesArgs,
+) => {
+  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,
+            }),
+          }
+        : {}),
     },
-    [views]
-  );
+  };
+};
+
+export const createStorageAgentHandlers = (views: readonly StorageView[]) => ({
+  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: StorageListEntriesArgs) => {
+    const view = resolveStorage(views, input.adapterId, input.storageId);
+    return listStorageKeys(view, input);
+  },
+
+  readEntry: async ({
+    adapterId,
+    storageId,
+    key,
+  }: {
+    adapterId?: string;
+    storageId?: string;
+    key: string;
+  }) => {
+    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: StorageView[]) => {
+  const handlers = createStorageAgentHandlers(views);
 
   useRozenitePluginAgentTool({
     pluginId: STORAGE_AGENT_PLUGIN_ID,
     tool: storageToolDefinitions.listStorages,
-    handler: async () => ({
-      storages: await Promise.all(
-        views.map(async (view) => ({
-          adapterId: view.target.adapterId,
-          storageId: view.target.storageId,
-          adapterName: view.adapterName,
-          storageName: view.storageName,
-          supportedTypes: view.capabilities.supportedTypes,
-          entryCount: (await view.getAllKeys()).length,
-        }))
-      ),
-    }),
+    handler: handlers.listStorages,
   });
 
   useRozenitePluginAgentTool({
     pluginId: STORAGE_AGENT_PLUGIN_ID,
     tool: storageToolDefinitions.listEntries,
-    handler: async ({ adapterId, storageId, offset = 0, limit = 100 }) => {
-      const view = resolveStorage(adapterId, storageId);
-      const allKeys = await view.getAllKeys();
-      const safeOffset = Math.max(0, Math.floor(offset));
-      const safeLimit = Math.max(1, Math.floor(limit));
-      const keys = allKeys.slice(safeOffset, safeOffset + safeLimit);
-
-      return {
-        adapterId: view.target.adapterId,
-        storageId: view.target.storageId,
-        total: allKeys.length,
-        offset: safeOffset,
-        limit: safeLimit,
-        keys,
-      };
-    },
+    handler: handlers.listEntries,
   });
 
   useRozenitePluginAgentTool({
     pluginId: STORAGE_AGENT_PLUGIN_ID,
     tool: storageToolDefinitions.readEntry,
-    handler: async ({ adapterId, storageId, key }) => {
-      const view = resolveStorage(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,
-      };
-    },
+    handler: handlers.readEntry,
   });
 
   useRozenitePluginAgentTool({
     pluginId: STORAGE_AGENT_PLUGIN_ID,
     tool: storageToolDefinitions.createEntry,
     handler: async ({ adapterId, storageId, key, type, value }) => {
-      const view = resolveStorage(adapterId, storageId);
+      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.`
+          `Key "${key}" already exists in storage "${formatViewRef(view)}". Use edit-entry instead.`,
         );
       }
 
@@ -170,12 +291,12 @@ export const useStorageAgentTools = (views: StorageView[]) => {
     pluginId: STORAGE_AGENT_PLUGIN_ID,
     tool: storageToolDefinitions.editEntry,
     handler: async ({ adapterId, storageId, key, type, value }) => {
-      const view = resolveStorage(adapterId, storageId);
+      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.`
+          `Key "${key}" not found in storage "${formatViewRef(view)}". Use create-entry instead.`,
         );
       }
 
@@ -195,7 +316,7 @@ export const useStorageAgentTools = (views: StorageView[]) => {
     pluginId: STORAGE_AGENT_PLUGIN_ID,
     tool: storageToolDefinitions.removeEntry,
     handler: async ({ adapterId, storageId, key }) => {
-      const view = resolveStorage(adapterId, storageId);
+      const view = resolveStorage(views, adapterId, storageId);
       const existed = !!(await view.get(key));
       await view.delete(key);