CyberPod SDK

A fully-typed TypeScript SDK for integrating with the CyberPod Core API. Built with a global functions pattern for easy, intuitive usage.

Installation

npm install @cpod/sdk
# or
pnpm add @cpod/sdk
# or
yarn add @cpod/sdk
Copy

Quick Start

1. Initialize the SDK

import { initializeSDK } from "@cpod/sdk";

// Option A: Auto-read from environment variables (recommended)
// Reads NEXT_PUBLIC_CPOD_BASE_URL and CPOD_API_KEY automatically
initializeSDK();

// Option B: With access token (for authenticated users)
initializeSDK(userAccessToken);

// Option C: Manual configuration
import { initSDK } from "@cpod/sdk";
initSDK({
  baseUrl: process.env.NEXT_PUBLIC_CPOD_BASE_URL!,
  apiKey: process.env.CPOD_API_KEY!,
});
Copy

Environment Variables:
The SDK reads CPOD_BASE_URL or NEXT_PUBLIC_CPOD_BASE_URL for the base URL,
and CPOD_API_KEY or NEXT_PUBLIC_CPOD_API_KEY for the API key.

2. Authenticate (if not using API key)

import { authenticateUser, setAccessToken } from "@cpod/sdk";

const tokens = await authenticateUser({
  username: "user@example.com",
  password: "password",
});

// Token is automatically stored, or set manually:
setAccessToken(tokens.access_token);
Copy

3. Use the SDK

import { getUser, listExperts, chat, listProjects } from "@cpod/sdk";

// Get current user
const user = await getUser();
console.log(`Hello, ${user.full_name}!`);

// List available experts
const experts = await listExperts();

// Chat completion
const response = await chat.complete({
  message: "Hello!",
  expert_id: experts[0].id,
});

// Streaming chat
for await (const chunk of chat.stream({ message: "Write a poem" })) {
  process.stdout.write(chunk.content);
}

// List projects
const projects = await listProjects();
Copy

Documentation

Getting Started

Document	Description
Overview	Complete capability overview with examples
Quick Reference	All functions at a glance
Next.js Guide	Step-by-step Next.js integration
Examples	React component examples

Reference

Document	Description
SDK Reference	Detailed function reference
API Reference	Backend API endpoints & schemas
Roadmap	Feature status & future plans
Design Guide	Design tokens & theming (@cpod/tokens)

Module Summary

Fully Implemented (20 modules)

Module	Docs	Functions	Description
Auth	auth.md	5	Authentication, sessions, tokens
Users	users.md	15	User management (self-service & admin)
Chat	chat.md	2	Chat completions (streaming & non-streaming)
Experts	experts.md	8	AI expert management
Projects	projects.md	15	Project CRUD, files, chats
Tasks	tasks.md	17	Task execution & history
Files	files.md	16	File upload, download, management
Folders	folders.md	4	Folder management
Categories	categories.md	4	Category management
Notifications	notifications.md	11	User notifications
Document Search	document-search.md	7	Full-text search & entities
Graphs	graphs.md	8	Graph visualization
Applications	applications.md	7	Application management
Chat Management	chat-management.md	6	Chat CRUD & expert assignment
Company	company.md	13	Company settings & configuration
MCP Servers	mcp-servers.md	15	MCP server & tool management
Storage	storage.md	3	Key-value storage
API Tokens	api-tokens.md	4	API token management
Dashboard	dashboard.md	3	Dashboard metrics & stats
Secrets	secrets.md	27	Secret management

Stub Modules (8 modules - backend pending)

Module	Functions	Description
Permissions	8	Role-based access control
Audit	5	Activity logging, audit trail
Organization	10	Organization/tenant management
App Runtime	25+	Per-app config, analytics, prompts, tasks
Prompts	8	Global prompt templates
Fetch & Cache	7	URL fetching with caching
File Signed URLs	5	Pre-signed upload/download URLs
Notification Prefs	3	User notification preferences

Total: 250+ functions across 28 modules

Common Use Cases

Authentication with API Key

import { initSDK, getUser, listExperts } from "@cpod/sdk";

initSDK({
  baseUrl: "https://api.cyberpod.cloud/api",
  apiKey: "your-api-key",
});

const user = await getUser();
const experts = await listExperts();
Copy

Chat Completion

import { chat } from "@cpod/sdk";

// Non-streaming
const response = await chat.complete({
  message: "What is machine learning?",
  expert_id: "expert-uuid",
});
console.log(response.content);

// Streaming
for await (const chunk of chat.stream({
  message: "Explain quantum computing",
  expert_id: "expert-uuid",
})) {
  process.stdout.write(chunk.content);
}
Copy

File Management

import { uploadFile, listFolders, getFoldersAndFiles } from "@cpod/sdk";

// Upload a file
const formData = new FormData();
formData.append("file", fileBlob);
formData.append("folder_id", folderId);
const uploaded = await uploadFile(formData);

// List folders and files
const folders = await listFolders();
const filesAndFolders = await getFoldersAndFiles();
Copy

Project Management

import {
  createProject,
  listProjects,
  addFilesToProject,
  createProjectChat,
} from "@cpod/sdk";

// Create project
const project = await createProject({
  name: "My Project",
  description: "Project description",
  expert_ids: ["expert-1", "expert-2"],
});

// Add files
await addFilesToProject(project.id, { file_ids: ["file-1", "file-2"] });

// Create chat in project
const chat = await createProjectChat(project.id, {
  title: "Project Discussion",
});
Copy

Error Handling

import { CyberPodError, NotImplementedError } from "@cpod/sdk";

try {
  const result = await someOperation();
} catch (error) {
  if (error instanceof CyberPodError) {
    console.error(`API Error [${error.status}]: ${error.message}`);
  } else if (error instanceof NotImplementedError) {
    console.error(`Feature not implemented: ${error.feature}`);
  }
}
Copy

TypeScript Support

Full TypeScript support with exported types:

import type {
  // Configuration
  CyberPodConfig,

  // Auth
  AuthTokens,
  LoginCredentials,
  Session,

  // Users
  User,
  CreateUserRequest,

  // Chat
  ChatRequest,
  ChatResponse,
  ChatChunk,

  // Projects
  Project,
  CreateProjectRequest,

  // And 100+ more types...
} from "@cpod/sdk";
Copy

Class-based API (Alternative)

For those who prefer a class-based approach:

import { CyberPod } from "@cpod/sdk";

const sdk = new CyberPod({
  baseUrl: process.env.NEXT_PUBLIC_CPOD_BASE_URL!,
  apiKey: process.env.CPOD_API_KEY,
});

// Access modules via sdk instance
const user = await sdk.users.getUser();
const projects = await sdk.projects.listProjects();
const response = await sdk.chat.complete({ message: "Hello" });
Copy

Development

# Install dependencies
npm install

# Build
npm run build

# Type check
npm run typecheck

# Run tests
npm test

# Run examples
npm run example
npm run example:chat
Copy

Project Structure

packages/
├── core/                    # Main SDK package (@cpod/sdk)
│   ├── src/
│   │   ├── index.ts         # Global functions & exports
│   │   ├── client.ts        # HTTP client with retry & error handling
│   │   ├── auth/            # Authentication module
│   │   ├── users/           # User management module
│   │   ├── chat/            # Chat completions module
│   │   ├── projects/        # Projects module
│   │   ├── tasks/           # Tasks module
│   │   ├── files/           # File management module
│   │   ├── experts/         # AI experts module
│   │   ├── notifications/   # Notifications module
│   │   ├── company/         # Company settings module
│   │   ├── mcp-servers/     # MCP servers module
│   │   ├── api-tokens/      # API token management module
│   │   ├── dashboard/       # Dashboard metrics module
│   │   ├── secrets/         # Secret management module
│   │   ├── permissions/     # Permissions (stub)
│   │   ├── audit/           # Audit logs (stub)
│   │   ├── organization/    # Organization (stub)
│   │   ├── app-runtime/     # App runtime (stub)
│   │   ├── prompts/         # Prompts (stub)
│   │   ├── fetch-cache/     # Fetch & cache (stub)
│   │   └── ...              # Other modules
│   └── dist/                # Built output (ESM + CJS + types)
├── react/                   # React hooks & components (@cpod/react)
└── tokens/                  # Design tokens (@cpod/tokens)

docs/
├── overview-sdk.md          # Complete capability overview
├── QUICK-REFERENCE.md       # Quick reference (all functions)
├── SDK-REFERENCE.md         # Detailed API reference
├── ROADMAP.md               # Feature status & roadmap
├── nextjs-installation.md   # Next.js setup guide
├── api-reference.md         # Backend API documentation
├── design-guide.md          # Design system guide
├── modules/                 # Per-module documentation (20 files)
└── examples/                # React component examples
Copy

CLI Tool

The @cpod/cli package provides tools to scaffold, validate, and bundle CyberPod apps.

Install

npm install -g @cpod/cli
Copy

Quick Start

# Create a new app
cpod-apps create my-app

# Develop
cd my-app
npm install
npm run dev

# Bundle for deployment
cpod-apps bundle
Copy

Commands

Command	Description
cpod-apps create [name]	Scaffold a new app
cpod-apps validate [path]	Validate app or bundle
cpod-apps bundle [path]	Create deployment bundle
cpod-apps keygen	Generate signing keys
cpod-apps doctor	Check environment

See CLI Documentation for details.

Related Packages

Package	Description
@cpod/sdk	Core SDK with all API functions
@cpod/cli	CLI for app scaffolding and bundling
@cpod/react	React hooks and components
@cpod/tokens	Design tokens and Tailwind preset

License

MIT