@ai4b-team/fsaos-gateway-sdk 3.31.1 → 3.33.0

package/README.md

@@ -101,7 +101,8 @@ The SDK does not decide when AI should respond, spawn agents, or infer agent ide
 - `fetchVfsItem(path)` — Fetch a single item
 - `fetchVfsItemById(id)` — Fetch a single item by UUID
 - `fetchVfsChildren(path)` — Fetch children (also warms item cache)
-- `fetchItems(filter)` — Fetch items by type with structured filters
+- `fetchItems(filter)` — Fetch items with structured filters: one `type`, or `any_of` groups spanning types; `fields`, `field_in`, `discovery`, sort and offset
+- `itemsFilterFromQueryFilter(typeData, { scope?, limit? })` — Turn a stored saved filter (a `query_filter` child of an arrangement) into the filter `useInfiniteItems` takes
 - `fetchTypeDefinitions(scopeId?)` — Fetch type definitions as `Map<string, TypeDefinition>`
 - `fetchEdgesForItem(itemId)` — Fetch edges (incoming + outgoing)
 - `fetchVfsTree(path, depth?, types?, limit?)` — Fetch recursive tree
@@ -167,6 +168,22 @@ loaded items moving out still refresh their former list. Closed lists are marked
 stale without fetching, and unchanged lists reopen from cache. All consumers of
 the same filtered query should use the same realtime setting.
 
+A filter names one `type`, or `any_of`: 1-10 groups, each with an `item_type`,
+`fields` and `field_in`, so one listing spans item types with one total and one
+page order. `discovery: 'catalog'` keeps only what the kernel classes as a
+person's own standalone things; the kernel applies it before paging. A menu's
+stored sections are run without building a filter by hand:
+
+```ts
+const { resolvedChildren } = useArrangement({ key: 'library' });
+const section = resolvedChildren.find(child => child.child_type === 'query_filter');
+const list = useInfiniteItems(
+  itemsFilterFromQueryFilter(section?.type_data, { scope: accountPath, limit: 50 }),
+  { realtime: true },
+);
+// list.allItems, list.fetchNextPage(), list.isExhausted, list.totalHint
+```
+
 A relevant burst refreshes the loaded pages once, using the existing
 `refreshQuery` protection against overlapping loads. Multiple pages are read
 again together so offset pagination stays consistent after inserts/deletes.