cloudingsdk

CloudingSDK

TypeScript/JavaScript SDK for Clouding.io - A comprehensive cloud infrastructure management platform.

Table of Contents

• Installation
• Quick Start
• Authentication
• API Reference
• Examples
• Error Handling
• TypeScript Support
• Contributing
• License

Installation

npm install cloudingsdk

yarn add cloudingsdk

pnpm add cloudingsdk

Quick Start

import CloudingSDK from 'cloudingsdk';

// Initialize the SDK
const clouding = new CloudingSDK('your-api-key');

// List all servers
const servers = await clouding.servers.getServers();
console.log('Servers:', servers);

// Create a new server
const newServer = await clouding.servers.createServer({
  name: 'my-server',
  hostname: 'my-server.example.com',
  flavorId: '1x2',
  accessConfiguration: {
    sshKeyId: 'your-ssh-key-id',
    password: null,
    savePassword: false
  },
  volume: {
    source: 'image',
    id: 'image-id',
    ssdGb: 25
  },
  publicPortFirewallIds: ['firewall-id']
});

Authentication

The SDK uses API key authentication. You can obtain your API key from the Clouding Portal.

// Basic initialization
const clouding = new CloudingSDK('your-api-key');

// Custom base URL (optional)
const clouding = new CloudingSDK('your-api-key', 'https://api.clouding.io');

// Access authentication headers
const headers = clouding.getAuthHeaders();

⚠️ Security Note: Never expose your API key in client-side code. Use environment variables or secure configuration management.

API Reference

Account Management

// Get account limits
const limits = await clouding.account.getLimits({ page: 1, pageSize: 20 });

// Get specific limit by name
const serverLimit = await clouding.account.getLimitByName('server');

Actions

// List all actions
const actions = await clouding.actions.getActions({ page: 1, pageSize: 20 });

// Get action by ID
const action = await clouding.actions.getActionById('action-id');

Backups

// List all backups
const backups = await clouding.backups.getBackups();

// Filter backups by server
const serverBackups = await clouding.backups.getBackups({ 
  serverId: 'server-id' 
});

// Get backup by ID
const backup = await clouding.backups.getBackupById('backup-id');

Firewalls

// List firewalls
const firewalls = await clouding.firewalls.getFirewalls();

// Create firewall
const firewall = await clouding.firewalls.createFirewall({
  name: 'My Firewall',
  description: 'Web server firewall'
});

// Create firewall rule
const rule = await clouding.firewalls.createFirewallRule(firewall.id, {
  sourceIp: '0.0.0.0/0',
  protocol: 'tcp',
  description: 'Allow HTTP',
  portRangeMin: 80,
  portRangeMax: 80
});

// Enable/disable rules
await clouding.firewalls.enableFirewallRule('rule-id');
await clouding.firewalls.disableFirewallRule('rule-id');

// Delete firewall
await clouding.firewalls.deleteFirewall('firewall-id');

Images

// List available images
const images = await clouding.images.getImages();

// Get image details
const image = await clouding.images.getImageById('image-id');
console.log('Access methods:', image.accessMethods);

Servers

// List servers
const servers = await clouding.servers.getServers();

// Create server from image
const server = await clouding.servers.createServer({
  name: 'web-server',
  hostname: 'web.example.com',
  flavorId: '2x4',
  accessConfiguration: {
    sshKeyId: 'ssh-key-id',
    password: null,
    savePassword: false
  },
  volume: {
    source: 'image',
    id: 'ubuntu-20-04',
    ssdGb: 50
  },
  backupPreferences: {
    slots: 7,
    frequency: 'OneDay'
  },
  publicPortFirewallIds: ['firewall-id']
});

// Get server details
const serverDetails = await clouding.servers.getServerById('server-id');

// Reinstall server
const reinstalled = await clouding.servers.reinstallServer('server-id', {
  name: 'web-server-v2',
  hostname: 'web-v2.example.com',
  flavorId: '4x8',
  accessConfiguration: {
    sshKeyId: 'new-ssh-key-id',
    password: null,
    savePassword: false
  },
  volume: {
    source: 'image',
    id: 'ubuntu-22-04',
    ssdGb: 100
  }
});

// Delete server
const deleteAction = await clouding.servers.deleteServer('server-id');

Sizes (Flavors & Volumes)

// Get available server flavors
const flavors = await clouding.sizes.getFlavors();

// Get volume size options
const volumeSizes = await clouding.sizes.getVolumeSizes();

Snapshots

// List snapshots
const snapshots = await clouding.snapshots.getSnapshots();

// Get snapshot details
const snapshot = await clouding.snapshots.getSnapshotById('snapshot-id');

// Update snapshot
await clouding.snapshots.updateSnapshot('snapshot-id', {
  name: 'Updated Snapshot',
  description: 'Updated description'
});

// Delete snapshot
const deleteAction = await clouding.snapshots.deleteSnapshot('snapshot-id');

SSH Keys

// List SSH keys
const sshKeys = await clouding.sshKeys.getSSHKeys();

// Create SSH key
const sshKey = await clouding.sshKeys.createSSHKey({
  name: 'my-key',
  publicKey: 'ssh-rsa AAAAB3NzaC1yc2E...'
});

// Generate SSH key on server
const generatedKey = await clouding.sshKeys.generateSSHKey({
  name: 'generated-key'
});

// Delete SSH key
await clouding.sshKeys.deleteSSHKey('key-id');

VPCs (Virtual Private Clouds)

// List VPCs
const vpcs = await clouding.vpcs.getVPCs();

// Create VPC
const vpc = await clouding.vpcs.createVPC({
  name: 'Production Network',
  description: 'Main production VPC',
  subnetCidr: '10.0.0.0/16',
  dnsNameservers: ['8.8.8.8', '8.8.4.4']
});

// Update VPC
await clouding.vpcs.updateVPC('vpc-id', {
  name: 'Updated VPC Name',
  dnsNameservers: ['1.1.1.1', '1.0.0.1']
});

// Set as default VPC
await clouding.vpcs.setVPCAsDefault('vpc-id');

// Delete VPC
await clouding.vpcs.deleteVPC('vpc-id');

Examples

Complete Server Setup

import CloudingSDK from 'cloudingsdk';

const clouding = new CloudingSDK(process.env.CLOUDING_API_KEY!);

async function setupWebServer() {
  try {
    // 1. Create SSH key
    const sshKey = await clouding.sshKeys.generateSSHKey({
      name: 'web-server-key'
    });

    // 2. Create firewall
    const firewall = await clouding.firewalls.createFirewall({
      name: 'Web Server Firewall',
      description: 'HTTP/HTTPS access'
    });

    // 3. Add firewall rules
    await clouding.firewalls.createFirewallRule(firewall.id, {
      sourceIp: '0.0.0.0/0',
      protocol: 'tcp',
      description: 'Allow HTTP',
      portRangeMin: 80,
      portRangeMax: 80
    });

    await clouding.firewalls.createFirewallRule(firewall.id, {
      sourceIp: '0.0.0.0/0',
      protocol: 'tcp',
      description: 'Allow HTTPS',
      portRangeMin: 443,
      portRangeMax: 443
    });

    // 4. Get available images
    const images = await clouding.images.getImages();
    const ubuntuImage = images.images.find(img => 
      img.name.includes('Ubuntu')
    );

    // 5. Create server
    const server = await clouding.servers.createServer({
      name: 'web-server-01',
      hostname: 'web01.example.com',
      flavorId: '2x4',
      accessConfiguration: {
        sshKeyId: sshKey.id,
        password: null,
        savePassword: false
      },
      volume: {
        source: 'image',
        id: ubuntuImage!.id,
        ssdGb: 50
      },
      backupPreferences: {
        slots: 7,
        frequency: 'OneDay'
      },
      publicPortFirewallIds: [firewall.id]
    });

    console.log('Server created:', server.id);
    console.log('SSH Key fingerprint:', sshKey.fingerprint);
    
    return server;
  } catch (error) {
    console.error('Setup failed:', error);
    throw error;
  }
}

setupWebServer();

Monitoring Server Actions

async function monitorServerCreation(serverId: string) {
  const server = await clouding.servers.getServerById(serverId);
  
  if (server.action) {
    console.log(`Action ${server.action.id} status: ${server.action.status}`);
    
    // Poll action status
    while (server.action.status === 'inProgress') {
      await new Promise(resolve => setTimeout(resolve, 5000)); // Wait 5s
      
      const action = await clouding.actions.getActionById(server.action.id);
      console.log(`Action status: ${action.status}`);
      
      if (action.status === 'completed') {
        console.log('Server creation completed!');
        break;
      } else if (action.status === 'failed') {
        console.error('Server creation failed!');
        break;
      }
    }
  }
}

Error Handling

The SDK throws standard JavaScript errors with descriptive messages:

try {
  const server = await clouding.servers.getServerById('invalid-id');
} catch (error) {
  if (error instanceof Error) {
    console.error('API Error:', error.message);
    // Example: "HTTP 404: Not Found"
  }
}

Common Error Patterns

// Wrapper function with retry logic
async function withRetry<T>(
  operation: () => Promise<T>, 
  maxRetries = 3
): Promise<T> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await operation();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      
      const delay = Math.pow(2, i) * 1000; // Exponential backoff
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
  throw new Error('Max retries exceeded');
}

// Usage
const servers = await withRetry(() => clouding.servers.getServers());

TypeScript Support

The SDK is built with TypeScript and provides full type definitions:

import CloudingSDK, { 
  Server, 
  CreateServerRequest, 
  Firewall,
  SSHKey 
} from 'cloudingsdk';

const clouding = new CloudingSDK('api-key');

// Fully typed responses
const servers: Server[] = (await clouding.servers.getServers()).servers;

// Typed request objects
const serverConfig: CreateServerRequest = {
  name: 'typed-server',
  hostname: 'typed.example.com',
  flavorId: '1x2',
  accessConfiguration: {
    sshKeyId: 'key-id',
    password: null,
    savePassword: false
  },
  volume: {
    source: 'image',
    id: 'image-id',
    ssdGb: 25
  },
  publicPortFirewallIds: ['firewall-id']
};

Pagination

Most list endpoints support pagination:

// Basic pagination
const page1 = await clouding.servers.getServers({ page: 1, pageSize: 10 });
const page2 = await clouding.servers.getServers({ page: 2, pageSize: 10 });

// Iterate through all pages
async function getAllServers() {
  const allServers: Server[] = [];
  let page = 1;
  let hasMore = true;
  
  while (hasMore) {
    const response = await clouding.servers.getServers({ 
      page, 
      pageSize: 50 
    });
    
    allServers.push(...response.servers);
    hasMore = response.links.next !== null;
    page++;
  }
  
  return allServers;
}

Environment Configuration

// .env file
CLOUDING_API_KEY=your-api-key-here
CLOUDING_BASE_URL=https://api.clouding.io

// Application
import CloudingSDK from 'cloudingsdk';

const clouding = new CloudingSDK(
  process.env.CLOUDING_API_KEY!,
  process.env.CLOUDING_BASE_URL
);

Rate Limiting

The Clouding API implements rate limiting. The SDK will throw errors for rate limit violations:

try {
  await clouding.servers.getServers();
} catch (error) {
  if (error.message.includes('429')) {
    console.log('Rate limited. Please wait before retrying.');
    // Implement exponential backoff
  }
}

Contributing

• Fork the repository
• Create a feature branch: git checkout -b feature/new-feature
• Make your changes
• Add tests if applicable
• Run the build: npm run build
• Submit a pull request

Development Setup

# Clone the repository
git clone https://github.com/your-org/cloudingsdk.git
cd cloudingsdk

# Install dependencies
npm install

# Build the project
npm run build

# Run tests (when available)
npm test

API Documentation

For detailed API documentation, visit the Clouding API Documentation.

Support

• Documentation: Clouding Docs
• API Reference: API Docs
• Support Portal: Clouding Support
• Community: Clouding Community

License

MIT License - see the LICENSE file for details.

Changelog

v1.0.0

• Initial release
• Complete API coverage for all Clouding.io endpoints
• Full TypeScript support
• Comprehensive error handling
• Bilingual documentation (ES/EN)

Made with ❤️ for the Clouding.io community