@ziggy-ai/client-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ziggy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,395 @@
+# @ziggy-ai/client-sdk
+
+TypeScript SDK for integrating host applications with Ziggy's v1 API.
+
+## Install
+
+```bash
+npm install @ziggy-ai/client-sdk
+```
+
+## Quick Start
+
+```typescript
+import { ZiggyClient } from '@ziggy-ai/client-sdk';
+
+const ziggy = new ZiggyClient({
+  baseUrl: 'https://ziggy.example.com',
+  appId: 'my-app',
+  apiKey: 'pk_live_abc123',
+});
+
+// Connect (creates session, starts context batching + analytics)
+const session = await ziggy.connect({
+  userId: 'user-1',
+  context: {
+    page: { path: '/dashboard', type: 'dashboard', title: 'Dashboard' },
+    user: { id: 'user-1', tier: 'pro', sessionCount: 42 },
+  },
+  onTrigger: (response) => {
+    if (response.trigger) showProactiveBubble(response.trigger);
+  },
+});
+
+// Streaming chat
+for await (const event of ziggy.chat.stream({ message: 'Why did my transform fail?' })) {
+  switch (event.type) {
+    case 'content.delta': appendToUI(event.content); break;
+    case 'tool.start': showToolIndicator(event.toolName); break;
+    case 'metadata': renderActions(event.quickActions); break;
+  }
+}
+
+// Disconnect (flushes analytics, stops batching, ends session)
+await ziggy.disconnect();
+```
+
+## API
+
+### ZiggyClient
+
+The main entry point. Composes specialized sub-clients for each API area.
+
+```typescript
+const ziggy = new ZiggyClient({
+  baseUrl: string;   // Ziggy API base URL
+  appId: string;     // Your app identifier
+  apiKey: string;    // API key (from App node in Ziggy)
+  timeout?: number;  // Request timeout in ms (default: 30000)
+});
+```
+
+#### Lifecycle
+
+```typescript
+// Connect — creates session, wires userId, starts batching
+const session = await ziggy.connect({
+  userId: string;
+  context: Record<string, unknown>;
+  capabilities?: string[];  // default: ['streaming', 'actions']
+  onTrigger?: (response: ContextPushResponse) => void;
+});
+
+// Disconnect — flush analytics, stop batching, destroy session
+await ziggy.disconnect();
+```
+
+---
+
+### Chat
+
+```typescript
+// Non-streaming
+const response = await ziggy.chat.send({ message: 'Help me debug this' });
+console.log(response.response.content);
+console.log(response.response.agentId); // 'knuckles', 'ziggy', etc.
+
+// Streaming (ndjson, MCP 2025-03-26 standard)
+for await (const event of ziggy.chat.stream({ message: 'Help me debug this' })) {
+  // event.type: 'stream.start' | 'agent.start' | 'content.delta' |
+  //             'content.done' | 'tool.start' | 'tool.result' |
+  //             'metadata' | 'stream.end' | 'error'
+}
+
+// Resume interrupted stream
+for await (const event of ziggy.chat.resume(streamId, lastSeqNumber)) {
+  // Pick up where you left off
+}
+```
+
+**Chat request options:**
+
+```typescript
+{
+  message: string;
+  attachments?: Array<{ type: 'screenshot' | 'file_reference'; id: string }>;
+  context?: Record<string, unknown>;  // Bundled context update
+  requestId?: string;                  // Client-generated dedup ID
+}
+```
+
+---
+
+### Context
+
+Context updates are auto-batched every 10 seconds. Important changes (page navigation, errors, process status) flush immediately.
+
+```typescript
+// Queue a context update (merges with pending batch)
+ziggy.context.update({
+  page: { path: '/settings', type: 'settings', title: 'Settings' },
+});
+
+// Queue an event
+ziggy.context.addEvent({
+  type: 'button_click',
+  timestamp: new Date().toISOString(),
+  data: { buttonId: 'retry' },
+});
+
+// Force flush
+await ziggy.context.flush();
+```
+
+---
+
+### App Configuration
+
+Register triggers, quick actions, brand identity, and credentials.
+
+```typescript
+// Brand
+await ziggy.app.setBrand({
+  identity: { name: 'Coach', tagline: 'Your training partner' },
+  voice: { tone: ['motivational', 'knowledgeable'], formality: 'casual-professional' },
+  theme: { primaryColor: '#2E7D32', chatPosition: 'bottom-right' },
+});
+const brand = await ziggy.app.getBrand();
+
+// Triggers (full sync — replaces all existing)
+await ziggy.app.registerTriggers({
+  triggers: [{
+    id: 'transform-error',
+    name: 'Transform Error',
+    condition: { type: 'process_status', value: 'error' },
+    priority: 'critical',
+    message: "That didn't work — want me to figure out why?",
+  }],
+});
+const { triggers } = await ziggy.app.listTriggers();
+await ziggy.app.deleteTrigger('transform-error');
+
+// Quick Actions (full sync)
+await ziggy.app.registerQuickActions({
+  sets: [{
+    id: 'dashboard-empty',
+    contextState: 'dashboard-empty',
+    conditions: { pageTypes: ['dashboard'] },
+    actions: [{ id: 'start', label: 'Get started', action: 'onboarding.start', priority: 1 }],
+  }],
+});
+const { sets } = await ziggy.app.listQuickActions();
+await ziggy.app.deleteQuickActionSet('dashboard-empty');
+
+// Credentials (encrypted at rest, AES-256-GCM)
+await ziggy.app.setCredentials({ github_token: 'ghp_...', supabase_key: 'eyJ...' });
+const { credentials, updatedAt } = await ziggy.app.getCredentials(); // keys only, never values
+await ziggy.app.deleteCredentials();
+```
+
+---
+
+### Callback Handler
+
+Handle tool execution requests from Ziggy. When Ziggy needs your app to do something (navigate, retry a process, etc.), it POSTs to your registered callback URL.
+
+```typescript
+import { CallbackHandler } from '@ziggy-ai/client-sdk';
+
+const handler = new CallbackHandler();
+
+handler
+  .on('support.navigate', async (params) => {
+    router.push(params.path as string);
+    return { navigated: true };
+  })
+  .on('support.retry_process', async (params) => {
+    await processes.retry(params.processId as string);
+    return { retried: true };
+  });
+
+// Mount in your API framework
+app.post('/api/ziggy/callback', async (req, res) => {
+  const result = await handler.handle(req.body);
+  res.json(result);
+});
+```
+
+---
+
+### Tools
+
+Invoke tools directly (e.g., from quick action buttons).
+
+```typescript
+const result = await ziggy.tools.invoke('support.navigate', { path: '/settings' });
+
+// Streaming tool invocation
+for await (const event of ziggy.tools.invokeStream('support.respond', { message: 'Hi' })) {
+  // event.type: 'tool.start' | 'tool.result'
+}
+```
+
+---
+
+### Feedback
+
+```typescript
+// Quick reaction
+await ziggy.feedback.react('msg-1', 'helpful');
+// reaction: 'helpful' | 'not_helpful' | 'wrong' | 'perfect'
+
+// Detailed feedback
+await ziggy.feedback.submit({
+  conversationId: 'conv-1',
+  type: 'accuracy',  // 'accuracy' | 'helpfulness' | 'tone' | 'action' | 'correction'
+  rating: 4,
+  comment: 'Good answer but missed one detail',
+  userId: 'user-1',
+});
+
+// Record coordination outcome (for learning loop)
+await ziggy.feedback.recordOutcome({
+  coordinationId: 'coord-1',
+  success: true,
+  agentIds: ['knuckles'],
+});
+```
+
+---
+
+### Quests
+
+Track multi-step workflows.
+
+```typescript
+const { quest } = await ziggy.quests.create({
+  title: 'Investigate transform failure',
+  sessionId: session.sessionId,
+  initiatorId: 'knuckles',
+  steps: [
+    { label: 'Check logs', agentId: 'ziggy' },
+    { label: 'Analyze error' },
+  ],
+});
+
+await ziggy.quests.updateStep(quest.id, quest.steps[0].id, {
+  status: 'complete',
+  update: { message: 'Found 3 errors in logs' },
+});
+
+// Stream quest updates
+for await (const event of ziggy.quests.stream(quest.id)) {
+  // event.type: 'quest.status' | 'quest.step_update' | 'quest.complete'
+}
+```
+
+---
+
+### Analytics
+
+Events are auto-batched every 30 seconds and flushed on disconnect.
+
+```typescript
+ziggy.analytics.track('feature_used', { feature: 'dark-mode' });
+ziggy.analytics.track('page_viewed', { path: '/settings' });
+```
+
+---
+
+## Stream Events
+
+All streaming endpoints use ndjson (newline-delimited JSON) with sequence numbers for resumption.
+
+| Event Type | Key Fields | Description |
+|------------|------------|-------------|
+| `stream.start` | `streamId`, `messageId` | Always first |
+| `agent.start` | `agentId`, `agentRole` | Routed agent begins |
+| `agent.switch` | `fromAgentId`, `toAgentId` | Agent handoff |
+| `content.delta` | `content` | Partial text |
+| `content.done` | `fullContent` | Complete text |
+| `tool.start` | `toolId`, `toolName` | Tool invoked |
+| `tool.progress` | `toolId`, `progress` | Tool progress (0-1) |
+| `tool.result` | `toolId`, `success` | Tool completed |
+| `metadata` | `confidence`, `quickActions` | Response metadata |
+| `stream.end` | `messageId`, `durationMs` | Always last |
+| `error` | `code`, `message`, `retryable` | Error during stream |
+
+### Stream Resumption
+
+```typescript
+import { SequenceTracker } from '@ziggy-ai/client-sdk';
+
+const tracker = new SequenceTracker();
+
+for await (const event of ziggy.chat.stream({ message: 'Hello' })) {
+  tracker.update(event);
+  // ... process event
+}
+
+// If disconnected, resume:
+if (tracker.streamId) {
+  for await (const event of ziggy.chat.resume(tracker.streamId, tracker.lastSeq)) {
+    // Picks up from where you left off
+  }
+}
+```
+
+---
+
+## Error Handling
+
+```typescript
+import { ZiggyError, ZiggyConnectionError } from '@ziggy-ai/client-sdk';
+
+try {
+  await ziggy.chat.send({ message: 'Hello' });
+} catch (error) {
+  if (error instanceof ZiggyConnectionError) {
+    // Network/timeout — error.retryable is true
+    console.log('Connection failed, will retry');
+  } else if (error instanceof ZiggyError) {
+    // API error — check error.status
+    console.log(`API error ${error.status}: ${error.message}`);
+  }
+}
+```
+
+### Retry Utility
+
+```typescript
+import { withRetry } from '@ziggy-ai/client-sdk';
+
+const result = await withRetry(
+  () => ziggy.chat.send({ message: 'Hello' }),
+  { maxRetries: 3, baseDelayMs: 1000, maxDelayMs: 30000 },
+);
+// Retries with exponential backoff + jitter. Skips retry for 4xx errors.
+```
+
+---
+
+## Architecture
+
+The SDK is a thin client that maps to Ziggy's v1 REST API:
+
+```
+ZiggyClient
+├── sessions    → POST/DELETE /v1/sessions
+├── chat        → POST /v1/chat, POST /v1/chat/stream
+├── context     → POST /v1/sessions/:id/context (auto-batched)
+├── tools       → POST /v1/tools/invoke
+├── feedback    → POST /v1/feedback/*
+├── quests      → /v1/quests/*
+├── analytics   → POST /v1/feedback/analytics/events (auto-batched)
+├── app         → /v1/apps/* (triggers, quick actions, brand, credentials)
+└── callbacks   → CallbackHandler (host-side, receives Ziggy tool requests)
+```
+
+**Key design decisions:**
+
+- **Auto-batching** — Context (10s) and analytics (30s) are batched to reduce API calls. Important context changes flush immediately.
+- **Streaming** — Uses Streamable HTTP with ndjson (MCP 2025-03-26 standard). Sequence numbers enable reconnection.
+- **Composition** — Each API area is a separate module composed by `ZiggyClient`.
+- **Zero dependencies** — Uses only `fetch` (built into Node 18+ and all modern browsers).
+
+---
+
+## Development
+
+```bash
+npm run build       # Build with tsup (ESM + .d.ts)
+npm run dev         # Watch mode
+npm run typecheck   # Type check without emit
+npm test            # Run tests (vitest)
+```