pybao-xc-sdk 1.5.51

package/README.md

@@ -0,0 +1,145 @@
+# @pyb/sdk
+
+PYB-CLI Server SDK for Web UI integration.
+
+## Installation
+
+```bash
+npm install @pyb/sdk
+# or
+bun add @pyb/sdk
+```
+
+## Usage
+
+### HTTP Client
+
+```typescript
+import { PybClient } from '@pyb/sdk'
+
+const client = new PybClient({
+  baseUrl: 'http://localhost:4096/v1',
+  timeout: 120000,
+})
+
+// Facade-first: create a session
+const session = await client.session.create({
+  config: {
+    model: 'claude-sonnet-4-20250514',
+  },
+})
+
+// Facade-first: send a prompt
+const response = await client.session.prompt(session.sessionId, {
+  message: 'Hello, how are you?',
+})
+
+// Facade-first: list sessions
+const { items } = await client.session.list({ status: 'active' })
+```
+
+### SSE Event Subscription
+
+```typescript
+import { createSSEClient } from '@pyb/sdk'
+
+const sse = createSSEClient({
+  baseUrl: 'http://localhost:4096/v1',
+})
+
+// Subscribe to specific events
+const unsub1 = sse.subscribe('message.created', (event) => {
+  console.log('New message:', event.data.message)
+})
+
+const unsub2 = sse.subscribe('tool.started', (event) => {
+  console.log('Tool started:', event.data.toolName)
+})
+
+// Subscribe to all events
+const unsub3 = sse.subscribeAll((event) => {
+  console.log('Event:', event.type)
+})
+
+// Connect
+sse.connect()
+
+// Later, clean up
+unsub1()
+unsub2()
+unsub3()
+sse.disconnect()
+```
+
+### Permission Handling
+
+```typescript
+import { createSSEClient, PybClient } from '@pyb/sdk'
+
+const client = new PybClient()
+const sse = createSSEClient()
+
+sse.subscribe('permission.requested', async (event) => {
+  const { permissionId, toolName, input, risk } = event.data
+
+  // Show permission dialog to user
+  const userDecision = await showPermissionDialog({
+    toolName,
+    input,
+    risk,
+  })
+
+  // Respond to server
+  await client.respondToPermission(permissionId, {
+    decision: userDecision.decision,
+    remember: userDecision.remember ? { scope: 'session' } : undefined,
+  })
+})
+
+sse.connect()
+```
+
+## API Reference
+
+### PybClient Facades
+
+| Facade | Methods |
+|--------|---------|
+| `client.session` | `create/list/get/update/delete/prompt/abort/messages` |
+| `client.mcp` | `list/connect/disconnect` |
+| `client.tool` | `list/execute` |
+| `client.config` | `get/update` |
+| `client` | `getHealth/respondToPermission/getPendingPermissions` |
+
+Legacy flat API remains temporarily for migration and maps to the facade methods above.
+
+### SSEClient
+
+| Method | Description |
+|--------|-------------|
+| `connect()` | Start SSE connection |
+| `disconnect()` | Close SSE connection |
+| `subscribe(eventType, callback)` | Subscribe to specific event |
+| `subscribeAll(callback)` | Subscribe to all events |
+| `isConnected()` | Check connection status |
+
+## Event Types
+
+| Event Type | Description |
+|------------|-------------|
+| `server.connected` | Server connection established |
+| `server.heartbeat` | Periodic heartbeat |
+| `session.created` | New session created |
+| `session.updated` | Session updated |
+| `message.created` | New message created |
+| `message.updated` | Message content updated |
+| `tool.started` | Tool execution started |
+| `tool.progress` | Tool execution progress |
+| `tool.completed` | Tool execution completed |
+| `permission.requested` | Permission confirmation needed |
+| `permission.responded` | Permission response received |
+| `error` | Error occurred |
+
+## License
+
+MIT