@cf-vibesdk/sdk 0.0.4 → 0.0.5

package/README.md

@@ -1,140 +1,354 @@
 # @cf-vibesdk/sdk
 
-Client SDK for the VibeSDK platform.
+Official TypeScript SDK for the VibeSDK platform - build and deploy fullstack apps with AI.
 
-## Install
+## Compatibility
+
+Works in any JavaScript runtime with native WebSocket support:
+
+| Runtime | Support |
+|---------|---------|
+| Cloudflare Workers | Native WebSocket |
+| Browsers | Native WebSocket |
+| Bun | Native WebSocket |
+| Node.js 22+ | Native WebSocket |
+
+## Installation
 
 ```bash
 npm install @cf-vibesdk/sdk
 ```
 
-## Quickstart (Bun)
+## Quick Start
 
 ```ts
 import { PhasicClient } from '@cf-vibesdk/sdk';
 
 const client = new PhasicClient({
-  baseUrl: 'http://localhost:5173',
+  baseUrl: 'https://build.cloudflare.dev',
   apiKey: process.env.VIBESDK_API_KEY!,
 });
 
-const session = await client.build('Build a simple hello world page.', {
-  projectType: 'app',
-  autoGenerate: true,
-});
+// Build a new app
+const session = await client.build('Build a todo app with React');
 
-// High-level lifecycle waits
-await session.wait.generationStarted();
+// Wait until deployable and deploy
 await session.wait.deployable();
-
-// Preview deployment (command + awaitable)
-const previewWait = session.wait.previewDeployed();
 session.deployPreview();
-const deployed = await previewWait;
+const preview = await session.wait.previewDeployed();
 
-console.log('Preview URL:', deployed.previewURL);
-
-// Workspace is always kept in sync from agent state + WS events
-console.log(session.files.listPaths());
-console.log(session.files.read('README.md'));
+console.log('Preview URL:', preview.previewURL);
+console.log('Files:', session.files.listPaths());
 
 session.close();
 ```
 
-## Quickstart (Node)
+## Authentication
 
-Node requires a WebSocket factory (the browser `WebSocket` global is not available):
+| Method | Use Case |
+|--------|----------|
+| `apiKey` | Recommended. Automatically exchanged for a short-lived JWT. |
+| `token` | Use when you already have a JWT access token. |
 
 ```ts
-import { PhasicClient } from '@cf-vibesdk/sdk';
-import { createNodeWebSocketFactory } from '@cf-vibesdk/sdk/node';
+// Using API key (recommended)
+const client = new PhasicClient({
+  baseUrl: 'https://build.cloudflare.dev',
+  apiKey: 'vibe_xxxxxxxxxxxx',
+});
 
+// Using pre-minted JWT
 const client = new PhasicClient({
-  baseUrl: 'http://localhost:5173',
-  apiKey: process.env.VIBESDK_API_KEY!,
-  webSocketFactory: createNodeWebSocketFactory(),
+  baseUrl: 'https://build.cloudflare.dev',
+  token: 'eyJhbGciOiJIUzI1NiIs...',
 });
+```
+
+## Clients
+
+| Client | Default Behavior |
+|--------|------------------|
+| `VibeClient` | No default - specify `behaviorType` in build options |
+| `PhasicClient` | `behaviorType: 'phasic'` (phase-based generation) |
+| `AgenticClient` | `behaviorType: 'agentic'` (autonomous agent) |
+
+All clients share the same API. The specialized clients simply set a default `behaviorType`.
 
-const session = await client.build('Build a simple hello world page.', {
-  projectType: 'app',
-  autoGenerate: true,
+## Building Apps
+
+### `client.build(prompt, options?)`
+
+Create a new app from a natural language prompt.
+
+```ts
+const session = await client.build('Build a weather dashboard', {
+  projectType: 'app',           // 'app' | 'component' | 'api'
+  behaviorType: 'phasic',       // 'phasic' | 'agentic'
+  language: 'typescript',       // Optional
+  frameworks: ['react'],        // Optional
+  selectedTemplate: 'vite',     // Optional template name
+  autoConnect: true,            // Auto-connect WebSocket (default: true)
+  autoGenerate: true,           // Auto-start generation (default: true)
+  credentials: { ... },         // Optional provider API keys
+  onBlueprintChunk: (chunk) => console.log(chunk),
 });
+```
 
-await session.wait.generationStarted();
-await session.wait.deployable();
-session.close();
+### `client.connect(agentId)`
+
+Connect to an existing app session.
+
+```ts
+const session = await client.connect('agent-id-here', {
+  credentials: { ... },  // Optional
+});
+await session.connect();
 ```
 
-## Authentication
+## App Management
 
-Use either:
+```ts
+// List apps
+const publicApps = await client.apps.listPublic({ limit: 20, sort: 'recent' });
+const myApps = await client.apps.listMine();
+const recent = await client.apps.listRecent();
+const favorites = await client.apps.listFavorites();
+
+// Get app details
+const app = await client.apps.get('app-id');
+
+// Manage apps
+await client.apps.delete('app-id');
+await client.apps.setVisibility('app-id', 'public'); // 'public' | 'private'
+await client.apps.toggleStar('app-id');
+await client.apps.toggleFavorite('app-id');
+
+// Git clone token
+const { cloneUrl, expiresAt } = await client.apps.getGitCloneToken('app-id');
+```
 
-- `apiKey`: a VibeSDK API key (recommended for CLIs and automation)
-- `token`: an already-minted JWT access token
+## BuildSession
 
-When `apiKey` is provided, the SDK exchanges it for a short-lived access token and caches it.
+The `BuildSession` object provides real-time interaction with code generation.
 
-## Workspace (no platform file APIs)
+### Properties
 
-The SDK reconstructs and maintains a local view of the codebase using:
+| Property | Description |
+|----------|-------------|
+| `agentId` | Unique identifier for this session |
+| `behaviorType` | `'phasic'` or `'agentic'` |
+| `projectType` | Type of project being built |
 
-- `agent_connected.state.generatedFilesMap`
-- `cf_agent_state.state.generatedFilesMap`
-- incremental `file_*` messages
+### Commands
 
-APIs:
+```ts
+session.startGeneration();      // Start code generation
+session.stop();                 // Stop generation
+session.resume();               // Resume generation
+session.deployPreview();        // Deploy to preview environment
+session.deployCloudflare();     // Deploy to Cloudflare Workers
+session.clearConversation();    // Clear conversation history
+session.close();                // Close the session
+
+// Send follow-up message
+session.followUp('Add dark mode support', {
+  images: [{ base64: '...', mimeType: 'image/png' }],  // Optional
+});
+```
 
-- `session.files.listPaths()`
-- `session.files.read(path)`
-- `session.files.snapshot()`
-- `session.files.tree()`
+### Wait Helpers
 
-## Waiting primitives
+High-level async waits for generation milestones:
 
-Use high-level waits instead of depending on agent-internal message ordering:
+```ts
+// Generation lifecycle
+await session.wait.generationStarted({ timeoutMs: 60_000 });
+await session.wait.generationComplete({ timeoutMs: 600_000 });
 
-- `session.wait.generationStarted()`
-- `session.wait.generationComplete()`
-- `session.wait.deployable()` (phasic resolves on `phase_validated`)
-- `session.wait.previewDeployed()`
-- `session.wait.cloudflareDeployed()`
+// Phase events (phasic mode)
+await session.wait.phase({ type: 'phase_validated' });
 
-All waits default to a long timeout (10 minutes). You can override per call:
+// Deployment readiness
+const { files, reason } = await session.wait.deployable();
+
+// Deployment completion
+const preview = await session.wait.previewDeployed();
+console.log(preview.previewURL);
+
+const cf = await session.wait.cloudflareDeployed();
+console.log(cf.deploymentUrl);
+```
+
+### Events
 
 ```ts
-await session.wait.generationComplete({ timeoutMs: 2 * 60_000 });
+// High-level events
+session.on('connected', (msg) => { ... });
+session.on('generation', (msg) => { ... });  // started, complete, stopped, resumed
+session.on('phase', (msg) => { ... });       // generating, generated, implementing, etc.
+session.on('file', (msg) => { ... });        // generating, generated, regenerated
+session.on('preview', (msg) => { ... });     // started, completed, failed
+session.on('cloudflare', (msg) => { ... });  // started, completed, error
+session.on('error', ({ error }) => { ... });
+
+// WebSocket events
+session.on('ws:open', () => { ... });
+session.on('ws:close', ({ code, reason }) => { ... });
+session.on('ws:error', ({ error }) => { ... });
+session.on('ws:reconnecting', ({ attempt, delayMs }) => { ... });
+
+// Listen to specific message type
+session.onMessageType('file_generated', (msg) => {
+  console.log('Generated:', msg.file.filePath);
+});
+
+// Wait for specific message
+const msg = await session.waitForMessageType('generation_complete', 60_000);
 ```
 
-## Reliable WebSocket connections
+### File Access
 
-Connections automatically reconnect with exponential backoff + jitter.
+```ts
+const paths = session.files.listPaths();        // ['src/App.tsx', ...]
+const content = session.files.read('src/App.tsx');
+const snapshot = session.files.snapshot();      // { 'src/App.tsx': '...', ... }
+const tree = session.files.tree();              // Nested file tree structure
+```
+
+### State
+
+```ts
+// Current state
+const state = session.state.get();
+console.log(state.connection);  // 'disconnected' | 'connecting' | 'connected'
+console.log(state.generation);  // { status: 'idle' | 'running' | 'stopped' | 'complete', ... }
+console.log(state.phase);       // { status: 'idle' | 'generating' | ... }
+console.log(state.preview);     // Preview deployment state
+console.log(state.cloudflare);  // Cloudflare deployment state
+
+// Subscribe to changes
+session.state.onChange((next, prev) => {
+  console.log('State changed:', next);
+});
+
+// Workspace file changes
+session.workspace.onChange((change) => {
+  console.log(change.type, change.path); // 'upsert' | 'delete' | 'reset'
+});
+```
+
+## WebSocket Reliability
+
+Connections automatically reconnect with exponential backoff.
+
+```ts
+// Custom retry config
+await session.connect({
+  retry: {
+    enabled: true,        // Default: true
+    initialDelayMs: 1000, // Default: 1000
+    maxDelayMs: 30000,    // Default: 30000
+    maxRetries: 10,       // Default: Infinity
+  },
+});
+
+// Disable auto-reconnect
+await session.connect({ retry: { enabled: false } });
+```
+
+## HTTP Retry
+
+HTTP requests automatically retry on 5xx errors.
+
+```ts
+const client = new PhasicClient({
+  baseUrl: 'https://build.cloudflare.dev',
+  apiKey: 'vibe_xxx',
+  retry: {
+    enabled: true,        // Default: true
+    initialDelayMs: 1000, // Default: 1000
+    maxDelayMs: 10000,    // Default: 10000
+    maxRetries: 3,        // Default: 3
+  },
+});
+```
+
+## Utilities
 
-Events:
+### Blueprint Parsing
 
-- `session.on('ws:reconnecting', ({ attempt, delayMs, reason }) => { ... })`
+```ts
+import { BlueprintStreamParser, blueprintToMarkdown } from '@cf-vibesdk/sdk';
+
+// Parse streaming blueprint chunks
+const parser = new BlueprintStreamParser();
+parser.append(chunk1);
+parser.append(chunk2);
+const markdown = parser.toMarkdown();
 
-To disable reconnect:
+// Convert blueprint object to markdown
+const md = blueprintToMarkdown(blueprint);
+```
+
+### Timeout Helper
 
 ```ts
-session.connect({ retry: { enabled: false } });
+import { withTimeout, TimeoutError } from '@cf-vibesdk/sdk';
+
+try {
+  const result = await withTimeout(someAsyncOperation(), 30000, 'Operation timed out');
+} catch (e) {
+  if (e instanceof TimeoutError) {
+    console.log('Timed out!');
+  }
+}
 ```
 
-## Low-level access
+## Error Handling
 
-For advanced clients, you can subscribe to the raw typed WS stream:
+All API methods return an `ApiResponse<T>` discriminated union:
 
-- `session.on('ws:message', (msg) => { ... })`
+```ts
+const result = await client.apps.get('app-id');
 
-The SDK also exposes `ws:raw` when the platform sends malformed/untyped payloads.
+if (result.success) {
+  console.log(result.data);
+} else {
+  console.error(result.error.message);
+}
+```
+
+## TypeScript
+
+All types are exported:
 
-## Tests
+```ts
+import type {
+  VibeClientOptions,
+  BuildOptions,
+  BuildSession,
+  SessionState,
+  ApiResponse,
+  AppDetails,
+  Credentials,
+  BehaviorType,
+  ProjectType,
+  // ... and more
+} from '@cf-vibesdk/sdk';
+```
 
-From `sdk/`:
+## Testing
 
-- Unit: `bun run test`
-- Integration (requires local platform + API key): `bun run test:integration`
+```bash
+cd sdk
+
+# Unit tests
+bun test
+
+# Integration tests (requires API key)
+VIBESDK_INTEGRATION_API_KEY=your_key bun run test:integration
+```
 
-Integration expects:
+## License
 
-- `VIBESDK_INTEGRATION_API_KEY`
-- optional `VIBESDK_INTEGRATION_BASE_URL` (default `http://localhost:5173`)
+MIT