Universal TypeScript SDK for Chucky - build Claude-powered AI assistants for browser and Node.js
npm install @chucky.cloud/sdk



Universal TypeScript SDK for Chucky - build Claude-powered AI assistants for browser and Node.js.
``bash`
npm install @chucky.cloud/sdk
`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);
`
- 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
`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"
`
`typescript`
const session = await client.resumeSession('session-123', {
continue: true,
});
`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);
}
}
`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],
});
`
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' }] };
},
});
`
`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],
});
`
`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,
},
});
`
`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');
}
`
`typescript
const client = new ChuckyClient({
// Required
token: 'your-jwt-token',
// Optional
baseUrl: 'wss://conjure.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
});
`
`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 / },
},
});
`
`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');
}
}
`
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';
``
MIT