@juggernautcloud/cloud

Official Node.js / TypeScript SDK for the Juggernaut Cloud Platform. Execute AI processes, manage cloud database schemas, retrieve job results, and handle file assets with full TypeScript support.

Installation

npm install @juggernautcloud/cloud

Quick Start

import { init, runProcess, getJobResults, DatabaseSchema } from '@juggernautcloud/cloud';

// Initialize once per application lifecycle
init('your-client-id', 'your-api-key');

// Run a process
const job = await runProcess({
  processId: 'process_123',
  inputs: { topic: 'AI Trends' },
  metadata: { source: 'dashboard' }
});

// Poll for completion and get results
const results = await getJobResults(job.jobId);
console.log(results);

Table of Contents

• Initialization
• Process Execution
  • Run a Process
  • Schedule a Process
  • Job Events & Polling
  • Get Job Results
  • Retrieve Job Files
• Database Operations
  • Schema Instance
  • CRUD Operations
  • Bulk Operations
  • Query & Aggregation
  • Public Access Points
• Prompts
• Error Handling
• TypeScript Types

Initialization

import { init } from '@juggernautcloud/cloud';

init(clientId: string, apiKey: string);

Must be called once before any other SDK method. Sets global authentication credentials for all subsequent API calls.

Process Execution

Run a Process

Execute a Juggernaut process pipeline immediately.

import { runProcess } from '@juggernautcloud/cloud';

const job = await runProcess({
  processId: 'your-process-id',
  inputs: {
    market: 'US_EQUITY',
    symbol: 'AAPL'
  },
  metadata: {
    userId: 'user_123',
    traceId: 'trace_456'
  }
  // Optional: accessPoint: 'https://your-endpoint.com'
});

ProcessExecutionOptions

| Property | Type | Required | Description | |----------|------|----------|-------------| | processId | string | ✅ | The process definition ID to execute | | inputs | Record<string, any> | ✅ | Input payload passed to the process | | metadata | Record<string, any> | ❌ | Arbitrary metadata attached to the job | | accessPoint | string | ❌ | Custom endpoint URL for private / white-label deployments |

Returns: Promise<JobReference> — contains jobId and referenceId for tracking.

Schedule a Process

Schedule a process to run at a future time or on a recurring basis.

import { scheduleProcess } from '@juggernautcloud/cloud';

const schedule = await scheduleProcess({
  processId: 'your-process-id',
  cron: '0 9 * * 1',      // Optional: cron expression
  scheduledAt: '2026-05-01T09:00:00Z', // Optional: ISO 8601 datetime
  inputs: { /* ... */ },
  metadata: { /* ... */ }
});

Job Events & Polling

Monitor the lifecycle of a running job via events. The SDK supports automatic polling with a built-in poller.

Manual Event Fetch

import { getProcessJobEvents } from '@juggernautcloud/cloud';

const events = await getProcessJobEvents({
  referenceId: 'ref_abc123'
});

Automatic Polling (Recommended)

const poller = await getProcessJobEvents({
  referenceId: 'ref_abc123',
  polling: {
    intervalMs: 2000,   // Poll every 2 seconds
    durationMs: 300000  // Optional: stop polling after 5 minutes
  }
  // Optional: accessPoint: 'https://your-endpoint.com'
});

// The poller is an async iterable
for await (const tick of poller) {
  console.log('Events:', tick.data);
  
  if (tick.done) {
    console.log('Final Results:', tick.results);
    break;
  }
}

Polling Response Shape

| Property | Type | Description | |----------|------|-------------| | data | JobEvent[] | Array of events since last poll | | done | boolean | true when job reaches terminal status | | results | any \| null | Final job output (only populated when done === true) |

Terminal Statuses: job-end, job-error, job-completed, process-completed, process-ended

Get Job Results

Fetch the final output of a completed job. Typically you don't need to call this directly when using the polling helper above (it auto-fetches results on completion).

import { getJobResults } from '@juggernautcloud/cloud';

const results = await getJobResults('jobId_123');

Retrieve Job Files

Some processes return file assets (images, audio, text) as structured links. Use getJobFile to download them.

import { getJobFile } from '@juggernautcloud/cloud';

// Link format from job results: file(image):64f8a1b2c3d4e5f6a7b8c9d0
const fileBuffer = await getJobFile('jobId_123', 'file(image):64f8a1b2c3d4e5f6a7b8c9d0');

Supported File Types: image, audio, text

Database Operations

The SDK includes a fluent DatabaseSchema class for interacting with Juggernaut Cloud Database resources.

Schema Instance

import { DatabaseSchema } from '@juggernautcloud/cloud';

// Private schema
const users = new DatabaseSchema('schema_users_123');

// Public schema via access point
const publicPosts = new DatabaseSchema('schema_posts_456', 'Posts', 'https://api.yoursite.com/public');

Constructor: new DatabaseSchema(schemaId, name?, accessPoint?)

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | schemaId | string | ✅ | The schema resource ID | | name | string | ❌ | Human-readable label | | accessPoint | string | ❌ | Public access endpoint URL |

CRUD Operations

// CREATE
const newRecord = await users.insert({
  email: '[email protected]',
  role: 'admin',
  createdAt: new Date().toISOString()
});

// READ ONE
const record = await users.getRecord('64f8a1b2c3d4e5f6a7b8c9d0');

// UPDATE
const updated = await users.update('64f8a1b2c3d4e5f6a7b8c9d0', {
  role: 'superadmin'
});

// DELETE
await users.delete('64f8a1b2c3d4e5f6a7b8c9d0');

Bulk Operations

// Insert many
await users.insertMany([
  { email: '[email protected]', role: 'user' },
  { email: '[email protected]', role: 'user' }
]);

// Update many (matches all records where role === 'guest')
await users.updateMany(
  { role: 'guest' },
  { role: 'user' }
);

// Bulk delete by query string
await users.bulkDelete('role = "inactive"');

Query & Aggregation

// Raw query with parameters
const results = await users.query(
  'SELECT * FROM users WHERE role = ? AND createdAt > ?',
  { role: 'admin', createdAt: '2026-01-01' }
);

// Count
const count = await users.count('role = "admin"');

// Existence check
const hasAdmins = await users.exists('role = "admin"');

Public Access Points

When an accessPoint is provided to the DatabaseSchema constructor, all operations automatically route through the public API layer instead of the authenticated private layer. This is useful for white-label or client-facing database proxies.

const publicSchema = new DatabaseSchema('schema_123', null, 'https://public-api.example.com');

// No auth headers required; routes through access point
const data = await publicSchema.query('SELECT * FROM leads');

Prompts

Retrieve the raw content of a stored prompt template.

import { getPromptContent } from '@juggernautcloud/cloud';

const promptText = await getPromptContent('prompt_123');
console.log(promptText); // "You are a financial analyst. Analyze the following..."

Error Handling

The SDK throws descriptive errors for invalid arguments before hitting the network:

| Method | Throws When | |--------|-------------| | DatabaseSchema.getRecord() | id is falsy | | DatabaseSchema.query() | queryString is falsy | | DatabaseSchema.insert() | record is not an object | | DatabaseSchema.insertMany() | data is not a non-empty array | | DatabaseSchema.update() | id is falsy or data is not an object | | DatabaseSchema.updateMany() | query or data is not an object | | DatabaseSchema.delete() | id is falsy | | DatabaseSchema.bulkDelete() | query is falsy | | DatabaseSchema.count() | query is falsy | | DatabaseSchema.exists() | query is falsy | | getJobFile() | link does not match file(type):id pattern |

All network errors from CloudResourceManager bubble up as standard Error objects with the message returned by the API.

TypeScript Types

Key interfaces exported from the package:

interface ProcessExecutionOptions {
  processId: string;
  inputs: Record<string, any>;
  metadata?: Record<string, any>;
  accessPoint?: string;
}

interface ProcessScheduleOptions {
  processId: string;
  inputs?: Record<string, any>;
  metadata?: Record<string, any>;
  cron?: string;
  scheduledAt?: string;
  // ... additional scheduler-specific fields
}

interface ProcessJobEventsRequest {
  referenceId: string;
  polling?: {
    intervalMs: number;
    durationMs?: number;
  };
  accessPoint?: string;
}

License

MIT © Juggernaut Labs

Need help? Visit www.juggernautlabs.ai or open an issue in the SDK repository.