@chucky.cloud/sdk 0.1.0

package/README.md

@@ -0,0 +1,330 @@
+# @chucky.cloud/sdk
+
+SDK for interacting with Chucky sandbox - supports both browser and Node.js.
+
+## Installation
+
+```bash
+npm install @chucky.cloud/sdk
+```
+
+## Quick Start
+
+```typescript
+import { ChuckyClient, tool, createBudget, createToken } from '@chucky.cloud/sdk';
+
+// Server-side: Create a token for your user
+const token = await createToken({
+  userId: 'user-123',
+  projectId: 'your-project-uuid',
+  secret: 'your-hmac-secret',
+  budget: createBudget({
+    aiDollars: 1.00,
+    computeHours: 1,
+    window: 'day',
+  }),
+});
+
+// Create client with the token
+const client = new ChuckyClient({ token });
+
+// Create a session
+const session = await client.createSession({
+  model: 'claude-sonnet-4-5-20250929',
+});
+
+// Send a message and get response
+const result = await session.send('Hello, world!');
+console.log(result.text);
+```
+
+## Features
+
+- **Browser & Node.js Support**: Same API works in both environments
+- **Sessions**: Multi-turn conversations with state persistence
+- **One-shot Prompts**: Stateless prompt execution
+- **Tools**: Define custom tools with full type safety
+- **Streaming**: Real-time response streaming
+- **Token Management**: Create and verify JWT tokens
+
+## Sessions
+
+### Creating a Session
+
+```typescript
+const session = await client.createSession({
+  model: 'claude-sonnet-4-5-20250929',
+  systemPrompt: 'You are a helpful assistant.',
+  maxTurns: 10,
+});
+
+const result = await session.send('What is 2 + 2?');
+console.log(result.text); // "4"
+
+// Multi-turn conversation
+const followUp = await session.send('And what is that times 3?');
+console.log(followUp.text); // "12"
+```
+
+### Resuming a Session
+
+```typescript
+const session = await client.resumeSession('session-123', {
+  continue: true,
+});
+```
+
+### Streaming Responses
+
+```typescript
+for await (const event of session.sendStream('Tell me a story')) {
+  if (event.type === 'text') {
+    process.stdout.write(event.text);
+  } else if (event.type === 'tool_use') {
+    console.log('Using tool:', event.name);
+  }
+}
+```
+
+## Tools
+
+### Defining Tools
+
+```typescript
+import { tool, textResult } from '@chucky.cloud/sdk';
+
+const weatherTool = tool(
+  'get_weather',
+  'Get current weather for a city',
+  {
+    type: 'object',
+    properties: {
+      city: { type: 'string', description: 'City name' },
+      unit: { type: 'string', enum: ['celsius', 'fahrenheit'] },
+    },
+    required: ['city'],
+  },
+  async ({ city, unit }) => textResult(`Weather in ${city}: Sunny, 72°${unit === 'celsius' ? 'C' : 'F'}`)
+);
+
+const session = await client.createSession({
+  tools: [weatherTool],
+});
+```
+
+### Browser Tools
+
+Tools that execute in the browser:
+
+```typescript
+import { browserTool } from '@chucky.cloud/sdk';
+
+const alertTool = browserTool({
+  name: 'show_alert',
+  description: 'Show an alert dialog',
+  inputSchema: {
+    type: 'object',
+    properties: { message: { type: 'string' } },
+    required: ['message'],
+  },
+  handler: async ({ message }) => {
+    alert(message);
+    return { content: [{ type: 'text', text: 'Alert shown' }] };
+  },
+});
+```
+
+### MCP Server Builder
+
+```typescript
+import { mcpServer, tool } from '@chucky.cloud/sdk';
+
+const myTools = mcpServer('my-tools', '1.0.0')
+  .addTool({
+    name: 'greet',
+    description: 'Greet someone',
+    inputSchema: {
+      type: 'object',
+      properties: { name: { type: 'string' } },
+      required: ['name'],
+    },
+    handler: async ({ name }) => ({
+      content: [{ type: 'text', text: `Hello, ${name}!` }],
+    }),
+  })
+  .build();
+
+const session = await client.createSession({
+  mcpServers: [myTools],
+});
+```
+
+## Token Management
+
+### Creating Tokens (Server-side)
+
+```typescript
+import { createToken, createBudget } from '@chucky.cloud/sdk';
+
+const token = await createToken({
+  userId: 'user-123',
+  projectId: 'your-project-uuid',
+  secret: 'your-hmac-secret',
+  expiresIn: 3600, // 1 hour
+  budget: createBudget({
+    aiDollars: 5.00,
+    computeHours: 2,
+    window: 'day',
+  }),
+  permissions: {
+    tools: ['get_weather', 'search'],
+    maxTurns: 20,
+  },
+});
+```
+
+### Verifying Tokens
+
+```typescript
+import { verifyToken, decodeToken, isTokenExpired } from '@chucky.cloud/sdk';
+
+// Verify signature
+const isValid = await verifyToken(token, 'your-hmac-secret');
+
+// Decode without verification
+const decoded = decodeToken(token);
+console.log(decoded.payload.sub); // User ID
+console.log(decoded.payload.budget); // Budget limits
+
+// Check expiration
+if (isTokenExpired(token)) {
+  console.log('Token has expired');
+}
+```
+
+## Client Options
+
+```typescript
+const client = new ChuckyClient({
+  // Required
+  token: 'your-jwt-token',
+
+  // Optional
+  baseUrl: 'wss://box.chucky.cloud/ws', // Custom endpoint
+  debug: false,                          // Enable debug logging
+  timeout: 30000,                        // Connection timeout (ms)
+  keepAliveInterval: 300000,             // Keep-alive interval (ms)
+  autoReconnect: true,                   // Auto-reconnect on disconnect
+  maxReconnectAttempts: 5,               // Max reconnect attempts
+});
+```
+
+## Session Options
+
+```typescript
+const session = await client.createSession({
+  // Model
+  model: 'claude-sonnet-4-5-20250929',
+  fallbackModel: 'claude-3-5-haiku-20241022',
+
+  // Limits
+  maxTurns: 10,
+  maxBudgetUsd: 1.00,
+  maxThinkingTokens: 10000,
+
+  // System prompt
+  systemPrompt: 'You are a helpful assistant.',
+  // Or use preset:
+  // systemPrompt: { type: 'preset', preset: 'claude_code', append: 'Be concise.' },
+
+  // Tools
+  tools: [myTool],
+  allowedTools: ['get_weather'],
+  disallowedTools: ['dangerous_tool'],
+
+  // MCP servers
+  mcpServers: [myServer],
+
+  // Sub-agents
+  agents: {
+    researcher: {
+      name: 'Researcher',
+      model: 'claude-sonnet-4-5-20250929',
+      tools: ['search'],
+    },
+  },
+
+  // Session management
+  sessionId: 'session-123',    // Resume existing session
+  forkSession: true,           // Fork instead of resume
+  continue: true,              // Continue from where left off
+
+  // Output
+  includePartialMessages: true,
+  outputFormat: {
+    type: 'json_schema',
+    schema: { /* your schema */ },
+  },
+});
+```
+
+## Error Handling
+
+```typescript
+import {
+  ChuckyError,
+  ConnectionError,
+  AuthenticationError,
+  BudgetExceededError,
+  ConcurrencyLimitError,
+} from '@chucky.cloud/sdk';
+
+try {
+  await session.send('Hello');
+} catch (error) {
+  if (error instanceof BudgetExceededError) {
+    console.log('Budget exceeded:', error.message);
+  } else if (error instanceof ConcurrencyLimitError) {
+    console.log('Too many concurrent sessions');
+  } else if (error instanceof AuthenticationError) {
+    console.log('Invalid token');
+  } else if (error instanceof ConnectionError) {
+    console.log('Connection failed');
+  }
+}
+```
+
+## TypeScript
+
+The SDK is fully typed. All types are exported:
+
+```typescript
+import type {
+  // Options
+  ClientOptions,
+  SessionOptions,
+  PromptOptions,
+
+  // Tools
+  ToolDefinition,
+  ToolResult,
+  ToolInputSchema,
+  McpServerDefinition,
+
+  // Results
+  SessionResult,
+  PromptResult,
+  Message,
+
+  // Token
+  BudgetTokenPayload,
+  TokenBudget,
+
+  // Streaming
+  StreamingEvent,
+} from '@chucky.cloud/sdk';
+```
+
+## License
+
+MIT

package/dist/browser.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Browser Entry Point
+ *
+ * Optimized exports for browser environments.
+ * Excludes Node.js-specific functionality like token creation.
+ */
+export * from './index.js';
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,YAAY,CAAC"}

package/dist/browser.js

@@ -0,0 +1,12 @@
+/**
+ * Browser Entry Point
+ *
+ * Optimized exports for browser environments.
+ * Excludes Node.js-specific functionality like token creation.
+ */
+// Re-export everything from main index
+export * from './index.js';
+// Browser-specific note: Token creation uses Web Crypto API
+// which is available in modern browsers. For older browsers,
+// you may need a polyfill.
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,uCAAuC;AACvC,cAAc,YAAY,CAAC;AAE3B,4DAA4D;AAC5D,6DAA6D;AAC7D,2BAA2B"}

package/dist/client/ChuckyClient.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Chucky Client
+ *
+ * Main entry point for the Chucky SDK.
+ * Provides methods to create sessions and execute prompts.
+ */
+import type { ClientOptions, SessionOptions, PromptOptions, ConnectionStatus, ClientEventHandlers } from '../types/options.js';
+import type { PromptResult } from '../types/results.js';
+import { Session } from './Session.js';
+/**
+ * Chucky client for interacting with the sandbox service
+ *
+ * @example
+ * ```typescript
+ * import { ChuckyClient } from '@chucky.cloud/sdk';
+ *
+ * const client = new ChuckyClient({
+ *   token: 'your-jwt-token',
+ * });
+ *
+ * // Create a session
+ * const session = await client.createSession({
+ *   model: 'claude-sonnet-4-5-20250929',
+ *   systemPrompt: 'You are a helpful assistant.',
+ * });
+ *
+ * // Send messages
+ * const result = await session.send('Hello, world!');
+ * console.log(result.text);
+ *
+ * // Or use one-shot prompts
+ * const response = await client.prompt({
+ *   message: 'What is 2 + 2?',
+ *   model: 'claude-sonnet-4-5-20250929',
+ * });
+ * console.log(response.text);
+ * ```
+ */
+export declare class ChuckyClient {
+    private readonly options;
+    private transport;
+    private eventHandlers;
+    private activeSessions;
+    /**
+     * Create a new Chucky client
+     */
+    constructor(options: ClientOptions);
+    /**
+     * Get the current connection status
+     */
+    get status(): ConnectionStatus;
+    /**
+     * Set event handlers
+     */
+    on(handlers: ClientEventHandlers): this;
+    /**
+     * Create a new session
+     *
+     * @param options - Session configuration options
+     * @returns A new session instance
+     *
+     * @example
+     * ```typescript
+     * const session = await client.createSession({
+     *   model: 'claude-sonnet-4-5-20250929',
+     *   systemPrompt: 'You are a helpful coding assistant.',
+     *   tools: [
+     *     {
+     *       name: 'get_weather',
+     *       description: 'Get the current weather',
+     *       inputSchema: {
+     *         type: 'object',
+     *         properties: {
+     *           city: { type: 'string', description: 'City name' },
+     *         },
+     *         required: ['city'],
+     *       },
+     *       handler: async ({ city }) => ({
+     *         content: [{ type: 'text', text: `Weather in ${city}: Sunny, 72°F` }],
+     *       }),
+     *     },
+     *   ],
+     * });
+     * ```
+     */
+    createSession(options?: SessionOptions): Promise<Session>;
+    /**
+     * Resume an existing session
+     *
+     * @param sessionId - The session ID to resume
+     * @param options - Additional session options
+     * @returns The resumed session
+     *
+     * @example
+     * ```typescript
+     * const session = await client.resumeSession('session-123', {
+     *   continue: true,
+     * });
+     * ```
+     */
+    resumeSession(sessionId: string, options?: Omit<SessionOptions, 'sessionId'>): Promise<Session>;
+    /**
+     * Execute a one-shot prompt (stateless)
+     *
+     * @param options - Prompt configuration
+     * @returns The prompt result
+     *
+     * @example
+     * ```typescript
+     * const result = await client.prompt({
+     *   message: 'Explain quantum computing in simple terms',
+     *   model: 'claude-sonnet-4-5-20250929',
+     * });
+     * console.log(result.text);
+     * ```
+     */
+    prompt(options: PromptOptions): Promise<PromptResult>;
+    /**
+     * Execute a prompt with streaming
+     *
+     * @param options - Prompt configuration
+     * @yields Stream events and final result
+     *
+     * @example
+     * ```typescript
+     * for await (const event of client.promptStream({ message: 'Tell me a story' })) {
+     *   if (event.type === 'text') {
+     *     process.stdout.write(event.text);
+     *   }
+     * }
+     * ```
+     */
+    promptStream(options: PromptOptions): AsyncGenerator<StreamingEvent, PromptResult, unknown>;
+    /**
+     * Close all active sessions and disconnect
+     */
+    close(): Promise<void>;
+    /**
+     * Create a new transport instance
+     */
+    private createTransport;
+}
+/**
+ * Streaming event types
+ */
+export interface StreamingTextEvent {
+    type: 'text';
+    text: string;
+}
+export interface StreamingToolUseEvent {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+export interface StreamingToolResultEvent {
+    type: 'tool_result';
+    id: string;
+    content: unknown;
+    isError?: boolean;
+}
+export interface StreamingThinkingEvent {
+    type: 'thinking';
+    thinking: string;
+}
+export interface StreamingErrorEvent {
+    type: 'error';
+    error: Error;
+}
+export type StreamingEvent = StreamingTextEvent | StreamingToolUseEvent | StreamingToolResultEvent | StreamingThinkingEvent | StreamingErrorEvent;
+/**
+ * Create a Chucky client
+ *
+ * @param options - Client configuration
+ * @returns A new ChuckyClient instance
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from '@chucky.cloud/sdk';
+ *
+ * const client = createClient({
+ *   token: 'your-jwt-token',
+ * });
+ * ```
+ */
+export declare function createClient(options: ClientOptions): ChuckyClient;
+//# sourceMappingURL=ChuckyClient.d.ts.map

package/dist/client/ChuckyClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChuckyClient.d.ts","sourceRoot":"","sources":["../../src/client/ChuckyClient.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAOvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAC6B;IACrD,OAAO,CAAC,SAAS,CAAmC;IACpD,OAAO,CAAC,aAAa,CAA2B;IAChD,OAAO,CAAC,cAAc,CAAmC;IAEzD;;OAEG;gBACS,OAAO,EAAE,aAAa;IAQlC;;OAEG;IACH,IAAI,MAAM,IAAI,gBAAgB,CAE7B;IAED;;OAEG;IACH,EAAE,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI;IAKvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,aAAa,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;IAiBnE;;;;;;;;;;;;;OAaG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,IAAI,CAAC,cAAc,EAAE,WAAW,CAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAOzG;;;;;;;;;;;;;;OAcG;IACG,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAW3D;;;;;;;;;;;;;;OAcG;IACI,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,cAAc,CAAC,cAAc,EAAE,YAAY,EAAE,OAAO,CAAC;IAiBlG;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAY5B;;OAEG;IACH,OAAO,CAAC,eAAe;CAWxB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,UAAU,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,aAAa,CAAC;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,KAAK,CAAC;CACd;AAED,MAAM,MAAM,cAAc,GACtB,kBAAkB,GAClB,qBAAqB,GACrB,wBAAwB,GACxB,sBAAsB,GACtB,mBAAmB,CAAC;AAExB;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,YAAY,CAEjE"}