@happyvertical/smrt-web 0.42.6 → 0.43.0

package/dist/webmcp.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Register every collection's generated tool descriptors with WebMCP.
+ *
+ * @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 interface RegisterWebMcpToolsOptions {
+    /** REST base path for the fetchers (default `/api/v1`). */
+    basePath?: string;
+    /** Injectable fetch (tests / SSR-safe wrappers). */
+    fetchFn?: typeof fetch;
+    /** Shared smrt-web cache handle used by page collections. */
+    client?: SmrtWebClient;
+    /** Optional cache scope matching the page collection's scope. */
+    scope?: string;
+    /**
+     * Override how a definition's CRUD fetchers are built. Defaults to
+     * {@link createDefinitionFetchers}; the primary seam for testing `execute`
+     * without a live server.
+     */
+    resolveFetchers?: (definition: SmrtWebCollectionDefinition) => SmrtCrudFetchers;
+    /** Predicate to include/exclude individual tools (e.g. reads-only surfaces). */
+    filter?: (definition: SmrtWebCollectionDefinition, descriptor: NonNullable<SmrtWebCollectionDefinition['toolDescriptors']>[number]) => boolean;
+}
+
+/**
+ * The per-collection CRUD surface of the generated REST client
+ * (`createClient(basePath).<collection>` from `@happyvertical/smrt-virt-client`).
+ *
+ * Return types are `unknown` on purpose: generated fetchers resolve with
+ * whatever the server sent, so this package normalizes and validates payloads
+ * centrally — see {@link unwrapListResult} / {@link unwrapItemResult}.
+ */
+declare interface SmrtCrudFetchers {
+    list(params?: Record<string, unknown>): Promise<unknown>;
+    get?(id: string): Promise<unknown>;
+    create(data: Record<string, unknown>): Promise<unknown>;
+    update?(id: string, data: Record<string, unknown>): Promise<unknown>;
+    delete?(id: string): Promise<unknown>;
+    /** Invoke a generated custom action route. */
+    custom?(action: string, args: Record<string, unknown>, route?: SmrtWebToolRouteDescriptor): Promise<unknown>;
+}
+
+/**
+ * Opaque handle to the shared client cache / request-dedup layer. Create one
+ * with {@link createSmrtWebClient} and pass the SAME instance to every
+ * collection that should share a cache and deduplicate in-flight requests.
+ *
+ * The engine (currently a TanStack Query client) is intentionally hidden behind
+ * this brand so it stays swappable — do not depend on its concrete shape.
+ */
+declare interface SmrtWebClient {
+    /** Phantom brand — this handle wraps the hidden client-cache engine. */
+    readonly __smrtWebClient: 'SmrtWebClient';
+}
+
+declare interface SmrtWebCollectionDefinition<TData extends object = object> {
+    /** REST collection name (e.g. `products`). */
+    name: string;
+    /**
+     * Canonical qualified model identity (e.g.
+     * `@happyvertical/smrt-products:Product`). Generated definitions always
+     * provide it; optional here for source compatibility with manual literals
+     * authored before policy-aware web collections.
+     */
+    objectRef?: string;
+    /** Source class name (e.g. `Product`). */
+    className: string;
+    /** Path under the API base path (e.g. `/products`). */
+    endpoint: string;
+    /** Primary key field name (`id` for SmrtObject). */
+    idField: string;
+    /** CRUD + custom actions exposed by the api decorator config. */
+    actions: string[];
+    /**
+     * WebMCP/MCP tool descriptors for the exposed actions (#1812). Optional so
+     * hand-built definitions (older codegen, tests) still satisfy the type; a
+     * missing value means "no WebMCP tools to register".
+     */
+    toolDescriptors?: WebToolDescriptor[];
+    /** Persisted field metadata keyed by field name. */
+    fields: Record<string, SmrtWebFieldDefinition>;
+    /**
+     * Manifest-derived relationship edges to sibling REST collections. Drives
+     * relationship-derived cache invalidation: a settled mutation on this
+     * collection invalidates the caches of the collections these edges name.
+     * Optional so hand-built definitions (older codegen, tests) still satisfy the
+     * type; a missing value means "no derived edges".
+     */
+    relationships?: SmrtWebRelationship[];
+    /** Phantom row-type carrier — never present at runtime. */
+    _row?: TData;
+}
+
+/**
+ * Field metadata emitted per column by the `@happyvertical/smrt-virt-web`
+ * virtual module (generated from the package manifest).
+ */
+declare interface SmrtWebFieldDefinition {
+    type: SmrtWebFieldType;
+    required?: boolean;
+    /** Whether the public field contract explicitly permits `null`. */
+    nullable?: boolean;
+    default?: unknown;
+    /** Developer-authored `@field({ description })` (#2046) — end-user help seed. */
+    description?: string;
+    /** Static `@field({ ui })` hints (#2046). */
+    ui?: SmrtWebFieldUIHints;
+}
+
+/**
+ * The field types core's web-collection emission actually produces —
+ * relationship pseudo-columns (`oneToMany`/`manyToMany`) and STI `meta`
+ * internals never reach an emitted definition. Textual mirror of core's
+ * `WebFieldType` (this package is deliberately smrt-dependency-free, so it
+ * cannot import the source type); the four co-managed sites are core's
+ * runtime type, the ambient virt-web d.ts, the physical `@smrt/web` d.ts,
+ * and this mirror.
+ */
+declare type SmrtWebFieldType = 'text' | 'decimal' | 'boolean' | 'integer' | 'datetime' | 'json' | 'foreignKey' | 'crossPackageRef';
+
+/** Static `@field({ ui })` hints (#2046) — the field-policy rail seed. */
+declare interface SmrtWebFieldUIHints {
+    basic?: boolean;
+    group?: string;
+    order?: number;
+    locked?: boolean;
+}
+
+/**
+ * A manifest-derived edge from this collection to a sibling REST collection,
+ * emitted by the `@happyvertical/smrt-virt-web` virtual module. When a mutation
+ * on this collection settles, the caches of the collections named by these
+ * edges are invalidated (relationship-derived invalidation, #1761), so a
+ * dependent view refetches without any hand-wired cache key.
+ *
+ * SMRT-owned data — no client-engine (`@tanstack/*`) type appears here, so it
+ * stays inside the engine-absorption boundary.
+ */
+declare interface SmrtWebRelationship {
+    /** The declaring field carrying the relationship (e.g. `groupId`, `items`). */
+    field: string;
+    /** The relationship kind, mirroring the manifest field type. */
+    kind: SmrtWebRelationshipKind;
+    /** REST collection name the edge resolves to (e.g. `ad_groups`). */
+    relatedCollection: string;
+}
+
+/** The relationship kinds a generated web collection edge can describe. */
+declare type SmrtWebRelationshipKind = 'foreignKey' | 'crossPackageRef' | 'oneToMany' | 'manyToMany';
+
+declare interface SmrtWebToolRouteDescriptor {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    scope: 'item' | 'collection';
+    /** Route segments below the collection endpoint; dynamic segments use `[x]`. */
+    path: string[];
+    /** Transport names rewritten by the tool schema (e.g. `actionId` → `id`). */
+    parameterAliases?: Record<string, string>;
+    /** The generated method accepts one `options` bag as its sole argument. */
+    optionsBag?: boolean;
+}
+
+/**
+ * One generated collection definition: everything needed to construct a client
+ * collection over the generated REST surface. The `_row` property is a phantom
+ * type carrier threaded through codegen — it never exists at runtime, it only
+ * lets factories infer the row type from a definition.
+ */
+/**
+ * One WebMCP / MCP tool descriptor for a collection action (#1812). Emitted by
+ * the core web-collections codegen as PLAIN DATA (this package has no smrt
+ * dependency), shaped to match Chrome's `document.modelContext.registerTool`
+ * input — see https://developer.chrome.com/docs/ai/webmcp. Consumed by
+ * {@link registerWebMcpTools} in `./webmcp`.
+ */
+declare interface WebToolDescriptor {
+    /** The action this tool performs (`list` | `get` | … | a custom method name). */
+    action: string;
+    /** Tool id, `${className.toLowerCase()}_${action}` (e.g. `product_list`). */
+    name: string;
+    description: string;
+    /** JSON Schema for the tool's arguments. */
+    inputSchema: Record<string, unknown>;
+    /** True for non-mutating reads → WebMCP `annotations.readOnlyHint`. */
+    readOnly: boolean;
+    /** Generated custom-route transport metadata. */
+    route?: SmrtWebToolRouteDescriptor;
+}
+
+export { }

package/dist/webmcp.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-web",
-  "version": "0.42.6",
+  "version": "0.43.0",
   "description": "SMRT browser client data runtime: typed collection factory wrapping the client-data engine over generated REST clients",
   "author": "HappyVertical",
   "type": "module",
@@ -16,6 +16,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./webmcp": {
+      "types": "./dist/webmcp.d.ts",
+      "import": "./dist/webmcp.js"
     }
   },
   "dependencies": {