wakumo-ai-sdk-js

A scalable, modern JavaScript/TypeScript SDK and CLI for interacting with the Wakumo AI backend (API & WebSocket).

Features

• TypeScript-first: Full type safety and autocompletion
• Modular: Easy to extend with new APIs, types, and CLI commands
• CLI: Powerful command-line tool for automation and scripting
• Node.js & Browser: SDK works in both environments (CLI is Node.js only)

Directory Structure

wakumo-ai-sdk-js/
├── src/
│   ├── api/           # API modules (REST, WS, ...)
│   ├── client/        # Main client (config, auth, API init)
│   ├── types/         # TypeScript types/interfaces
│   ├── utils/         # Utility functions (helpers, error handling, ...)
│   ├── cli/           # CLI entrypoint and commands
│   └── index.ts       # SDK entrypoint (exports public API)
├── test/              # Unit/integration tests
├── dist/              # Build output
├── package.json
├── tsconfig.json
└── README.md

Installation

Using Yarn

yarn add wakumo-ai-sdk-js

Using npm

npm install wakumo-ai-sdk-js

Configuration

You can configure the SDK in two ways:

1. Environment Variables (recommended for CLI & scripts)

• WAKUMO_API_KEY – Your API key (required)
• WAKUMO_API_URL – API endpoint (default: https://api.wakumo.ai)
• WAKUMO_WS_URL – WebSocket endpoint (default: wss://api.wakumo.ai)

Example:

export WAKUMO_API_KEY=your_key
export WAKUMO_API_URL=https://your-custom-endpoint
export WAKUMO_WS_URL=wss://your-custom-ws-endpoint

2. Pass Directly to WakumoAIClient Constructor (recommended for SDK usage)

import { WakumoAIClient } from 'wakumo-ai-sdk-js';

const client = new WakumoAIClient({
  apiKey: 'your_key',
  apiUrl: 'https://your-custom-endpoint',
  wsUrl: 'wss://your-custom-ws-endpoint',
});

If a value is not provided, the SDK will fallback to the corresponding environment variable, or use the default.

Usage

1. SDK (TypeScript/Node.js)

import { WakumoAIClient } from 'wakumo-ai-sdk-js';

const client = new WakumoAIClient({ apiKey: 'YOUR_API_KEY' });

// Get conversation details
const info = await client.conversation.getConversation('conversation_id');
console.log(info);

// Create a new conversation
const created = await client.conversation.create('Hello!', ['image_url'], ['file_url'], { origin_context });
console.log(created);

2. CLI

Build the CLI

yarn build

Run CLI commands

node dist/cli/index.js conversation get --id <conversation_id>

node dist/cli/index.js conversation trajectory-v2 --id <conversation_id> [--per-page 50] [--direction next] [--cursor <cursor>]

Tip: Set your API key and endpoint via environment variables for convenience.

Extending the SDK

• Add new API modules in src/api/
• Add new types in src/types/ and export via src/types/index.ts
• Add CLI commands in src/cli/
• Add utility functions in src/utils/

Contributing & Support

• PRs and issues are welcome!
• For questions or support, please contact the maintainer.