@serve.zone/api 🔌

The powerful API client for Cloudly. Connect your applications to multi-cloud infrastructure with type-safe, real-time communication.

🎯 What is @serve.zone/api?

This is your programmatic gateway to the Cloudly platform. Built with TypeScript, it provides a robust, type-safe interface for managing cloud resources, orchestrating containers, and automating infrastructure operations.

✨ Features

- 🔒 Type-Safe - Full TypeScript support with comprehensive interfaces
- ⚡ Real-Time - WebSocket-based communication for instant updates
- 🔑 Secure Authentication - Token-based identity management
- 📦 Resource Management - Complete control over clusters, images, and services
- 🎭 Multi-Identity - Support for service accounts and user authentication
- 🔄 Reactive Streams - RxJS integration for event-driven programming

🚀 Installation

``bash
pnpm add @serve.zone/api
`

🎬 Quick Start

`typescript
import { CloudlyApiClient } from '@serve.zone/api';

// Initialize the client
const client = new CloudlyApiClient({
registerAs: 'api',
cloudlyUrl: 'https://cloudly.example.com:443'
});

// Start the connection
await client.start();

// Authenticate with a service token
const identity = await client.getIdentityByToken('your-service-token', {
tagConnection: true,
statefullIdentity: true
});

console.log('🎉 Connected as:', identity.name);
`

🔐 Authentication

$3

`typescript
// Authenticate using a service token
const identity = await client.getIdentityByToken(serviceToken, {
tagConnection: true, // Tag this connection with the identity
statefullIdentity: true // Maintain state across reconnections
});
`

$3

`typescript
// Get current identity
const currentIdentity = client.identity;

// Check permissions
if (currentIdentity.permissions.includes('cluster:write')) {
// Perform cluster operations
}
`

📚 Core Operations

$3

`typescript
// Create an image entry
const image = await client.images.createImage({
name: 'my-app',
description: 'Production application image'
});

// Push a new version
const imageStream = fs.createReadStream('app.tar');
await image.pushImageVersion('2.0.0', imageStream);

// List all images
const images = await client.images.listImages();
`

$3

`typescript
// Get cluster configuration
const clusterConfig = await client.getClusterConfigFromCloudlyByIdentity(identity);

// Deploy to cluster
await client.deployToCluster({
clusterName: 'production',
serviceName: 'api-service',
image: 'my-app:2.0.0',
replicas: 3
});
`

$3

`typescript
// Request SSL certificate
const certificate = await client.getCertificateForDomain({
domainName: 'api.example.com',
type: 'ssl',
identity: identity
});

// Use certificate in your application
console.log('Certificate:', certificate.cert);
console.log('Private Key:', certificate.key);
`

$3

`typescript
// Create secret group
const secretGroup = await client.secrets.createSecretGroup({
name: 'api-secrets',
secrets: [
{ key: 'DATABASE_URL', value: 'postgres://...' },
{ key: 'REDIS_URL', value: 'redis://...' }
]
});

// Retrieve secrets
const secrets = await client.secrets.getSecretGroup('api-secrets');
`

🔄 Real-Time Updates

Subscribe to configuration changes and server actions using RxJS:

`typescript
// Listen for configuration updates
client.configUpdateSubject.subscribe({
next: (config) => {
console.log('📡 Configuration updated:', config);
// React to configuration changes
}
});

// Handle server action requests
client.serverActionSubject.subscribe({
next: (action) => {
console.log('⚡ Server action:', action.type);
// Process server-initiated actions
}
});
`

🎯 Advanced Usage

$3

`typescript
// Stream logs from a service
const logStream = await client.logs.streamLogs({
service: 'api-service',
follow: true
});

logStream.on('data', (log) => {
console.log(log.message);
});
`

$3

`typescript
// Deploy multiple services
const deployments = await Promise.all([
client.deploy({ service: 'frontend', image: 'app:latest' }),
client.deploy({ service: 'backend', image: 'api:latest' }),
client.deploy({ service: 'worker', image: 'worker:latest' })
]);
`

$3

`typescript
try {
await client.start();
} catch (error) {
if (error.code === 'AUTH_FAILED') {
console.error('Authentication failed:', error.message);
} else if (error.code === 'CONNECTION_LOST') {
console.error('Connection lost, retrying...');
await client.reconnect();
}
}
`

🧹 Cleanup

Always gracefully disconnect when done:

`typescript
// Stop the client connection
await client.stop();
console.log('✅ Disconnected cleanly');
`

🔌 API Reference

$3

Main client class for interacting with Cloudly.

#### Constructor Options

`typescript
interface ICloudlyApiClientOptions {
registerAs: TClientType; // 'api' | 'cli' | 'web'
cloudlyUrl: string; // Full URL including protocol and port
}
`

#### Methods

- start() - Initialize connection
- stop() - Close connection
- getIdentityByToken() - Authenticate with token
- getClusterConfigFromCloudlyByIdentity() - Get cluster configuration
- getCertificateForDomain() - Request SSL certificate
- images - Image management namespace
- secrets - Secret management namespace
- clusters - Cluster management namespace

🎬 Complete Example

`typescript
import { CloudlyApiClient } from '@serve.zone/api';

async function main() {
// Initialize client
const client = new CloudlyApiClient({
registerAs: 'api',
cloudlyUrl: 'https://cloudly.example.com:443'
});

try {
// Connect and authenticate
await client.start();
const identity = await client.getIdentityByToken(process.env.SERVICE_TOKEN, {
tagConnection: true,
statefullIdentity: true
});

// Create and deploy an image
const image = await client.images.createImage({
name: 'my-service',
description: 'Microservice application'
});

// Push image version
const stream = getImageStream(); // Your image stream
await image.pushImageVersion('1.0.0', stream);

// Deploy to cluster
await client.deployToCluster({
clusterName: 'production',
serviceName: 'my-service',
image: 'my-service:1.0.0',
replicas: 3,
environment: {
NODE_ENV: 'production'
}
});

console.log('✅ Deployment successful!');

} catch (error) {
console.error('❌ Error:', error);
} finally {
await client.stop();
}
}

main();
``

License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the license file within this repository.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

$3

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

$3

Task Venture Capital GmbH
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.