@ai4b-team/fsaos-gateway-sdk 3.11.1 → 3.12.2

package/README.md

@@ -24,7 +24,16 @@ Mount Runtime:
   6. __FSAOS_MOUNT__()    → renders the component
 ```
 
-## Exports (38 total)
+## Location vs. Access — the two kinds of read
+
+Two questions look similar but are answered by different calls. Getting this right is the difference between a correct UI and one that shows a member items that aren't theirs.
+
+- **Location** — "what is at this path / of this type in this account?" → `useItems`, `useList`, `useTree`. These scope to the current account and return what's there. They do **not** know *who you are within the account*.
+- **Access** — "what can THIS actor reach in THIS context?" → `useResolvedItems`. Resolved server-side by the kernel: union of account / member / space / system / licensed tiers, frame-bounded to the acting principal, preference-cascade aware.
+
+Rule of thumb: if the answer should differ depending on *who is asking* or *which channel they are in* — connectors, tools, or anything member-scoped — use `useResolvedItems`. The SDK never computes frames or permissions client-side; it forwards to the kernel and renders the answer.
+
+## Exports
 
 ### Error
 - `EnforcementDeniedError` — Error class for enforcement denials (rules, access, entitlement)
@@ -35,6 +44,7 @@ Mount Runtime:
 - `getSessionEntry()` — Get current session entry (or null)
 - `getAccessToken()` — Get current auth token (waits for first auth event)
 - `setCachedToken()` — Manually set auth token (for embed tokens)
+- `getScope()` / `setScope()` / `subscribeScope()` — Active scope (account/switcher) accessors + subscription
 
 ### Gateway Call
 - `gatewayCall(method, params)` — Core RPC dispatcher: `POST /d/{hostname}`
@@ -69,11 +79,14 @@ The SDK does not decide when AI should respond, spawn agents, or infer agent ide
 ### VFS Operations (pure async functions)
 - `normalizeItem(raw)` — Normalize raw gateway response to `VFSItem`
 - `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
 - `fetchTypeDefinitions(scopeId?)` — Fetch type definitions as `Map<string, TypeDefinition>`
 - `fetchEdgesForItem(itemId)` — Fetch edges (incoming + outgoing)
 - `fetchVfsTree(path, depth?, types?, limit?)` — Fetch recursive tree
 - `fetchMemberFocus(scopeId, types?, limit?)` — Fetch member-focus items
+- `fetchResolvedItems(contextId, itemType)` — Imperative form of `useResolvedItems` (access resolution)
 
 ### Cache Invalidation
 - `invalidateChildren(path)` — Invalidate children query
@@ -84,8 +97,9 @@ The SDK does not decide when AI should respond, spawn agents, or infer agent ide
 - `invalidateTypes(scopeId?)` — Invalidate type definitions
 
 ### Realtime
-- `initVfsRealtime(scopeId)` — Subscribe to Supabase Realtime for VFS changes
-- `disposeVfsRealtime()` — Tear down realtime channel
+- `initVfsRealtimeWs(scopeId)` — Subscribe to VFS changes over WebSocket
+- `disposeVfsRealtimeWs()` — Tear down realtime connection
+- `mountRealtimeScope(path)` / `unmountRealtimeScope(path)` — Add/remove a scope from the realtime subscription
 
 ### React Hooks (TanStack Query)
 
@@ -94,12 +108,46 @@ The SDK does not decide when AI should respond, spawn agents, or infer agent ide
 | Hook | Description |
 |------|-------------|
 | `useItem(path)` | Single item by path |
-| `useList(path)` | Children of a path |
+| `useItemById(id)` | Single item by UUID |
+| `useList(path)` / `useChildren(path)` | Children of a path (location) |
+| `useItems(filter)` | Items by type with filters (location; account-scoped, **not** frame-aware) |
+| `useInfiniteItems(filter)` | Infinite-scroll items by type |
+| `useInfiniteChildren(path)` | Infinite-scroll directory listing |
 | `useTree(path, depth?)` | Recursive tree |
-| `useSearch(query, types?)` | Search items |
+| `useSearch(query, types?)` | Keyword search |
+| `useResolve(params)` | Multi-signal search (exact + trigram + keyword + semantic) |
+| `useResolvedItems(contextId, itemType)` | **Access** resolution — what this actor can reach here (frame-bounded, pref-aware). Use for connectors, tools, any member-scoped type. |
+| `useOpen(path, options?)` | Open envelope — render directives + compatible components |
 | `useEdges(itemId)` | Edges for an item |
-| `useTypes(scopeId?)` | All type definitions |
-| `useType(typeKey, scopeId?)` | Single type definition |
+| `useTypes(scopeId?)` / `useType(typeKey, scopeId?)` | Type definitions |
+| `useTypeHelpers(scopeId?)` | Derived type-system helper functions |
+| `useMemberFocus(scopeId, types?, limit?)` | Items relevant to the current user in a scope |
+| `useItemVersions(itemId, opts?)` | Version history (`useItemHistory` is deprecated) |
+| `useRecentActivity(scopePath, limit?, offset?)` | Audit log for a scope |
+| `useScope()` / `useScopeReady()` | Current scope session / readiness |
+| `useAuth()` | Reactive Supabase auth |
+| `useAccounts()` | Account memberships + switching |
+| `usePrincipal()` / `useUpdatePrincipal()` | Current principal identity / update |
+| `useAsset(idOrPath)` | Resolve an asset URL |
+| `useComponent(path)` | Dynamically load a component from the edge |
+| `useTheme()` | Read theme CSS custom properties |
+
+**Channel / notification hooks:**
+
+| Hook | Description |
+|------|-------------|
+| `useChannelMessages(opts)` | Channel messages + bundled cards |
+| `useInfiniteChannelMessages(opts)` | Cursor-paginated messages (live tail) |
+| `useAllChannels()` / `useChannels()` / `useDmChannels()` | Channel lists (all / public / DM) |
+| `useNotifications(opts?)` | Notifications feed |
+| `useUnreadCounts(opts?)` | Aggregated unread counts |
+
+**Realtime hooks:**
+
+| Hook | Description |
+|------|-------------|
+| `useEventStream(...)` | Subscribe to SSE events by type |
+| `useRealtimeQuery(opts)` | `useQuery` that auto-refetches on matching events |
 
 **Mutation hooks:**
 
@@ -116,17 +164,21 @@ The SDK does not decide when AI should respond, spawn agents, or infer agent ide
 
 ```
 src/
-  types.ts          — All type definitions (VFSItem, TypeDefinition, VFSEdge, etc.)
-  config.ts         — Reads __FSAOS_CONFIG__, creates Supabase client
-  enforcement.ts    — EnforcementDeniedError class
-  session.ts        — Auth token lifecycle, domain session init
-  client.ts         — gatewayCall() — the core RPC dispatcher
-  query-client.ts   — TanStack QueryClient with VFS-tuned defaults
-  vfs-keys.ts       — Query key factory
-  vfs.ts            — VFS fetch functions + cache invalidation helpers
-  hooks.ts          — All React hooks (useQuery/useMutation wrappers)
-  realtime.ts       — Supabase Realtime subscriptions + debounced invalidation
-  index.ts          — Barrel export (38 symbols)
+  types.ts             — All type definitions (VFSItem, TypeDefinition, VFSEdge, etc.)
+  config.ts            — Reads __FSAOS_CONFIG__, creates Supabase client
+  enforcement.ts       — EnforcementDeniedError class
+  session.ts           — Auth token lifecycle, domain session init, scope accessors
+  client.ts            — gatewayCall() — the core RPC dispatcher
+  query-client.ts      — TanStack QueryClient with VFS-tuned defaults
+  vfs-keys.ts          — Query key factory
+  vfs.ts               — VFS fetch functions + cache invalidation helpers
+  vfs-realtime-ws.ts   — WebSocket realtime subscriptions
+  ws.ts                — WebSocket transport (events, scope, ping)
+  hooks.ts             — All React hooks (useQuery/useMutation wrappers)
+  resolved-items.ts    — useResolvedItems / fetchResolvedItems (access resolution)
+  upload.ts            — File upload (imperative + hook)
+  schema-utils.ts      — Schema interpretation utilities
+  index.ts             — Barrel export
 ```
 
 ## Build
@@ -140,7 +192,7 @@ node build.mjs --dev    # dist/gateway.dev.js (readable, ~128 KB)
 The build produces:
 - `dist/gateway.js` — Minified IIFE assigned to `window.__FSAOS_GATEWAY__`
 - `dist/gateway.dev.js` — Unminified for debugging
-- `dist/*.d.ts` — TypeScript declarations (11 files)
+- `dist/*.d.ts` — TypeScript declarations
 - `dist/*.js.map` — Source maps
 
 ## Dependencies
@@ -154,7 +206,7 @@ The build produces:
 
 ## Zero Kernel
 
-This SDK has **zero** references to "kernel" in source, bundle, or type declarations. All naming uses gateway terminology.
+This SDK has **zero** references to "kernel" in source, bundle, or type declarations. All naming uses gateway terminology. (The kernel owns resolution, frames, and enforcement; the SDK is the control surface that forwards to it.)
 
 ## License