@rudra-js/a2ui 0.0.0-stage → 0.8.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clive Dsouza
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,193 @@
-# Temporary Holding Version
+# @rudra-js/a2ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+This package is part of [rudra-js](https://rudrajs.com).
+
+rudra-js is an open-source TypeScript library (MIT) you install from npm. A language model designs one product-recommendation block for a page in your shop, rudra-js checks it against your catalog, and React renders it.
+
+It is not a hosted platform, a visual or low-code app builder, or a workspace you sign up for.
+
+This package puts that block inside the interfaces an [A2UI](https://a2ui.org) agent builds. It
+adds one component, `RudraRecommendations`, to the catalog your A2UI renderer draws from. The agent
+places it and hints at what the shopper is looking at. Your server still picks the products and
+builds the block with `@rudra-js/core`, and the browser renders it with `@rudra-js/react`.
+
+It works with version 0.9 of the A2UI protocol, through `@a2ui/react` and `@a2ui/web_core` 0.14.
+
+## Install
+
+```sh
+npm install @rudra-js/a2ui @rudra-js/core @rudra-js/react @rudra-js/attested @a2ui/react @a2ui/web_core react react-dom
+```
+
+Everything but zod is a peer dependency, so your app holds one copy of each. On pnpm, read
+[zod](#zod) first.
+
+Keep `skipLibCheck: true`. Without it, A2UI's own declarations fail to typecheck: they need `"dom"`
+in `lib`, and two of their imports have no file extension, which `nodenext` refuses.
+
+## Three pieces
+
+### The catalog your agent is prompted with
+
+Put `agentCatalog.toJson()` in your agent's prompt and have it create surfaces with
+`catalogId: agentCatalog.id`. If you have catalog instructions of your own, join them to
+`RUDRA_RECOMMENDATIONS_INSTRUCTIONS`.
+
+```ts
+import { Catalog } from '@a2ui/web_core/v0_9';
+import { basicCatalog } from '@a2ui/web_core/v0_9/basic_catalog';
+import { RUDRA_RECOMMENDATIONS_INSTRUCTIONS, rudraRecommendationsApi } from '@rudra-js/a2ui/server';
+
+export const agentCatalog = new Catalog(
+  'https://shop.example/a2ui/catalog.json',
+  'v0.9',
+  [...basicCatalog.components.values(), rudraRecommendationsApi],
+  [...basicCatalog.functions.values()],
+  { instructions: RUDRA_RECOMMENDATIONS_INSTRUCTIONS },
+);
+```
+
+The first `toJson()` logs one "Recursive reference detected" warning per hint. It's harmless.
+
+### Your endpoint
+
+`shopperFor` and `candidatesFor` stand for the session and catalog code you already have.
+`provider: null` calls no model, so pass your own provider. In the default cohort mode the model
+never sees `searchQuery`, so the agent's search only counts with `generation: 'per-shopper'`.
+
+```ts
+import { createComponentGenerator, parseTrackingInput } from '@rudra-js/core';
+import {
+  fitRecommendationRequest,
+  parseRecommendationRequest,
+  type RecommendationRequest,
+  type RecommendationResult,
+} from '@rudra-js/a2ui/server';
+import { candidatesFor, shopperFor } from './your-shop.js';
+
+const generator = createComponentGenerator({ provider: null });
+
+export async function POST(request: Request): Promise<Response> {
+  let asked: RecommendationRequest;
+  try {
+    asked = parseRecommendationRequest(await request.json());
+  } catch {
+    return new Response('Bad request', { status: 400 });
+  }
+
+  const shopper = await shopperFor(request);
+  const candidates = await candidatesFor(shopper);
+  const hints = fitRecommendationRequest(asked, candidates);
+  const input = parseTrackingInput({
+    user: { id: shopper.id },
+    context: { surface: 'assistant', locale: shopper.locale, ...hints },
+    candidates,
+    signals: shopper.signals,
+  });
+  const spec = await generator.generate(input);
+
+  const result: RecommendationResult = { spec, products: input.candidates, bundles: input.bundles };
+  return Response.json(result);
+}
+```
+
+- `parseRecommendationRequest` accepts only `currentSku`, `currentCategory`, `searchQuery` and
+  `maxItems`. Anything else is a 400.
+- `fitRecommendationRequest` drops a SKU or category none of your candidates has.
+- Pick candidates on your side, not from the hints. Each new category, `maxItems` or candidate set
+  is a new model call, and with `per-shopper` so is each shopper and each new SKU or search, so
+  rate-limit the endpoint (see [SECURITY.md](https://github.com/clivedsouza1010/rudra-js/blob/main/SECURITY.md)).
+- Send back `input.candidates` and `input.bundles`, not your raw catalog.
+
+### The browser
+
+```tsx
+import type { ReactCatalogComponent } from '@a2ui/react/v0_9';
+import { Catalog, MessageProcessor } from '@a2ui/web_core/v0_9';
+import { basicCatalog } from '@a2ui/web_core/v0_9/basic_catalog';
+import { createRudraRecommendationsComponent } from '@rudra-js/a2ui';
+
+const recommendations = createRudraRecommendationsComponent({
+  async loadRecommendations(request, signal) {
+    const response = await fetch('/api/recommendations', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(request),
+      signal,
+    });
+    if (!response.ok) throw new Error(`recommendations: HTTP ${response.status}`);
+    return response.json();
+  },
+  locale: 'en-US',
+});
+
+const shopCatalog = new Catalog<ReactCatalogComponent>(
+  'https://shop.example/a2ui/catalog.json',
+  'v0.9',
+  [...basicCatalog.components.values(), recommendations],
+  [...basicCatalog.functions.values()],
+);
+
+export const processor = new MessageProcessor<ReactCatalogComponent>([shopCatalog]);
+```
+
+Give the browser catalog the same id as the agent catalog, because A2UI looks it up by the
+`catalogId` the agent sends. Render the processor's surfaces with `A2uiSurface`. The options take
+`loadRecommendations`, `placeholder`, `onError`, and every `RudraComponent` prop except `spec`,
+`products` and `bundles`.
+
+## What the component does
+
+- It reads each hint as a literal or from the agent's data model (`{ "path": "/viewing/sku" }`),
+  and sends only the four. It leaves out a blank one, and one the server would turn away, like a
+  `maxItems` of 40. A literal of the wrong type, like a numeric SKU, makes A2UI refuse the agent's
+  whole message.
+- It asks once the hints hold still for 300 ms, and keeps the last block up until the next one
+  arrives. `signal` aborts when the hints change or the component unmounts.
+- It checks the result against core's schemas before rendering any of it.
+- It shows `placeholder` until the first load. On a failed load, a bad result or a render error it
+  shows nothing and calls `onError`.
+- Each component on a surface sends its own request.
+
+## Where it runs
+
+`@rudra-js/a2ui` holds `createRudraRecommendationsComponent` and its types, and loads only in the
+browser, because `@a2ui/react` needs a DOM. The agent catalog and your endpoint import from
+`@rudra-js/a2ui/server`, which runs anywhere. In Next.js a `'use client'` file still runs on the
+server for the first render, so load the one that imports `@rudra-js/a2ui` from a client component
+with `next/dynamic` and `ssr: false`.
+
+A2UI renders on the client, so a crawler won't see a block an agent places. For a product page,
+render `RudraComponent` on the server, as the
+[`@rudra-js/react` README](https://github.com/clivedsouza1010/rudra-js/tree/main/packages/react)
+describes.
+
+## zod
+
+A2UI's schemas are zod 3, so this package depends on zod 3 while the rest of rudra-js uses zod 4.
+npm installs both, each where its package finds it, and you don't need either one yourself.
+
+On pnpm, `@a2ui/react` gets core's zod 4 as its zod peer, and the browser example stops
+typechecking (TS2344). If your app has no zod of its own, add zod 3:
+
+```sh
+pnpm add zod@^3.25.76
+```
+
+If your app uses zod 4, drop the peer from `@a2ui/react` in `.pnpmfile.cjs`, and pnpm gives it
+the zod 3 it depends on:
+
+```js
+module.exports = {
+  hooks: {
+    readPackage(manifest) {
+      if (manifest.name === '@a2ui/react') delete manifest.peerDependencies?.zod;
+      return manifest;
+    },
+  },
+};
+```
+
+## Licence
+
+[MIT](./LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createRudraRecommendationsComponent, type RecommendationLoader, type RudraRecommendationsOptions, } from './recommendations-component.js';
+export type { RecommendationRequest } from './recommendation-request.js';
+export type { RecommendationResult } from './recommendation-result.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mCAAmC,EACnC,KAAK,oBAAoB,EACzB,KAAK,2BAA2B,GACjC,MAAM,gCAAgC,CAAC;AAExC,YAAY,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACzE,YAAY,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createRudraRecommendationsComponent, } from './recommendations-component.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mCAAmC,GAGpC,MAAM,gCAAgC,CAAC"}

package/dist/recommendation-request.d.ts

@@ -0,0 +1,11 @@
+import type { Product } from '@rudra-js/core';
+export interface RecommendationRequest {
+    currentSku?: string | undefined;
+    currentCategory?: string | undefined;
+    searchQuery?: string | undefined;
+    maxItems?: number | undefined;
+}
+export declare function parseRecommendationRequest(value: unknown): RecommendationRequest;
+export declare function fitRecommendationRequest(request: RecommendationRequest, candidates: readonly Pick<Product, 'sku' | 'category'>[]): RecommendationRequest;
+export declare function pickRecommendationRequest(written: Readonly<Record<string, unknown>>, resolved: Readonly<Record<string, unknown>>): RecommendationRequest;
+//# sourceMappingURL=recommendation-request.d.ts.map

package/dist/recommendation-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommendation-request.d.ts","sourceRoot":"","sources":["../src/recommendation-request.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAE9C,MAAM,WAAW,qBAAqB;IACpC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAMD,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,qBAAqB,CAEhF;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,qBAAqB,EAC9B,UAAU,EAAE,SAAS,IAAI,CAAC,OAAO,EAAE,KAAK,GAAG,UAAU,CAAC,EAAE,GACvD,qBAAqB,CAUvB;AAKD,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAC1C,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAC1C,qBAAqB,CAQvB"}

package/dist/recommendation-request.js

@@ -0,0 +1,34 @@
+import { renderContextSchema } from '@rudra-js/core/schemas';
+const recommendationRequestSchema = renderContextSchema
+    .pick({ currentSku: true, currentCategory: true, searchQuery: true })
+    .extend({ maxItems: renderContextSchema.shape.maxItems.unwrap().optional() });
+export function parseRecommendationRequest(value) {
+    return recommendationRequestSchema.parse(value);
+}
+export function fitRecommendationRequest(request, candidates) {
+    const { currentSku, currentCategory, searchQuery, maxItems } = request;
+    const fitted = {};
+    if (candidates.some((candidate) => candidate.sku === currentSku))
+        fitted.currentSku = currentSku;
+    if (candidates.some((candidate) => candidate.category === currentCategory)) {
+        fitted.currentCategory = currentCategory;
+    }
+    if (searchQuery !== undefined)
+        fitted.searchQuery = searchQuery;
+    if (maxItems !== undefined)
+        fitted.maxItems = maxItems;
+    return fitted;
+}
+const isBlank = (value) => value === undefined || (typeof value === 'string' && value.trim() === '');
+export function pickRecommendationRequest(written, resolved) {
+    const request = {};
+    for (const [field, schema] of Object.entries(recommendationRequestSchema.shape)) {
+        if (!Object.hasOwn(written, field))
+            continue;
+        const checked = schema.safeParse(resolved[field]);
+        if (checked.success && !isBlank(checked.data))
+            request[field] = checked.data;
+    }
+    return recommendationRequestSchema.parse(request);
+}
+//# sourceMappingURL=recommendation-request.js.map

package/dist/recommendation-request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommendation-request.js","sourceRoot":"","sources":["../src/recommendation-request.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAU7D,MAAM,2BAA2B,GAAG,mBAAmB;KACpD,IAAI,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;KACpE,MAAM,CAAC,EAAE,QAAQ,EAAE,mBAAmB,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;AAEhF,MAAM,UAAU,0BAA0B,CAAC,KAAc;IACvD,OAAO,2BAA2B,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,wBAAwB,CACtC,OAA8B,EAC9B,UAAwD;IAExD,MAAM,EAAE,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IACvE,MAAM,MAAM,GAA0B,EAAE,CAAC;IACzC,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,KAAK,UAAU,CAAC;QAAE,MAAM,CAAC,UAAU,GAAG,UAAU,CAAC;IACjG,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,QAAQ,KAAK,eAAe,CAAC,EAAE,CAAC;QAC3E,MAAM,CAAC,eAAe,GAAG,eAAe,CAAC;IAC3C,CAAC;IACD,IAAI,WAAW,KAAK,SAAS;QAAE,MAAM,CAAC,WAAW,GAAG,WAAW,CAAC;IAChE,IAAI,QAAQ,KAAK,SAAS;QAAE,MAAM,CAAC,QAAQ,GAAG,QAAQ,CAAC;IACvD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,OAAO,GAAG,CAAC,KAAc,EAAW,EAAE,CAC1C,KAAK,KAAK,SAAS,IAAI,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AAE5E,MAAM,UAAU,yBAAyB,CACvC,OAA0C,EAC1C,QAA2C;IAE3C,MAAM,OAAO,GAA4B,EAAE,CAAC;IAC5C,KAAK,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,2BAA2B,CAAC,KAAK,CAAC,EAAE,CAAC;QAChF,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC;YAAE,SAAS;QAC7C,MAAM,OAAO,GAAG,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;QAClD,IAAI,OAAO,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC;YAAE,OAAO,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAC/E,CAAC;IACD,OAAO,2BAA2B,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AACpD,CAAC"}

package/dist/recommendation-result.d.ts

@@ -0,0 +1,8 @@
+import type { Bundle, ComponentSpec, Product } from '@rudra-js/core';
+export interface RecommendationResult {
+    spec: ComponentSpec;
+    products: readonly Product[];
+    bundles?: readonly Bundle[];
+}
+export declare function parseRecommendationResult(value: unknown): RecommendationResult;
+//# sourceMappingURL=recommendation-result.d.ts.map

package/dist/recommendation-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommendation-result.d.ts","sourceRoot":"","sources":["../src/recommendation-result.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAErE,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,aAAa,CAAC;IACpB,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IAC7B,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB,CAU9E"}

package/dist/recommendation-result.js

@@ -0,0 +1,13 @@
+import { bundleSchema, parseComponentSpec, productSchema } from '@rudra-js/core/schemas';
+export function parseRecommendationResult(value) {
+    if (typeof value !== 'object' || value === null) {
+        throw new TypeError('the recommendation result is not an object');
+    }
+    const { spec, products, bundles } = value;
+    return {
+        spec: parseComponentSpec(spec),
+        products: productSchema.array().parse(products),
+        bundles: bundleSchema.array().default([]).parse(bundles),
+    };
+}
+//# sourceMappingURL=recommendation-result.js.map

package/dist/recommendation-result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommendation-result.js","sourceRoot":"","sources":["../src/recommendation-result.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AASzF,MAAM,UAAU,yBAAyB,CAAC,KAAc;IACtD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,MAAM,IAAI,SAAS,CAAC,4CAA4C,CAAC,CAAC;IACpE,CAAC;IACD,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,KAAgC,CAAC;IACrE,OAAO;QACL,IAAI,EAAE,kBAAkB,CAAC,IAAI,CAAC;QAC9B,QAAQ,EAAE,aAAa,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC;QAC/C,OAAO,EAAE,YAAY,CAAC,KAAK,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC;KACzD,CAAC;AACJ,CAAC"}

package/dist/recommendations-api.d.ts

@@ -0,0 +1,62 @@
+import { z } from 'zod/v3';
+export declare const RUDRA_RECOMMENDATIONS_INSTRUCTIONS: string;
+export declare const rudraRecommendationsApi: {
+    name: string;
+    schema: z.ZodObject<{
+        currentSku: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodObject<{
+            path: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            path: string;
+        }, {
+            path: string;
+        }>, z.ZodType<import("@a2ui/web_core/v0_9").FunctionCall, z.ZodTypeDef, import("@a2ui/web_core/v0_9").FunctionCall>]>>;
+        currentCategory: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodObject<{
+            path: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            path: string;
+        }, {
+            path: string;
+        }>, z.ZodType<import("@a2ui/web_core/v0_9").FunctionCall, z.ZodTypeDef, import("@a2ui/web_core/v0_9").FunctionCall>]>>;
+        searchQuery: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodObject<{
+            path: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            path: string;
+        }, {
+            path: string;
+        }>, z.ZodType<import("@a2ui/web_core/v0_9").FunctionCall, z.ZodTypeDef, import("@a2ui/web_core/v0_9").FunctionCall>]>>;
+        maxItems: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodObject<{
+            path: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            path: string;
+        }, {
+            path: string;
+        }>, z.ZodType<import("@a2ui/web_core/v0_9").FunctionCall, z.ZodTypeDef, import("@a2ui/web_core/v0_9").FunctionCall>]>>;
+    }, "strip", z.ZodTypeAny, {
+        currentSku?: string | import("@a2ui/web_core/v0_9").FunctionCall | {
+            path: string;
+        } | undefined;
+        currentCategory?: string | import("@a2ui/web_core/v0_9").FunctionCall | {
+            path: string;
+        } | undefined;
+        searchQuery?: string | import("@a2ui/web_core/v0_9").FunctionCall | {
+            path: string;
+        } | undefined;
+        maxItems?: number | import("@a2ui/web_core/v0_9").FunctionCall | {
+            path: string;
+        } | undefined;
+    }, {
+        currentSku?: string | import("@a2ui/web_core/v0_9").FunctionCall | {
+            path: string;
+        } | undefined;
+        currentCategory?: string | import("@a2ui/web_core/v0_9").FunctionCall | {
+            path: string;
+        } | undefined;
+        searchQuery?: string | import("@a2ui/web_core/v0_9").FunctionCall | {
+            path: string;
+        } | undefined;
+        maxItems?: number | import("@a2ui/web_core/v0_9").FunctionCall | {
+            path: string;
+        } | undefined;
+    }>;
+};
+//# sourceMappingURL=recommendations-api.d.ts.map

package/dist/recommendations-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommendations-api.d.ts","sourceRoot":"","sources":["../src/recommendations-api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAI3B,eAAO,MAAM,kCAAkC,QAIP,CAAC;AAmBzC,eAAO,MAAM,uBAAuB;IAClC,IAAI;IACJ,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CACP,CAAC"}

package/dist/recommendations-api.js

@@ -0,0 +1,20 @@
+import { z } from 'zod/v3';
+import { CommonSchemas } from '@a2ui/web_core/v0_9';
+import { FIELD_LIMITS } from '@rudra-js/core/schemas';
+export const RUDRA_RECOMMENDATIONS_INSTRUCTIONS = 'RudraRecommendations shows product recommendations from this shop. Place it and ' +
+    'say what the shopper is looking at. The shop chooses the products and writes the heading, and ' +
+    "every title, price, image and link comes from the shop's catalog. Do not write product names, " +
+    'prices, ratings or offers around it.';
+const recommendationsPropertiesSchema = z.object({
+    currentSku: CommonSchemas.DynamicString.optional().describe('SKU of the product the shopper is looking at or asking about. It is left out of the ' +
+        'recommendations. Use only a SKU the shop gave you.'),
+    currentCategory: CommonSchemas.DynamicString.optional().describe('Catalog category the shopper is browsing or asking about.'),
+    searchQuery: CommonSchemas.DynamicString.optional().describe("What the shopper searched for or asked for, in the shopper's own words."),
+    maxItems: CommonSchemas.DynamicNumber.optional().describe(`Most products to show, a whole number from 1 to ${FIELD_LIMITS.maxItems}. The shop decides ` +
+        'when this is left out or out of range.'),
+});
+export const rudraRecommendationsApi = {
+    name: 'RudraRecommendations',
+    schema: recommendationsPropertiesSchema,
+};
+//# sourceMappingURL=recommendations-api.js.map

package/dist/recommendations-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommendations-api.js","sourceRoot":"","sources":["../src/recommendations-api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAC3B,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEtD,MAAM,CAAC,MAAM,kCAAkC,GAC7C,kFAAkF;IAClF,gGAAgG;IAChG,gGAAgG;IAChG,sCAAsC,CAAC;AAEzC,MAAM,+BAA+B,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,UAAU,EAAE,aAAa,CAAC,aAAa,CAAC,QAAQ,EAAE,CAAC,QAAQ,CACzD,sFAAsF;QACpF,oDAAoD,CACvD;IACD,eAAe,EAAE,aAAa,CAAC,aAAa,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAC9D,2DAA2D,CAC5D;IACD,WAAW,EAAE,aAAa,CAAC,aAAa,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAC1D,yEAAyE,CAC1E;IACD,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,QAAQ,EAAE,CAAC,QAAQ,CACvD,mDAAmD,YAAY,CAAC,QAAQ,qBAAqB;QAC3F,wCAAwC,CAC3C;CACF,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,IAAI,EAAE,sBAAsB;IAC5B,MAAM,EAAE,+BAA+B;CACxC,CAAC"}

package/dist/recommendations-component.d.ts

@@ -0,0 +1,13 @@
+import { type ReactNode } from 'react';
+import { type ReactComponentImplementation } from '@a2ui/react/v0_9';
+import { type RudraComponentProps } from '@rudra-js/react';
+import { type RecommendationRequest } from './recommendation-request.js';
+import { type RecommendationResult } from './recommendation-result.js';
+export type RecommendationLoader = (request: RecommendationRequest, signal: AbortSignal) => Promise<RecommendationResult>;
+export interface RudraRecommendationsOptions extends Omit<RudraComponentProps, 'spec' | 'products' | 'bundles'> {
+    loadRecommendations: RecommendationLoader;
+    placeholder?: ReactNode;
+    onError?: (error: unknown) => void;
+}
+export declare function createRudraRecommendationsComponent({ loadRecommendations, placeholder, onError, ...blockProps }: RudraRecommendationsOptions): ReactComponentImplementation;
+//# sourceMappingURL=recommendations-component.d.ts.map

package/dist/recommendations-component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommendations-component.d.ts","sourceRoot":"","sources":["../src/recommendations-component.tsx"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AACf,OAAO,EAAiC,KAAK,4BAA4B,EAAE,MAAM,kBAAkB,CAAC;AAEpG,OAAO,EAAkB,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAE3E,OAAO,EAA6B,KAAK,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACpG,OAAO,EAA6B,KAAK,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAElG,MAAM,MAAM,oBAAoB,GAAG,CACjC,OAAO,EAAE,qBAAqB,EAC9B,MAAM,EAAE,WAAW,KAChB,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAEnC,MAAM,WAAW,2BAA4B,SAAQ,IAAI,CACvD,mBAAmB,EACnB,MAAM,GAAG,UAAU,GAAG,SAAS,CAChC;IACC,mBAAmB,EAAE,oBAAoB,CAAC;IAC1C,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC;AA+ED,wBAAgB,mCAAmC,CAAC,EAClD,mBAAmB,EACnB,WAAkB,EAClB,OAAO,EACP,GAAG,UAAU,EACd,EAAE,2BAA2B,GAAG,4BAA4B,CAiB5D"}

package/dist/recommendations-component.js

@@ -0,0 +1,73 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Component, useCallback, useEffect, useRef, useState, useSyncExternalStore, } from 'react';
+import { createComponentImplementation } from '@a2ui/react/v0_9';
+import { RudraComponent } from '@rudra-js/react';
+import { rudraRecommendationsApi } from './recommendations-api.js';
+import { pickRecommendationRequest } from './recommendation-request.js';
+import { parseRecommendationResult } from './recommendation-result.js';
+const HINT_SETTLE_MS = 300;
+function useWrittenProperties(model) {
+    const subscribe = useCallback((onChange) => {
+        const subscription = model.onUpdated.subscribe(onChange);
+        return () => subscription.unsubscribe();
+    }, [model]);
+    return useSyncExternalStore(subscribe, () => model.properties);
+}
+function useRecommendationResult(request, loadRecommendations, onError) {
+    const [state, setState] = useState({ status: 'loading' });
+    const shownRequestKey = useRef(null);
+    const requestKey = JSON.stringify(request);
+    useEffect(() => {
+        if (requestKey === shownRequestKey.current)
+            return;
+        const controller = new AbortController();
+        const asked = JSON.parse(requestKey);
+        async function load() {
+            try {
+                const result = parseRecommendationResult(await loadRecommendations(asked, controller.signal));
+                if (controller.signal.aborted)
+                    return;
+                shownRequestKey.current = requestKey;
+                setState({ status: 'ready', result, requestKey });
+            }
+            catch (error) {
+                if (controller.signal.aborted)
+                    return;
+                shownRequestKey.current = null;
+                setState({ status: 'failed' });
+                onError?.(error);
+            }
+        }
+        const timer = setTimeout(load, HINT_SETTLE_MS);
+        return () => {
+            clearTimeout(timer);
+            controller.abort();
+        };
+    }, [requestKey, loadRecommendations, onError]);
+    return state;
+}
+class RenderFailureBoundary extends Component {
+    state = { hasFailed: false };
+    static getDerivedStateFromError() {
+        return { hasFailed: true };
+    }
+    componentDidCatch(error) {
+        this.props.onError?.(error);
+    }
+    render() {
+        return this.state.hasFailed ? null : this.props.children;
+    }
+}
+export function createRudraRecommendationsComponent({ loadRecommendations, placeholder = null, onError, ...blockProps }) {
+    return createComponentImplementation(rudraRecommendationsApi, function RudraRecommendations({ props, context }) {
+        const written = useWrittenProperties(context.componentModel);
+        const request = pickRecommendationRequest(written, props);
+        const state = useRecommendationResult(request, loadRecommendations, onError);
+        if (state.status === 'loading')
+            return placeholder;
+        if (state.status === 'failed')
+            return null;
+        return (_jsx(RenderFailureBoundary, { onError: onError, children: _jsx(RudraComponent, { ...blockProps, ...state.result }) }, state.requestKey));
+    });
+}
+//# sourceMappingURL=recommendations-component.js.map

package/dist/recommendations-component.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommendations-component.js","sourceRoot":"","sources":["../src/recommendations-component.tsx"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -0,0 +1,4 @@
+export { RUDRA_RECOMMENDATIONS_INSTRUCTIONS, rudraRecommendationsApi, } from './recommendations-api.js';
+export { fitRecommendationRequest, parseRecommendationRequest, type RecommendationRequest, } from './recommendation-request.js';
+export type { RecommendationResult } from './recommendation-result.js';
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kCAAkC,EAClC,uBAAuB,GACxB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,wBAAwB,EACxB,0BAA0B,EAC1B,KAAK,qBAAqB,GAC3B,MAAM,6BAA6B,CAAC;AAErC,YAAY,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/server.js

@@ -0,0 +1,3 @@
+export { RUDRA_RECOMMENDATIONS_INSTRUCTIONS, rudraRecommendationsApi, } from './recommendations-api.js';
+export { fitRecommendationRequest, parseRecommendationRequest, } from './recommendation-request.js';
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kCAAkC,EAClC,uBAAuB,GACxB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,wBAAwB,EACxB,0BAA0B,GAE3B,MAAM,6BAA6B,CAAC"}

package/package.json

@@ -1,6 +1,80 @@
 {
   "name": "@rudra-js/a2ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.8.1",
+  "description": "A2UI component for rudra-js: lets an A2UI agent place a product-recommendation block whose products, prices and wording come from your shop, not from the agent",
+  "keywords": [
+    "rudra-js",
+    "a2ui",
+    "product-recommendations",
+    "react",
+    "llm",
+    "agents",
+    "generative-ui",
+    "ecommerce",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": "Clive Dsouza",
+  "homepage": "https://rudrajs.com",
+  "bugs": {
+    "url": "https://github.com/clivedsouza1010/rudra-js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clivedsouza1010/rudra-js.git",
+    "directory": "packages/a2ui"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^3.25.76"
+  },
+  "peerDependencies": {
+    "@a2ui/react": "^0.14.0",
+    "@a2ui/web_core": "^0.14.0",
+    "@rudra-js/core": "^0.8.1",
+    "@rudra-js/react": "^0.8.1",
+    "react": "^18.2.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@a2ui/react": "0.14.0",
+    "@a2ui/web_core": "0.14.0",
+    "@rudra-js/core": "0.8.1",
+    "@rudra-js/react": "0.8.1",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "jsdom": "^27.4.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export {
+  createRudraRecommendationsComponent,
+  type RecommendationLoader,
+  type RudraRecommendationsOptions,
+} from './recommendations-component.js';
+
+export type { RecommendationRequest } from './recommendation-request.js';
+export type { RecommendationResult } from './recommendation-result.js';

package/src/recommendation-request.ts

@@ -0,0 +1,48 @@
+import { renderContextSchema } from '@rudra-js/core/schemas';
+import type { Product } from '@rudra-js/core';
+
+export interface RecommendationRequest {
+  currentSku?: string | undefined;
+  currentCategory?: string | undefined;
+  searchQuery?: string | undefined;
+  maxItems?: number | undefined;
+}
+
+const recommendationRequestSchema = renderContextSchema
+  .pick({ currentSku: true, currentCategory: true, searchQuery: true })
+  .extend({ maxItems: renderContextSchema.shape.maxItems.unwrap().optional() });
+
+export function parseRecommendationRequest(value: unknown): RecommendationRequest {
+  return recommendationRequestSchema.parse(value);
+}
+
+export function fitRecommendationRequest(
+  request: RecommendationRequest,
+  candidates: readonly Pick<Product, 'sku' | 'category'>[],
+): RecommendationRequest {
+  const { currentSku, currentCategory, searchQuery, maxItems } = request;
+  const fitted: RecommendationRequest = {};
+  if (candidates.some((candidate) => candidate.sku === currentSku)) fitted.currentSku = currentSku;
+  if (candidates.some((candidate) => candidate.category === currentCategory)) {
+    fitted.currentCategory = currentCategory;
+  }
+  if (searchQuery !== undefined) fitted.searchQuery = searchQuery;
+  if (maxItems !== undefined) fitted.maxItems = maxItems;
+  return fitted;
+}
+
+const isBlank = (value: unknown): boolean =>
+  value === undefined || (typeof value === 'string' && value.trim() === '');
+
+export function pickRecommendationRequest(
+  written: Readonly<Record<string, unknown>>,
+  resolved: Readonly<Record<string, unknown>>,
+): RecommendationRequest {
+  const request: Record<string, unknown> = {};
+  for (const [field, schema] of Object.entries(recommendationRequestSchema.shape)) {
+    if (!Object.hasOwn(written, field)) continue;
+    const checked = schema.safeParse(resolved[field]);
+    if (checked.success && !isBlank(checked.data)) request[field] = checked.data;
+  }
+  return recommendationRequestSchema.parse(request);
+}

package/src/recommendation-result.ts

@@ -0,0 +1,20 @@
+import { bundleSchema, parseComponentSpec, productSchema } from '@rudra-js/core/schemas';
+import type { Bundle, ComponentSpec, Product } from '@rudra-js/core';
+
+export interface RecommendationResult {
+  spec: ComponentSpec;
+  products: readonly Product[];
+  bundles?: readonly Bundle[];
+}
+
+export function parseRecommendationResult(value: unknown): RecommendationResult {
+  if (typeof value !== 'object' || value === null) {
+    throw new TypeError('the recommendation result is not an object');
+  }
+  const { spec, products, bundles } = value as Record<string, unknown>;
+  return {
+    spec: parseComponentSpec(spec),
+    products: productSchema.array().parse(products),
+    bundles: bundleSchema.array().default([]).parse(bundles),
+  };
+}

package/src/recommendations-api.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod/v3';
+import { CommonSchemas } from '@a2ui/web_core/v0_9';
+import { FIELD_LIMITS } from '@rudra-js/core/schemas';
+
+export const RUDRA_RECOMMENDATIONS_INSTRUCTIONS =
+  'RudraRecommendations shows product recommendations from this shop. Place it and ' +
+  'say what the shopper is looking at. The shop chooses the products and writes the heading, and ' +
+  "every title, price, image and link comes from the shop's catalog. Do not write product names, " +
+  'prices, ratings or offers around it.';
+
+const recommendationsPropertiesSchema = z.object({
+  currentSku: CommonSchemas.DynamicString.optional().describe(
+    'SKU of the product the shopper is looking at or asking about. It is left out of the ' +
+      'recommendations. Use only a SKU the shop gave you.',
+  ),
+  currentCategory: CommonSchemas.DynamicString.optional().describe(
+    'Catalog category the shopper is browsing or asking about.',
+  ),
+  searchQuery: CommonSchemas.DynamicString.optional().describe(
+    "What the shopper searched for or asked for, in the shopper's own words.",
+  ),
+  maxItems: CommonSchemas.DynamicNumber.optional().describe(
+    `Most products to show, a whole number from 1 to ${FIELD_LIMITS.maxItems}. The shop decides ` +
+      'when this is left out or out of range.',
+  ),
+});
+
+export const rudraRecommendationsApi = {
+  name: 'RudraRecommendations',
+  schema: recommendationsPropertiesSchema,
+};

package/src/recommendations-component.tsx

@@ -0,0 +1,130 @@
+import {
+  Component,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  useSyncExternalStore,
+  type ReactNode,
+} from 'react';
+import { createComponentImplementation, type ReactComponentImplementation } from '@a2ui/react/v0_9';
+import type { ComponentModel } from '@a2ui/web_core/v0_9';
+import { RudraComponent, type RudraComponentProps } from '@rudra-js/react';
+import { rudraRecommendationsApi } from './recommendations-api.js';
+import { pickRecommendationRequest, type RecommendationRequest } from './recommendation-request.js';
+import { parseRecommendationResult, type RecommendationResult } from './recommendation-result.js';
+
+export type RecommendationLoader = (
+  request: RecommendationRequest,
+  signal: AbortSignal,
+) => Promise<RecommendationResult>;
+
+export interface RudraRecommendationsOptions extends Omit<
+  RudraComponentProps,
+  'spec' | 'products' | 'bundles'
+> {
+  loadRecommendations: RecommendationLoader;
+  placeholder?: ReactNode;
+  onError?: (error: unknown) => void;
+}
+
+const HINT_SETTLE_MS = 300;
+
+type LoadState =
+  | { status: 'loading' }
+  | { status: 'failed' }
+  | { status: 'ready'; result: RecommendationResult; requestKey: string };
+
+function useWrittenProperties(model: ComponentModel): Readonly<Record<string, unknown>> {
+  const subscribe = useCallback(
+    (onChange: () => void) => {
+      const subscription = model.onUpdated.subscribe(onChange);
+      return () => subscription.unsubscribe();
+    },
+    [model],
+  );
+  return useSyncExternalStore(subscribe, () => model.properties);
+}
+
+function useRecommendationResult(
+  request: RecommendationRequest,
+  loadRecommendations: RecommendationLoader,
+  onError: RudraRecommendationsOptions['onError'],
+): LoadState {
+  const [state, setState] = useState<LoadState>({ status: 'loading' });
+  const shownRequestKey = useRef<string | null>(null);
+  const requestKey = JSON.stringify(request);
+
+  useEffect(() => {
+    if (requestKey === shownRequestKey.current) return;
+    const controller = new AbortController();
+    const asked: RecommendationRequest = JSON.parse(requestKey);
+
+    async function load() {
+      try {
+        const result = parseRecommendationResult(
+          await loadRecommendations(asked, controller.signal),
+        );
+        if (controller.signal.aborted) return;
+        shownRequestKey.current = requestKey;
+        setState({ status: 'ready', result, requestKey });
+      } catch (error) {
+        if (controller.signal.aborted) return;
+        shownRequestKey.current = null;
+        setState({ status: 'failed' });
+        onError?.(error);
+      }
+    }
+
+    const timer = setTimeout(load, HINT_SETTLE_MS);
+    return () => {
+      clearTimeout(timer);
+      controller.abort();
+    };
+  }, [requestKey, loadRecommendations, onError]);
+
+  return state;
+}
+
+class RenderFailureBoundary extends Component<
+  { onError: RudraRecommendationsOptions['onError']; children: ReactNode },
+  { hasFailed: boolean }
+> {
+  override state = { hasFailed: false };
+
+  static getDerivedStateFromError() {
+    return { hasFailed: true };
+  }
+
+  override componentDidCatch(error: unknown) {
+    this.props.onError?.(error);
+  }
+
+  override render() {
+    return this.state.hasFailed ? null : this.props.children;
+  }
+}
+
+export function createRudraRecommendationsComponent({
+  loadRecommendations,
+  placeholder = null,
+  onError,
+  ...blockProps
+}: RudraRecommendationsOptions): ReactComponentImplementation {
+  return createComponentImplementation(
+    rudraRecommendationsApi,
+    function RudraRecommendations({ props, context }) {
+      const written = useWrittenProperties(context.componentModel);
+      const request = pickRecommendationRequest(written, props);
+      const state = useRecommendationResult(request, loadRecommendations, onError);
+
+      if (state.status === 'loading') return placeholder;
+      if (state.status === 'failed') return null;
+      return (
+        <RenderFailureBoundary key={state.requestKey} onError={onError}>
+          <RudraComponent {...blockProps} {...state.result} />
+        </RenderFailureBoundary>
+      );
+    },
+  );
+}

package/src/server.ts

@@ -0,0 +1,12 @@
+export {
+  RUDRA_RECOMMENDATIONS_INSTRUCTIONS,
+  rudraRecommendationsApi,
+} from './recommendations-api.js';
+
+export {
+  fitRecommendationRequest,
+  parseRecommendationRequest,
+  type RecommendationRequest,
+} from './recommendation-request.js';
+
+export type { RecommendationResult } from './recommendation-result.js';