@tung-engineering/agent-platform-web-sdk 0.0.78 → 0.0.81

package/README.md

@@ -0,0 +1,132 @@
+# @tung-engineering/agent-platform-web-sdk
+
+Embeddable Web SDK for [Agent Platform](https://agent-platform.tung.engineering). Drop it into any web page to get a floating capture button that turns any element — or any recorded click-through flow — into an Agent Platform task or planning session, without leaving the page you're looking at.
+
+- 🖱️ **Element picker** — click the capture button, then click any element on the page to attach it (with surrounding DOM context) to a new task or planning session
+- ⏺️ **Interaction recorder** — record a multi-step click-through flow and turn the whole sequence into a browser-automation task
+- 🤖 **Automation runner** — a floating panel that streams a running task's browser actions live, with per-step approve/answer prompts when the agent needs input
+- 📋 **Captures list** — a running list of everything captured from the current browser, with unread/status badges
+- 🔒 **Secure by design** — connects via a short-lived, OAuth2-style token exchange; your long-lived Agent Platform API token is never entered into or stored by the SDK
+
+## Installation
+
+```bash
+npm install @tung-engineering/agent-platform-web-sdk
+```
+
+Node.js is only used to install the package — the SDK itself is a browser-only, zero-dependency-at-runtime bundle (its few dependencies are bundled in).
+
+## Quick start (npm package)
+
+**1. Import and initialize.** `init()` needs your project's short code and, to actually connect to a backend, a `backendUrl` + short-lived `token` (see [Getting a token](#getting-a-token) below — you can skip both and use the built-in connect UI instead, see step 3).
+
+```ts
+import { init } from '@tung-engineering/agent-platform-web-sdk';
+
+await init({
+  projectCode: 'YOUR_PROJECT_CODE',
+  backendUrl: 'https://your-agent-platform-instance.example.com',
+  token: sdkToken, // short-lived SDK token, see "Getting a token"
+});
+```
+
+This injects the SDK's styles and shows a floating capture button (FAB) in the bottom-right corner of the page.
+
+**2. Use the picker.** Click the FAB, then click any element on the page — a capture panel opens letting you turn that element into a task or planning session in your Agent Platform project. This also works from your own code:
+
+```ts
+import { activateElementPicker } from '@tung-engineering/agent-platform-web-sdk';
+
+activateElementPicker(); // same as clicking the FAB yourself
+```
+
+**3. Or skip the token exchange — use the built-in connect UI.** If you don't already have a short-lived token (e.g. building an internal tool, not shipping a hardcoded token to end users), call `configure()` instead of `init()`. It opens a small panel where the user enters your backend URL, signs in via a popup, and picks a project — the SDK stores the resulting short-lived token in `sessionStorage` and initializes itself:
+
+```ts
+import { configure } from '@tung-engineering/agent-platform-web-sdk';
+
+configure(); // opens the "Connect to Agent Platform" panel
+```
+
+**4. Clean up when you're done** (e.g. on route change in an SPA):
+
+```ts
+import { destroy } from '@tung-engineering/agent-platform-web-sdk';
+
+destroy(); // removes the FAB, closes any open panels, tears down listeners
+```
+
+## Quick start (script tag, no build step)
+
+You can also load the SDK directly from your Agent Platform backend without installing anything:
+
+```html
+<script src="https://your-agent-platform-instance.example.com/web-sdk/web-sdk.min.js"></script>
+```
+
+This self-boots: it looks for a saved connection in `sessionStorage` and either restores it (showing a ready-to-use FAB) or shows the FAB in "click to connect" mode. Once loaded, the same API is available on `window.AgentPlatformWebSdk`:
+
+```html
+<script>
+  // Open the connect panel (same flow as configure() above)
+  AgentPlatformWebSdk.configure();
+
+  // Or connect programmatically with a token obtained out-of-band
+  AgentPlatformWebSdk.init({
+    projectCode: 'YOUR_PROJECT_CODE',
+    backendUrl: 'https://your-agent-platform-instance.example.com',
+    token: sdkToken,
+  });
+</script>
+```
+
+## Getting a token
+
+The SDK never accepts or stores a long-lived personal API token. There are two ways to get the short-lived token `init()` expects:
+
+1. **Interactive (recommended for most integrations)** — call `configure()` / `AgentPlatformWebSdk.configure()`. It opens a popup to your Agent Platform instance's own sign-in/consent screen, receives a single-use authorization code via `postMessage`, and exchanges it for a short-lived SDK token automatically. Nothing to implement on your end.
+2. **Out-of-band (for pre-authenticated embeds)** — have your own backend perform the same authorization-code exchange (`POST /auth/tokens/exchange-code` on your Agent Platform instance) and pass the resulting token straight into `init({ token })`.
+
+Either way, the token is short-lived and is only ever persisted to `sessionStorage` — closing the browser/tab always requires reconnecting.
+
+## API reference
+
+| Export | Description |
+|---|---|
+| `init(options: SdkOptions): Promise<void>` | Initializes the SDK and shows the FAB. Safe to call again with the same options (no-op). |
+| `updateCredentials(backendUrl: string, token: string): Promise<void>` | Swaps the backend URL / token on an already-initialized SDK (e.g. after a token refresh). |
+| `configure(): void` | Opens the built-in "Connect to Agent Platform" panel; saves the result and calls `init()` for you. |
+| `clearConfig(): void` | Clears saved credentials from `sessionStorage` and tears down the SDK back to setup mode. |
+| `activateElementPicker(): void` / `deactivateElementPicker(): void` | Starts/stops the element picker without clicking the FAB. |
+| `isPickerRunning(): boolean` | Whether the element picker is currently active. |
+| `showFab(): void` / `hideFab(): void` | Show/hide the floating buttons without tearing down the rest of the SDK. |
+| `destroy(): void` | Fully tears down the SDK: removes the FAB, closes any open panel, stops all listeners. |
+| `autoInit(): void` | Runs automatically when the script-tag bundle is loaded; not meant to be called from the npm import. |
+
+`SdkOptions`:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `projectCode` | `string` | yes | Short, human-readable project code (e.g. `"AP"`). |
+| `backendUrl` | `string` | no | Base URL of your Agent Platform backend. Omit to boot in "click to connect" mode. |
+| `token` | `string` | no | Short-lived SDK token (see [Getting a token](#getting-a-token)). Omit to boot in "click to connect" mode. |
+
+## TypeScript
+
+Type declarations ship with the package — no `@types/...` package needed.
+
+```ts
+import { init, type SdkOptions } from '@tung-engineering/agent-platform-web-sdk';
+
+const options: SdkOptions = {
+  projectCode: 'YOUR_PROJECT_CODE',
+  backendUrl: 'https://your-agent-platform-instance.example.com',
+  token: sdkToken,
+};
+
+await init(options);
+```
+
+## Browser support
+
+The SDK is browser-only — it reads `window`/`document`/`sessionStorage`/`localStorage` at call time and is a no-op in non-browser environments (safe to import in an SSR/isomorphic build; just don't call `init()`/`configure()` on the server).