Official JS and Python SDKs

[karutoil]

Summary

Create official client SDKs for JavaScript/TypeScript and Python, enabling programmatic server management, automation, and integration with billing panels (WHMCS, Paymenter) and custom tooling.

Current State

• REST API has 100+ endpoints with Zod-validated input/output schemas
• docs/usage-examples.md has cURL, Python, and Node.js snippet examples (manual, not typed)
• docs/automation.md covers webhook + API automation patterns
• @catalyst/plugin-sdk exists for plugin development, but there's no client SDK for external API consumers
• Frontend services/api/ layer is the only typed API client — not reusable externally
• SSO providers WHMCS and Paymenter are already supported in auth

Requirements

JavaScript/TypeScript SDK (@catalyst/client)

• Full type coverage for all API endpoints (generate from OpenAPI spec once Complete OpenAPI/Swagger documentation #138 is complete)
• Authentication helpers: session-based, API key, and token management
• Server lifecycle methods: create, start, stop, restart, kill, delete, clone
• Console streaming (SSE wrapper)
• File management operations
• Backup operations
• Node and template management
• WebSocket client for real-time events
• Tree-shakeable, works in Node.js and browsers

Python SDK (catalyst-client)

• Same API coverage as JS SDK
• Async-first (aiohttp or httpx)
• Type hints for all models and methods
• Context manager for session management
• PyPI package with proper packaging

Shared Requirements

• Generated from OpenAPI spec (or manually maintained with spec validation)
• Versioned in lockstep with the backend API version
• Comprehensive docstrings/JSDoc with examples
• Integration test suite against live API
• Changelog and migration guides for breaking changes

Acceptance Criteria

• @catalyst/client npm package with full endpoint coverage
• catalyst-client PyPI package with full endpoint coverage
• Both SDKs handle authentication (session + API key)
• TypeScript types generated from or validated against OpenAPI spec
• README with quickstart examples for each SDK
• At least 5 integration test scenarios per SDK