@ktmcp-cli/billingo 1.0.0

package/src/commands/partners.js

@@ -0,0 +1,130 @@
+/**
+ * Partner Commands
+ *
+ * Manage business partners (customers, suppliers)
+ */
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import { get, post, put, del, formatOutput } from '../lib/api.js';
+import { readFileSync } from 'fs';
+
+export function registerPartnerCommands(program) {
+  const partners = new Command('partners')
+    .description('Manage partners (customers, suppliers)');
+
+  partners
+    .command('list')
+    .description('List all partners')
+    .option('-p, --page <number>', 'Page number', '1')
+    .option('--per-page <number>', 'Results per page', '25')
+    .option('-f, --format <format>', 'Output format (json, pretty)', 'pretty')
+    .action(async (options) => {
+      const spinner = ora('Fetching partners...').start();
+      try {
+        const data = await get('/partners', {
+          page: options.page,
+          per_page: options.perPage,
+        });
+        spinner.succeed('Partners retrieved');
+        console.log(formatOutput(data, options.format));
+      } catch (error) {
+        spinner.fail('Failed to fetch partners');
+        console.error(chalk.red('Error:'), error.message);
+        process.exit(1);
+      }
+    });
+
+  partners
+    .command('get <id>')
+    .description('Get partner by ID')
+    .option('-f, --format <format>', 'Output format (json, pretty)', 'pretty')
+    .action(async (id, options) => {
+      const spinner = ora(`Fetching partner ${id}...`).start();
+      try {
+        const data = await get(`/partners/${id}`);
+        spinner.succeed('Partner retrieved');
+        console.log(formatOutput(data, options.format));
+      } catch (error) {
+        spinner.fail('Failed to fetch partner');
+        console.error(chalk.red('Error:'), error.message);
+        process.exit(1);
+      }
+    });
+
+  partners
+    .command('create')
+    .description('Create a new partner')
+    .option('-f, --file <path>', 'JSON file with partner data')
+    .option('-d, --data <json>', 'JSON string with partner data')
+    .action(async (options) => {
+      const spinner = ora('Creating partner...').start();
+      try {
+        let data;
+        if (options.file) {
+          data = JSON.parse(readFileSync(options.file, 'utf-8'));
+        } else if (options.data) {
+          data = JSON.parse(options.data);
+        } else {
+          spinner.fail('No data provided');
+          console.error(chalk.red('Error: Provide data with --file or --data'));
+          process.exit(1);
+        }
+
+        const result = await post('/partners', data);
+        spinner.succeed('Partner created');
+        console.log(formatOutput(result, 'pretty'));
+      } catch (error) {
+        spinner.fail('Failed to create partner');
+        console.error(chalk.red('Error:'), error.message);
+        process.exit(1);
+      }
+    });
+
+  partners
+    .command('update <id>')
+    .description('Update a partner')
+    .option('-f, --file <path>', 'JSON file with partner data')
+    .option('-d, --data <json>', 'JSON string with partner data')
+    .action(async (id, options) => {
+      const spinner = ora(`Updating partner ${id}...`).start();
+      try {
+        let data;
+        if (options.file) {
+          data = JSON.parse(readFileSync(options.file, 'utf-8'));
+        } else if (options.data) {
+          data = JSON.parse(options.data);
+        } else {
+          spinner.fail('No data provided');
+          console.error(chalk.red('Error: Provide data with --file or --data'));
+          process.exit(1);
+        }
+
+        const result = await put(`/partners/${id}`, data);
+        spinner.succeed('Partner updated');
+        console.log(formatOutput(result, 'pretty'));
+      } catch (error) {
+        spinner.fail('Failed to update partner');
+        console.error(chalk.red('Error:'), error.message);
+        process.exit(1);
+      }
+    });
+
+  partners
+    .command('delete <id>')
+    .description('Delete a partner')
+    .action(async (id) => {
+      const spinner = ora(`Deleting partner ${id}...`).start();
+      try {
+        await del(`/partners/${id}`);
+        spinner.succeed('Partner deleted');
+      } catch (error) {
+        spinner.fail('Failed to delete partner');
+        console.error(chalk.red('Error:'), error.message);
+        process.exit(1);
+      }
+    });
+
+  program.addCommand(partners);
+}

package/src/commands/products.js

@@ -0,0 +1,130 @@
+/**
+ * Product Commands
+ *
+ * Manage products for invoicing
+ */
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import { get, post, put, del, formatOutput } from '../lib/api.js';
+import { readFileSync } from 'fs';
+
+export function registerProductCommands(program) {
+  const products = new Command('products')
+    .description('Manage products');
+
+  products
+    .command('list')
+    .description('List all products')
+    .option('-p, --page <number>', 'Page number', '1')
+    .option('--per-page <number>', 'Results per page', '25')
+    .option('-f, --format <format>', 'Output format (json, pretty)', 'pretty')
+    .action(async (options) => {
+      const spinner = ora('Fetching products...').start();
+      try {
+        const data = await get('/products', {
+          page: options.page,
+          per_page: options.perPage,
+        });
+        spinner.succeed('Products retrieved');
+        console.log(formatOutput(data, options.format));
+      } catch (error) {
+        spinner.fail('Failed to fetch products');
+        console.error(chalk.red('Error:'), error.message);
+        process.exit(1);
+      }
+    });
+
+  products
+    .command('get <id>')
+    .description('Get product by ID')
+    .option('-f, --format <format>', 'Output format (json, pretty)', 'pretty')
+    .action(async (id, options) => {
+      const spinner = ora(`Fetching product ${id}...`).start();
+      try {
+        const data = await get(`/products/${id}`);
+        spinner.succeed('Product retrieved');
+        console.log(formatOutput(data, options.format));
+      } catch (error) {
+        spinner.fail('Failed to fetch product');
+        console.error(chalk.red('Error:'), error.message);
+        process.exit(1);
+      }
+    });
+
+  products
+    .command('create')
+    .description('Create a new product')
+    .option('-f, --file <path>', 'JSON file with product data')
+    .option('-d, --data <json>', 'JSON string with product data')
+    .action(async (options) => {
+      const spinner = ora('Creating product...').start();
+      try {
+        let data;
+        if (options.file) {
+          data = JSON.parse(readFileSync(options.file, 'utf-8'));
+        } else if (options.data) {
+          data = JSON.parse(options.data);
+        } else {
+          spinner.fail('No data provided');
+          console.error(chalk.red('Error: Provide data with --file or --data'));
+          process.exit(1);
+        }
+
+        const result = await post('/products', data);
+        spinner.succeed('Product created');
+        console.log(formatOutput(result, 'pretty'));
+      } catch (error) {
+        spinner.fail('Failed to create product');
+        console.error(chalk.red('Error:'), error.message);
+        process.exit(1);
+      }
+    });
+
+  products
+    .command('update <id>')
+    .description('Update a product')
+    .option('-f, --file <path>', 'JSON file with product data')
+    .option('-d, --data <json>', 'JSON string with product data')
+    .action(async (id, options) => {
+      const spinner = ora(`Updating product ${id}...`).start();
+      try {
+        let data;
+        if (options.file) {
+          data = JSON.parse(readFileSync(options.file, 'utf-8'));
+        } else if (options.data) {
+          data = JSON.parse(options.data);
+        } else {
+          spinner.fail('No data provided');
+          console.error(chalk.red('Error: Provide data with --file or --data'));
+          process.exit(1);
+        }
+
+        const result = await put(`/products/${id}`, data);
+        spinner.succeed('Product updated');
+        console.log(formatOutput(result, 'pretty'));
+      } catch (error) {
+        spinner.fail('Failed to update product');
+        console.error(chalk.red('Error:'), error.message);
+        process.exit(1);
+      }
+    });
+
+  products
+    .command('delete <id>')
+    .description('Delete a product')
+    .action(async (id) => {
+      const spinner = ora(`Deleting product ${id}...`).start();
+      try {
+        await del(`/products/${id}`);
+        spinner.succeed('Product deleted');
+      } catch (error) {
+        spinner.fail('Failed to delete product');
+        console.error(chalk.red('Error:'), error.message);
+        process.exit(1);
+      }
+    });
+
+  program.addCommand(products);
+}

package/src/commands/utilities.js

@@ -0,0 +1,34 @@
+/**
+ * Utility Commands
+ *
+ * Utility functions (ID conversion, etc.)
+ */
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import { get, formatOutput } from '../lib/api.js';
+
+export function registerUtilityCommands(program) {
+  const utilities = new Command('utils')
+    .description('Utility functions');
+
+  utilities
+    .command('convert-id <id>')
+    .description('Convert legacy API ID to v3 ID')
+    .option('-f, --format <format>', 'Output format (json, pretty)', 'pretty')
+    .action(async (id, options) => {
+      const spinner = ora(`Converting ID ${id}...`).start();
+      try {
+        const data = await get(`/utils/convert-legacy-id/${id}`);
+        spinner.succeed('ID converted');
+        console.log(formatOutput(data, options.format));
+      } catch (error) {
+        spinner.fail('Failed to convert ID');
+        console.error(chalk.red('Error:'), error.message);
+        process.exit(1);
+      }
+    });
+
+  program.addCommand(utilities);
+}

package/src/lib/api.js

@@ -0,0 +1,160 @@
+/**
+ * API Client Module
+ *
+ * HTTP client for Billingo API with error handling and rate limiting
+ */
+
+import axios from 'axios';
+import chalk from 'chalk';
+import { getAuthHeaders } from './auth.js';
+import { getBaseUrl } from './config.js';
+
+/**
+ * Create configured axios instance
+ * @returns {Object} Axios instance
+ */
+function createApiClient() {
+  const baseURL = getBaseUrl();
+
+  const client = axios.create({
+    baseURL,
+    timeout: 30000,
+    headers: getAuthHeaders(),
+  });
+
+  // Response interceptor for error handling
+  client.interceptors.response.use(
+    (response) => {
+      // Log rate limit info if available
+      if (response.headers['x-ratelimit-remaining']) {
+        const remaining = response.headers['x-ratelimit-remaining'];
+        const limit = response.headers['x-ratelimit-limit'];
+
+        if (parseInt(remaining) < 10) {
+          console.warn(
+            chalk.yellow(`Warning: Only ${remaining}/${limit} API calls remaining in this window`)
+          );
+        }
+      }
+
+      return response;
+    },
+    (error) => {
+      if (error.response) {
+        // Server responded with error status
+        const { status, data } = error.response;
+
+        switch (status) {
+          case 401:
+            throw new Error('Authentication failed. Check your API key.');
+          case 403:
+            throw new Error('Access denied. Insufficient permissions.');
+          case 404:
+            throw new Error('Resource not found.');
+          case 422:
+            throw new Error(
+              `Validation error: ${JSON.stringify(data.message || data, null, 2)}`
+            );
+          case 429:
+            const retryAfter = error.response.headers['retry-after'];
+            throw new Error(
+              `Rate limit exceeded. Retry after ${retryAfter} seconds.`
+            );
+          case 500:
+            throw new Error('Server error. Please try again later.');
+          default:
+            throw new Error(
+              `API error (${status}): ${JSON.stringify(data, null, 2)}`
+            );
+        }
+      } else if (error.request) {
+        // Request made but no response
+        throw new Error('No response from server. Check your connection.');
+      } else {
+        // Error setting up request
+        throw new Error(`Request error: ${error.message}`);
+      }
+    }
+  );
+
+  return client;
+}
+
+/**
+ * Make GET request
+ * @param {string} endpoint - API endpoint
+ * @param {Object} params - Query parameters
+ * @returns {Promise<Object>} Response data
+ */
+export async function get(endpoint, params = {}) {
+  const client = createApiClient();
+  const response = await client.get(endpoint, { params });
+  return response.data;
+}
+
+/**
+ * Make POST request
+ * @param {string} endpoint - API endpoint
+ * @param {Object} data - Request body
+ * @returns {Promise<Object>} Response data
+ */
+export async function post(endpoint, data = {}) {
+  const client = createApiClient();
+  const response = await client.post(endpoint, data);
+  return response.data;
+}
+
+/**
+ * Make PUT request
+ * @param {string} endpoint - API endpoint
+ * @param {Object} data - Request body
+ * @returns {Promise<Object>} Response data
+ */
+export async function put(endpoint, data = {}) {
+  const client = createApiClient();
+  const response = await client.put(endpoint, data);
+  return response.data;
+}
+
+/**
+ * Make DELETE request
+ * @param {string} endpoint - API endpoint
+ * @returns {Promise<Object>} Response data
+ */
+export async function del(endpoint) {
+  const client = createApiClient();
+  const response = await client.delete(endpoint);
+  return response.data;
+}
+
+/**
+ * Download file from API
+ * @param {string} endpoint - API endpoint
+ * @returns {Promise<Buffer>} File buffer
+ */
+export async function downloadFile(endpoint) {
+  const client = createApiClient();
+  const response = await client.get(endpoint, { responseType: 'arraybuffer' });
+  return response.data;
+}
+
+/**
+ * Format output for CLI display
+ * @param {*} data - Data to format
+ * @param {string} format - Output format (json, pretty)
+ * @returns {string} Formatted output
+ */
+export function formatOutput(data, format = 'pretty') {
+  if (format === 'json') {
+    return JSON.stringify(data, null, 2);
+  }
+
+  // Pretty print for terminal
+  if (Array.isArray(data)) {
+    return data.map((item, idx) => {
+      return `${chalk.cyan(`[${idx}]`)} ${JSON.stringify(item, null, 2)}`;
+    }).join('\n\n');
+  }
+
+  return JSON.stringify(data, null, 2);
+}

package/src/lib/auth.js

@@ -0,0 +1,32 @@
+/**
+ * Authentication Module
+ *
+ * Handles API key authentication for Billingo API
+ */
+
+import { getApiKey } from './config.js';
+
+/**
+ * Get authentication headers for API requests
+ * @returns {Object} Headers object with API key
+ * @throws {Error} If API key is not configured
+ */
+export function getAuthHeaders() {
+  const apiKey = getApiKey();
+
+  return {
+    'X-API-KEY': apiKey,
+    'Accept': 'application/json',
+    'Content-Type': 'application/json',
+  };
+}
+
+/**
+ * Validate API key format
+ * @param {string} apiKey - API key to validate
+ * @returns {boolean} True if format is valid
+ */
+export function validateApiKeyFormat(apiKey) {
+  // Billingo API keys are typically 32+ character alphanumeric strings
+  return typeof apiKey === 'string' && apiKey.length >= 20;
+}

package/src/lib/config.js

@@ -0,0 +1,87 @@
+/**
+ * Configuration Management
+ *
+ * Handles API key storage and configuration using conf package
+ */
+
+import Conf from 'conf';
+import { config as dotenvConfig } from 'dotenv';
+
+// Load environment variables
+dotenvConfig();
+
+const config = new Conf({
+  projectName: 'billingo-cli',
+  defaults: {
+    apiKey: process.env.BILLINGO_API_KEY || '',
+    baseUrl: process.env.BILLINGO_BASE_URL || 'https://api.billingo.hu/v3',
+  },
+});
+
+/**
+ * Get configuration value
+ * @param {string} key - Configuration key
+ * @returns {*} Configuration value
+ */
+export function getConfig(key) {
+  return config.get(key);
+}
+
+/**
+ * Set configuration value
+ * @param {string} key - Configuration key
+ * @param {*} value - Configuration value
+ */
+export function setConfig(key, value) {
+  config.set(key, value);
+}
+
+/**
+ * Get all configuration
+ * @returns {Object} All configuration values
+ */
+export function getAllConfig() {
+  return config.store;
+}
+
+/**
+ * Delete configuration value
+ * @param {string} key - Configuration key
+ */
+export function deleteConfig(key) {
+  config.delete(key);
+}
+
+/**
+ * Clear all configuration
+ */
+export function clearConfig() {
+  config.clear();
+}
+
+/**
+ * Get API key from config or environment
+ * @returns {string} API key
+ * @throws {Error} If API key is not configured
+ */
+export function getApiKey() {
+  const apiKey = getConfig('apiKey') || process.env.BILLINGO_API_KEY;
+
+  if (!apiKey) {
+    throw new Error(
+      'API key not configured. Set it with: billingo config set API_KEY <your-api-key>\n' +
+      'Or set BILLINGO_API_KEY environment variable.\n' +
+      'Get your API key at: https://app.billingo.hu/api-key'
+    );
+  }
+
+  return apiKey;
+}
+
+/**
+ * Get base URL from config or environment
+ * @returns {string} Base URL
+ */
+export function getBaseUrl() {
+  return getConfig('baseUrl') || process.env.BILLINGO_BASE_URL || 'https://api.billingo.hu/v3';
+}