npm package: @mzhub/portal-server
Description: AI Portal Manager - Server-side LLM coordination for co-browsing
Latest version: 0.1.1

# @mzhub/portal-server

**AI Portal Manager** — Server-side LLM coordination for AI co-browsing.

## Installation

```bash
npm install @mzhub/portal-server socket.io
```

### Optional Dependencies

```bash
# LangChain tools
npm install @langchain/core zod
```

## Quick Start

```ts
import { PortalServer, createTools } from "@mzhub/portal-server";
import http from "http";
import express from "express";

const app = express();
const httpServer = http.createServer(app);

// Create portal server
const portal = new PortalServer({
  httpServer,
  session: { ttlMs: 30 * 60 * 1000 }, // 30 minutes
  debug: true,
});

// Handle new sessions
portal.on("session:created", (session) => {
  console.log("New session:", session.id);
  portal.startViewing(session.id);
});

// Handle DOM snapshots
portal.on("session:dom", (sessionId, snapshot) => {
  console.log("DOM received:", snapshot.url);

  // Create tools for this session
  const tools = createTools(portal, sessionId);

  // Validate and highlight an element
  const result = tools.highlight({
    selector: "#login-btn",
    message: "Click here to login",
  });

  console.log("Highlight result:", result);
});

// Handle handoff requests
portal.on("handoff:requested", (request) => {
  console.log("Human handoff requested:", request.reason);
  // Route to human support queue
});

httpServer.listen(3001);
```

## LangChain Integration

```ts
import { createPortalTools } from "@mzhub/portal-server/langchain";
import { ChatOpenAI } from "@langchain/openai";
import { AgentExecutor, createOpenAIFunctionsAgent } from "langchain/agents";

portal.on("session:dom", async (sessionId, snapshot) => {
  // Create LangChain-compatible tools
  const tools = await createPortalTools(portal, sessionId);

  const model = new ChatOpenAI({ model: "gpt-4" });

  // Use with agent
  const agent = await createOpenAIFunctionsAgent({
    llm: model,
    tools,
    prompt: yourPrompt,
  });

  const executor = new AgentExecutor({ agent, tools });
  await executor.invoke({ input: "Help me find the checkout button" });
});
```

## Generic Tools

Use with any LLM framework:

```ts
import { createTools } from "@mzhub/portal-server";

const tools = createTools(portal, sessionId);

// All tools return { success: boolean, data?: T, error?: string }
tools.highlight({ selector: "#btn", message: "Click here" });
tools.scrollTo({ selector: "#reviews" });
tools.fillForm({ selector: "#email", value: "user@example.com" });
tools.click({ selector: "#submit" });
tools.validateSelector({ selector: "#nonexistent" });
tools.handoffToHuman({ reason: "User requested human support" });
```

## Outcome-Based Tools

High-level tools for common scenarios:

```ts
import { createOutcomeTools } from "@mzhub/portal-server";

const outcomes = createOutcomeTools(portal, sessionId);

await outcomes.guideToCheckout(); // Finds and highlights checkout
await outcomes.guideToOrders(); // Finds order history
await outcomes.highlightProductFeatures();
await outcomes.showSearchBar();
await outcomes.guideToLogin();
await outcomes.guideToSupport();
```

## API Reference

### PortalServer

| Method                           | Description              |
| -------------------------------- | ------------------------ |
| `getSession(id)`                 | Get session by ID        |
| `getAllSessions()`               | Get all active sessions  |
| `destroySession(id, reason)`     | Terminate a session      |
| `sendCommand(id, command)`       | Send command to client   |
| `startViewing(id)`               | Start AI viewing mode    |
| `stopViewing(id)`                | Stop AI viewing mode     |
| `validateSelector(id, selector)` | Check if selector exists |
| `getSnapshot(id)`                | Get cached DOM snapshot  |
| `handoffToHuman(id, reason)`     | Request human support    |
| `getAuditLog(id)`                | Get session action log   |
| `shutdown()`                     | Graceful shutdown        |

### Events

| Event                  | Description             |
| ---------------------- | ----------------------- |
| `session:created`      | New session connected   |
| `session:destroyed`    | Session ended           |
| `session:dom`          | DOM snapshot received   |
| `session:scroll`       | User scrolled           |
| `session:focus`        | User focused element    |
| `session:networkError` | Network request failed  |
| `handoff:requested`    | Human support requested |
| `error`                | Socket error            |

## License

MIT