@serve.zone/interfaces 5.0.4 → 5.3.0

package/ts_interfaces/readme.md

@@ -1,207 +1,375 @@
-# @serve.zone/interfaces
+# @serve.zone/interfaces 📋
 
-interfaces for working with containers
+**TypeScript interfaces for the Cloudly ecosystem.** Type-safe contracts for multi-cloud infrastructure management.
 
-## Install
+## 🎯 What is @serve.zone/interfaces?
 
-To install `@serve.zone/interfaces`, run the following command in your terminal:
+This package provides the complete set of TypeScript interfaces that power the Cloudly platform. It ensures type safety and consistency across all components - from API requests to data models, from service definitions to infrastructure configurations.
+
+## ✨ Features
+
+- **🔒 Type Safety** - Comprehensive TypeScript interfaces for all Cloudly operations
+- **📦 Modular Structure** - Organized by domain for easy navigation
+- **🔄 Version Compatibility** - Interfaces versioned with the platform
+- **📚 Well Documented** - Each interface includes JSDoc comments
+- **🎭 Multi-Purpose** - Used by API clients, CLI tools, and web interfaces
+- **✅ Validation Ready** - Compatible with runtime type checking libraries
+
+## 🚀 Installation
 
 ```bash
-npm install @serve.zone/interfaces --save
+pnpm add @serve.zone/interfaces
 ```
 
-This will add `@serve.zone/interfaces` to your project's dependencies, allowing you to import and use various predefined interfaces that facilitate container operations and interactions within the ServeZone ecosystem.
+## 🏗️ Interface Categories
 
-## Usage
+### 📡 Request/Response Interfaces
 
-The `@serve.zone/interfaces` module provides a robust set of TypeScript interfaces designed to standardize interaction with various services and components in a cloud-native environment. The interfaces are targeted at simplifying the integration process with container orchestration, network configurations, logging, and service definitions. The module is particularly useful if you're working on infrastructure or service orchestration solutions using Node.js and TypeScript.
+Typed contracts for API communication:
 
-This document guides you through a comprehensive use case scenario of `@serve.zone/interfaces`. We will cover how to effectively utilize these interfaces to set up cloud services, manage application configurations, and handle system-related communications. This tutorial will explore various feature sets within the module, focusing on real-world implementations and practical coding strategies.
+```typescript
+import { 
+  IRequest_GetAllImages,
+  IRequest_CreateCluster,
+  IRequest_DeployService 
+} from '@serve.zone/interfaces';
+
+// Type-safe request
+const request: IRequest_GetAllImages['request'] = {
+  identity: userIdentity,
+  filters: {
+    tag: 'production'
+  }
+};
 
-### Prerequisites
+// Type-safe response
+const response: IRequest_GetAllImages['response'] = {
+  images: [...]
+};
+```
 
-Before diving in, make sure to satisfy the following prerequisites:
+### 📦 Data Models
 
-- **Node.js**: Ensure you have Node.js installed (preferably the latest LTS version).
-  
-- **TypeScript**: Your environment should support TypeScript, as this module leverages strong typing offered by TypeScript.
-  
-- **Cloud Account Access**: Some of the interfaces interact with live cloud services; thus, ensure you have necessary credentials (like API tokens) available for testing or integration.
+Core data structures for Cloudly entities:
 
-### Core Interfaces and Scenarios
+```typescript
+import { 
+  ICluster, 
+  IService, 
+  IImage, 
+  ISecret,
+  IServer 
+} from '@serve.zone/interfaces';
+
+// Define a service
+const service: IService = {
+  id: 'service-123',
+  data: {
+    name: 'api-service',
+    imageId: 'image-456',
+    imageVersion: '2.0.0',
+    environment: {
+      NODE_ENV: 'production'
+    },
+    scaleFactor: 3,
+    balancingStrategy: 'round-robin',
+    ports: {
+      web: 80,
+      metrics: 9090
+    },
+    domains: [
+      { name: 'api.example.com' }
+    ],
+    deploymentIds: [],
+    deploymentDirectiveIds: []
+  }
+};
+```
 
-#### 1. Handling Typed Requests
+### 🔐 Authentication & Identity
 
-One fundamental aspect is defining typed requests, which standardizes API call definitions across different microservices or components. The module offers interfaces such as `IRequest_GetAllImages`, `IRequest_CreateCluster`, that you can extend or implement within your service logic to ensure strong typing and consistency.
+Identity management interfaces:
 
 ```typescript
-import { IRequest_GetAllImages } from '@serve.zone/interfaces/requests/image';
+import { 
+  IIdentity, 
+  IServiceToken,
+  IPermission 
+} from '@serve.zone/interfaces';
+
+const identity: IIdentity = {
+  id: 'user-789',
+  name: 'service-account',
+  type: 'service',
+  permissions: ['cluster:read', 'service:write'],
+  tokenHash: 'hashed-token',
+  metadata: {
+    createdAt: new Date(),
+    lastAccess: new Date()
+  }
+};
+```
 
-class ImageService {
-  private cloudlyClient;
+### 🌐 Network Configuration
 
-  constructor(cloudlyClient: CloudlyApiClient) {
-    this.cloudlyClient = cloudlyClient;
-  }
+Networking and routing interfaces:
 
-  public async fetchAllImages() {
-    const request: IRequest_GetAllImages['request'] = {
-      identity: this.cloudlyClient.identity,
-    };
-    const response = await this.cloudlyClient.typedsocketClient.fireTypedRequest<IRequest_GetAllImages>(request);
-    return response.images;
+```typescript
+import { 
+  IReverseProxyConfig,
+  IDomainConfig,
+  ILoadBalancerConfig 
+} from '@serve.zone/interfaces';
+
+const proxyConfig: IReverseProxyConfig = {
+  domain: 'app.example.com',
+  path: '/api',
+  serviceAddress: 'http://api-service:3000',
+  ssl: true,
+  headers: {
+    'X-Real-IP': '$remote_addr'
   }
-}
+};
 ```
 
-In the above code, we structured a simple function to retrieve all images from a service, assuming the `cloudlyClient` is your authenticated API client. The typed request interface ensures that both the request and response align with the expected types.
+### 📊 Monitoring & Metrics
 
-#### 2. Logging and Smart Logging Interfaces
-
-Logging is a crucial aspect of cloud applications. The module provides interfaces to assist in integrating logging systems like `@push.rocks/smartlog-interfaces`.
+Observability interfaces:
 
 ```typescript
-import { ILogger, ILogConfig } from '@push.rocks/smartlog-interfaces';
+import { 
+  IServerMetrics,
+  IServiceMetrics,
+  IClusterHealth 
+} from '@serve.zone/interfaces';
+
+const metrics: IServerMetrics = {
+  serverId: 'server-001',
+  cpuUsageInPercent: 65,
+  memoryUsageinMB: 3072,
+  memoryAvailableInMB: 8192,
+  diskUsageInPercent: 40,
+  networkInMbps: 100,
+  networkOutMbps: 150,
+  containerCount: 12,
+  containerMetrics: [...]
+};
+```
 
-class LoggerService {
-  private logger: ILogger;
+### 🔒 Secret Management
 
-  constructor(logConfig: ILogConfig) {
-    this.logger = new SmartLogger(logConfig);
-  }
+Security and credential interfaces:
 
-  public logMessage(logPackage: ILogPackage) {
-    this.logger.log(logPackage);
+```typescript
+import { 
+  ISecretGroup,
+  ISecretBundle,
+  IEncryptedData 
+} from '@serve.zone/interfaces';
+
+const secretGroup: ISecretGroup = {
+  id: 'secrets-123',
+  name: 'database-credentials',
+  secrets: [
+    {
+      key: 'DB_HOST',
+      value: 'encrypted-value',
+      encrypted: true
+    },
+    {
+      key: 'DB_PASSWORD',
+      value: 'encrypted-value',
+      encrypted: true
+    }
+  ],
+  metadata: {
+    environment: 'production',
+    service: 'api'
   }
-}
+};
 ```
 
-This illustrates a logger service utilizing `ILogConfig` to configure and initiate a logging mechanism. You can log structured data using `logPackage`, thus enhancing traceability and debugging efficiency.
-
-#### 3. Container Service Management
+## 📚 Common Usage Patterns
 
-Managing containers, particularly when dealing with microservices, can be complex, but interfaces like `IService`, `ICluster`, and `IServer` aid in structuring container service management.
+### Creating Type-Safe API Clients
 
 ```typescript
-import { IService } from '@serve.zone/interfaces/data/service';
-
-function defineService(): IService {
-  return {
-    id: 'unique-service-id',
-    data: {
-      name: 'my-container-service',
-      imageId: 'unique-image-id',
-      imageVersion: '1.0.0',
-      environment: { KEY: 'VALUE' },
-      secretBundleId: 'bundle-id',
-      scaleFactor: 2,
-      balancingStrategy: 'round-robin',
-      ports: { web: 80 },
-      domains: [{ name: 'example.com' }],
-      deploymentIds: [],
-      deploymentDirectiveIds: [],
-    }
-  };
+import { 
+  IRequest_CreateService,
+  IService 
+} from '@serve.zone/interfaces';
+
+class ServiceClient {
+  async createService(
+    serviceData: IService['data']
+  ): Promise<IService> {
+    const request: IRequest_CreateService['request'] = {
+      identity: this.identity,
+      serviceData
+    };
+    
+    const response = await this.client.send<IRequest_CreateService>(
+      'createService',
+      request
+    );
+    
+    return response.service;
+  }
 }
 ```
 
-In the example, a service definition is drafted, encapsulating critical service metadata, including its environment variables, domain configuration, and load balancing strategy. Adhering to `IService` ensures that all necessary service data is encapsulated correctly.
-
-#### 4. Network Configuration and Routing
-
-Networking is integral to cloud-native applications. Interfaces in `@serve.zone/interfaces` help shape network interaction patterns.
+### Validating Incoming Data
 
 ```typescript
-import { IReverseProxyConfig } from '@serve.zone/interfaces/data/traffic';
+import { ICluster } from '@serve.zone/interfaces';
+import { validateType } from 'your-validation-library';
 
-const proxyConfig: IReverseProxyConfig = {
-  domain: 'example.com',
-  path: '/',
-  serviceAddress: 'http://service:8080',
-  ssl: true,
-};
-
-function configureProxy() {
-  // Logic to apply the proxyConfig, potentially using Typedi, Smartclient, or similar libraries.
+function validateClusterData(data: unknown): ICluster {
+  if (!validateType<ICluster>(data)) {
+    throw new Error('Invalid cluster data');
+  }
+  return data;
 }
 ```
 
-Here, `IReverseProxyConfig` is used to define a reverse proxy for a service. Such configurations are necessary for routing external requests into internal services securely.
+### Building Configuration Objects
 
-### Advanced Interface Utilization
+```typescript
+import { 
+  ICloudlyConfig,
+  IMongoDescriptor 
+} from '@serve.zone/interfaces';
+
+const config: ICloudlyConfig = {
+  cfToken: process.env.CF_TOKEN!,
+  hetznerToken: process.env.HETZNER_TOKEN!,
+  environment: 'production',
+  letsEncryptEmail: 'certs@example.com',
+  publicUrl: 'cloudly.example.com',
+  publicPort: 443,
+  mongoDescriptor: {
+    mongoDbUrl: process.env.MONGO_URL!,
+    mongoDbName: 'cloudly',
+    mongoDbUser: process.env.MONGO_USER!,
+    mongoDbPass: process.env.MONGO_PASS!
+  }
+};
+```
 
-#### Monitoring and Metrics Collection
+## 🎯 Advanced Features
 
-For observability, you can track system metrics using `IServerMetrics` or cluster status interfaces.
+### Generic Request Handler
 
 ```typescript
-import { IServerMetrics } from '@serve.zone/interfaces/data/server';
-
-function reportMetrics(metrics: IServerMetrics) {
-  console.log(`CPU Usage: ${metrics.cpuUsageInPercent}%`);
-  console.log(`Memory Usage: ${metrics.memoryUsageinMB}MB`);
+import { ITypedRequest } from '@serve.zone/interfaces';
+
+class RequestHandler {
+  async handle<T extends ITypedRequest>(
+    request: T['request']
+  ): Promise<T['response']> {
+    // Type-safe request handling
+    return this.processRequest(request);
+  }
 }
-
-const sampleMetrics: IServerMetrics = {
-  serverId: 'server-123',
-  cpuUsageInPercent: 45,
-  memoryUsageinMB: 2048,
-  memoryAvailableInMB: 4096,
-  containerCount: 10,
-  containerMetrics: [],
-};
-
-reportMetrics(sampleMetrics);
 ```
 
-Implementing such metrics tracking provides insight into performance bottlenecks and helps strategize scaling decisions.
+### Discriminated Unions
 
-#### Certificate Management
+```typescript
+import { IDeploymentStatus } from '@serve.zone/interfaces';
+
+function handleStatus(status: IDeploymentStatus) {
+  switch (status.type) {
+    case 'pending':
+      console.log('Deployment pending...');
+      break;
+    case 'running':
+      console.log(`Running on ${status.serverId}`);
+      break;
+    case 'failed':
+      console.log(`Failed: ${status.error}`);
+      break;
+  }
+}
+```
 
-To handle SSL certificates programmatically, utilize interfaces such as `IRequest_Any_Cloudly_GetCertificateForDomain`.
+### Extending Interfaces
 
 ```typescript
-import { IRequest_Any_Cloudly_GetCertificateForDomain } from '@serve.zone/interfaces/requests/certificate';
+import { IService } from '@serve.zone/interfaces';
 
-async function fetchCertificate(cloudlyClient: CloudlyApiClient, domainName: string) {
-  const request: IRequest_Any_Cloudly_GetCertificateForDomain['request'] = {
-    identity: cloudlyClient.identity,
-    domainName: domainName,
-    type: 'ssl'
+interface IExtendedService extends IService {
+  customMetadata: {
+    team: string;
+    costCenter: string;
+    sla: 'standard' | 'premium';
   };
-
-  return await cloudlyClient.typedsocketClient.fireTypedRequest<IRequest_Any_Cloudly_GetCertificateForDomain>(request);
 }
 ```
 
-Managing certificates dynamically via typed requests simplifies deployment and automates the security dimensions of your applications.
+## 🔄 Version Compatibility
 
-#### Integrating with External Messaging Services
+| @serve.zone/interfaces | @serve.zone/cloudly | @serve.zone/api | @serve.zone/cli |
+|------------------------|---------------------|-----------------|-----------------|
+| 5.x                    | 5.x                 | 5.x             | 5.x             |
+| 4.x                    | 4.x                 | 4.x             | 4.x             |
+| 3.x                    | 3.x                 | 3.x             | 3.x             |
 
-Use `IRequest_SendEmail` to integrate platform services for sending emails:
+## 📖 Interface Documentation
 
-```typescript
-import { IRequest_SendEmail } from '@serve.zone/interfaces/platformservice/mta';
-
-async function sendNotification(emailClient: any) {
-  const emailRequest: IRequest_SendEmail['request'] = {
-    title: 'Welcome to ServeZone!',
-    from: 'service@company.com',
-    to: 'user@example.com',
-    body: '<h1>Congratulations</h1><p>Your account has been created successfully.</p>',
-  };
+All interfaces include comprehensive JSDoc comments:
 
-  await emailClient.sendEmail(emailRequest);
+```typescript
+/**
+ * Represents a cluster configuration
+ * @interface ICluster
+ */
+export interface ICluster {
+  /**
+   * Unique identifier for the cluster
+   * @type {string}
+   */
+  id: string;
+  
+  /**
+   * Cluster configuration data
+   * @type {IClusterData}
+   */
+  data: IClusterData;
 }
 ```
 
-This approach demonstrates abstracting the email sending functionality using typed interfaces, contributing to code consistency and robustness.
+## 🛠️ Development Tips
 
-### Conclusion
+### Import Organization
 
-The `@serve.zone/interfaces` module equips developers with a set of interfaces tailored for managing containers, orchestrating cloud services, and handling system interactions seamlessly. By applying these interfaces, projects can achieve coherence, reduce coupling, and simplify the integration process across various service domains.
+```typescript
+// Group imports by category
+import { 
+  // Data models
+  ICluster,
+  IService,
+  IImage,
+  
+  // Requests
+  IRequest_CreateCluster,
+  IRequest_DeployService,
+  
+  // Configuration
+  ICloudlyConfig,
+  IReverseProxyConfig
+} from '@serve.zone/interfaces';
+```
+
+### Type Guards
 
-Focusing on practical applications, try extending these interfaces to suit additional requirements in your projects. Engage actively with the module community, or contribute new ideas to enhance the breadth and depth of this interface library. Explore the integration patterns showcased here and contribute toward a sophisticated cloud-native development framework.
+```typescript
+import { IService, ICluster } from '@serve.zone/interfaces';
+
+function isService(entity: IService | ICluster): entity is IService {
+  return 'imageId' in entity.data;
+}
+```
 
 ## License and Legal Information
 
@@ -220,4 +388,4 @@ 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.
+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.

package/ts_interfaces/requests/baremetal.ts

@@ -0,0 +1,22 @@
+import * as plugins from '../plugins.js';
+import type { IBareMetal } from '../data/baremetal.js';
+
+export interface IRequest_Any_Cloudly_GetBaremetalServers {
+  method: 'getBaremetalServers';
+  request: {};
+  response: {
+    baremetals: IBareMetal[];
+  };
+}
+
+export interface IRequest_Any_Cloudly_ControlBaremetal {
+  method: 'controlBaremetal';
+  request: {
+    baremetalId: string;
+    action: 'powerOn' | 'powerOff' | 'reset';
+  };
+  response: {
+    success: boolean;
+    message: string;
+  };
+}

package/ts_interfaces/requests/cluster.ts

@@ -41,6 +41,7 @@ export interface IRequest_CreateCluster extends plugins.typedrequestInterfaces.i
   request: {
     identity: userInterfaces.IIdentity;
     clusterName: string;
+    setupMode?: 'manual' | 'hetzner' | 'aws' | 'digitalocean';
   };
   response: {
     cluster: clusterInterfaces.ICluster;

package/ts_interfaces/requests/deployment.ts

@@ -0,0 +1,141 @@
+import * as plugins from '../plugins.js';
+import type { IDeployment } from '../data/deployment.js';
+import type { IIdentity } from '../data/user.js';
+
+export interface IReq_Any_Cloudly_GetDeploymentById 
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_GetDeploymentById
+> {
+  method: 'getDeploymentById';
+  request: {
+    identity: IIdentity;
+    deploymentId: string;
+  };
+  response: {
+    deployment: IDeployment;
+  };
+}
+
+export interface IReq_Any_Cloudly_GetDeployments
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_GetDeployments
+> {
+  method: 'getDeployments';
+  request: {
+    identity: IIdentity;
+  };
+  response: {
+    deployments: IDeployment[];
+  };
+}
+
+export interface IReq_Any_Cloudly_GetDeploymentsByService
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_GetDeploymentsByService
+> {
+  method: 'getDeploymentsByService';
+  request: {
+    identity: IIdentity;
+    serviceId: string;
+  };
+  response: {
+    deployments: IDeployment[];
+  };
+}
+
+export interface IReq_Any_Cloudly_GetDeploymentsByNode
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_GetDeploymentsByNode
+> {
+  method: 'getDeploymentsByNode';
+  request: {
+    identity: IIdentity;
+    nodeId: string;
+  };
+  response: {
+    deployments: IDeployment[];
+  };
+}
+
+export interface IReq_Any_Cloudly_CreateDeployment
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_CreateDeployment
+> {
+  method: 'createDeployment';
+  request: {
+    identity: IIdentity;
+    deploymentData: Partial<IDeployment>;
+  };
+  response: {
+    deployment: IDeployment;
+  };
+}
+
+export interface IReq_Any_Cloudly_UpdateDeployment
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_UpdateDeployment
+> {
+  method: 'updateDeployment';
+  request: {
+    identity: IIdentity;
+    deploymentId: string;
+    deploymentData: Partial<IDeployment>;
+  };
+  response: {
+    deployment: IDeployment;
+  };
+}
+
+export interface IReq_Any_Cloudly_DeleteDeploymentById
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_DeleteDeploymentById
+> {
+  method: 'deleteDeploymentById';
+  request: {
+    identity: IIdentity;
+    deploymentId: string;
+  };
+  response: {
+    success: boolean;
+  };
+}
+
+export interface IReq_Any_Cloudly_RestartDeployment
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_RestartDeployment
+> {
+  method: 'restartDeployment';
+  request: {
+    identity: IIdentity;
+    deploymentId: string;
+  };
+  response: {
+    success: boolean;
+    deployment: IDeployment;
+  };
+}
+
+export interface IReq_Any_Cloudly_ScaleDeployment
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_ScaleDeployment
+> {
+  method: 'scaleDeployment';
+  request: {
+    identity: IIdentity;
+    deploymentId: string;
+    replicas: number;
+  };
+  response: {
+    success: boolean;
+    deployment: IDeployment;
+  };
+}