npm package: @multicloud-io/client
Description: Customer-facing Multicloud API client with limited field exposure
Author: Multicloud Team
Latest version: 1.0.13

# 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

```bash
npm install @multicloud-io/client
```

## Quick Start

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

```bash
# 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`:

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

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

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

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

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

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

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

```bash
# 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.