@lifebyte-systems-sa/wuyong-client 0.1.3

package/README.md

@@ -0,0 +1,129 @@
+# @lifebyte-systems-sa/wuyong-client
+
+TypeScript client for the Wuyong Orchestrator `/chat` API.
+
+The SDK is framework-agnostic and works with any frontend that can provide:
+
+- an Auth0 access token
+- one or more selected trading logins
+- a Wuyong Orchestrator base URL
+
+## Install
+
+From this monorepo workspace:
+
+```bash
+npm install
+npm test --workspace @lifebyte-systems-sa/wuyong-client
+npm run build --workspace @lifebyte-systems-sa/wuyong-client
+```
+
+In a frontend application, install the public package from the npm registry:
+
+```bash
+npm install @lifebyte-systems-sa/wuyong-client
+```
+
+```ts
+import { WuyongClient, WuyongError } from "@lifebyte-systems-sa/wuyong-client";
+```
+
+## Basic usage
+
+```ts
+const client = new WuyongClient({
+  baseUrl: "https://orchestrator-sa.example.com",
+  getAccessToken: () => getAccessTokenSilently(),
+  getLogins: () => selectedTradingLogins,
+});
+
+const result = await client.chat({
+  threadId: "conversation-123",
+  message: "我的账户现在风险怎么样？",
+});
+
+console.log(result.answer);
+```
+
+The SDK sends:
+
+- `POST /chat`
+- `Authorization: Bearer <Auth0 JWT>`
+- `x-wuyong-logins: 100003,100004`
+- `mode: "member"`
+- `capability: "readonly"`
+
+## Auth0
+
+`getAccessToken` should return an Auth0 JWT that the Orchestrator can validate.
+
+The token should include `user_id` or `sub`. If Member Portal tools are needed, it should also include:
+
+```json
+{
+  "app_metadata": {
+    "php_access_token": "<member-portal-token>"
+  }
+}
+```
+
+Do not expose or send `php_refresh_token` to Wuyong.
+
+## Trading logins
+
+`getLogins` returns the selected trading account logins:
+
+```ts
+getLogins: () => [100003]
+```
+
+Multiple logins are sent as a comma-separated `x-wuyong-logins` header.
+
+If no logins are available, `client.chat()` throws:
+
+```ts
+WuyongError { code: "MISSING_LOGINS" }
+```
+
+## Error handling
+
+```ts
+try {
+  const result = await client.chat({ threadId, message });
+  renderAnswer(result.answer);
+} catch (error) {
+  if (error instanceof WuyongError) {
+    switch (error.code) {
+      case "AUTH_REQUIRED":
+        loginWithRedirect();
+        break;
+      case "MISSING_LOGINS":
+        showAccountPicker();
+        break;
+      case "INVALID_REQUEST":
+        showValidationError(error.details);
+        break;
+      case "SERVER_ERROR":
+      case "NETWORK_ERROR":
+        showRetryMessage();
+        break;
+    }
+  }
+}
+```
+
+## Response
+
+`client.chat()` returns:
+
+```ts
+type ChatResponse = {
+  answer: string;
+  facts: Record<string, Fact>;
+  audit_events: AuditEvent[];
+  ui_events: UiEvent[];
+  tool_calls: string[];
+};
+```
+
+Use `answer` for the user-visible response. Use `facts`, `tool_calls`, and `audit_events` for traceability/debug views.

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+export type WuyongErrorCode = "AUTH_REQUIRED" | "INVALID_REQUEST" | "SERVER_ERROR" | "MISSING_LOGINS" | "NETWORK_ERROR";
+export interface WuyongClientOptions {
+    baseUrl: string;
+    getAccessToken: () => Promise<string> | string;
+    getLogins: () => Promise<number[]> | number[];
+    fetch?: typeof fetch;
+}
+export interface ChatRequest {
+    threadId: string;
+    message: string;
+}
+export interface Fact {
+    key: string;
+    value: Record<string, unknown>;
+    source_tool: string;
+    source_mcp_server: string;
+    ttl_seconds: number;
+    ts: string;
+    [key: string]: unknown;
+}
+export interface AuditEvent {
+    agent: string;
+    action: string;
+    outcome: string;
+    [key: string]: unknown;
+}
+export interface UiEvent {
+    type?: string;
+    [key: string]: unknown;
+}
+export interface ChatResponse {
+    answer: string;
+    facts: Record<string, Fact>;
+    audit_events: AuditEvent[];
+    ui_events: UiEvent[];
+    tool_calls: string[];
+}
+export declare class WuyongError extends Error {
+    readonly code: WuyongErrorCode;
+    readonly status?: number;
+    readonly details?: string;
+    constructor(code: WuyongErrorCode, message: string, options?: {
+        status?: number;
+        details?: string;
+    });
+}
+export declare class WuyongClient {
+    private readonly baseUrl;
+    private readonly getAccessToken;
+    private readonly getLogins;
+    private readonly fetchImpl;
+    constructor(options: WuyongClientOptions);
+    chat(request: ChatRequest): Promise<ChatResponse>;
+    private errorFromResponse;
+}

package/dist/index.js

@@ -0,0 +1,75 @@
+export class WuyongError extends Error {
+    code;
+    status;
+    details;
+    constructor(code, message, options = {}) {
+        super(message);
+        this.name = "WuyongError";
+        this.code = code;
+        this.status = options.status;
+        this.details = options.details;
+    }
+}
+export class WuyongClient {
+    baseUrl;
+    getAccessToken;
+    getLogins;
+    fetchImpl;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.getAccessToken = options.getAccessToken;
+        this.getLogins = options.getLogins;
+        this.fetchImpl = options.fetch ?? fetch;
+    }
+    async chat(request) {
+        const [token, logins] = await Promise.all([this.getAccessToken(), this.getLogins()]);
+        if (!logins.length) {
+            throw new WuyongError("MISSING_LOGINS", "At least one trading login is required.");
+        }
+        let response;
+        try {
+            response = await this.fetchImpl(`${this.baseUrl}/chat`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${token}`,
+                    "x-wuyong-logins": logins.join(","),
+                },
+                body: JSON.stringify({
+                    thread_id: request.threadId,
+                    mode: "member",
+                    capability: "readonly",
+                    message: request.message,
+                }),
+            });
+        }
+        catch (error) {
+            throw new WuyongError("NETWORK_ERROR", "Unable to reach Wuyong Orchestrator.", {
+                details: error instanceof Error ? error.message : String(error),
+            });
+        }
+        if (!response.ok) {
+            throw await this.errorFromResponse(response);
+        }
+        return (await response.json());
+    }
+    async errorFromResponse(response) {
+        const details = await response.text();
+        if (response.status === 401) {
+            return new WuyongError("AUTH_REQUIRED", "Authentication is required.", {
+                status: response.status,
+                details,
+            });
+        }
+        if (response.status === 422) {
+            return new WuyongError("INVALID_REQUEST", "The Wuyong request is invalid.", {
+                status: response.status,
+                details,
+            });
+        }
+        return new WuyongError("SERVER_ERROR", "Wuyong Orchestrator returned an error.", {
+            status: response.status,
+            details,
+        });
+    }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@lifebyte-systems-sa/wuyong-client",
+  "version": "0.1.3",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lifebyte-systems-sa/ai-routers.git",
+    "directory": "packages/wuyong-client"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.8"
+  }
+}