@clawtree/sdk

Dead-simple SDK for integrating with ClawTree — the secure webhook relay for AI agents.

Installation

npm install @clawtree/sdk
# or
bun add @clawtree/sdk

Quick Start

import { ClawTree } from '@clawtree/sdk';

const ct = new ClawTree({
  apiKey: 'ct_your_api_key',
  botName: 'my-bot'
});

// Register an endpoint with schema validation
ct.endpoint('hello', {
  schema: { name: 'string' },
  handler: ({ name }) => ({
    body: { message: `Hello, ${name}!` }
  })
});

// Start listening
ct.listen();

Your bot now has a public webhook URL at https://api.clawtree.link/hook/{id}/{token}.

Features

• Idempotent endpoints — Restart your script 100 times, endpoints are reused
• Schema validation — Simple schema DSL or bring your own Zod
• Auto-reconnect — Handles disconnections gracefully
• OpenClaw integration — Forward webhooks to your AI with one flag

Schema Types

ct.endpoint('example', {
  schema: {
    name: 'string',           // required string
    age: 'number',            // required number
    active: 'boolean',        // required boolean
    email: 'string?',         // optional string
    tier: { enum: ['free', 'pro'] },  // enum
    tags: { array: 'string' } // array of strings
  },
  handler: (data) => ({ body: data })
});

OpenClaw Integration

Forward webhooks to your AI for processing:

const ct = new ClawTree({
  apiKey: 'ct_xxx',
  openclaw: {
    hooksUrl: 'http://localhost:18789/hooks',
    token: 'your_hooks_token'
  }
});

// Forward only — AI handles everything
ct.endpoint('ai-query', {
  schema: { question: 'string' },
  forwardToOpenclaw: true
});

// Handler wraps AI response
ct.endpoint('smart-endpoint', {
  schema: { query: 'string' },
  forwardToOpenclaw: true,
  handler: async (payload, { forward }) => {
    // Pre-process
    const enriched = { ...payload, timestamp: Date.now() };
    
    // Forward to AI
    const aiResponse = await forward(enriched);
    
    // Post-process
    return { body: { response: aiResponse, processed: true } };
  }
});

API Reference

new ClawTree(config)

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | required | ClawTree API key | | botName | string | - | Bot name for identification | | apiUrl | string | wss://api.clawtree.link | ClawTree WebSocket URL | | openclaw | object | - | OpenClaw hooks config | | autoReconnect | boolean | true | Auto-reconnect on disconnect | | maxReconnectAttempts | number | 10 | Max reconnection attempts |

ct.endpoint(name, config)

| Option | Type | Description | |--------|------|-------------| | schema | object | Schema for validation | | handler | function | Handler function | | forwardToOpenclaw | boolean | Forward to OpenClaw hooks | | requireAuth | boolean | Require auth token (coming soon) |

Handler Context

handler: (payload, context) => {
  context.forward(payload);  // Forward to OpenClaw
  context.endpointId;        // Endpoint ID
  context.endpointName;      // Endpoint name
  context.deliveryId;        // Unique delivery ID
  context.headers;           // Request headers
}

License

MIT