Quick Start

Quick Start Guide

Get started with UnboundBytes in under 5 minutes. This guide will walk you through installing the SDK, authenticating, and making your first API call.

Prerequisites

• Node.js 20.x or later
• An UnboundBytes account with API credentials
• A registered tenant

Installation

npm

npm install @unboundbytes/sdk

yarn

yarn add @unboundbytes/sdk

pnpm

pnpm add @unboundbytes/sdk

Basic Usage

1. Import the SDK

   import { UnboundBytesClient } from '@unboundbytes/sdk';

2. Create a client instance

   const client = new UnboundBytesClient({
     auth: {
       type: 'bearer',
       token: 'your-auth-token'
     }
   });

3. Make your first API call

   // Check API health
   const health = await client.healthCheck();
   console.log('API Status:', health.status);
   
   // List devices for your tenant
   const devices = await client.listDevices('ten_your-tenant-id');
   console.log('Devices:', devices);

Authentication Methods

UnboundBytes supports three authentication methods:

Bearer Token (Web Applications)

Best for web applications using OIDC or similar identity providers.

const client = new UnboundBytesClient({
  auth: {
    type: 'bearer',
    token: 'your-jwt-token',
    // Optional: Automatic token refresh
    expiresAt: Date.now() + 3600000, // 1 hour
    refreshHandler: async () => {
      const newToken = await fetchNewToken();
      return { token: newToken, expiresAt: Date.now() + 3600000 };
    }
  }
});

HMAC (Agent Communication)

Required for agent-to-orchestrator communication with signed requests.

const client = new UnboundBytesClient({
  auth: {
    type: 'hmac',
    agentId: 'agt_your-agent-id',
    tenantId: 'ten_your-tenant-id',
    sharedSecret: 'your-shared-secret'
  }
});

API Key (Programmatic Access)

Simplified authentication for scripts and automation.

const client = new UnboundBytesClient({
  auth: {
    type: 'apikey',
    apiKey: 'key_your-api-key',
    tenantId: 'ten_your-tenant-id'
  }
});

Complete Example

Here’s a complete example showing common operations:

import { UnboundBytesClient, APIError } from '@unboundbytes/sdk';

async function main() {
  // Initialize client
  const client = new UnboundBytesClient({
    baseUrl: 'https://api.unboundbytes.com',
    auth: {
      type: 'bearer',
      token: process.env.UB_API_TOKEN!
    },
    timeout: 30000,
    maxRetries: 3
  });

  const tenantId = 'ten_my-tenant';

  try {
    // Get tenant dashboard summary
    const summary = await client.getTenantDashboard(tenantId);
    console.log('Dashboard:', summary);

    // List all devices
    const devices = await client.listDevices(tenantId);
    console.log(`Found ${devices.length} devices`);

    // Get details for first device
    if (devices.length > 0) {
      const device = await client.getDevice(devices[0].deviceId);
      console.log('Device details:', device);

      // List backups for device
      const backups = await client.listDeviceBackups(device.deviceId);
      console.log(`Device has ${backups.length} backups`);
    }

    // List deployments
    const deployments = await client.listDeployments(tenantId);
    console.log(`Found ${deployments.length} deployments`);

  } catch (error) {
    if (error instanceof APIError) {
      console.error(`API Error: ${error.code} - ${error.message}`);
      console.error('Status:', error.statusCode);
    } else {
      throw error;
    }
  }
}

main();

Next Steps

• Installation Guide - Detailed installation instructions
• API Overview - Complete API reference
• Authentication - Deep dive into auth methods
• TypeScript SDK - Full SDK documentation