@ai4b-team/fsaos-gateway-sdk 3.36.0 → 3.38.0

package/README.md

@@ -138,6 +138,7 @@ The SDK does not decide when AI should respond, spawn agents, or infer agent ide
 | `useList(path)` / `useChildren(path)` | Children of a path (location) |
 | `useItems(filter)` | Items by type with filters (location; account-scoped, **not** frame-aware) |
 | `useInfiniteItems(filter, { realtime? })` | Kernel-filtered infinite pages; optional event-driven refresh, cached items, load more and refetch. No polling. |
+| `useIncrementalItems(filter, { shouldReadUpdate? })` | Live created-at feed: query pages once, point-read inserts and selected updates, reconcile after deletes/reconnect. No polling. |
 | `useInfiniteChildren(path)` | Infinite-scroll directory listing |
 | `useTree(path, depth?)` | Recursive tree |
 | `useSearch(query, types?)` | Keyword search |
@@ -168,6 +169,15 @@ 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.
 
+For a high-traffic message feed, `useIncrementalItems` avoids reloading every
+loaded page whenever a reply changes. It supports one item `type`, an explicit
+`scope`, `sort_by: 'created_at'`, and optional `parent_id`, `fields`, or
+`field_in`. It returns the same list and pagination fields as
+`useInfiniteItems`. Inserts cost one item read; updates are ignored unless
+`shouldReadUpdate(change, loadedItems)` selects them; deletes and reconnects
+reconcile the pages. More complex filters fall back to the ordinary realtime
+listing. The host still needs its normal account or path WebSocket subscription.
+
 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
@@ -319,3 +329,22 @@ 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.
+
+### Personal sidebar Sections
+
+`usePersonalSections(contextId, 'channels' | 'chats' | 'projects')` reads personal
+reference groups. Use a Space ID for channels/projects or a channel ID for chats.
+The hook returns `sections`, `ready`, `change`, `destination`, and loading/error
+state. `change` supports create, rename, delete, assign, remove and reorder
+operations; it preserves canonical item locations. Supply a stable client UUID
+for `section_id` on create so a retry cannot create a duplicate Section.
+
+Capture `destination(sectionId)` before starting a new channel or chat, then call
+`assignPersonalSection(destination, savedItemId)` once the canonical item has
+been saved. Retry that filing separately from creation/sending. The captured
+Space and context isolate late results after navigation. Versioned snapshots
+prevent late responses from replacing newer organization; refresh uses existing
+coalesced item-change events and reconnects, with no polling.
+
+Requires the `personal-sections` kernel method from migration `0793523446ad`.
+Projects are protocol-ready; a consumer must supply its Project UI separately.