@optima-chat/cli-core

Shared core library for Optima CLI suite

Overview

@optima-chat/cli-core is the foundational library for the Optima CLI suite, providing shared functionality for authentication, HTTP communication, output formatting, and configuration management.

Used by:

• @optima-chat/merchant-cli - Merchant BI tool
• @optima-chat/platform-cli - Platform operations BI tool
• @optima-chat/ops-cli - System operations tool

Features

• 🔐 Authentication - OAuth 2.0 Device Flow with auto token refresh
• 🌐 HTTP Client - Axios-based client with automatic authentication and error handling
• 📊 Output Formatting - JSON (default), Pretty tables, ASCII charts, CSV export
• ⚙️ Configuration Management - Encrypted config storage with environment variable support
• 🛠️ Utilities - Date/number formatting, table rendering, chart generation

Installation

npm install @optima-chat/cli-core
# or
pnpm add @optima-chat/cli-core

Usage

Authentication

import { AuthManager } from '@optima-chat/cli-core';

const authManager = new AuthManager({
  authUrl: 'https://auth.optima.shop',
  clientId: 'your-client-id',
});

// Check if authenticated
if (!await authManager.isAuthenticated()) {
  // Perform OAuth Device Flow
  await authManager.login();
}

// Get valid token (auto-refreshes if expired)
const token = await authManager.getToken();

HTTP Client

import { BaseApiClient } from '@optima-chat/cli-core';

const client = new BaseApiClient({
  baseURL: 'https://api.optima.shop',
  authManager,
});

// Authenticated request (token added automatically)
const response = await client.get('/api/merchants/me');

Output Formatting

import { OutputFormatter } from '@optima-chat/cli-core';

const formatter = new OutputFormatter({
  format: 'json', // 'json' | 'pretty' | 'csv'
});

// Format data
const output = formatter.format({
  success: true,
  data: {
    total_revenue: 125000.50,
    total_orders: 342,
  },
});

console.log(output);

Configuration Management

import { ConfigManager } from '@optima-chat/cli-core';

const config = new ConfigManager({
  projectName: 'optima-cli',
});

// Set value (encrypted)
config.set('accessToken', 'eyJhbGciOiJSUzI1...');

// Get value
const token = config.get('accessToken');

Utilities

import { DateUtils, NumberUtils, TableRenderer } from '@optima-chat/cli-core';

// Date formatting
DateUtils.format(new Date(), 'yyyy-MM-dd'); // "2025-10-29"
DateUtils.formatRelative(pastDate); // "2 days ago"

// Number formatting
NumberUtils.formatCurrency(125000.50, 'USD'); // "$125,000.50"
NumberUtils.formatPercentage(0.153); // "15.3%"

// Table rendering
const table = TableRenderer.create({
  head: ['Name', 'Price', 'Stock'],
  rows: [
    ['Product A', '$29.99', '100'],
    ['Product B', '$49.99', '50'],
  ],
});
console.log(table.toString());

API Reference

AuthManager

class AuthManager {
  constructor(options: AuthOptions);
  isAuthenticated(): Promise<boolean>;
  login(): Promise<void>;
  logout(): Promise<void>;
  getToken(): Promise<string>;
  refreshToken(): Promise<void>;
}

BaseApiClient

class BaseApiClient {
  constructor(options: ApiClientOptions);
  get<T>(url: string, config?: AxiosRequestConfig): Promise<T>;
  post<T>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T>;
  put<T>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T>;
  delete<T>(url: string, config?: AxiosRequestConfig): Promise<T>;
}

OutputFormatter

class OutputFormatter {
  constructor(options: FormatterOptions);
  format(data: any): string;
  formatJSON(data: any): string;
  formatPretty(data: any): string;
  formatCSV(data: any[]): string;
}

ConfigManager

class ConfigManager {
  constructor(options: ConfigOptions);
  get(key: string): any;
  set(key: string, value: any): void;
  delete(key: string): void;
  clear(): void;
  has(key: string): boolean;
}

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Watch mode
pnpm dev

# Run tests
pnpm test

# Test coverage
pnpm test:coverage

# Lint
pnpm lint

# Format
pnpm format

Testing

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run with coverage
pnpm test:coverage

Architecture

See the Architecture Documentation for detailed design and implementation details.

Contributing

Please read our Contributing Guide before submitting Pull Requests.

License

MIT © Optima Development Team

Links

• Documentation
• GitHub
• NPM
• Issues