@ai4b-team/fsaos-gateway-sdk 3.34.2 → 3.35.0

package/dist/index.d.cts

@@ -1085,6 +1085,10 @@ interface ItemsFilter {
     type?: string;
     /** Scope path boundary. Defaults to session scope. */
     scope?: string;
+    /** Explicit mounted Space UUIDs, filtered by the kernel before pagination.
+     * [] returns no work. Omitted preserves legacy scope behavior. This is a
+     * read selection, never a write target or permission grant. */
+    spaceIds?: string[];
     /** Direct parent_id filter. */
     parent_id?: string;
     /** Name ILIKE filter (partial match). */
@@ -1131,7 +1135,7 @@ declare function isListableItemsFilter(filter: ItemsFilter | null | undefined):
  * icon, ...) are ignored. `extra` adds what the screen owns: scope, page size.
  * Returns null when the stored filter names nothing to list.
  */
-declare function itemsFilterFromQueryFilter(typeData: Record<string, unknown> | null | undefined, extra?: Pick<ItemsFilter, 'scope' | 'limit' | 'name' | 'parent_id'>): ItemsFilter | null;
+declare function itemsFilterFromQueryFilter(typeData: Record<string, unknown> | null | undefined, extra?: Pick<ItemsFilter, 'scope' | 'spaceIds' | 'limit' | 'name' | 'parent_id'>): ItemsFilter | null;
 /**
  * Fetch items with structured filters: one type, or OR-groups across types.
  * Calls kernel_query (gateway 'query' method). The kernel filters before it
@@ -1654,7 +1658,88 @@ declare function useSearch(query: string | undefined | null, itemTypes?: string[
 /** Multi-signal search (exact + trigram + keyword + semantic vector) via kernel resolve. */
 declare function useResolve(params: ResolveParams | null | undefined): _tanstack_react_query.UseQueryResult<ResolveResponse, Error>;
 /** Fetch items with structured filters: one type, or OR-groups across types. */
-declare function useItems(filter: ItemsFilter | null | undefined): _tanstack_react_query.UseQueryResult<VFSItem[], Error>;
+declare function useItems(filter: ItemsFilter | null | undefined): _tanstack_react_query.QueryObserverRefetchErrorResult<VFSItem[], Error> | _tanstack_react_query.QueryObserverSuccessResult<VFSItem[], Error> | _tanstack_react_query.QueryObserverLoadingErrorResult<VFSItem[], Error> | _tanstack_react_query.QueryObserverPendingResult<VFSItem[], Error> | _tanstack_react_query.QueryObserverPlaceholderResult<VFSItem[], Error> | {
+    data: undefined;
+    error: Error;
+    isError: true;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: true;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "error";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<VFSItem[], Error>>;
+    fetchStatus: _tanstack_react_query.FetchStatus;
+    promise: Promise<VFSItem[]>;
+} | {
+    data: undefined;
+    error: null;
+    isError: false;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: true;
+    isPlaceholderData: false;
+    status: "success";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<VFSItem[], Error>>;
+    fetchStatus: _tanstack_react_query.FetchStatus;
+    promise: Promise<VFSItem[]>;
+} | {
+    data: undefined;
+    isError: false;
+    error: null;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: true;
+    isPlaceholderData: true;
+    status: "success";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<VFSItem[], Error>>;
+    fetchStatus: _tanstack_react_query.FetchStatus;
+    promise: Promise<VFSItem[]>;
+};
 interface InfiniteItemsOptions {
     /** Keep this cached listing fresh through the SDK's existing realtime transport. No polling. Defaults to false. */
     realtime?: boolean;
@@ -1967,6 +2052,8 @@ declare function useAccounts(): AccountsState;
 /** The working set (mounts) as reactive state, plus mount/unmount verbs. */
 declare function useMounts(): {
     mounts: MountRef[];
+    selectedSpaces: MountRef[];
+    readSpaceIds: string[];
     homeAnchor: MountRef | null;
     anchor: MountRef | null;
     setAnchor: typeof selectMount;

package/dist/index.d.ts

@@ -1085,6 +1085,10 @@ interface ItemsFilter {
     type?: string;
     /** Scope path boundary. Defaults to session scope. */
     scope?: string;
+    /** Explicit mounted Space UUIDs, filtered by the kernel before pagination.
+     * [] returns no work. Omitted preserves legacy scope behavior. This is a
+     * read selection, never a write target or permission grant. */
+    spaceIds?: string[];
     /** Direct parent_id filter. */
     parent_id?: string;
     /** Name ILIKE filter (partial match). */
@@ -1131,7 +1135,7 @@ declare function isListableItemsFilter(filter: ItemsFilter | null | undefined):
  * icon, ...) are ignored. `extra` adds what the screen owns: scope, page size.
  * Returns null when the stored filter names nothing to list.
  */
-declare function itemsFilterFromQueryFilter(typeData: Record<string, unknown> | null | undefined, extra?: Pick<ItemsFilter, 'scope' | 'limit' | 'name' | 'parent_id'>): ItemsFilter | null;
+declare function itemsFilterFromQueryFilter(typeData: Record<string, unknown> | null | undefined, extra?: Pick<ItemsFilter, 'scope' | 'spaceIds' | 'limit' | 'name' | 'parent_id'>): ItemsFilter | null;
 /**
  * Fetch items with structured filters: one type, or OR-groups across types.
  * Calls kernel_query (gateway 'query' method). The kernel filters before it
@@ -1654,7 +1658,88 @@ declare function useSearch(query: string | undefined | null, itemTypes?: string[
 /** Multi-signal search (exact + trigram + keyword + semantic vector) via kernel resolve. */
 declare function useResolve(params: ResolveParams | null | undefined): _tanstack_react_query.UseQueryResult<ResolveResponse, Error>;
 /** Fetch items with structured filters: one type, or OR-groups across types. */
-declare function useItems(filter: ItemsFilter | null | undefined): _tanstack_react_query.UseQueryResult<VFSItem[], Error>;
+declare function useItems(filter: ItemsFilter | null | undefined): _tanstack_react_query.QueryObserverRefetchErrorResult<VFSItem[], Error> | _tanstack_react_query.QueryObserverSuccessResult<VFSItem[], Error> | _tanstack_react_query.QueryObserverLoadingErrorResult<VFSItem[], Error> | _tanstack_react_query.QueryObserverPendingResult<VFSItem[], Error> | _tanstack_react_query.QueryObserverPlaceholderResult<VFSItem[], Error> | {
+    data: undefined;
+    error: Error;
+    isError: true;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: true;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "error";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<VFSItem[], Error>>;
+    fetchStatus: _tanstack_react_query.FetchStatus;
+    promise: Promise<VFSItem[]>;
+} | {
+    data: undefined;
+    error: null;
+    isError: false;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: true;
+    isPlaceholderData: false;
+    status: "success";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<VFSItem[], Error>>;
+    fetchStatus: _tanstack_react_query.FetchStatus;
+    promise: Promise<VFSItem[]>;
+} | {
+    data: undefined;
+    isError: false;
+    error: null;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: true;
+    isPlaceholderData: true;
+    status: "success";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<VFSItem[], Error>>;
+    fetchStatus: _tanstack_react_query.FetchStatus;
+    promise: Promise<VFSItem[]>;
+};
 interface InfiniteItemsOptions {
     /** Keep this cached listing fresh through the SDK's existing realtime transport. No polling. Defaults to false. */
     realtime?: boolean;
@@ -1967,6 +2052,8 @@ declare function useAccounts(): AccountsState;
 /** The working set (mounts) as reactive state, plus mount/unmount verbs. */
 declare function useMounts(): {
     mounts: MountRef[];
+    selectedSpaces: MountRef[];
+    readSpaceIds: string[];
     homeAnchor: MountRef | null;
     anchor: MountRef | null;
     setAnchor: typeof selectMount;

package/dist/index.js

@@ -757,6 +757,10 @@ function listingTypes(filter) {
 }
 function affectsListing(query, filter, event) {
   if (containsChangedItem(query, event)) return true;
+  if (filter.spaceIds !== void 0) {
+    if (!filter.spaceIds.length) return false;
+    if (event.space_item_id !== void 0 && !filter.spaceIds.includes(event.space_item_id) && !filter.spaceIds.includes(event.old_space_item_id)) return false;
+  }
   const scope = filter.scope;
   const scoped = typeof scope === "string" && scope !== "__unscoped__";
   const hasPath = typeof event.path === "string" || typeof event.old_path === "string";
@@ -800,6 +804,29 @@ function clearInfiniteItemsRefreshes(client2) {
   pending2.delete(client2);
 }
 
+// src/items-selection.ts
+var SelectedSpaceContractError = class extends Error {
+  constructor() {
+    super("The server did not confirm the selected-Space listing contract");
+  }
+};
+function assertItemsSelection(requested, returned) {
+  if (!Array.isArray(returned) || returned.some((id) => typeof id !== "string") || JSON.stringify([...new Set(returned)].sort()) !== JSON.stringify(requested)) {
+    throw new SelectedSpaceContractError();
+  }
+}
+function normalizeItemsSelection(filter) {
+  if (!filter || filter.spaceIds === void 0) return filter;
+  return {
+    ...filter,
+    spaceIds: [...new Set(filter.spaceIds.map((id) => id.toLowerCase()))].sort(),
+    ...filter.limit !== void 0 ? { limit: Math.max(1, Math.min(filter.limit, 500)) } : {}
+  };
+}
+function unavailableItemsSelection(error) {
+  return error instanceof SelectedSpaceContractError || error instanceof EnforcementDeniedError || error instanceof GatewayRequestError && (error.payload?.error === "SPACE_SELECTION_UNAVAILABLE" || error.payload?.error === "QUERY_PARAMS_INVALID" || error.status === 401 || error.status === 403);
+}
+
 // src/vfs-keys.ts
 function sk() {
   return getScope() ?? "__unscoped__";
@@ -822,7 +849,7 @@ var vfsKeys = {
   /** Search results (scope-aware — search is scoped). */
   search: (query, types) => ["vfs", sk(), "search", query, ...types ?? []],
   /** Items query (type-based listing with filters, scope-aware). */
-  items: (type, filters) => ["vfs", sk(), "items", type, JSON.stringify(filters ?? {})],
+  items: (type, filters) => ["vfs", sk(), "items", type, JSON.stringify(normalizeItemsSelection(filters ?? {}))],
   /** All items queries for current scope (for broad invalidation). */
   allItems: () => ["vfs", sk(), "items"],
   /** Recursive tree at a path + depth (scope-aware). */
@@ -1712,12 +1739,15 @@ function itemsFilterFromQueryFilter(typeData, extra = {}) {
   return { ...filter, ...extra };
 }
 async function fetchItems(filter, options = {}) {
+  filter = normalizeItemsSelection(filter);
+  if (filter.spaceIds?.length === 0) return { items: [], total_hint: 0 };
   const params = {};
   if (filter.type) params.item_type = filter.type;
   if (filter.scope) {
     params.scope_path = filter.scope;
   }
   const filters = {};
+  if (filter.spaceIds !== void 0) filters.space_ids = filter.spaceIds;
   if (filter.name) filters.name = filter.name;
   if (filter.tag) filters.tag = filter.tag;
   if (filter.parent_id) filters.parent_id = filter.parent_id;
@@ -1744,6 +1774,9 @@ async function fetchItems(filter, options = {}) {
   }
   try {
     const response = await gatewayCall("query", params);
+    if (filter.spaceIds !== void 0) {
+      assertItemsSelection(filter.spaceIds, response.selected_space_ids ?? response.content?.selected_space_ids);
+    }
     const items = extractItems(response);
     for (const item of items) {
       getQueryClient().setQueryData(vfsKeys.item(item.path), item);
@@ -1751,7 +1784,7 @@ async function fetchItems(filter, options = {}) {
     return { items, total_hint: response.total ?? response.content?.total ?? items.length };
   } catch (err) {
     console.error(`[gateway] Failed to fetch items of type ${filter.type ?? "(any_of)"}:`, err);
-    if (options.throwOnError) throw err;
+    if (options.throwOnError || filter.spaceIds !== void 0) throw err;
     return { items: [], total_hint: 0 };
   }
 }
@@ -2365,22 +2398,28 @@ function useResolve(params) {
 }
 function useItems(filter) {
   useScopeKey();
-  const stableFilter = useMemo(() => filter, [JSON.stringify(filter)]);
-  return useQuery({
+  const selected = normalizeItemsSelection(filter);
+  const stableFilter = useMemo(() => selected, [JSON.stringify(selected)]);
+  const query = useQuery({
     queryKey: vfsKeys.items(
       stableFilter?.type ?? "",
       stableFilter
     ),
     queryFn: () => fetchItems(stableFilter),
     enabled: isListableItemsFilter(stableFilter),
+    ...stableFilter?.spaceIds !== void 0 ? {
+      retry: (attempt, error) => !unavailableItemsSelection(error) && attempt < 1
+    } : {},
     select: (result) => result.items
   });
+  return stableFilter?.spaceIds !== void 0 && unavailableItemsSelection(query.error) ? { ...query, data: void 0 } : query;
 }
 function useInfiniteItems(filter, options = {}) {
   const scopeKey = useScopeKey();
   const { realtime = false } = options;
-  const PAGE_SIZE = filter?.limit ?? 20;
-  const stableFilter = useMemo(() => filter, [JSON.stringify(filter)]);
+  const selected = normalizeItemsSelection(filter);
+  const PAGE_SIZE = selected?.limit ?? 20;
+  const stableFilter = useMemo(() => selected, [JSON.stringify(selected)]);
   const stableKey = useMemo(() => ["vfs", getScope() ?? "__unscoped__", "infinite-items", stableFilter?.type ?? "", JSON.stringify(stableFilter ?? {})], [scopeKey, stableFilter]);
   const query = useInfiniteQuery({
     queryKey: stableKey,
@@ -2393,16 +2432,21 @@ function useInfiniteItems(filter, options = {}) {
     },
     initialPageParam: 0,
     getNextPageParam: (lastPage, _allPages, lastPageParam) => {
+      if (stableFilter?.spaceIds !== void 0 && lastPage.total_hint !== void 0 && lastPageParam + lastPage.items.length >= lastPage.total_hint) return void 0;
       if (lastPage.items.length < PAGE_SIZE) return void 0;
       return lastPageParam + lastPage.items.length;
     },
     enabled: isListableItemsFilter(stableFilter),
+    ...stableFilter?.spaceIds !== void 0 ? {
+      retry: (attempt, error) => !unavailableItemsSelection(error) && attempt < 1
+    } : {},
     // Realtime marks the cache stale only on relevant changes or reconnect.
     // Expanding a channel or handing it to another observer reuses its pages.
     staleTime: realtime ? Infinity : void 0,
     meta: realtime && stableFilter ? { infiniteItemsRealtime: { filter: stableFilter } } : {}
   });
   const allItems = useMemo(() => {
+    if (stableFilter?.spaceIds !== void 0 && unavailableItemsSelection(query.error)) return [];
     if (!query.data?.pages) return [];
     const seen = /* @__PURE__ */ new Set();
     const flat = [];
@@ -2415,17 +2459,18 @@ function useInfiniteItems(filter, options = {}) {
       }
     }
     return flat;
-  }, [query.data?.pages]);
+  }, [query.data?.pages, query.error, stableFilter]);
+  const unavailable = stableFilter?.spaceIds !== void 0 && unavailableItemsSelection(query.error);
   return {
     allItems,
     refetch: query.refetch,
     fetchNextPage: query.fetchNextPage,
     isFetchingNextPage: query.isFetchingNextPage,
-    isExhausted: !query.hasNextPage,
+    isExhausted: unavailable || !query.hasNextPage,
     isLoading: query.isLoading,
     isFetching: query.isFetching,
     error: query.error,
-    totalHint: query.data?.pages?.[0]?.total_hint
+    totalHint: unavailable ? void 0 : query.data?.pages?.[0]?.total_hint
   };
 }
 function useInfiniteChildren(path) {
@@ -2733,10 +2778,15 @@ function useMounts() {
   useScopeKey();
   const version = useSyncExternalStore(subscribeMounts, getMountVersion, getMountVersion);
   const mounts = useMemo(() => getMounts(), [version]);
+  const anchor = getAnchorRef();
+  const selectedSpaces = useMemo(() => mounts.filter((ref) => ref.kind === "space" && (anchor?.kind === "account" || ref.id === anchor?.id)), [mounts, anchor]);
+  const readSpaceIds = useMemo(() => selectedSpaces.map((ref) => ref.id).sort(), [selectedSpaces]);
   return {
     mounts,
+    selectedSpaces,
+    readSpaceIds,
     homeAnchor: getHomeAnchor(),
-    anchor: getAnchorRef(),
+    anchor,
     setAnchor: selectMount,
     replaceMounts,
     mount,