Skip to main content

Node.js SDK API Reference

Complete reference for all classes, methods, and types in the ASCEND Node.js SDK v2.0.

Installation​

npm install @ascend-ai/sdk

AscendClient​

The main client class for interacting with the ASCEND Platform.

Constructor​

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

const client = new AscendClient(options: AscendClientOptions);

AscendClientOptions​

interface AscendClientOptions {
  /** Organization API key (required) */
  apiKey: string;
  /** Unique agent identifier (required) */
  agentId: string;
  /** Human-readable agent name (required) */
  agentName: string;
  /** API endpoint URL */
  apiUrl?: string;
  /** Deployment environment */
  environment?: string;
  /** Fail mode when ASCEND is unreachable */
  failMode?: FailMode;
  /** Request timeout in milliseconds */
  timeout?: number;
  /** Maximum retry attempts */
  maxRetries?: number;
  /** Enable debug logging */
  debug?: boolean;
  /** Log level */
  logLevel?: 'DEBUG' | 'INFO' | 'WARNING' | 'ERROR';
  /** Use JSON format for logs */
  jsonLogs?: boolean;
  /** Enable metrics collection */
  enableMetrics?: boolean;
  /** Circuit breaker options */
  circuitBreakerOptions?: CircuitBreakerOptions;
  /** HMAC signing secret */
  signingSecret?: string;
}

Default Values​

OptionDefault
apiUrlhttps://pilot.owkai.app
environment"production"
failModeFailMode.CLOSED
timeout30000 (30 seconds)
maxRetries3
debugfalse
enableMetricstrue

Methods​

register()​

Register this agent with the ASCEND platform.

async register(options: RegisterOptions): Promise<RegisterResponse>

RegisterOptions​

interface RegisterOptions {
  /** Agent type: "supervised", "autonomous", "mcp_server" */
  agentType: string;
  /** List of capabilities */
  capabilities: string[];
  /** Resources this agent can access */
  allowedResources?: string[];
  /** Additional metadata */
  metadata?: Record<string, unknown>;
}

RegisterResponse​

interface RegisterResponse {
  agentId: string;
  status: string;
  registeredAt: string;
  capabilities: string[];
  metadata?: Record<string, unknown>;
}

Example​

const registration = await client.register({
  agentType: 'automation',
  capabilities: ['database.query', 'file.read', 'api.call'],
  allowedResources: ['production_db', 'customer_api'],
  metadata: { version: '1.0.0', owner: 'platform-team' }
});

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

evaluateAction()​

Evaluate an action for authorization.

async evaluateAction(options: EvaluateActionOptions): Promise<EvaluateActionResult>

EvaluateActionOptions​

interface EvaluateActionOptions {
  /** Action type in "category.action" format */
  actionType: string;
  /** Resource identifier */
  resource: string;
  /** Action-specific parameters */
  parameters?: Record<string, unknown>;
  /** Additional context for risk scoring */
  context?: Record<string, unknown>;
  /** Wait for approval if pending */
  waitForApproval?: boolean;
  /** Approval timeout in milliseconds */
  approvalTimeout?: number;
  /** Override risk level */
  riskLevel?: string;
  /** Force human approval */
  requireHumanApproval?: boolean;
}

EvaluateActionResult​

interface EvaluateActionResult {
  decision: Decision;
  actionId: string;
  reason?: string;
  riskScore?: number;
  policyViolations: string[];
  conditions: string[];
  approvalRequestId?: string;
  requiredApprovers: string[];
  expiresAt?: string;
  metadata: Record<string, unknown>;
}

Example​

const decision = await client.evaluateAction({
  actionType: 'financial.refund',
  resource: 'stripe_api',
  parameters: {
    amount: 100.00,
    currency: 'USD',
    customerId: 'cust_123'
  },
  context: {
    sessionId: 'sess_abc',
    userRequest: 'Process refund for order #456'
  }
});

if (decision.decision === Decision.ALLOWED) {
  console.log(`Action approved: ${decision.actionId}`);
} else if (decision.decision === Decision.PENDING) {
  console.log(`Awaiting approval: ${decision.approvalRequestId}`);
} else {
  console.log(`Denied: ${decision.reason}`);
}

logActionCompleted()​

Log successful action completion.

async logActionCompleted(
  actionId: string,
  result?: Record<string, unknown>,
  durationMs?: number
): Promise<ActionLogResponse>

Example​

const startTime = Date.now();
const result = await executeQuery();
const durationMs = Date.now() - startTime;

await client.logActionCompleted(
  decision.actionId,
  { rowCount: result.length },
  durationMs
);

logActionFailed()​

Log action failure.

async logActionFailed(
  actionId: string,
  error: string | Error,
  durationMs?: number
): Promise<ActionLogResponse>

Example​

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

checkApproval()​

Check approval status.

async checkApproval(approvalRequestId: string): Promise<ApprovalStatusResponse>

ApprovalStatusResponse​

interface ApprovalStatusResponse {
  approvalRequestId: string;
  status: 'pending' | 'approved' | 'rejected';
  approvedBy?: string;
  rejectedBy?: string;
  rejectionReason?: string;
  decidedAt?: string;
}

Example​

if (decision.decision === Decision.PENDING) {
  const status = await client.checkApproval(decision.approvalRequestId!);

  if (status.status === 'approved') {
    await executeAction();
  } else if (status.status === 'rejected') {
    console.log(`Rejected: ${status.rejectionReason}`);
  }
}

configureWebhook()​

Configure webhook for event notifications.

async configureWebhook(options: WebhookOptions): Promise<WebhookConfigResponse>

WebhookOptions​

interface WebhookOptions {
  /** HTTPS endpoint URL */
  url: string;
  /** Events to subscribe to */
  events: string[];
  /** Signing secret */
  secret?: string;
}

Valid Events​

  • action.approved
  • action.denied
  • action.pending
  • policy.violation
  • agent.trust_changed

Example​

const config = await client.configureWebhook({
  url: 'https://your-app.com/webhooks/ascend',
  events: ['action.approved', 'action.denied', 'policy.violation'],
  secret: 'whsec_your_secret_here'
});

console.log(`Webhook ID: ${config.webhookId}`);

testConnection()​

Test API connectivity.

async testConnection(): Promise<ConnectionStatus>

ConnectionStatus​

interface ConnectionStatus {
  status: 'connected' | 'error';
  apiVersion?: string;
  latency?: number;
  error?: string;
}

Example​

const status = await client.testConnection();

if (status.status === 'connected') {
  console.log(`Connected. Latency: ${status.latency}ms`);
} else {
  console.error(`Connection error: ${status.error}`);
}

getCircuitBreakerState()​

Get circuit breaker status.

getCircuitBreakerState(): { state: CircuitState; failures: number }

resetCircuitBreaker()​

Reset the circuit breaker.

resetCircuitBreaker(): void

getMetrics()​

Get metrics snapshot.

getMetrics(): MetricsSnapshot | null

MetricsSnapshot​

interface MetricsSnapshot {
  totalRequests: number;
  successCount: number;
  errorCount: number;
  successRate: number;
  avgLatency: number;
  p50Latency: number;
  p95Latency: number;
  p99Latency: number;
  requestsPerMinute: number;
  retryCount: number;
  timeoutCount: number;
  windowStart: Date;
  windowEnd: Date;
}

Enums​

Decision​

Authorization decision values.

enum Decision {
  /** Action is allowed to proceed */
  ALLOWED = 'allowed',
  /** Action is denied */
  DENIED = 'denied',
  /** Action is pending human approval */
  PENDING = 'pending'
}

FailMode​

Fail mode configuration.

enum FailMode {
  /** Block actions when ASCEND is unreachable */
  CLOSED = 'closed',
  /** Allow actions when ASCEND is unreachable */
  OPEN = 'open'
}

CircuitState​

Circuit breaker states.

enum CircuitState {
  CLOSED = 'closed',
  OPEN = 'open',
  HALF_OPEN = 'half_open'
}

RiskLevel​

Risk assessment levels.

enum RiskLevel {
  LOW = 'low',
  MEDIUM = 'medium',
  HIGH = 'high',
  CRITICAL = 'critical'
}

Error Classes​

AscendError​

Base error class.

class AscendError extends Error {
  readonly code: string;
  readonly details: Record<string, unknown>;

  toJSON(): Record<string, unknown>;
}

AuthenticationError​

Raised when authentication fails.

class AuthenticationError extends AscendError {
  // code: 'AUTH_ERROR'
}

AuthorizationError​

Raised when an action is denied.

class AuthorizationError extends AscendError {
  readonly policyViolations: string[];
  readonly riskScore?: number;
  // code: 'AUTHZ_DENIED'
}

TimeoutError​

Raised when an operation times out.

class TimeoutError extends AscendError {
  readonly timeoutMs: number;
  // code: 'TIMEOUT'
}

RateLimitError​

Raised when rate limit is exceeded.

class RateLimitError extends AscendError {
  readonly retryAfter: number;  // seconds
  // code: 'RATE_LIMIT'
}

ConnectionError​

Raised when connection fails.

class ConnectionError extends AscendError {
  // code: 'CONNECTION_ERROR'
}

CircuitBreakerOpenError​

Raised when circuit breaker is open.

class CircuitBreakerOpenError extends AscendError {
  readonly recoveryTimeSeconds: number;
  // code: 'CIRCUIT_OPEN'
}

ValidationError​

Raised when validation fails.

class ValidationError extends AscendError {
  readonly fieldErrors: Record<string, string>;
  // code: 'VALIDATION_ERROR'
}

CircuitBreaker​

Circuit breaker for resilient API calls.

CircuitBreakerOptions​

interface CircuitBreakerOptions {
  /** Failures before opening circuit (default: 5) */
  failureThreshold?: number;
  /** Seconds before recovery attempt (default: 30) */
  recoveryTimeout?: number;
  /** Test requests in half-open state (default: 3) */
  halfOpenMaxCalls?: number;
}

Methods​

class CircuitBreaker {
  getState(): CircuitState;
  getFailures(): number;
  recordSuccess(): void;
  recordFailure(): void;
  allowRequest(): boolean;
  reset(): void;
}

AscendClient (Legacy API)​

Legacy client API for backward compatibility.

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

const client = new AscendClient({
  apiKey: 'your-api-key',
  organizationSlug: 'your-org'
});

Legacy Methods​

// Submit action (legacy)
async submitAction(action: AgentAction): Promise<AuthorizationDecision>

// Get action status
async getActionStatus(actionId: string): Promise<AuthorizationDecision>

// Wait for decision
async waitForDecision(actionId: string, timeout?: number): Promise<AuthorizationDecision>

// Get action details
async getActionDetails(actionId: string): Promise<ActionDetails>

// List actions
async listActions(options?: ListOptions): Promise<ActionListResponse>

// Approve action (admin)
async approveAction(actionId: string, comments?: string): Promise<AuthorizationDecision>

// Deny action (admin)
async denyAction(actionId: string, reason: string): Promise<AuthorizationDecision>

// Batch submission
async submitActionBatch(actions: AgentAction[], options?: BatchOptions): Promise<BatchResponse>

Type Definitions​

AgentAction​

interface AgentAction {
  agentId: string;
  agentName: string;
  actionType: ActionType | string;
  resource: string;
  resourceId?: string;
  details?: Record<string, unknown>;
  context?: ActionContext;
  riskIndicators?: RiskIndicators;
}

RiskIndicators​

interface RiskIndicators {
  piiInvolved?: boolean;
  financialData?: boolean;
  externalTransfer?: boolean;
  dataSensitivity?: 'low' | 'medium' | 'high' | 'critical';
  amountThreshold?: 'normal' | 'exceeded';
  complianceFlags?: string[];
}

ActionContext​

interface ActionContext {
  userRequest?: string;
  sessionId?: string;
  ipAddress?: string;
  userAgent?: string;
  timestamp?: string;
  [key: string]: unknown;
}

BatchOptions​

interface BatchOptions {
  /** Process in parallel (default: true) */
  parallel?: boolean;
  /** Batch timeout in milliseconds */
  timeout?: number;
  /** Continue on errors */
  continueOnError?: boolean;
  /** Wait for all decisions */
  waitForDecisions?: boolean;
}

BatchResponse​

interface BatchResponse {
  results: BatchActionResult[];
  totalSubmitted: number;
  successCount: number;
  errorCount: number;
  duration: number;
  allSucceeded: boolean;
}

See Also​

Last updated on