@happyvertical/smrt-web 0.43.3 → 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
@@ -250,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
@@ -533,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). */
@@ -550,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;
 }
 
 /**
@@ -1198,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
@@ -1279,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
@@ -1302,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 MAX_SMRT_WEB_DATA_QUERY_WARNINGS, C as MAX_SMRT_WEB_DATA_QUERY_FACETS, D as MAX_SMRT_WEB_DATA_QUERY_RESULT_BYTES, E as MAX_SMRT_WEB_DATA_QUERY_PAGE_LIMIT, M as normalizeSmrtWebDataQueryResult, N as runWrapMutation, O as MAX_SMRT_WEB_DATA_QUERY_ROWS, S as MAX_SMRT_WEB_DATA_QUERY_CONTAINER_ITEMS, T as MAX_SMRT_WEB_DATA_QUERY_OFFSET, _ as getOutboxHandle, a as createSmrtWebClient, b as registerDurableResource, c as unwrapItemResult, d as createUpdateState, f as createSmrtWebEventSubscriber, g as persistCollection, h as DEFAULT_PERSIST_DEBOUNCE_MS, i as createSmrtCollection, j as executeSmrtWebDataQuery, k as MAX_SMRT_WEB_DATA_QUERY_STRING_LENGTH, l as unwrapListResult, m as createSmrtWebQuery, n as buildListQuery, o as getEngineCollection, p as liveInvalidation, r as createDefinitionFetchers, s as newLocalId, t as SmrtWebRequestError, u as registerWebMcpTools, v as offlineOutbox, w as MAX_SMRT_WEB_DATA_QUERY_FACET_VALUES, x as wipeDurableStore, y as durableStoreNamespace } from "./chunks/src-D9RvoJSQ.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, 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-D9RvoJSQ.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.3",
+  "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",