@ai4b-team/fsaos-gateway-sdk 3.32.0 → 3.34.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.
@@ -183,6 +200,7 @@ reconciles the remaining count. No background polling is used.
 | `useChannelMessages(opts)` | Channel messages + bundled cards |
 | `useInfiniteChannelMessages(opts)` | Cursor-paginated messages (live tail) |
 | `useAllChannels()` / `useChannels()` / `useDmChannels()` | Channel lists (all / public / DM) |
+| `usePersonalItemOrder('channel-order' \| 'project-order', items)` | Apply and save the selected Space member's personal order through existing arrangements. |
 | `useNotifications(opts?)` | Notifications feed |
 | `useUnreadCounts(opts?)` | Aggregated unread counts |
 
@@ -278,3 +296,20 @@ This SDK has **zero** references to "kernel" in source, bundle, or type declarat
 and use this package as a dependency in your own applications, but you may **not**
 copy, modify, or redistribute it as a standalone library. All rights reserved by
 AI4B Team.
+
+### Personal channel and project ordering
+
+`usePersonalItemOrder(key, items)` reuses `resolve-arrangement` and the ordinary
+`update` primitive. Supply a complete collection of canonical IDs; render the
+returned `items` and call `reorder(ids)` once at drop. It returns `contextKey`
+for resetting in-progress UI gestures when the Space changes, plus `ready`,
+`supported`, `isLoading`, `isSaving`, `error`, `saveError` and `refetch`.
+
+The hook reads only the selected Space member's provisioned `channel-order` or
+`project-order` arrangement. Account mounts are unsupported and make no requests.
+It never creates a missing arrangement or falls back to a shared blueprint.
+A save preserves unseen IDs, rejects stale Space callbacks and invalid lists,
+and reconciles through the existing coalesced arrangement refresh. No polling,
+item reads or parent changes are involved. For paged collections, apply ordering
+in the backend before pagination; this hook does not discover Project folders
+or provide that paged read contract.