@multicloud-io/client

Multicloud Client

A TypeScript/JavaScript library for customer-facing operations with Multicloud servers. This package provides only customer API methods with limited field exposure for security.

IMPORTANT: This library is designed for server-side use only. Never expose Multicloud credentials or use this library in client/browser environments.

Features

• Customer-only operations: Only customer-facing API methods are exposed
• Limited field exposure: Uses customer JSON views to hide sensitive data
• mTLS authentication: Secure client certificate authentication
• TypeScript support: Full TypeScript definitions included
• Configuration management: Environment-based configuration

Installation

npm install @multicloud-io/client

Quick Start

import { MulticloudConfig, MulticloudClient } from '@multicloud-io/client';

// Basic usage with default configuration
const params = MulticloudConfig.getConnectionParams();
const client = new MulticloudCustomerClient(params);

// Get jobs for an application
const jobs = await client.getCustomerJobs('my-app');

// Get tasks for specific jobs
const tasks = await client.getCustomerTasks('my-app', new Set([1, 2, 3]));

Configuration

The library uses environment variables for configuration:

# Required
MULTICLOUD_SERVER_URL=https://your-multicloud-server.com

# Optional
MULTICLOUD_ACCESS_TOKEN=your-access-token
MULTICLOUD_CLIENT_CERT_PATH=/path/to/client.crt
MULTICLOUD_CLIENT_KEY_PATH=/path/to/client.key
MULTICLOUD_DEBUG=true

Or use a configuration file at ~/.multicloud/config.yaml:

serverUrl: https://your-multicloud-server.com
accessToken: your-access-token
clientCert: /path/to/client.crt
clientKey: /path/to/client.key
debug: true

Available Methods

Health Check

• pingCustomer() - Test connection to customer API

Job Management

• getCustomerJobs(applicationId, clusterId?) - Get jobs for an application
• addCustomerJobs(jobDescs, applicationId, clusterId) - Add jobs to a cluster
• customerJobAction(jobId, action, applicationId, clusterId, scaleBy?) - Perform job actions

Cluster Management

• getCustomerClusters(applicationId, clusterId?) - Get clusters for an application
• getCustomerClusterLocations(applicationId, clusterId) - Get cluster locations

Task Management

• getCustomerTasks(applicationId, jobIds?, clusterId?) - Get tasks for an application

Server Information

• getCustomerServers(applicationId, clusterId?) - Get basic server information

Utility Functions

import { createMulticloudClient, isMulticloudEnabled } from '@multicloud-io/client';

// Quick client creation
const client = createMulticloudCustomerClient({ debug: true });

// Check if multicloud is enabled
if (isMulticloudEnabled()) {
  // Use multicloud
} else {
  // Use fallback
}

Security

This package is designed with security in mind:

• Server-side only: Never use in browser environments
• Limited exposure: Only customer-facing methods are available
• Field filtering: Sensitive fields are automatically filtered out
• Authentication required: All operations require proper authentication

Examples

Get Application Jobs

const client = new MulticloudCustomerClient(params);

// Get all jobs for an application
const jobs = await client.getCustomerJobs('my-application');

// Get jobs for a specific cluster
const clusterJobs = await client.getCustomerJobs('my-application', 'cluster-1');

Manage Tasks

// Get tasks for specific job IDs
const jobIds = new Set([1, 2, 3]);
const tasks = await client.getCustomerTasks('my-application', jobIds);

// Get all tasks for an application
const allTasks = await client.getCustomerTasks('my-application');

Add Jobs

const jobDescs = [
  {
    name: 'my-job',
    image: 'nginx:latest',
    targetInstanceCount: 2,
    command: 'echo "Hello World"'
  }
];

const result = await client.addCustomerJobs(jobDescs, 'my-application', 'cluster-1');

Job Actions

// Start a job
await client.customerJobAction('job-1', 'start', 'my-application', 'cluster-1');

// Scale a job
await client.customerJobAction('job-1', 'scale', 'my-application', 'cluster-1', 3);

// Stop a job
await client.customerJobAction('job-1', 'stop', 'my-application', 'cluster-1');

Error Handling

The library provides specific error types:

import { 
  MulticloudConnectionError,
  MulticloudAuthenticationError,
  MulticloudNetworkError,
  MulticloudResponseError
} from '@multicloud-io/client';

try {
  const jobs = await client.getCustomerJobs('my-app');
} catch (error) {
  if (error instanceof MulticloudAuthenticationError) {
    // Handle authentication errors
  } else if (error instanceof MulticloudNetworkError) {
    // Handle network errors
  }
}

Development

# Install dependencies
npm install

# Build the package
npm run build

# Run tests
npm test

# Watch mode for development
npm run build:watch

License

MIT License - see LICENSE file for details.