Multicloud Connection Library (TypeScript/JavaScript)

A comprehensive TypeScript/JavaScript library for connecting to Multicloud servers with mTLS authentication, configuration management, and full REST API support.

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

🚀 Quick Start

$3

``bash
npm install @multicloud/connection-js
`

$3

`typescript
import { MulticloudConfig, MulticloudRESTClient } from '@multicloud/connection-js';

// Basic usage with default configuration
const params = MulticloudConfig.getConnectionParams();
const client = new MulticloudRESTClient(params);
const clusters = await client.getClusters();
`

$3

`typescript
import { createMulticloudClient, isMulticloudEnabled } from '@multicloud/connection-js';

// Check if multicloud is configured
if (isMulticloudEnabled()) {
// Create client with defaults
const client = createMulticloudClient({ debug: true });
const clusters = await client.getClusters();
} else {
// Use fallback/mock data
}
`

📖 Features

$3


- Multiple Configuration Sources: Environment variables, YAML files, and direct parameters
- Precedence Handling: Direct overrides > Environment variables > Config file > Defaults
- Variable Substitution: Support for ${variable} syntax in YAML files
- Flexible Environment Prefixes: Customize environment variable names per project

$3

- mTLS Client Certificates: Full support for mutual TLS authentication
- JWT Access Tokens: Support for Keycloak-issued JWT tokens via Authorization header
- SSL Verification Controls: Enable/disable SSL verification for development
- Certificate Management: Automatic certificate loading with proper error handling
- Security Validation: Production mode requires certificates

$3

- Complete API Coverage: All Multicloud endpoints (clusters, jobs, servers)
- Proper Error Handling: Structured exceptions for different error types
- Connection Testing: Built-in connectivity diagnostics
- Timeout Management: Configurable request timeouts
- Debug Logging: Optional verbose logging for troubleshooting

🔧 Configuration

$3

The library supports configurable environment variable prefixes (default: MULTICLOUD_):

`bash


Default prefix (MULTICLOUD_)

MULTICLOUD_URL=https://backend.multicloud.io:8443
MULTICLOUD_CLIENT_CERT=/path/to/client.crt
MULTICLOUD_CLIENT_KEY=/path/to/client.key
MULTICLOUD_VERIFY_SSL=false
MULTICLOUD_TIMEOUT=15000
MULTICLOUD_DEBUG=true

Custom prefix (MY_APP_MULTICLOUD_)

MY_APP_MULTICLOUD_URL=https://backend.multicloud.io:8443
MY_APP_MULTICLOUD_CLIENT_CERT=/path/to/client.crt

... etc

`

$3

Default location: ~/.multicloud/config.yaml

`yaml
multicloud_url: https://backend.multicloud.io:8443
verify_ssl: false
timeout: 15
debug: false

certificates:
dir: ~/.multicloud
client-cert: ${dir}/multicloud-client.crt
client-key: ${dir}/multicloud-client.key
`

$3

1. Direct overrides (highest priority)
2. Environment variables
3. Configuration file
4. Default values (lowest priority)

🛠️ API Reference

$3

`typescript
// Get connection parameters with default settings
const params = MulticloudConfig.getConnectionParams();

// Get connection parameters with overrides
const params = MulticloudConfig.getConnectionParams(
{ debug: true, timeout: 10000 },
{ envPrefix: 'MY_APP_MULTICLOUD_' }
);

// Check if multicloud is enabled
const enabled = MulticloudConfig.isEnabled();

// Get configuration info for debugging
const info = MulticloudConfig.getConfigInfo();
`

$3

`typescript
const client = new MulticloudRESTClient(params);

// Test connection
const connected = await client.testConnection();

// Cluster operations
const clusters = await client.getClusters();
const appClusters = await client.getApplicationClusters(1);
const cluster = await client.getCluster(123);

// Job operations
const jobs = await client.getJobs();
const job = await client.getJob(456);
const newJob = await client.createJob({ name: 'My Job', clusterId: 123 });

// Server operations
const servers = await client.getServers();
const server = await client.getServer(789);
await client.restartServer(789);
`

$3

`typescript
// Frontend passes access token after user login to Keycloak
const client = createMulticloudClient({
accessToken: userJwtToken // Obtained from Keycloak after user authentication
});

// Updating token dynamically (e.g., after token refresh)
client.setAccessToken(newAccessToken);

// Clearing token (e.g., on user logout)
client.clearAccessToken();

// Mixed authentication (mTLS + JWT for service-to-service + user context)
const client = createMulticloudClient({
clientCert: '/path/to/cert.pem',
clientKey: '/path/to/key.pem',
accessToken: userJwtToken // User's JWT token from frontend login
});
`

$3

`typescript
import {
MulticloudConnectionError,
MulticloudAuthenticationError,
MulticloudConfigurationError,
MulticloudNetworkError,
MulticloudResponseError
} from '@multicloud/connection-js';

try {
const client = createMulticloudClient();
const clusters = await client.getClusters();
} catch (error) {
if (error instanceof MulticloudAuthenticationError) {
// Handle certificate/auth issues
} else if (error instanceof MulticloudNetworkError) {
// Handle network/connectivity issues
} else if (error instanceof MulticloudConfigurationError) {
// Handle configuration problems
}
}
`

🌍 Multi-Project Usage

$3

`typescript
// Project A uses default prefix
const clientA = createMulticloudClient();

// Project B uses custom prefix
const clientB = createMulticloudClient(
{},
{ envPrefix: 'PROJECT_B_MULTICLOUD_' }
);
`

$3

`typescript
const client = createMulticloudClient(
{},
{ configFile: '/etc/myapp/multicloud.yaml' }
);
`

$3

`typescript
const client = createMulticloudClient(
{},
{ isProduction: process.env.NODE_ENV === 'production' }
);
`

🧪 Testing and Development

$3

`bash
npm run build
`

$3

`bash
npm run build:watch
`

$3

`bash
npm test
`

📦 Integration Examples

$3

`typescript
// pages/api/clusters.ts
import { createMulticloudClient, isMulticloudEnabled } from '@multicloud/connection-js';

export default async function handler(req, res) {
try {
if (!isMulticloudEnabled()) {
return res.status(503).json({ error: 'Multicloud not configured' });
}

const client = createMulticloudClient();
const clusters = await client.getClusters();
res.json(clusters);
} catch (error) {
console.error('Multicloud error:', error);
res.status(500).json({ error: 'Failed to fetch clusters' });
}
}
`

$3

`typescript
import express from 'express';
import { createMulticloudClient } from '@multicloud/connection-js';

const app = express();

app.get('/api/clusters', async (req, res) => {
try {
const client = createMulticloudClient();
const clusters = await client.getClusters();
res.json(clusters);
} catch (error) {
res.status(500).json({ error: error.message });
}
});
`

$3

`typescript
#!/usr/bin/env node
import { createMulticloudClient, MulticloudConnectionError } from '@multicloud/connection-js';

async function main() {
try {
const client = createMulticloudClient({ debug: true });
const clusters = await client.getClusters();

console.log('Available clusters:');
clusters.forEach(cluster => {
console.log(- ${cluster.name} (${cluster.region}));
});
} catch (error) {
if (error instanceof MulticloudConnectionError) {
console.error('Failed to connect to Multicloud:', error.message);
process.exit(1);
}
throw error;
}
}

main().catch(console.error);
`

🔍 Debugging

$3

`typescript
const client = createMulticloudClient({ debug: true });
`

$3

`typescript
import { MulticloudConfig } from '@multicloud/connection-js';

const info = MulticloudConfig.getConfigInfo();
console.log('Configuration info:', info);
`

$3

`typescript
const client = createMulticloudClient();
try {
const connected = await client.testConnection();
console.log('Connection test:', connected ? 'SUCCESS' : 'FAILED');
} catch (error) {
console.error('Connection test failed:', error.message);
}
`

🤝 Contributing

1. Install dependencies: npm install
2. Make changes: Edit source files in src/
3. Build: npm run build
4. Test: npm test`
5. Submit PR: Create a pull request with your changes

📄 License

MIT - See LICENSE file for details.

🔗 Related Documentation

- Python Version - Python implementation of the same library
- Connection Guide - Detailed connection documentation
- Multi-Project Usage - Advanced usage patterns