Installation & Setup

This guide will walk you through installing and setting up the CKBox Node.js SDK in your project. By the end of this guide, you’ll have the SDK installed and be ready to make your first API calls.

Prerequisites

Before installing the CKBox Node.js SDK, ensure your environment meets these requirements:

Node.js: Version 16.0.0 or higher
Package Manager: npm, yarn, or pnpm
Module System: ES modules support (the SDK is designed for modern Node.js applications)

Package Installation

Using npm

npm install @ckbox/sdk-node

Using yarn

yarn add @ckbox/sdk-node

Using pnpm

pnpm add @ckbox/sdk-node

Obtaining Access Credentials

Before you can use the SDK, you need to obtain your API credentials from the CKBox Customer Portal.

What is an Access Key?

The Access Key is a secret credential that authenticates your application with CKBox services. It’s used to generate JWT tokens that authorize API requests. This key should be kept secure and never exposed in client-side code.

Getting Your Credentials

Log in to Customer Portal
- Visit the Customer Portal
- Sign in with your account credentials
Navigate to API Credentials
- Go to the Subscription -> Cloud environments
- Select “Access credentials” from the sidebar
Create or Copy Access Key
- If you don’t have an access key, click “Create a new access key”
- Copy your existing access key if you already have one
Get Environment ID
- In the Cloud environments tab copy the Environment ID for the environment you want to use
- You can have multiple environments (e.g., development, staging, production)

Security Best Practices

⚠️ Never commit your access key to version control

Store your credentials using environment variables:

# .env file (add to .gitignore)
CKBOX_ACCESS_KEY=your_access_key_here
CKBOX_ENVIRONMENT_ID=your_environment_id_here

Basic Setup

1. Import the SDK

// ES modules (recommended)
import CKBox from '@ckbox/sdk-node';

// CommonJS (if needed)
const { default: CKBox } = require('@ckbox/sdk-node');

2. Configure Environment Variables

Create a .env file in your project root:

# Required credentials
CKBOX_ACCESS_KEY=your_access_key_here
CKBOX_ENVIRONMENT_ID=your_environment_id_here

# Optional settings
CKBOX_WORKSPACE_ID=your_workspace_id
CKBOX_SERVICE_ORIGIN=https://api.ckbox.io

3. Initialize the SDK

import CKBox from '@ckbox/sdk-node';
import 'dotenv/config'; // Load environment variables

// Basic configuration
const ckbox = new CKBox({
  accessKey: process.env.CKBOX_ACCESS_KEY,
  environmentId: process.env.CKBOX_ENVIRONMENT_ID
});

// Access the main components
const { uploader, assets } = ckbox;

Step-by-Step First Implementation

Let’s create a complete example that demonstrates uploading a file and retrieving it:

1. Create Project Structure

mkdir ckbox-example
cd ckbox-example
npm init -y
npm install @ckbox/sdk-node dotenv

2. Bootstrap CKBox object

// upload-example.js
import 'dotenv/config';
import fs from 'fs';
import CKBox from '@ckbox/sdk-node';

export const ckbox = new CKBox({
  accessKey: process.env.CKBOX_ACCESS_KEY,
  environmentId: process.env.CKBOX_ENVIRONMENT_ID,
  // Optional: specify user context
  userId: 'user-123',
  userName: 'John Doe',
  role: 'user'
});

3. Create Your First Upload Script

// upload-example.js
...

async function uploadFile() {
  try {
    // Upload a file with progress tracking
    console.log('Starting file upload...');
    
    const result = await ckbox.uploader.uploadFile('./sample-image.jpg', {
      onProgress: (progress) => {
        console.log(`Upload progress: ${progress.progress}%`);
      }
    });
    
    console.log('Upload successful!');
    console.log('Asset ID:', result.id);
    console.log('File URL:', result.url);
    
    return result;
  } catch (error) {
    console.error('Upload failed:', error.message);
    throw error;
  }
}

// Run the upload
uploadFile()
  .then(asset => {
    console.log('✅ Upload completed successfully');
  })
  .catch(error => {
    console.error('❌ Upload failed:', error);
  });

4. Test Your Setup

# Add a test image to your project directory
# Run the upload script
node upload-example.js