@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

pnpm add @serve.zone/api

🎬 Quick Start

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

Service Token Authentication

// 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
});

Identity Management

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

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

📚 Core Operations

🐳 Image Management

// 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();

🌐 Cluster Operations

// 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
});

🔒 Certificate Management

// 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);

🔐 Secret Management

// 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:

// 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

Streaming Operations

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

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

Batch Operations

// 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' })
]);

Error Handling

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:

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

🔌 API Reference

CloudlyApiClient

Main client class for interacting with Cloudly.

Constructor Options

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

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.

Trademarks

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.

Company Information

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 [email protected].

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.