@happyvertical/smrt-web 0.43.2 → 0.43.4

package/dist/index.d.ts

@@ -15,7 +15,7 @@ export declare function buildListQuery(params?: Record<string, unknown>): string
  * instead of resolving with them. Typed/legacy 4xx detail is retained; 5xx
  * failures stay opaque and payload-free.
  */
-export declare function createDefinitionFetchers(definition: SmrtWebCollectionDefinition<object>, basePath?: string, fetchFn?: typeof fetch): SmrtCrudFetchers;
+export declare function createDefinitionFetchers(definition: Pick<SmrtWebCollectionDefinition<object>, 'name' | 'endpoint'>, basePath?: string, fetchFn?: typeof fetch): SmrtCrudFetchers;
 
 /**
  * Create a typed client collection over a generated SMRT collection definition
@@ -131,6 +131,14 @@ export declare function createSmrtWebClient(): SmrtWebClient;
  */
 export declare function createSmrtWebEventSubscriber(config: SmrtWebEventSubscriberConfig): SmrtWebEventSubscriber;
 
+/**
+ * Create a query controller over one SMRT collection. Query rows stay in a
+ * separate keyed cache; the collection's full list is never loaded.
+ */
+export declare function createSmrtWebQuery<TData extends object>(_collection: SmrtWebCollection<TData>, transport: SmrtWebQueryTransport, options?: {
+    staleTimeMs?: number;
+}): SmrtWebQuery<TData>;
+
 /**
  * Create the framework-free `updateAvailable` primitive. Kicks off async
  * contract detection immediately (compare running vs. persisted manifest hash);
@@ -242,6 +250,17 @@ export declare function getEngineCollection<TData extends object>(handle: SmrtWe
  */
 export declare function getOutboxHandle(namespace: string): OutboxHandle | undefined;
 
+/**
+ * Invalidate materialized collection caches through the opaque SMRT client.
+ *
+ * This is the public cache-coherence seam for transports that execute a write
+ * without constructing a {@link SmrtWebCollection} (for example, a tool-only
+ * WebMCP definition). Matching is by collection name across every scope on the
+ * shared client, mirroring settled collection mutations: over-invalidation is
+ * safe, while leaving a related page cache stale is not.
+ */
+export declare function invalidateSmrtWebCollections(client: SmrtWebClient, collectionNames: readonly string[]): void;
+
 /**
  * A thin per-collection capability that subscribes THIS collection to live
  * signals for its `tableName`. On attach it registers `ctx.invalidate` (the
@@ -525,9 +544,9 @@ export declare function registerDurableResource(namespace: string, resource: Dur
  * @returns a disposer that deregisters all tools this call registered. On a
  * browser without WebMCP the call is a no-op and the disposer is inert.
  */
-export declare function registerWebMcpTools(definitions: SmrtWebCollectionDefinition[], options?: RegisterWebMcpToolsOptions): () => void;
+export declare function registerWebMcpTools(definitions: readonly WebMcpRegistrationDefinition[], options?: RegisterWebMcpToolsOptions): WebMcpRegistrationDisposer;
 
-export declare interface RegisterWebMcpToolsOptions {
+export declare interface RegisterWebMcpToolsOptions extends WebMcpExposurePolicy {
     /** REST base path for the fetchers (default `/api/v1`). */
     basePath?: string;
     /** Injectable fetch (tests / SSR-safe wrappers). */
@@ -542,8 +561,16 @@ export declare interface RegisterWebMcpToolsOptions {
      * without a live server.
      */
     resolveFetchers?: (definition: SmrtWebCollectionDefinition) => SmrtCrudFetchers;
+    /**
+     * Override direct REST fetchers for a canonical tool-only definition.
+     * Fetchers are optional because a get-only or custom-action-only model does
+     * not have a list or create route.
+     */
+    resolveToolFetchers?: (definition: WebMcpToolDefinition) => Partial<SmrtCrudFetchers>;
     /** Predicate to include/exclude individual tools (e.g. reads-only surfaces). */
     filter?: (definition: SmrtWebCollectionDefinition, descriptor: NonNullable<SmrtWebCollectionDefinition['toolDescriptors']>[number]) => boolean;
+    /** Predicate for canonical per-tool definitions. */
+    filterTool?: (definition: WebMcpToolDefinition) => boolean;
 }
 
 /**
@@ -1040,6 +1067,64 @@ export declare interface SmrtWebMutationEnvelope {
     readonly baseUpdatedAt?: string;
 }
 
+export declare interface SmrtWebQuery<TData extends object = object> {
+    readonly state: SmrtWebQueryState<TData>;
+    readonly request: SmrtWebDataQueryRequest | undefined;
+    execute(request: SmrtWebDataQueryRequest, options?: SmrtWebQueryRunOptions): Promise<SmrtWebDataQueryResult>;
+    refresh(options?: Omit<SmrtWebQueryRunOptions, 'mode' | 'force'>): Promise<SmrtWebDataQueryResult | undefined>;
+    retry(): Promise<SmrtWebDataQueryResult | undefined>;
+    subscribe(listener: (state: SmrtWebQueryState<TData>) => void): () => void;
+    subscribeLive(): SmrtWebQueryLiveSubscription | undefined;
+    invalidate(): void;
+    dispose(): void;
+}
+
+export declare interface SmrtWebQueryLiveSubscription {
+    unsubscribe(): void;
+    reconnect(): void;
+}
+
+/** How a query run is allowed to affect the visible query state. */
+export declare type SmrtWebQueryMode = 'visible' | 'background' | 'prefetch' | 'silent';
+
+export declare interface SmrtWebQueryPage {
+    kind: 'offset' | 'cursor';
+    limit: number;
+    offset?: number;
+    nextCursor?: string;
+    hasMore: boolean;
+}
+
+export declare interface SmrtWebQueryRunOptions {
+    mode?: SmrtWebQueryMode;
+    signal?: AbortSignal;
+    /** Cancel this run after the given number of milliseconds. */
+    deadlineMs?: number;
+    /** Bypass the keyed cache and execute a fresh request (used by refresh). */
+    force?: boolean;
+}
+
+export declare interface SmrtWebQueryState<TData extends object = object> {
+    readonly rows: ReadonlyArray<TData>;
+    readonly page: SmrtWebQueryPage | undefined;
+    readonly total: SmrtWebDataQueryResult['total'] | undefined;
+    readonly loading: boolean;
+    readonly refreshing: boolean;
+    readonly stale: boolean;
+    readonly error: unknown;
+    readonly lastUpdated: number | undefined;
+    readonly result: SmrtWebDataQueryResult | undefined;
+}
+
+export declare interface SmrtWebQueryTransport extends SmrtWebDataQueryTransport {
+    /** Subscribe to changes for this exact query, not the entire collection. */
+    subscribe?(request: SmrtWebDataQueryRequest, onResult: (result: unknown) => void, options?: {
+        signal?: AbortSignal;
+    }): SmrtWebQueryLiveSubscription | {
+        unsubscribe(): void;
+    };
+}
+
 /**
  * A manifest-derived edge from this collection to a sibling REST collection,
  * emitted by the `@happyvertical/smrt-virt-web` virtual module. When a mutation
@@ -1132,6 +1217,9 @@ export declare interface SyncStateEvent {
     error?: string;
 }
 
+/** Reject generated REST error envelopes while preserving opaque successes. */
+export declare function throwIfSmrtWebError(result: unknown, context: string): unknown;
+
 /**
  * Normalize a generated-client item result (create/update) to a row.
  * `{ error }` payloads become failures — inside mutation handlers this is what
@@ -1213,6 +1301,52 @@ export declare interface UpdateStateConfig {
     namespace: DurableStoreKey;
 }
 
+/** Validate that an opaque cache handle came from {@link createSmrtWebClient}. */
+export declare function validateSmrtWebClient(client: SmrtWebClient): void;
+
+export declare interface WebMcpExposurePolicy {
+    /** Allowed effects. Omitted means read-only exposure. */
+    effects?: readonly WebMcpToolEffect[];
+    /** Prefix every registered tool name with `<namespace>_`. */
+    namespace?: string;
+    /** Optional maximum tools registered by one call. */
+    maxTools?: number;
+}
+
+/** Accepted legacy collection definitions and canonical per-tool definitions. */
+export declare type WebMcpRegistrationDefinition = SmrtWebCollectionDefinition | WebMcpToolDefinition;
+
+/** Disposes a registration and exposes completion of browser registration. */
+export declare interface WebMcpRegistrationDisposer {
+    (): void;
+    /** Rejects if the browser rejects any tool; all sibling tools are aborted. */
+    readonly ready: Promise<void>;
+}
+
+/**
+ * Canonical data-only definition for one API-backed browser tool. Unlike a
+ * collection definition, this does not imply that a list route or client cache
+ * exists. Generated definitions carry explicit semantics; manual legacy
+ * literals may omit them and register with fail-closed defaults.
+ */
+export declare interface WebMcpToolDefinition extends WebToolDescriptor {
+    /** Stable definition identity is `(collection, action)`. */
+    collection: string;
+    /** Canonical qualified row-model identity. */
+    objectRef: string;
+    /** Row-model class used by the shared MCP tool vocabulary. */
+    className: string;
+    endpoint: string;
+    idField: string;
+    idType: 'uuid' | 'text';
+    /** Complete generated route metadata, including CRUD actions. */
+    route: SmrtWebToolRouteDescriptor;
+    /** Cache-invalidation edges for materialized sibling collections. */
+    relationships: SmrtWebRelationship[];
+}
+
+export declare type WebMcpToolEffect = 'read' | 'write' | 'destructive';
+
 /**
  * One generated collection definition: everything needed to construct a client
  * collection over the generated REST surface. The `_row` property is a phantom
@@ -1236,6 +1370,12 @@ export declare interface WebToolDescriptor {
     inputSchema: Record<string, unknown>;
     /** True for non-mutating reads → WebMCP `annotations.readOnlyHint`. */
     readOnly: boolean;
+    /** Capability effect used by WebMCP exposure policy. */
+    effect?: 'read' | 'write' | 'destructive';
+    /** Whether repeating the tool with the same arguments is safe. */
+    idempotent?: boolean;
+    /** Whether the tool may interact outside the SMRT application. */
+    openWorld?: boolean;
     /** Generated custom-route transport metadata. */
     route?: SmrtWebToolRouteDescriptor;
 }

package/dist/index.js

@@ -1,2 +1,2 @@
-import { A as executeSmrtWebDataQuery, C as MAX_SMRT_WEB_DATA_QUERY_FACET_VALUES, D as MAX_SMRT_WEB_DATA_QUERY_ROWS, E as MAX_SMRT_WEB_DATA_QUERY_RESULT_BYTES, M as runWrapMutation, O as MAX_SMRT_WEB_DATA_QUERY_STRING_LENGTH, S as MAX_SMRT_WEB_DATA_QUERY_FACETS, T as MAX_SMRT_WEB_DATA_QUERY_PAGE_LIMIT, _ as offlineOutbox, a as createSmrtWebClient, b as wipeDurableStore, c as unwrapItemResult, d as createUpdateState, f as createSmrtWebEventSubscriber, g as getOutboxHandle, h as persistCollection, i as createSmrtCollection, j as normalizeSmrtWebDataQueryResult, k as MAX_SMRT_WEB_DATA_QUERY_WARNINGS, l as unwrapListResult, m as DEFAULT_PERSIST_DEBOUNCE_MS, n as buildListQuery, o as getEngineCollection, p as liveInvalidation, r as createDefinitionFetchers, s as newLocalId, t as SmrtWebRequestError, u as registerWebMcpTools, v as durableStoreNamespace, w as MAX_SMRT_WEB_DATA_QUERY_OFFSET, x as MAX_SMRT_WEB_DATA_QUERY_CONTAINER_ITEMS, y as registerDurableResource } from "./chunks/src-CDdW9uYx.js";
-export { DEFAULT_PERSIST_DEBOUNCE_MS, MAX_SMRT_WEB_DATA_QUERY_CONTAINER_ITEMS, MAX_SMRT_WEB_DATA_QUERY_FACETS, MAX_SMRT_WEB_DATA_QUERY_FACET_VALUES, MAX_SMRT_WEB_DATA_QUERY_OFFSET, MAX_SMRT_WEB_DATA_QUERY_PAGE_LIMIT, MAX_SMRT_WEB_DATA_QUERY_RESULT_BYTES, MAX_SMRT_WEB_DATA_QUERY_ROWS, MAX_SMRT_WEB_DATA_QUERY_STRING_LENGTH, MAX_SMRT_WEB_DATA_QUERY_WARNINGS, SmrtWebRequestError, buildListQuery, createDefinitionFetchers, createSmrtCollection, createSmrtWebClient, createSmrtWebEventSubscriber, createUpdateState, durableStoreNamespace, executeSmrtWebDataQuery, getEngineCollection, getOutboxHandle, liveInvalidation, newLocalId, normalizeSmrtWebDataQueryResult, offlineOutbox, persistCollection, registerDurableResource, registerWebMcpTools, runWrapMutation, unwrapItemResult, unwrapListResult, wipeDurableStore };
+import { A as MAX_SMRT_WEB_DATA_QUERY_RESULT_BYTES, C as registerDurableResource, D as MAX_SMRT_WEB_DATA_QUERY_FACET_VALUES, E as MAX_SMRT_WEB_DATA_QUERY_FACETS, F as normalizeSmrtWebDataQueryResult, I as runWrapMutation, M as MAX_SMRT_WEB_DATA_QUERY_STRING_LENGTH, N as MAX_SMRT_WEB_DATA_QUERY_WARNINGS, O as MAX_SMRT_WEB_DATA_QUERY_OFFSET, P as executeSmrtWebDataQuery, S as durableStoreNamespace, T as MAX_SMRT_WEB_DATA_QUERY_CONTAINER_ITEMS, _ as createSmrtWebQuery, a as createSmrtWebClient, b as getOutboxHandle, c as newLocalId, d as unwrapListResult, f as validateSmrtWebClient, g as liveInvalidation, h as createSmrtWebEventSubscriber, i as createSmrtCollection, j as MAX_SMRT_WEB_DATA_QUERY_ROWS, k as MAX_SMRT_WEB_DATA_QUERY_PAGE_LIMIT, l as throwIfSmrtWebError, m as createUpdateState, n as buildListQuery, o as getEngineCollection, p as registerWebMcpTools, r as createDefinitionFetchers, s as invalidateSmrtWebCollections, t as SmrtWebRequestError, u as unwrapItemResult, v as DEFAULT_PERSIST_DEBOUNCE_MS, w as wipeDurableStore, x as offlineOutbox, y as persistCollection } from "./chunks/src-n14q6RHC.js";
+export { DEFAULT_PERSIST_DEBOUNCE_MS, MAX_SMRT_WEB_DATA_QUERY_CONTAINER_ITEMS, MAX_SMRT_WEB_DATA_QUERY_FACETS, MAX_SMRT_WEB_DATA_QUERY_FACET_VALUES, MAX_SMRT_WEB_DATA_QUERY_OFFSET, MAX_SMRT_WEB_DATA_QUERY_PAGE_LIMIT, MAX_SMRT_WEB_DATA_QUERY_RESULT_BYTES, MAX_SMRT_WEB_DATA_QUERY_ROWS, MAX_SMRT_WEB_DATA_QUERY_STRING_LENGTH, MAX_SMRT_WEB_DATA_QUERY_WARNINGS, SmrtWebRequestError, buildListQuery, createDefinitionFetchers, createSmrtCollection, createSmrtWebClient, createSmrtWebEventSubscriber, createSmrtWebQuery, createUpdateState, durableStoreNamespace, executeSmrtWebDataQuery, getEngineCollection, getOutboxHandle, invalidateSmrtWebCollections, liveInvalidation, newLocalId, normalizeSmrtWebDataQueryResult, offlineOutbox, persistCollection, registerDurableResource, registerWebMcpTools, runWrapMutation, throwIfSmrtWebError, unwrapItemResult, unwrapListResult, validateSmrtWebClient, wipeDurableStore };

package/dist/webmcp.d.ts

@@ -4,9 +4,9 @@
  * @returns a disposer that deregisters all tools this call registered. On a
  * browser without WebMCP the call is a no-op and the disposer is inert.
  */
-export declare function registerWebMcpTools(definitions: SmrtWebCollectionDefinition[], options?: RegisterWebMcpToolsOptions): () => void;
+export declare function registerWebMcpTools(definitions: readonly WebMcpRegistrationDefinition[], options?: RegisterWebMcpToolsOptions): WebMcpRegistrationDisposer;
 
-export declare interface RegisterWebMcpToolsOptions {
+export declare interface RegisterWebMcpToolsOptions extends WebMcpExposurePolicy {
     /** REST base path for the fetchers (default `/api/v1`). */
     basePath?: string;
     /** Injectable fetch (tests / SSR-safe wrappers). */
@@ -21,8 +21,16 @@ export declare interface RegisterWebMcpToolsOptions {
      * without a live server.
      */
     resolveFetchers?: (definition: SmrtWebCollectionDefinition) => SmrtCrudFetchers;
+    /**
+     * Override direct REST fetchers for a canonical tool-only definition.
+     * Fetchers are optional because a get-only or custom-action-only model does
+     * not have a list or create route.
+     */
+    resolveToolFetchers?: (definition: WebMcpToolDefinition) => Partial<SmrtCrudFetchers>;
     /** Predicate to include/exclude individual tools (e.g. reads-only surfaces). */
     filter?: (definition: SmrtWebCollectionDefinition, descriptor: NonNullable<SmrtWebCollectionDefinition['toolDescriptors']>[number]) => boolean;
+    /** Predicate for canonical per-tool definitions. */
+    filterTool?: (definition: WebMcpToolDefinition) => boolean;
 }
 
 /**
@@ -162,6 +170,49 @@ declare interface SmrtWebToolRouteDescriptor {
     optionsBag?: boolean;
 }
 
+export declare interface WebMcpExposurePolicy {
+    /** Allowed effects. Omitted means read-only exposure. */
+    effects?: readonly WebMcpToolEffect[];
+    /** Prefix every registered tool name with `<namespace>_`. */
+    namespace?: string;
+    /** Optional maximum tools registered by one call. */
+    maxTools?: number;
+}
+
+/** Accepted legacy collection definitions and canonical per-tool definitions. */
+export declare type WebMcpRegistrationDefinition = SmrtWebCollectionDefinition | WebMcpToolDefinition;
+
+/** Disposes a registration and exposes completion of browser registration. */
+export declare interface WebMcpRegistrationDisposer {
+    (): void;
+    /** Rejects if the browser rejects any tool; all sibling tools are aborted. */
+    readonly ready: Promise<void>;
+}
+
+/**
+ * Canonical data-only definition for one API-backed browser tool. Unlike a
+ * collection definition, this does not imply that a list route or client cache
+ * exists. Generated definitions carry explicit semantics; manual legacy
+ * literals may omit them and register with fail-closed defaults.
+ */
+declare interface WebMcpToolDefinition extends WebToolDescriptor {
+    /** Stable definition identity is `(collection, action)`. */
+    collection: string;
+    /** Canonical qualified row-model identity. */
+    objectRef: string;
+    /** Row-model class used by the shared MCP tool vocabulary. */
+    className: string;
+    endpoint: string;
+    idField: string;
+    idType: 'uuid' | 'text';
+    /** Complete generated route metadata, including CRUD actions. */
+    route: SmrtWebToolRouteDescriptor;
+    /** Cache-invalidation edges for materialized sibling collections. */
+    relationships: SmrtWebRelationship[];
+}
+
+export declare type WebMcpToolEffect = 'read' | 'write' | 'destructive';
+
 /**
  * One generated collection definition: everything needed to construct a client
  * collection over the generated REST surface. The `_row` property is a phantom
@@ -185,6 +236,12 @@ declare interface WebToolDescriptor {
     inputSchema: Record<string, unknown>;
     /** True for non-mutating reads → WebMCP `annotations.readOnlyHint`. */
     readOnly: boolean;
+    /** Capability effect used by WebMCP exposure policy. */
+    effect?: 'read' | 'write' | 'destructive';
+    /** Whether repeating the tool with the same arguments is safe. */
+    idempotent?: boolean;
+    /** Whether the tool may interact outside the SMRT application. */
+    openWorld?: boolean;
     /** Generated custom-route transport metadata. */
     route?: SmrtWebToolRouteDescriptor;
 }

package/dist/webmcp.js

@@ -1,2 +1,2 @@
-import { u as registerWebMcpTools } from "./chunks/src-CDdW9uYx.js";
+import { p as registerWebMcpTools } from "./chunks/src-n14q6RHC.js";
 export { registerWebMcpTools };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-web",
-  "version": "0.43.2",
+  "version": "0.43.4",
   "description": "SMRT browser client data runtime: typed collection factory wrapping the client-data engine over generated REST clients",
   "author": "HappyVertical",
   "type": "module",