CloudNexus Node.js SDK

Official Node.js client library for interacting with CloudNexus infrastructure. Supports Node 18+ with full TypeScript definitions and async/await patterns.

Installation

Install the package using your preferred package manager:

bash

npm install @cloudnexus/sdk
# or
yarn add @cloudnexus/sdk
# or
pnpm add @cloudnexus/sdk

ℹ️ Prerequisites

Ensure you have a CloudNexus account and an API key generated from the dashboard. Node.js version 18.0 or higher is required.

Quick Start

Initialize the client and create your first compute instance in under 30 seconds.

javascript

import { CloudNexus } from '@cloudnexus/sdk';

const cn = new CloudNexus({
  apiKey: process.env.CN_API_KEY,
  region: 'us-east-1',
  timeout: 30000
});

async function bootServer() {
  const instance = await cn.compute.createInstance({
    type: 'standard-v2',
    name: 'production-api',
    image: 'ubuntu-22.04-lts',
    tags: ['web', 'production'],
    network: 'private'
  });

  console.log(`Instance created: ${instance.id}`);
  console.log(`Public IP: ${instance.network.ipv4.public}`);
}

bootServer();

Configuration

The SDK can be configured via constructor options or environment variables. Environment variables take precedence when omitted from the constructor.

Option	Env Variable	Type	Default	Description
`apiKey`	`CN_API_KEY`	string	Required	Your secret API key
`region`	`CN_REGION`	string	`us-east-1`	Default deployment region
`timeout`	`CN_TIMEOUT`	number	`30000`	Request timeout in ms
`retries`	`CN_RETRIES`	number	`3`	Automatic retry attempts
`debug`	`CN_DEBUG`	boolean	`false`	Enable verbose logging

Compute & Instances

Manage virtual machines, scaling groups, and deployment environments programmatically.

javascript

// List all instances
const instances = await cn.compute.listInstances({ status: 'running' });

// Restart instance gracefully
await cn.compute.restartInstance('inst_8x92ka3');

// Attach volume
await cn.compute.attachVolume({
  instanceId: 'inst_8x92ka3',
  volumeId: 'vol_29d1mx',
  device: '/dev/sdb'
});

Object Storage

S3-compatible interface for scalable object storage with lifecycle policies and encryption.

javascript

const { Readable } = require('stream');

// Upload file
await cn.storage.uploadObject({
  bucket: 'app-assets',
  key: 'uploads/avatar-2024.png',
  body: Readable.from('file-content'),
  metadata: { contentType: 'image/png' }
});

// Generate pre-signed URL
const url = await cn.storage.presign({
  bucket: 'app-assets',
  key: 'secret-report.pdf',
  expiresIn: 3600
});

Global CDN

Configure edge caching, purge stale content, and manage routing rules.

javascript

// Purge specific paths
await cn.cdn.purge(['/api/v1/*', '/static/images/*']);

// Update cache rules
await cn.cdn.updateCacheRules({
  zoneId: 'z_9a2bx',
  rules: [{
    match: '/assets/**',
    ttl: 86400,
    cacheControl: 'public, immutable'
  }]
});

Error Handling

All SDK methods throw CloudNexusError instances with standardized response codes and retry hints.

javascript

import { CloudNexusError } from '@cloudnexus/sdk';

try {
  await cn.compute.createInstance({ ... });
} catch (err) {
  if (err instanceof CloudNexusError) {
    console.error(`[${err.code}] ${err.message}`);
    console.error(`Request ID: ${err.requestId}`);
    console.error(`Should retry: ${err.shouldRetry}`);
  }
}

⚠️ Rate Limiting

The SDK automatically handles 429 responses with exponential backoff. You can override this via cn.config.rateLimitStrategy.

TypeScript Support

Full type definitions are included out-of-the-box. Import interfaces directly for strict typing.

typescript

import { CloudNexus, ComputeConfig, InstanceResponse } from '@cloudnexus/sdk';

const config: ComputeConfig = {
  type: 'standard-v2',
  name: 'ts-app',
  image: 'ubuntu-22.04',
  autoScale: {
    min: 2,
    max: 10,
    metric: 'cpu_usage',
    threshold: 80
  }
};

const instance: InstanceResponse = await cn.compute.createInstance(config);
console.log(instance.id); // Type-safe!

Authentication

Supports multiple auth strategies including API keys, OAuth2 tokens, and short-lived service account credentials.

javascript

// Using OAuth2 token
const cn = new CloudNexus({
  auth: {
    type: 'oauth2',
    token: process.env.CN_ACCESS_TOKEN,
    refreshToken: process.env.CN_REFRESH_TOKEN
  }
});