cloudly/ts_apiclient/readme.md

# @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

### Service Token Authentication

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

### Identity Management

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

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

## 📚 Core Operations

### 🐳 Image Management

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

### 🌐 Cluster Operations

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

### 🔒 Certificate Management

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

### 🔐 Secret Management

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

### Streaming Operations

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

### Batch Operations

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

### Error Handling

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

### CloudlyApiClient

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](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 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.