Node.js SDK Installation

Install the ASCEND Node.js SDK and verify your setup.

Requirements

• Node.js 18 or higher
• npm or yarn package manager

Installation

npm install @ascend-ai/sdk

Or with yarn:

yarn add @ascend-ai/sdk

Verify Installation

import { AscendClient } from '@ascend-ai/sdk';

const client = new AscendClient({
  apiKey: 'owkai_your_api_key_here',
  agentId: 'test-agent',
  agentName: 'Test Agent',
});

const status = await client.testConnection();

if (status.status === 'connected') {
  console.log(`Connected to ASCEND (v${status.apiVersion})`);
} else {
  console.log(`Connection error: ${status.error}`);
}

Environment Variables

The SDK reads configuration from environment variables when parameters are not provided:

Variable	Required	Default	Description
ASCEND_API_KEY	Yes	—	Your organization API key
ASCEND_API_URL	No	https://pilot.owkai.app	API endpoint URL
ASCEND_AGENT_ID	No	—	Default agent identifier
ASCEND_AGENT_NAME	No	—	Default agent name

export ASCEND_API_KEY="owkai_live_your_api_key_here"

import { AscendClient } from '@ascend-ai/sdk';

// Client reads from environment variables
const client = new AscendClient({ agentName: 'My Agent' });

Quick Start

import { AscendClient } from '@ascend-ai/sdk';

const client = new AscendClient({
  apiKey: 'owkai_live_xxxxxxxxxxxx',
  agentId: 'customer-service-agent',
  agentName: 'Customer Service AI',
  failMode: 'closed',
});

// Register agent
await client.register({
  agentType: 'automation',
  capabilities: ['database.query', 'api.call'],
});

// Evaluate an action
const decision = await client.evaluateAction({
  actionType: 'database.query',
  resource: 'production_db',
  parameters: { query: 'SELECT COUNT(*) FROM users' },
});

switch (decision.decision) {
  case 'allowed':
    console.log(`Approved! Risk: ${decision.riskScore}`);
    // Execute action, then log completion
    await client.logActionCompleted({
      actionId: decision.actionId,
      result: { rowCount: 42 },
      durationMs: 150,
    });
    break;

  case 'denied':
    console.log(`Denied: ${decision.reason}`);
    console.log(`Violations: ${decision.policyViolations}`);
    break;

  case 'pending':
    console.log(`Pending approval: ${decision.approvalRequestId}`);
    break;
}

Constructor Options

const client = new AscendClient({
  apiKey: string;           // Organization API key
  agentId: string;          // Unique agent identifier
  agentName: string;        // Human-readable agent name
  apiUrl?: string;          // API endpoint (default: https://pilot.owkai.app)
  environment?: string;     // 'production' | 'staging' | 'development'
  failMode?: string;        // 'closed' (default) | 'open'
  timeout?: number;         // Request timeout in ms (default: 5000)
  maxRetries?: number;      // Max retry attempts (default: 3)
  debug?: boolean;          // Enable debug logging (default: false)
});

TypeScript Types

The SDK includes full TypeScript type definitions:

import type {
  AscendClient,
  AuthorizationDecision,
  AgentAction,
  Decision,
  RiskLevel,
} from '@ascend-ai/sdk';

Error Handling

import {
  AscendClient,
  AuthenticationError,
  AuthorizationError,
  RateLimitError,
  TimeoutError,
  CircuitBreakerOpen,
} from '@ascend-ai/sdk';

try {
  const decision = await client.evaluateAction({
    actionType: 'database.query',
    resource: 'production_db',
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof TimeoutError) {
    console.error('Request timed out');
  } else if (error instanceof CircuitBreakerOpen) {
    console.error('Service unavailable');
  }
}

Fail Mode

Mode	Behavior	Use Case
closed	Block actions when ASCEND unreachable	Production (recommended)
open	Allow actions when ASCEND unreachable	Development/testing

// Production: fail-closed
const prodClient = new AscendClient({
  apiKey: 'owkai_prod_xxxxxxxxxxxx',
  agentId: 'prod-agent',
  agentName: 'Production Agent',
  failMode: 'closed',
});

// Development: fail-open
const devClient = new AscendClient({
  apiKey: 'owkai_dev_xxxxxxxxxxxx',
  agentId: 'dev-agent',
  agentName: 'Dev Agent',
  failMode: 'open',
});

Next Steps

• Client Configuration — Advanced configuration
• Agent Actions — Submit and manage actions
• Error Handling — Handle errors gracefully