@pluno/product-agent-web 0.1.0

package/INTEGRATION.md

@@ -0,0 +1,95 @@
+# Product Agent Embed Integration
+
+## Architecture
+
+Product Agent embed has three layers:
+
+1. Customer backend exchanges an integration secret for a short-lived Pluno embed token.
+2. Customer frontend uses the token with the stack-agnostic browser SDK.
+3. Optional widget bundle renders a default chat UI on top of the SDK.
+
+The browser never receives the integration secret.
+
+## Customer Backend Token Endpoint
+
+The customer creates an authenticated endpoint in their own app, for example `/api/pluno-product-agent-token`.
+That endpoint calls Pluno:
+
+```http
+POST /api/product-agent/embed/token
+Content-Type: application/json
+
+{
+  "public_key": "pa_pk_...",
+  "secret_key": "pa_sk_...",
+  "origin": "https://app.customer.com",
+  "metadata": {
+    "user_id": "customer-user-id",
+    "email": "user@customer.com",
+    "name": "User Name",
+    "plan": "enterprise"
+  }
+}
+```
+
+Pluno returns:
+
+```json
+{
+  "token": "...",
+  "expiresAt": "2026-05-14T12:00:00+00:00"
+}
+```
+
+## Headless Browser SDK
+
+```ts
+import { PlunoProductAgent } from "@pluno/product-agent-web";
+
+const agent = await PlunoProductAgent.init({
+  tokenProvider: async () => {
+    const response = await fetch("/api/pluno-product-agent-token", {
+      method: "POST",
+      credentials: "include",
+    });
+    return (await response.json()).token;
+  },
+});
+```
+
+Network capture is always enabled. The SDK sends captured request/response metadata and bodies using the built-in
+redaction pipeline before data leaves the browser.
+
+## Default Widget
+
+```html
+<script
+  type="module"
+  src="https://cdn.pluno.ai/product-agent/product-agent-widget.js"
+  data-pluno-token-endpoint="/api/pluno-product-agent-token"
+  data-pluno-launcher-label="Ask AI..."
+  data-pluno-accent-color="#18181b"
+  data-pluno-color-scheme="light"
+  data-pluno-position="bottom-right"
+></script>
+```
+
+Supported widget script-tag attributes:
+
+- `data-pluno-token-endpoint`
+- optional `data-pluno-token`
+- optional `data-pluno-backend-url`
+- optional `data-pluno-launcher-label`
+- optional `data-pluno-accent-color`
+- optional `data-pluno-color-scheme`
+- optional `data-pluno-position`
+- optional `data-pluno-auto-mount="false"`
+
+## Security Decisions
+
+- Integration secrets are backend-only.
+- Embed tokens are short-lived Pluno-signed JWTs.
+- The runtime validates the token origin against the integration allowlist.
+- The runtime validates the browser WebSocket `Origin` header against the token origin.
+- Network capture is always installed by the SDK/widget. There is intentionally no configuration or opt-out for now.
+- Browser-side redaction runs before network events and tool results are sent to Pluno.

package/README.md

@@ -0,0 +1,56 @@
+# Pluno Product Agent Web SDK
+
+Stack-agnostic browser SDK and default widget for embedding Product Agent into customer webapps.
+
+## Install
+
+```bash
+npm install @pluno/product-agent-web
+```
+
+Keep your Product Agent `secret_key` on your server. Browser code should only receive a short-lived session `token`, or call your own authenticated token endpoint.
+
+## Headless SDK
+
+```ts
+import { PlunoProductAgent } from "@pluno/product-agent-web";
+
+const agent = await PlunoProductAgent.init({
+  tokenProvider: async () => {
+    const response = await fetch("/api/pluno-product-agent-token", {
+      method: "POST",
+      credentials: "include",
+    });
+    const payload = await response.json();
+    return payload.token;
+  },
+});
+
+agent.on("state", (state) => {
+  renderYourOwnChatUi(state);
+});
+
+agent.sendMessage("Update my settings");
+```
+
+The SDK always captures product network activity by patching `fetch` and `XMLHttpRequest`. There is intentionally no opt-out for now.
+
+## Drop-In Widget
+
+```html
+<script
+  type="module"
+  src="https://cdn.pluno.ai/product-agent/product-agent-widget.js"
+  data-pluno-token-endpoint="/api/pluno-product-agent-token"
+  data-pluno-launcher-label="Ask AI..."
+  data-pluno-accent-color="#18181b"
+></script>
+```
+
+The token endpoint must be implemented by the customer backend. It should authenticate the current user, then call Pluno&apos;s `/api/product-agent/embed/token` endpoint with:
+
+- `public_key`
+- `secret_key`
+- `origin`
+- optional `metadata`, including `metadata.user_id` when the customer has a stable user id
+- optional `context`

package/dist/index.d.ts

@@ -0,0 +1,95 @@
+export type ProductAgentModel = "gpt-5.4-nano" | "gpt-5.4-mini" | "gpt-5.4";
+export type ProductAgentUser = {
+    id: string;
+    email?: string | null;
+    name?: string | null;
+    avatarUrl?: string | null;
+};
+export type ProductAgentPage = {
+    url: string;
+    title: string;
+    origin: string;
+};
+export type ProductAgentMessage = {
+    id: string;
+    role: "user" | "assistant" | "tool" | "system";
+    content: string;
+    createdAt: string;
+    dataType?: string;
+    loading?: boolean;
+};
+export type ProductAgentState = {
+    status: "idle" | "connecting" | "connected" | "reconnecting" | "closed" | "error";
+    user: ProductAgentUser | null;
+    sessionId: string | null;
+    messages: ProductAgentMessage[];
+    assistantDraft: string;
+    isThinking: boolean;
+    lastError: string | null;
+};
+export type ProductAgentInitOptions = {
+    token?: string;
+    tokenProvider?: () => Promise<string>;
+    backendUrl?: string;
+    model?: ProductAgentModel;
+    clientId?: string;
+    metadata?: Record<string, unknown>;
+    autoConnect?: boolean;
+    webSocketFactory?: ProductAgentWebSocketFactory;
+};
+export type ProductAgentWebSocket = {
+    readyState: number;
+    addEventListener(type: string, listener: (event: any) => void): void;
+    send(data: string): void;
+    close(): void;
+};
+export type ProductAgentWebSocketFactory = (url: string) => ProductAgentWebSocket;
+export type ProductAgentEventMap = {
+    state: ProductAgentState;
+    message: ProductAgentMessage;
+    delta: string;
+    error: Error;
+};
+type EventName = keyof ProductAgentEventMap;
+type Listener<T extends EventName> = (payload: ProductAgentEventMap[T]) => void;
+export declare class PlunoProductAgent {
+    private readonly options;
+    private readonly listeners;
+    private socket;
+    private reconnectTimer;
+    private heartbeatTimer;
+    private token;
+    private networkCaptureCleanup;
+    private networkBatchTimer;
+    private queuedNetworkEvents;
+    private queuedClientEvents;
+    private state;
+    private constructor();
+    static init(options: ProductAgentInitOptions): Promise<PlunoProductAgent>;
+    on<T extends EventName>(eventName: T, listener: Listener<T>): () => void;
+    getState(): ProductAgentState;
+    connect(): Promise<void>;
+    disconnect(): void;
+    destroy(): void;
+    sendMessage(content: string): void;
+    stop(): void;
+    startNewSession(): void;
+    private send;
+    private sendNow;
+    private flushQueuedClientEvents;
+    private handleServerEvent;
+    private executeToolCall;
+    private enableNetworkCapture;
+    private enqueueNetworkEvent;
+    private scheduleReconnect;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private setState;
+    private emit;
+}
+declare global {
+    interface Window {
+        __plunoProductAgentInstance?: PlunoProductAgent;
+    }
+}
+export default PlunoProductAgent;