Aqera JavaScript/TypeScript SDK

Idiomatic JavaScript/TypeScript client for the Aqera AI-Native OS platform.

Installation

npm install @arqera/sdk
# or
yarn add @arqera/sdk
# or
pnpm add @arqera/sdk

Quick Start

import { AqeraClient } from '@arqera/sdk';

// Initialize the client
const client = new AqeraClient({
  apiKey: process.env.ARQERA_API_KEY,
});

// List tasks
const tasks = await client.work.listTasks({ status: 'todo' });
console.log(tasks);

// Create a task
const newTask = await client.work.createTask({
  title: 'Implement new feature',
  description: 'Add user authentication',
  projectId: 1,
});

// Chat with Ara
const response = await client.ara.chat([
  { role: 'user', content: 'Show me my pending tasks' }
]);
console.log(response);

Modules

Work Module

Manage projects, tasks, workflows, and time tracking:

// Tasks
const tasks = await client.work.listTasks({ projectId: 1, status: 'todo' });
const task = await client.work.getTask(123);
await client.work.createTask({ title: 'New task', projectId: 1 });
await client.work.updateTask(123, { status: 'in_progress' });
await client.work.deleteTask(123);

// Projects
const projects = await client.work.listProjects({ status: 'active' });
const project = await client.work.getProject(1);
await client.work.createProject({ name: 'New project' });

// Workflows
const workflows = await client.work.listWorkflows({ module: 'work' });
const result = await client.work.executeWorkflow(1, { param: 'value' });

// Time tracking
const entries = await client.work.listTimeEntries({ taskId: 123 });
const timer = await client.work.startTimer(123);
await client.work.stopTimer(timer.id);

Agents Module

Manage and interact with agents:

// List agents
const agents = await client.agents.listAgents({ agentType: 'chat' });

// Get agent details
const agent = await client.agents.get(1);

// Create an agent
const agent = await client.agents.create({
  name: 'My Assistant',
  type: 'chat',
  capabilities: ['chat', 'task.execute']
});

// Chat with an agent
const response = await client.agents.chat(1, [
  { role: 'user', content: 'Help me with this task' }
]);

// Execute an action
const result = await client.agents.execute(1, 'create_task', {
  title: 'Task from agent'
});

Ara Module

AI chat and assistance:

// Simple chat
const response = await client.ara.chat([
  { role: 'user', content: 'What can you help me with?' }
]);

// Chat with session
const response = await client.ara.chat(
  [
    { role: 'user', content: 'Show me tasks' },
    { role: 'assistant', content: 'Here are your tasks...' },
    { role: 'user', content: 'Filter by high priority' }
  ],
  'session_123' // sessionId
);

// Get AI suggestions
const suggestions = await client.ara.suggest({
  module: 'work',
  action: 'list_tasks'
});

// Get feature explanation
const explanation = await client.ara.explain('task_workflows', 'standard');

// Navigation guidance
const guide = await client.ara.guide('settings');

Execute Endpoint

Execute Aqera workflows:

const result = await client.execute({
  intent: 'support.triage',
  context: {
    tenantId: 'tenant_123',
    userId: 'user_456'
  },
  inputs: {
    ticketId: 'TICKET-001',
    priority: 'high'
  }
});

Error Handling

import { AqeraClient, AqeraError } from '@arqera/sdk';

try {
  const tasks = await client.work.listTasks();
} catch (error) {
  if (error instanceof AqeraError) {
    console.error(`Error: ${error.message}`);
    if (error.statusCode) {
      console.error(`Status: ${error.statusCode}`);
    }
  }
}

Configuration

// Custom base URL and timeout
const client = new AqeraClient({
  apiKey: process.env.ARQERA_API_KEY,
  baseUrl: 'https://api.arqera.com',  // Default
  timeout: 30000,  // milliseconds
});

TypeScript Support

The SDK includes full TypeScript type definitions:

import { AqeraClient, TaskStatus, ProjectStatus } from '@arqera/sdk';

// Type-safe status values
const tasks = await client.work.listTasks({
  status: 'todo' as TaskStatus,
  limit: 10
});

API Reference

See the full API documentation at: https://docs.arqera.com/sdk/javascript