@gengage/assistant-fe 0.5.7 → 0.6.1

package/README.md

@@ -97,7 +97,7 @@ The chat widget includes a built-in history entry point in the header. Past chat
 
 ## Customization
 
-**Theme tokens** — no fork required:
+**Theme tokens** — configure visual defaults at the SDK boundary:
 ```ts
 chat.init({
   theme: { primaryColor: '#f27a1a', headerBg: '#1a1a2e' },
@@ -128,9 +128,9 @@ await initOverlayWidgets({
 
 **SimBut customization** — use theme tokens, `i18n.findSimilarLabel`, and `onFindSimilar` for the PDP image-overlay pill.
 
-**Full fork** — replace `src/chat/components/` entirely; keep `catalog.ts` + `index.ts`.
+**Reusable component changes** — update SDK components and keep `catalog.ts`, public exports, tests, and catalog previews in sync.
 
-See [docs/customization.md](docs/customization.md) for the fork and merchant-customization playbook.
+See [docs/customization.md](docs/customization.md) for the supported SDK customization surface.
 
 ---
 
@@ -138,30 +138,16 @@ See [docs/customization.md](docs/customization.md) for the fork and merchant-cus
 
 ```bash
 npm install
-npm run dev -- koctascomtr --sku=1000465056   # Local dev server with HMR
-npm run koctascomtr                            # Merchant shortcut with the seeded demo SKU
-npm run trendyolcom                            # Another merchant shortcut using its default PDP SKU
 npm run typecheck                              # TypeScript strict check
 npm run test                                   # Unit tests
 npm run test:chat-history                      # Targeted history + restore regression suite
 npm run build                                  # Build to dist/
-npm run catalog                                # Visual component catalog at :3002
+npm run catalog                                # Visual component catalog at :3002, with fixed generic styling presets
 npm run docs:build                             # Build contributor docs with VitePress
 ```
 
-**Using a local backend:**
-
-```bash
-npm run dev -- koctascomtr --sku=1000465056 --backend-url=http://localhost:7860
-```
-
-The local demos use the shared `defaultDevBackend` value from `demos/shared/default-dev-backend.ts`. For account-specific testing, set `MIDDLEWARE_URL` to the backend service location provided for your Gengage account:
-
-```bash
-MIDDLEWARE_URL=http://localhost:7860 npm run dev -- koctascomtr --sku=1000465056
-```
-
-Merchant demo pages under `demos/` now seed a default PDP SKU for direct launch flows, and the affected PDP shells hydrate their breadcrumb, summary content, and gallery imagery from middleware `productDetails` when the backend is available.
+This repo builds the SDK package only. Hosted account demos and exact client PDP/PLP clones live in
+`gengage-assistant-injector` and are deployed from that repository to `configs.gengage.ai`.
 
 ---
 
@@ -180,7 +166,6 @@ Merchant demo pages under `demos/` now seed a default PDP SKU for direct launch
 | [Security](docs/security-production.md) | Production CSP, postMessage origins, sanitization |
 | [Analytics](docs/analytics-contract.md) | GTM/GA dataLayer event mapping |
 | [Mobile SDK](docs/native-mobile-sdk.md) | Android/iOS/React Native integration |
-| [New Account](docs/new-account-guide.md) | Adding a new merchant demo |
 | [AGENTS](AGENTS.md) | Coding-agent architecture and code-path index |
 | [Contributing](CONTRIBUTING.md) | Shared SDK contribution workflow |
 
@@ -196,7 +181,6 @@ src/
   simrel/     # Similar products widget (GengageSimRel class + components)
   simbut/     # PDP image overlay pill widget (GengageSimBut class)
   native/     # Native WebView bridge exports
-demos/        # Merchant-branded demo pages and framework integration examples
 catalog/      # Visual component catalog (mock data, no backend)
 docs/         # Architecture, wire protocol, customization, analytics
 tests/        # Vitest unit tests + Playwright E2E

package/dist/agentic/adaptor/create-adaptor.d.ts

@@ -0,0 +1,19 @@
+import type { InjectorAdapter } from '../../common/transport.js';
+import type { AccountModule, BeaconCallback, ToolMap } from '../types.js';
+interface CreateInjectorAdapterArgs {
+    accountId: string;
+    worker: Worker;
+    beUrl: string;
+    devJwtSecret?: string | undefined;
+    tokenBrokerUrl?: string | undefined;
+    tokenBrokerAudience?: string | undefined;
+    defaultLocale?: string | undefined;
+    tools?: ToolMap | undefined;
+    beacon?: BeaconCallback | undefined;
+}
+export declare function createInjectorAdapter({ accountId, worker, beUrl, devJwtSecret, tokenBrokerUrl, tokenBrokerAudience, defaultLocale, tools, beacon, }: CreateInjectorAdapterArgs): InjectorAdapter;
+interface CreateMainThreadInjectorAdapterArgs extends Omit<CreateInjectorAdapterArgs, 'worker'> {
+    accountModule: AccountModule;
+}
+export declare function createMainThreadInjectorAdapter({ accountId, accountModule, beUrl, devJwtSecret, tokenBrokerUrl, tokenBrokerAudience, defaultLocale, tools, beacon, }: CreateMainThreadInjectorAdapterArgs): InjectorAdapter;
+export {};

package/dist/agentic/adaptor/fetch-bridge.d.ts

@@ -0,0 +1,11 @@
+import type { InjectorAdapter } from '../../common/transport.js';
+interface InstallFetchBridgeArgs {
+    accountId: string;
+    streamTransport: InjectorAdapter;
+}
+interface InstallFetchBridgeResult {
+    middlewareUrl: string;
+    stop: () => void;
+}
+export declare function installFetchTransportBridge({ accountId, streamTransport, }: InstallFetchBridgeArgs): InstallFetchBridgeResult;
+export {};

package/dist/agentic/adaptor/mount.d.ts

@@ -0,0 +1,38 @@
+import type { AccountModule, BeaconCallback, ToolMap } from '../types.js';
+interface MountAccountArgs {
+    accountId: string;
+    beUrl: string;
+    devJwtSecret?: string;
+    tokenBrokerUrl?: string;
+    tokenBrokerAudience?: string;
+    workerUrl: string;
+    defaultLocale?: string;
+    accountModule: AccountModule;
+    tools?: ToolMap;
+    beacon?: BeaconCallback;
+    allowBlobWorker?: boolean;
+}
+interface AgentDiagnostics {
+    accountId: string;
+    beUrl: string;
+    workerUrl: string;
+    mounted: boolean;
+    transport: 'worker' | 'main-thread';
+    flows: string[];
+}
+export interface AgentController {
+    type: 'agent';
+    stop: () => void;
+    diagnostics: () => AgentDiagnostics;
+}
+interface ModuleWorkerHandle {
+    worker: Worker;
+    cleanup: () => void;
+}
+interface CreateModuleWorkerOptions {
+    allowBlobWorker?: boolean;
+}
+export declare function mountAccount({ accountId, beUrl, devJwtSecret, tokenBrokerUrl, tokenBrokerAudience, workerUrl, defaultLocale, accountModule, tools, beacon, allowBlobWorker, }: MountAccountArgs): AgentController;
+export declare function canUseModuleWorker(workerUrl: string): boolean;
+export declare function createModuleWorker(workerUrl: string, name: string, options?: CreateModuleWorkerOptions): ModuleWorkerHandle;
+export {};

package/dist/agentic/context/chat-context.d.ts

@@ -0,0 +1,15 @@
+import type { ChatContext } from '../types.js';
+interface CreateChatContextArgs {
+    accountId: string;
+    locale?: string | undefined;
+    parentUrl?: string | undefined;
+    threadId?: string | undefined;
+    incomingContext?: unknown;
+}
+interface IncomingMessageLike {
+    role?: unknown;
+    content?: unknown;
+}
+export declare function createChatContext(args: CreateChatContextArgs): ChatContext;
+export declare function appendMessage(context: ChatContext, message: IncomingMessageLike): ChatContext;
+export {};

package/dist/agentic/context/context-store.d.ts

@@ -0,0 +1,20 @@
+import type { ProcessActionRequest } from '../../common/transport.js';
+import type { ChatContext, RpcFn } from '../types.js';
+interface ContextStoreOptions {
+    accountId: string;
+    locale?: string | undefined;
+    parentUrl?: string | undefined;
+    rpc: RpcFn;
+}
+type PatchInput = Partial<ChatContext> | null | undefined | ((current: ChatContext) => Partial<ChatContext> | null | undefined);
+export declare class ContextStore {
+    #private;
+    constructor({ accountId, locale, parentUrl, rpc }: ContextStoreOptions);
+    load(request: (ProcessActionRequest & {
+        sessionId?: string;
+    }) | null | undefined): Promise<ChatContext>;
+    patch(threadId: string | null | undefined, patch: PatchInput): ChatContext | null;
+    appendUserMessage(threadId: string | null | undefined, text: string): ChatContext | null;
+    commit(threadId: string | null | undefined): Promise<ChatContext | null>;
+}
+export {};

package/dist/agentic/context/persistence.d.ts

@@ -0,0 +1,12 @@
+import type { RpcFn } from '../types.js';
+interface LoadArgs {
+    accountId: string;
+    threadId: string;
+    rpc: RpcFn;
+}
+interface SaveArgs extends LoadArgs {
+    extensions: Record<string, unknown>;
+}
+export declare function loadStickyContext({ accountId, threadId, rpc }: LoadArgs): Promise<Record<string, unknown>>;
+export declare function saveStickyContext({ accountId, threadId, extensions, rpc }: SaveArgs): Promise<void>;
+export {};

package/dist/agentic/events/builders.d.ts

@@ -0,0 +1,10 @@
+import type { StreamEventAction, StreamEventDone, StreamEventError, StreamEventMetadata, StreamEventTextChunk, StreamEventUISpec } from '../../common/types.js';
+import type { UiSpecEnvelope } from '../types.js';
+export declare function metadata(args?: Record<string, unknown>): StreamEventMetadata;
+type TextChunkExtras = Omit<StreamEventTextChunk, 'type' | 'content' | 'final'>;
+export declare function textChunk(content: string, final?: boolean, extras?: TextChunkExtras): StreamEventTextChunk;
+export declare function uiSpec(args: UiSpecEnvelope): StreamEventUISpec;
+export declare function action(payload: StreamEventAction['action']): StreamEventAction;
+export declare function error(code: string, message: string): StreamEventError;
+export declare function done(): StreamEventDone;
+export {};

package/dist/agentic/events/error-taxonomy.d.ts

@@ -0,0 +1,27 @@
+import type { StreamEventError } from '../../common/types.js';
+interface AgentErrorOptions {
+    source?: string;
+    sourceCode?: string;
+    detail?: unknown;
+}
+export declare class AgentError extends Error {
+    readonly code: string;
+    readonly source: string;
+    readonly sourceCode?: string;
+    readonly detail?: unknown;
+    constructor(code: string, message: string, options?: AgentErrorOptions);
+}
+interface BeErrorLike {
+    code?: unknown;
+    detail?: unknown;
+}
+export declare function beErrorToAgentError(beError: BeErrorLike | null | undefined): AgentError;
+interface HttpErrorBody {
+    error?: {
+        code?: unknown;
+        detail?: unknown;
+    };
+}
+export declare function httpErrorToAgentError(status: number, body: HttpErrorBody | null | undefined): AgentError;
+export declare function caughtToStreamError(caught: unknown): StreamEventError;
+export {};

package/dist/agentic/events/product-normalize.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Account-agnostic product normalization. Maps a wide variety of catalog
+ * shapes (Algolia hits, scraped JSON-LD, direct product feeds) into the
+ * minimal field set that FE's ProductCard / ProductDetailsPanel renderers
+ * consume. Used by the UI-spec builders.
+ */
+export interface NormalizedProduct {
+    sku: string;
+    name: string;
+    url: string;
+    imageUrl?: string;
+    images?: string[];
+    price?: string;
+    originalPrice?: string;
+    brand?: string;
+    rating?: number;
+    reviewCount?: number;
+    cartCode?: string;
+    inStock?: boolean;
+    categoryNames?: string[];
+}
+export interface TrimmedProductFacts {
+    sku: unknown;
+    name?: unknown;
+    url?: unknown;
+    price?: unknown;
+    currency?: unknown;
+    category?: unknown;
+    category_names?: unknown;
+    image?: unknown;
+    in_stock?: unknown;
+    rating?: unknown;
+    review_count?: unknown;
+}
+export declare function normalizeProduct(product: unknown): NormalizedProduct | null;
+/**
+ * Compact product facts for BE LLM-op evidence. Account-agnostic core —
+ * keeps fields aligned with BE's shared productSchema (sharedSchemas.ts)
+ * and drops merchant-internal noise (cart codes, group ids, full image
+ * arrays, internal flags). Account-specific trimmers can wrap this and
+ * add domain-specific facet fields (e.g. occasion, color) on top.
+ */
+export declare function trimProductFactsCore(product: unknown): unknown;
+export declare function trimProductFactsListCore(products: unknown): unknown[];
+export declare function firstString(...values: unknown[]): string;
+export declare function numberValue(value: unknown): number;
+export declare function stringList(value: unknown): string[];

package/dist/agentic/events/ui-specs.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Account-agnostic UI-spec builders for FE-facing StreamEvents.
+ *
+ * Account flows compose these to emit `ui_spec` events. They produce the
+ * generic `chat` widget envelope used across all merchants. Account-specific
+ * decoration (occasion-aware copy, brand-themed cards, etc.) belongs in
+ * the account folder, but the structural specs live here.
+ */
+import type { UiSpecEnvelope } from '../types.js';
+import { firstString, numberValue, stringList } from './product-normalize.js';
+interface ActionRequest {
+    title?: string;
+    type?: string;
+    payload?: unknown;
+}
+interface ActionEntry {
+    label?: string;
+    title?: string;
+    shortName?: string;
+    action?: ActionRequest;
+    requestDetails?: ActionRequest;
+    request_details?: ActionRequest;
+}
+interface ComparisonInput {
+    multiple_product_details?: unknown[];
+    products?: unknown[];
+    recommended_choice_sku?: string;
+    recommended_choice?: string;
+    table?: Record<string, unknown>;
+    key_differences?: unknown;
+    special_considerations?: unknown;
+}
+export declare function productsUiSpec(products?: unknown[]): UiSpecEnvelope;
+export declare function productDetailsUiSpec(product: unknown): UiSpecEnvelope;
+export declare function comparisonUiSpec(comparison?: ComparisonInput): UiSpecEnvelope;
+export declare function actionButtonsUiSpec(actions?: ActionEntry[]): UiSpecEnvelope;
+export { firstString, numberValue, stringList };

package/dist/agentic/flow/beauty-consulting-turn.d.ts

@@ -0,0 +1 @@
+export declare const beautyConsultingTurnFlow: import("../types.js").Flow;

package/dist/agentic/flow/create-flow.d.ts

@@ -0,0 +1,2 @@
+import type { Flow, FlowStep } from '../types.js';
+export declare function createFlow(steps: readonly FlowStep[]): Flow;

package/dist/agentic/flow/dispatch.d.ts

@@ -0,0 +1,3 @@
+import type { ProcessActionRequest } from '../../common/transport.js';
+import type { Flow } from '../types.js';
+export declare function resolveFlow(dispatch: Record<string, Flow | undefined>, request: ProcessActionRequest | null | undefined): Flow | undefined;

package/dist/agentic/index.d.ts

@@ -0,0 +1,18 @@
+export { createInjectorAdapter, createMainThreadInjectorAdapter } from './adaptor/create-adaptor.js';
+export { installFetchTransportBridge } from './adaptor/fetch-bridge.js';
+export { canUseModuleWorker, createModuleWorker, mountAccount } from './adaptor/mount.js';
+export { ContextStore } from './context/context-store.js';
+export { action, done, error, metadata, textChunk, uiSpec } from './events/builders.js';
+export { AgentError, beErrorToAgentError, caughtToStreamError, httpErrorToAgentError, } from './events/error-taxonomy.js';
+export { normalizeProduct, trimProductFactsCore, trimProductFactsListCore } from './events/product-normalize.js';
+export { actionButtonsUiSpec, comparisonUiSpec, productDetailsUiSpec, productsUiSpec } from './events/ui-specs.js';
+export { beautyConsultingTurnFlow } from './flow/beauty-consulting-turn.js';
+export { createFlow } from './flow/create-flow.js';
+export { resolveFlow } from './flow/dispatch.js';
+export { setAssistantHostVisible } from './util/assistant-host.js';
+export { resolveBeUrl } from './util/be-url.js';
+export { createBrowserMemory, stableKey } from './util/browser-memory.js';
+export { createDiagnosticsTool, createReadPageTool, installBrowserTools } from './util/browser-tools.js';
+export { startLazyRuntimeLoader } from './util/lazy-runtime-loader.js';
+export { requestText } from './util/request-text.js';
+export { elapsedMs, nowIso } from './util/time.js';