@centry-digital/bukku-cli 2.0.0

package/README.md

@@ -0,0 +1,266 @@
+# @centry-digital/bukku-cli
+
+[![npm version](https://img.shields.io/npm/v/@centry-digital/bukku-cli)](https://www.npmjs.com/package/@centry-digital/bukku-cli)
+
+A command-line interface for [Bukku](https://bukku.my), a Malaysian accounting platform. Manage invoices, contacts, products, and more from your terminal.
+
+## What can it do?
+
+The CLI exposes **169 commands** across 9 categories, covering the full Bukku API:
+
+| Category | Commands | What you can do |
+|----------|----------|-----------------|
+| **Sales** | 42 | Quotes, orders, delivery orders, invoices, credit notes, payments, refunds |
+| **Purchases** | 36 | Purchase orders, bills, credit notes, goods received notes, payments, refunds |
+| **Banking** | 18 | Money in, money out, bank transfers |
+| **Contacts** | 12 | Customers, suppliers, contact groups |
+| **Products** | 18 | Products, bundles, product groups |
+| **Accounting** | 13 | Chart of accounts, journal entries |
+| **Files** | 3 | Upload and manage file attachments |
+| **Control Panel** | 21 | Locations, tags, tag groups |
+| **Reference Data** | 10 | Tax codes, currencies, payment methods, terms, and more |
+
+Every list/get/create/update/delete operation available in the Bukku web UI is available from the command line.
+
+## Quick Start
+
+Try it without installing:
+
+```bash
+npx @centry-digital/bukku-cli --help
+```
+
+Or install globally:
+
+```bash
+npm install -g @centry-digital/bukku-cli
+bukku --help
+```
+
+## Configuration
+
+The CLI needs two things: your API token and company subdomain. There are three ways to provide them, listed in order of precedence:
+
+### 1. CLI flags (highest precedence)
+
+```bash
+bukku --api-token YOUR_TOKEN --company-subdomain YOUR_SUB sales invoices list
+```
+
+### 2. Environment variables
+
+```bash
+export BUKKU_API_TOKEN=your-token-here
+export BUKKU_COMPANY_SUBDOMAIN=your-subdomain
+bukku sales invoices list
+```
+
+### 3. Config file (~/.bukkurc)
+
+```bash
+bukku config set api_token your-token-here
+bukku config set company_subdomain your-subdomain
+```
+
+Verify your configuration:
+
+```bash
+bukku config show
+```
+
+This shows the resolved value for each field and where it came from (flag, environment variable, or config file).
+
+## Usage Examples
+
+### Sales
+
+```bash
+# List recent invoices
+bukku sales invoices list --limit 5
+
+# Get a specific invoice
+bukku sales invoices get 123
+
+# Create an invoice
+bukku sales invoices create --data '{
+  "contact_id": 1,
+  "date": "2025-01-15",
+  "currency_code": "MYR",
+  "exchange_rate": 1,
+  "tax_mode": "exclusive",
+  "payment_mode": "credit",
+  "status": "draft",
+  "form_items": [{"account_id": 100, "description": "Consulting", "amount": 5000}],
+  "term_items": [{"payment_due": "100%", "date": "2025-02-15"}]
+}'
+
+# List quotes in table format
+bukku sales quotes list --format table
+```
+
+### Purchases
+
+```bash
+# List bills
+bukku purchases bills list --format table
+
+# Get a specific bill
+bukku purchases bills get 456
+
+# List purchase orders
+bukku purchases orders list --limit 10
+```
+
+### Banking
+
+```bash
+# List money-in transactions
+bukku banking money-in list --limit 10
+
+# List money-out transactions
+bukku banking money-out list --format table
+
+# List bank transfers
+bukku banking transfers list
+```
+
+### Contacts
+
+```bash
+# List all contacts
+bukku contacts contacts list --format table
+
+# Get a specific contact
+bukku contacts contacts get 789
+
+# List contact groups
+bukku contacts contact-groups list
+```
+
+### Products
+
+```bash
+# List products
+bukku products products list --format table
+
+# Get a specific product
+bukku products products get 123
+
+# List product groups
+bukku products product-groups list
+```
+
+### Accounting
+
+```bash
+# List journal entries
+bukku accounting journal-entries list
+
+# Search chart of accounts
+bukku accounting accounts list --format table
+```
+
+### Files
+
+```bash
+# Upload a file
+bukku files upload /path/to/receipt.pdf
+
+# List uploaded files
+bukku files files list
+```
+
+### Control Panel
+
+```bash
+# List locations
+bukku control-panel locations list
+
+# List tags
+bukku control-panel tags list --format table
+
+# List tag groups
+bukku control-panel tag-groups list
+```
+
+### Reference Data
+
+```bash
+# List tax codes
+bukku ref-data tax-codes
+
+# List currencies
+bukku ref-data currencies
+
+# List payment methods
+bukku ref-data payment-methods
+
+# List classification codes (Malaysia e-Invoice)
+bukku ref-data classification-codes
+```
+
+## Input Formats
+
+For create and update commands, provide JSON data in one of these ways:
+
+**Inline with `--data` flag:**
+
+```bash
+bukku sales invoices create --data '{"contact_id": 1, "date": "2025-01-15", ...}'
+```
+
+**Piped from a file:**
+
+```bash
+cat invoice.json | bukku sales invoices create
+```
+
+**Dry run (preview without sending):**
+
+```bash
+bukku sales invoices create --data '{"contact_id": 1, ...}' --dry-run
+```
+
+Dry run shows the HTTP method, URL, and request body that would be sent, without making the API call.
+
+## Output Formats
+
+**JSON (default):** Machine-readable output, easy to pipe to `jq`:
+
+```bash
+bukku sales invoices list | jq '.[0].total'
+```
+
+**Table:** Human-readable table format:
+
+```bash
+bukku sales invoices list --format table
+```
+
+Errors are written to stderr as structured JSON, so they don't interfere with piped output.
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Authentication error (missing or invalid credentials) |
+| 3 | API error (Bukku returned an error) |
+| 4 | Validation error (invalid input or config) |
+
+## Getting Your API Token
+
+1. Log into your [Bukku](https://bukku.my) account
+2. Go to **Control Panel > Integrations > API Access**
+3. Generate a new API token (or copy your existing one)
+4. Note your company subdomain from the URL (e.g. `mycompany` from `mycompany.bukku.my`)
+
+## Related
+
+- [@centry-digital/bukku-mcp](https://www.npmjs.com/package/@centry-digital/bukku-mcp) -- MCP server for connecting AI assistants (Claude, etc.) to Bukku
+- [GitHub repository](https://github.com/centry-digital/bukku)
+
+## License
+
+MIT

package/build/commands/config.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare const configCommand: Command;
+//# sourceMappingURL=config.d.ts.map

package/build/commands/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/commands/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAWpC,eAAO,MAAM,aAAa,SACgB,CAAC"}

package/build/commands/config.js

@@ -0,0 +1,68 @@
+import { Command } from 'commander';
+import { readRc, writeRc, checkPermissions } from '../config/rc.js';
+import { maskToken } from '../config/auth.js';
+const VALID_KEYS = ['api_token', 'company_subdomain'];
+function isValidKey(key) {
+    return VALID_KEYS.includes(key);
+}
+export const configCommand = new Command('config')
+    .description('Manage CLI configuration');
+// config set <key> <value>
+configCommand
+    .command('set')
+    .description('Set a config value')
+    .argument('<key>', 'Config key (api_token, company_subdomain)')
+    .argument('<value>', 'Config value')
+    .action(async (key, value) => {
+    if (!isValidKey(key)) {
+        console.error(JSON.stringify({
+            error: 'Invalid config key',
+            code: 'VALIDATION_ERROR',
+            details: { valid_keys: [...VALID_KEYS] },
+        }));
+        process.exit(4);
+    }
+    await writeRc(key, value);
+    console.log(JSON.stringify({ ok: true, key, message: 'Config updated' }));
+    const perms = await checkPermissions();
+    if (!perms.ok) {
+        console.error(`Warning: ~/.bukkurc has permissions ${perms.mode}, expected 0600. Run: chmod 600 ~/.bukkurc`);
+    }
+});
+// config show
+configCommand
+    .command('show')
+    .description('Show resolved configuration')
+    .action(async function () {
+    const rc = await readRc();
+    // Resolve each field with precedence: flags > env > rc
+    const parentOpts = this.parent?.parent?.opts() ?? {};
+    const config = {};
+    // api_token
+    if (parentOpts.apiToken) {
+        config['api_token'] = { value: maskToken(parentOpts.apiToken), source: 'flags' };
+    }
+    else if (process.env['BUKKU_API_TOKEN']) {
+        config['api_token'] = { value: maskToken(process.env['BUKKU_API_TOKEN']), source: 'env' };
+    }
+    else if (rc['api_token']) {
+        config['api_token'] = { value: maskToken(rc['api_token']), source: 'rc' };
+    }
+    else {
+        config['api_token'] = { value: null, source: 'not set' };
+    }
+    // company_subdomain
+    if (parentOpts.companySubdomain) {
+        config['company_subdomain'] = { value: parentOpts.companySubdomain, source: 'flags' };
+    }
+    else if (process.env['BUKKU_COMPANY_SUBDOMAIN']) {
+        config['company_subdomain'] = { value: process.env['BUKKU_COMPANY_SUBDOMAIN'], source: 'env' };
+    }
+    else if (rc['company_subdomain']) {
+        config['company_subdomain'] = { value: rc['company_subdomain'], source: 'rc' };
+    }
+    else {
+        config['company_subdomain'] = { value: null, source: 'not set' };
+    }
+    console.log(JSON.stringify({ config }));
+});

package/build/commands/custom/archive.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from 'commander';
+/**
+ * Register archive and unarchive commands for contacts, products, bundles, accounts, locations.
+ *
+ * These commands are added as subcommands under existing resource commands
+ * created by the factory (registerEntityCommands must run first).
+ */
+export declare function registerArchiveCommands(program: Command): void;
+//# sourceMappingURL=archive.d.ts.map

package/build/commands/custom/archive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../../src/commands/custom/archive.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAiCzC;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAoD9D"}

package/build/commands/custom/archive.js

@@ -0,0 +1,82 @@
+import { withAuth } from '../wrapper.js';
+import { outputJson } from '../../output/json.js';
+import { outputDryRun } from '../../output/dry-run.js';
+import { outputError, ExitCode } from '../../output/error.js';
+/**
+ * Archive/unarchive configs for entities that support is_archived toggling.
+ *
+ * Note: locations use singular /location/{id} path (API inconsistency).
+ */
+const ARCHIVE_CONFIGS = [
+    { group: 'contacts', resource: 'contacts', apiPath: '/contacts', description: 'contact' },
+    { group: 'products', resource: 'products', apiPath: '/products', description: 'product' },
+    { group: 'products', resource: 'bundles', apiPath: '/products/bundles', description: 'product bundle' },
+    { group: 'accounting', resource: 'accounts', apiPath: '/accounts', description: 'account' },
+    { group: 'control-panel', resource: 'locations', apiPath: '/location', description: 'location' },
+];
+/**
+ * Parse and validate a positional ID argument.
+ */
+function parseId(idArg) {
+    const parsed = parseInt(idArg, 10);
+    if (isNaN(parsed) || parsed <= 0) {
+        outputError({ error: 'ID must be a positive integer', code: 'VALIDATION_ERROR' }, ExitCode.VALIDATION);
+    }
+    return parsed;
+}
+/**
+ * Register archive and unarchive commands for contacts, products, bundles, accounts, locations.
+ *
+ * These commands are added as subcommands under existing resource commands
+ * created by the factory (registerEntityCommands must run first).
+ */
+export function registerArchiveCommands(program) {
+    for (const config of ARCHIVE_CONFIGS) {
+        // Find the group command (already created by factory)
+        const groupCmd = program.commands.find((c) => c.name() === config.group);
+        if (!groupCmd)
+            continue;
+        // Find the resource subcommand (already created by factory)
+        const resourceCmd = groupCmd.commands.find((c) => c.name() === config.resource);
+        if (!resourceCmd)
+            continue;
+        // Add archive subcommand
+        const archiveHandler = withAuth(async ({ client, opts, auth }) => {
+            const id = opts._entityId;
+            if (opts.dryRun) {
+                outputDryRun({ method: 'PATCH', path: `${config.apiPath}/${id}`, token: auth.apiToken, subdomain: auth.companySubdomain, body: { is_archived: true } });
+                return;
+            }
+            const data = await client.patch(`${config.apiPath}/${id}`, { is_archived: true });
+            outputJson(data);
+        });
+        resourceCmd
+            .command('archive <id>')
+            .description(`Archive a ${config.description}`)
+            .option('--dry-run', 'Show request details without executing', false)
+            .action(function (idArg, ...rest) {
+            const id = parseId(idArg);
+            this.setOptionValue('_entityId', id);
+            return archiveHandler.call(this, idArg, ...rest);
+        });
+        // Add unarchive subcommand
+        const unarchiveHandler = withAuth(async ({ client, opts, auth }) => {
+            const id = opts._entityId;
+            if (opts.dryRun) {
+                outputDryRun({ method: 'PATCH', path: `${config.apiPath}/${id}`, token: auth.apiToken, subdomain: auth.companySubdomain, body: { is_archived: false } });
+                return;
+            }
+            const data = await client.patch(`${config.apiPath}/${id}`, { is_archived: false });
+            outputJson(data);
+        });
+        resourceCmd
+            .command('unarchive <id>')
+            .description(`Unarchive a ${config.description}`)
+            .option('--dry-run', 'Show request details without executing', false)
+            .action(function (idArg, ...rest) {
+            const id = parseId(idArg);
+            this.setOptionValue('_entityId', id);
+            return unarchiveHandler.call(this, idArg, ...rest);
+        });
+    }
+}

package/build/commands/custom/file-upload.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from 'commander';
+/**
+ * Register the file upload command.
+ *
+ * Uploads a file to Bukku via multipart/form-data using BukkuClient.postMultipart.
+ * Validates the file exists before uploading.
+ */
+export declare function registerFileUploadCommand(program: Command): void;
+//# sourceMappingURL=file-upload.d.ts.map

package/build/commands/custom/file-upload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-upload.d.ts","sourceRoot":"","sources":["../../../src/commands/custom/file-upload.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQzC;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAyChE"}

package/build/commands/custom/file-upload.js

@@ -0,0 +1,47 @@
+import { basename } from 'node:path';
+import { access } from 'node:fs/promises';
+import { withAuth } from '../wrapper.js';
+import { outputJson } from '../../output/json.js';
+import { outputDryRun } from '../../output/dry-run.js';
+import { outputError, ExitCode } from '../../output/error.js';
+/**
+ * Register the file upload command.
+ *
+ * Uploads a file to Bukku via multipart/form-data using BukkuClient.postMultipart.
+ * Validates the file exists before uploading.
+ */
+export function registerFileUploadCommand(program) {
+    // Find or create the files group command.
+    // The factory creates a 'files' group for the file entity (list only),
+    // so it should already exist. If not, create it.
+    let groupCmd = program.commands.find((c) => c.name() === 'files');
+    if (!groupCmd) {
+        groupCmd = program
+            .command('files')
+            .description('File uploads and attachments');
+    }
+    const wrappedHandler = withAuth(async ({ client, opts, auth }) => {
+        const filePath = opts._filePath;
+        // Validate file exists
+        try {
+            await access(filePath);
+        }
+        catch {
+            outputError({ error: 'File not found: ' + filePath, code: 'VALIDATION_ERROR' }, ExitCode.VALIDATION);
+        }
+        if (opts.dryRun) {
+            outputDryRun({ method: 'POST', path: '/files', token: auth.apiToken, subdomain: auth.companySubdomain, body: { file: basename(filePath) } });
+            return;
+        }
+        const data = await client.postMultipart('/files', filePath);
+        outputJson(data);
+    });
+    groupCmd
+        .command('upload <path>')
+        .description('Upload a file to Bukku')
+        .option('--dry-run', 'Show request details without executing', false)
+        .action(function (pathArg, ...rest) {
+        this.setOptionValue('_filePath', pathArg);
+        return wrappedHandler.call(this, pathArg, ...rest);
+    });
+}

package/build/commands/custom/journal-entry.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from 'commander';
+/**
+ * Register journal entry create and update commands with double-entry validation.
+ *
+ * The factory generates list, get, and delete for journal entries.
+ * Create and update need custom handling to validate that debits equal credits
+ * before submitting to the API.
+ */
+export declare function registerJournalEntryCommands(program: Command): void;
+//# sourceMappingURL=journal-entry.d.ts.map

package/build/commands/custom/journal-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal-entry.d.ts","sourceRoot":"","sources":["../../../src/commands/custom/journal-entry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsBzC;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA0EnE"}

package/build/commands/custom/journal-entry.js

@@ -0,0 +1,82 @@
+import { validateDoubleEntry } from 'core';
+import { withAuth } from '../wrapper.js';
+import { outputJson } from '../../output/json.js';
+import { outputDryRun } from '../../output/dry-run.js';
+import { outputError, ExitCode } from '../../output/error.js';
+import { readJsonInput } from '../../input/json.js';
+/**
+ * Parse and validate a positional ID argument.
+ */
+function parseId(idArg) {
+    const parsed = parseInt(idArg, 10);
+    if (isNaN(parsed) || parsed <= 0) {
+        outputError({ error: 'ID must be a positive integer', code: 'VALIDATION_ERROR' }, ExitCode.VALIDATION);
+    }
+    return parsed;
+}
+/**
+ * Register journal entry create and update commands with double-entry validation.
+ *
+ * The factory generates list, get, and delete for journal entries.
+ * Create and update need custom handling to validate that debits equal credits
+ * before submitting to the API.
+ */
+export function registerJournalEntryCommands(program) {
+    // Find existing accounting group and journal-entries resource
+    const groupCmd = program.commands.find((c) => c.name() === 'accounting');
+    if (!groupCmd)
+        return;
+    const resourceCmd = groupCmd.commands.find((c) => c.name() === 'journal-entries');
+    if (!resourceCmd)
+        return;
+    // Add create subcommand
+    resourceCmd
+        .command('create')
+        .description('Create a new journal entry')
+        .option('--data <json>', 'JSON data (or pipe to stdin)')
+        .option('--dry-run', 'Show request details without executing', false)
+        .action(withAuth(async ({ client, opts, auth }) => {
+        const body = await readJsonInput(opts);
+        // Validate double-entry balance if journal_items present
+        if (body.journal_items && Array.isArray(body.journal_items)) {
+            const validation = validateDoubleEntry(body.journal_items);
+            if (!validation.valid) {
+                outputError({ error: validation.error, code: 'VALIDATION_ERROR' }, ExitCode.VALIDATION);
+            }
+        }
+        if (opts.dryRun) {
+            outputDryRun({ method: 'POST', path: '/journal_entries', token: auth.apiToken, subdomain: auth.companySubdomain, body });
+            return;
+        }
+        const data = await client.post('/journal_entries', body);
+        outputJson(data);
+    }));
+    // Add update subcommand
+    const updateHandler = withAuth(async ({ client, opts, auth }) => {
+        const id = opts._entityId;
+        const body = await readJsonInput(opts);
+        // Validate double-entry balance if journal_items present in update
+        if (body.journal_items && Array.isArray(body.journal_items)) {
+            const validation = validateDoubleEntry(body.journal_items);
+            if (!validation.valid) {
+                outputError({ error: validation.error, code: 'VALIDATION_ERROR' }, ExitCode.VALIDATION);
+            }
+        }
+        if (opts.dryRun) {
+            outputDryRun({ method: 'PUT', path: `/journal_entries/${id}`, token: auth.apiToken, subdomain: auth.companySubdomain, body });
+            return;
+        }
+        const data = await client.put(`/journal_entries/${id}`, body);
+        outputJson(data);
+    });
+    resourceCmd
+        .command('update <id>')
+        .description('Update a journal entry')
+        .option('--data <json>', 'JSON data (or pipe to stdin)')
+        .option('--dry-run', 'Show request details without executing', false)
+        .action(function (idArg, ...rest) {
+        const id = parseId(idArg);
+        this.setOptionValue('_entityId', id);
+        return updateHandler.call(this, idArg, ...rest);
+    });
+}

package/build/commands/custom/location-write.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from 'commander';
+/**
+ * Register location get/update/delete commands using singular /location/{id} path.
+ *
+ * The Bukku API uses /locations (plural) for list/create but /location/{id} (singular)
+ * for get/update/delete. The factory only generates list and create for locations,
+ * so these custom commands handle the singular-path operations.
+ */
+export declare function registerLocationWriteCommands(program: Command): void;
+//# sourceMappingURL=location-write.d.ts.map

package/build/commands/custom/location-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"location-write.d.ts","sourceRoot":"","sources":["../../../src/commands/custom/location-write.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsBzC;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA4EpE"}