Skip to main content
Coming Soon

The Node.js SDK (@ascend/sdk) is not yet published to npm. This documentation is a preview of the planned API. For production use, please use the Python SDK or the REST API.

Node.js SDK Quickstart

Get your AI agent governed by ASCEND in under 5 minutes using TypeScript or JavaScript.

Prerequisites​

  • Node.js 16.0.0 or higher
  • ASCEND API key (obtain from the Console)
  • npm or yarn package manager

Installation​

npm install @ascend/sdk

Or with yarn:

yarn add @ascend/sdk

Quick Start​

1. Initialize the Client​

import { AscendClient, FailMode, Decision } from '@ascend/sdk';

// Initialize with fail-closed mode (recommended for production)
const client = new AscendClient({
  apiKey: 'owkai_your_api_key_here',
  agentId: 'my-agent-001',
  agentName: 'My AI Agent',
  environment: 'production',
  failMode: FailMode.CLOSED
});

2. Register Your Agent​

// Register agent with ASCEND platform
const registration = await client.register({
  agentType: 'automation',
  capabilities: ['database.query', 'file.read', 'api.call'],
  allowedResources: ['production_db', 'customer_api']
});

console.log(`Agent registered: ${registration.agentId}`);

3. Evaluate Actions Before Execution​

// Request authorization for an action
const decision = await client.evaluateAction({
  actionType: 'database.query',
  resource: 'production_db',
  parameters: { query: 'SELECT * FROM customers WHERE id = 123' }
});

// Check the decision
if (decision.decision === Decision.ALLOWED) {
  // Execute the action
  const result = await executeDatabaseQuery();

  // Log successful completion
  await client.logActionCompleted(decision.actionId, {
    rowsReturned: result.length
  }, 150);

} else if (decision.decision === Decision.PENDING) {
  // Action requires human approval
  console.log(`Awaiting approval: ${decision.approvalRequestId}`);
  console.log(`Required approvers: ${decision.requiredApprovers}`);

} else {
  // Action was denied
  console.log(`Action denied: ${decision.reason}`);
  console.log(`Policy violations: ${decision.policyViolations}`);
}

Environment Variables​

The SDK supports configuration via environment variables:

VariableDescriptionRequired
ASCEND_API_KEYYour organization API keyYes
ASCEND_API_URLAPI endpoint (default: https://pilot.owkai.app)No
// Client will use environment variables
const client = new AscendClient({
  apiKey: process.env.ASCEND_API_KEY!,
  agentId: 'my-agent-001',
  agentName: 'My AI Agent'
});

Complete Example​

/**
 * Complete example: A customer service agent that processes refunds
 */
import { AscendClient, FailMode, Decision } from '@ascend/sdk';

// Initialize client
const client = new AscendClient({
  apiKey: 'owkai_prod_xxxxxxxxxxxx',
  agentId: 'customer-service-agent',
  agentName: 'Customer Service Bot',
  environment: 'production',
  failMode: FailMode.CLOSED,
  timeout: 5000
});

// Register the agent
await client.register({
  agentType: 'automation',
  capabilities: ['transaction.refund', 'customer.lookup'],
  allowedResources: ['stripe_api', 'customer_db']
});

interface RefundResult {
  status: string;
  refundId?: string;
  approvalId?: string;
  message?: string;
}

async function processRefund(
  customerId: string,
  amount: number,
  reason: string
): Promise<RefundResult> {
  // Request authorization
  const decision = await client.evaluateAction({
    actionType: 'transaction.refund',
    resource: 'stripe_api',
    parameters: {
      customerId,
      amount,
      currency: 'USD',
      reason
    },
    context: {
      sessionId: 'sess_abc123',
      userRequest: `Refund $${amount} for customer ${customerId}`
    }
  });

  // Handle decision
  if (decision.decision === Decision.ALLOWED) {
    const startTime = Date.now();

    try {
      // Execute the refund
      const refundResult = {
        refundId: 'ref_123456',
        status: 'processed',
        amount
      };

      // Log completion
      await client.logActionCompleted(
        decision.actionId,
        refundResult,
        Date.now() - startTime
      );

      return {
        status: 'completed',
        refundId: refundResult.refundId,
        message: `Refund ${refundResult.refundId} processed successfully`
      };

    } catch (error) {
      // Log failure
      await client.logActionFailed(
        decision.actionId,
        error as Error,
        Date.now() - startTime
      );
      throw error;
    }

  } else if (decision.decision === Decision.PENDING) {
    return {
      status: 'pending_approval',
      approvalId: decision.approvalRequestId,
      message: 'Refund requires manager approval'
    };

  } else {
    return {
      status: 'denied',
      message: decision.reason
    };
  }
}

// Execute
const result = await processRefund('cust_123', 150.00, 'Product defect');
console.log(result);

Error Handling​

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

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

} catch (error) {
  if (error instanceof AuthenticationError) {
    // Invalid or expired API key
    console.error(`Authentication failed: ${error.message}`);

  } else if (error instanceof AuthorizationError) {
    // Action explicitly denied by policy
    console.error(`Authorization denied: ${error.message}`);
    console.error(`Policy violations: ${error.policyViolations}`);
    console.error(`Risk score: ${error.riskScore}`);

  } else if (error instanceof TimeoutError) {
    // Request timed out
    console.error(`Request timed out after ${error.timeoutMs}ms`);

  } else if (error instanceof RateLimitError) {
    // Rate limit exceeded
    console.error(`Rate limited. Retry after ${error.retryAfter} seconds`);

  } else if (error instanceof CircuitBreakerOpenError) {
    // Service appears to be down
    console.error(`Service unavailable. Recovery in ${error.recoveryTimeSeconds}s`);
  }
}

Fail Mode Configuration​

The SDK supports two fail modes:

ModeBehaviorUse Case
CLOSEDBlock actions when ASCEND is unreachableProduction (recommended)
OPENAllow actions when ASCEND is unreachableDevelopment/testing
import { AscendClient, FailMode } from '@ascend/sdk';

// Production: fail-closed (secure)
const prodClient = new AscendClient({
  apiKey: 'owkai_prod_xxx',
  agentId: 'prod-agent',
  agentName: 'Production Agent',
  failMode: FailMode.CLOSED  // Default
});

// Development: fail-open (for testing)
const devClient = new AscendClient({
  apiKey: 'owkai_dev_xxx',
  agentId: 'dev-agent',
  agentName: 'Dev Agent',
  failMode: FailMode.OPEN
});

TypeScript Support​

The SDK is written in TypeScript and provides full type definitions:

import {
  AscendClient,
  AscendClientOptions,
  EvaluateActionResult,
  Decision,
  FailMode
} from '@ascend/sdk';

// Full type safety
const options: AscendClientOptions = {
  apiKey: 'owkai_prod_xxx',
  agentId: 'typed-agent',
  agentName: 'Typed Agent',
  environment: 'production',
  failMode: FailMode.CLOSED,
  timeout: 5000
};

const client = new AscendClient(options);

// Response types are inferred
const result: EvaluateActionResult = await client.evaluateAction({
  actionType: 'database.query',
  resource: 'production_db',
  parameters: { query: 'SELECT 1' }
});

Next Steps​

Support​