Agentic SDK

TypeScript SDK for building integrations with the akaBot 2.0 Agentic AI Platform, featuring flexible authentication, resource APIs, and developer-friendly abstractions for automation workflows.

Features

• 🔐 Flexible Authentication - Multiple auth providers (API Key, Environment, File, Static)
• 📦 Resource Management - Built-in support for Assets and Files
• 🎯 Type-Safe - Full TypeScript support with comprehensive type definitions
• 🔄 Modern Architecture - ESM and CJS support with tree-shaking
• ⚡ Performance - Lazy initialization and efficient HTTP client
• 🛡️ Error Handling - Comprehensive error types with detailed messages
• 🧪 Well-Tested - Extensive test coverage with Vitest
• 📝 Developer-Friendly - Intuitive API with JSDoc documentation

Installation

npm install @akabot/agentic-sdk

yarn add @akabot/agentic-sdk

pnpm add @akabot/agentic-sdk

Quick Start

Basic Usage

import { AgenticClient } from '@akabot/agentic-sdk';

// Create a client with default configuration
const client = new AgenticClient();

// Use the client
const assets = await client.asset.findAll();
console.log(assets);

Using Environment Variables

import { AgenticClient, EnvironmentAuthProvider } from '@akabot/agentic-sdk';

// Reads API key from environment variable
const client = new AgenticClient({
  authProvider: new EnvironmentAuthProvider({
    apiKeyEnvVar: 'MY_API_KEY',
  }),
});

Using Default Authentication

import { AgenticClient } from '@akabot/agentic-sdk';

// Uses DefaultAuthProvider with fallback chain:
// 1. Environment variable (AGENTIC_API_KEY)
// 2. Config file (.agentic/config.json)
// 3. Throws error if not found
const client = new AgenticClient();

Authentication

The SDK supports multiple authentication strategies through the AuthProvider interface.

Available Auth Providers

1. StaticAuthProvider

Use a pre-configured Auth instance:

import { AgenticClient, ApiKeyAuth, StaticAuthProvider } from '@akabot/agentic-sdk';

const auth = new ApiKeyAuth('your-api-key');
const client = new AgenticClient({
  authProvider: new StaticAuthProvider(auth),
});

2. EnvironmentAuthProvider

Load API key from environment variables:

import { EnvironmentAuthProvider } from '@akabot/agentic-sdk';

const provider = new EnvironmentAuthProvider({
  apiKeyEnvVar: 'MY_API_KEY', // defaults to 'AGENTIC_API_KEY'
});

3. FileAuthProvider

Load credentials from a JSON file:

import { FileAuthProvider } from '@akabot/agentic-sdk';

const provider = new FileAuthProvider({
  path: './config/credentials.json',
});

// credentials.json format:
// {
//   "apiKey": "your-api-key"
// }

4. DefaultAuthProvider

Tries multiple sources in order:

import { DefaultAuthProvider } from '@akabot/agentic-sdk';

const provider = new DefaultAuthProvider({
  envVar: 'AGENTIC_API_KEY', // Optional: custom env var name
  configPath: '.agentic/config.json', // Optional: custom config path
});

API Reference

AgenticClient

The main entry point for the SDK.

interface AgenticClientOptions {
  baseURL?: string; // API base URL
  authProvider?: AuthProvider; // Authentication provider
  timeout?: number; // Request timeout in milliseconds
}

Resources

The SDK provides the following resource clients:

Asset Resource

Manage assets with full CRUD operations:

• create() - Create a new asset
• findAll() - Find all assets with pagination
• search() - Search assets by term
• filterAll() - Filter assets by criteria
• findOne() - Find a single asset by name
• update() - Update an existing asset
• remove() - Delete an asset

Example:

const asset = await client.asset.create({
  name: 'my-asset',
  value: 'asset-value',
  type: AssetType.TEXT,
  scope: 'global',
});

const pagedAssets = await client.asset.findAll({ page: 1, limit: 10 });

File Resource

Handle file uploads and downloads with presigned URLs:

• create() - Create and upload a file
• getFile() - Get file metadata
• getDownloadLink() - Get presigned download URL
• delete() - Delete a file

Example:

// Node.js
const file = await client.file.create({
  file: fileBuffer,
  originalName: 'document.pdf',
});

// Browser
const file = await client.file.create({
  file: inputFile.files[0],
});

const downloadUrl = await client.file.getDownloadLink('file-id');

Error Handling

The SDK provides comprehensive error types for different scenarios:

import { ResourceNotFoundError, UnauthorizedError } from '@akabot/agentic-sdk';

try {
  const asset = await client.asset.findOne('non-existent');
} catch (error) {
  if (error instanceof ResourceNotFoundError) {
    console.error('Asset not found');
  } else if (error instanceof UnauthorizedError) {
    console.error('Authentication failed');
  }
}

Available error types: SdkError, ResourceNotFoundError, InvalidRequestError, UnauthorizedError, ForbiddenError, ConflictError, RateLimitError, ServerError, NetworkError, UnexpectedError

Development

# Install dependencies
npm install

# Run tests
npm test

# Build the SDK
npm run build

# Lint code
npm run lint

License

This project is licensed under the Apache-2.0 License - see the LICENSE file for details.