AKIN HQ TypeScript SDK

A TypeScript SDK for the AKIN HQ API service with support for AI processing, chat, and billing operations.

Installation

npm install akin-sdk

Quick Start

import ApiClient from 'akin-sdk';

// Initialize the client
const client = new ApiClient();

// Set authentication
client.setApiKey('your-api-key');
client.setBearerToken('your-bearer-token');

Usage Examples

AI Processing

// Process AI request with files
const aiResponse = await client.ai.process({
  AiConfigId: '12345678-1234-1234-1234-123456789012',
  Prompt: 'Analyze this document',
  SystemPromptId: 'system-prompt-id', // Optional system prompt ID
  PromptVariables: { // Optional prompt variables
    variable1: 'value1',
    variable2: 'value2'
  },
  files: [fileBlob] // Optional file uploads
});

console.log(aiResponse.content);
console.log('Tokens used:', aiResponse.tokensUsed);
console.log('Response time:', aiResponse.responseTimeMs + 'ms');

Chat Operations

// Send a chat message
const chatResponse = await client.chat.send({
  AiConfigId: '12345678-1234-1234-1234-123456789012',
  ConversationId: '87654321-4321-4321-4321-210987654321', // Optional
  Message: 'Hello, how can you help me?',
  ConversationTitle: 'New Conversation', // Optional
  SystemPromptId: 'system-prompt-id', // Optional system prompt ID
  PromptVariables: { // Optional prompt variables
    variable1: 'value1',
    variable2: 'value2'
  },
  files: [fileBlob] // Optional file uploads
});

console.log('Conversation ID:', chatResponse.conversationId);
console.log('Response:', chatResponse.message);
console.log('Tokens used:', chatResponse.tokensUsed);

// Get all conversations with pagination
const conversations = await client.chat.getConversations(1, 20); // page 1, 20 items per page
console.log('Total conversations:', conversations.totalCount);
console.log('Current page:', conversations.pageNumber);
console.log('Has next page:', conversations.hasNextPage);

// Get a specific conversation
const conversation = await client.chat.getConversation('conversation-id');

// Get messages for a conversation with pagination
const messages = await client.chat.getMessages('conversation-id', 1, 20);
console.log('Total messages:', messages.totalCount);
console.log('Messages:', messages.items);

// Delete a conversation
await client.chat.deleteConversation('conversation-id');

// Get or delete files
const file = await client.chat.getFile('file-id');
await client.chat.deleteFile('file-id');

Billing Operations

// Check if user is subscribed
const isSubscribed = await client.billing.isSubscribed();

// Create customer portal session
const portalUrl = await client.billing.createPortalSession('https://your-app.com/dashboard');
// Redirect user to portalUrl for billing management

Error Handling

The SDK provides specific error types for different scenarios:

import { 
  ApiClientError, 
  AuthenticationError, 
  AuthorizationError, 
  NotFoundError, 
  ValidationError 
} from 'akin-sdk';

try {
  const response = await client.ai.process({
    AiConfigId: 'invalid-id',
    Prompt: 'Test prompt'
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.log('Authentication failed:', error.message);
  } else if (error instanceof ValidationError) {
    console.log('Validation error:', error.message);
  } else if (error instanceof ApiClientError) {
    console.log('API error:', error.message, 'Status:', error.status);
  } else {
    console.log('Unexpected error:', error);
  }
}

Configuration

// You can configure the client at initialization
const client = new ApiClient({
  apiKey: 'your-api-key',
  bearerToken: 'your-bearer-token'
});

// Or set values individually
client.setApiKey('your-api-key');
client.setBearerToken('your-bearer-token');

// Configure a custom base URL (defaults to https://api.akin-hq.com)
client.setBaseUrl('https://your-custom-api.com');

Types

The SDK exports all TypeScript interfaces for the API:

import { 
  AiResponseDto, 
  ChatResponseDto, 
  ConversationDto,
  ConversationDtoPagedResult,
  MessageDto,
  MessageDtoPagedResult,
  FileAttachmentDto,
  AiProcessRequest,
  ChatSendRequest,
  ApiError,
  SdkConfig
} from 'akin-sdk';

Authentication

The API supports both API Key and Bearer Token authentication:

• API Key: Set via X-API-Key header using setApiKey()
• Bearer Token: Set via Authorization: Bearer <token> header using setBearerToken()

Both authentication methods can be used simultaneously if required by the API.

License

MIT