noxctl 0.4.1 → 0.5.0

package/README.md

@@ -261,6 +261,7 @@ Every operation is available both as a CLI command and as an MCP tool. The CLI i
 | `noxctl invoices create --customer <number> --input <file>` | `fortnox_create_invoice` | Create an invoice (mutation) |
 | `noxctl invoices update <docNumber> --input <file>` | `fortnox_update_invoice` | Update an invoice that has not been bookkeept (mutation) |
 | `noxctl invoices send <docNumber> [--method email\|print\|einvoice] [--subject <s>] [--body <s>] [--bcc <email>]` | `fortnox_send_invoice` | Send via email (default), print, or e-invoice (mutation) |
+| `noxctl invoices pdf <docNumber> [--file <path>\|-] [--mark-sent]` | `fortnox_invoice_pdf` | Download the invoice PDF (via `/preview`, no side effect). `--mark-sent` also flags it as sent afterwards (mutation) |
 | `noxctl invoices bookkeep <docNumber>` | `fortnox_bookkeep_invoice` | Bookkeep an invoice (mutation) |
 | `noxctl invoices credit <docNumber>` | `fortnox_credit_invoice` | Credit an invoice (mutation) |
 
@@ -480,6 +481,8 @@ CLI:
 noxctl invoices send 1001                              # prompts: "Send invoice 1001 via email. Continue? [y/N]"
 noxctl invoices send 1001 --yes                        # skip prompt (scripting/AI)
 noxctl invoices send 1001 --dry-run                    # preview without sending
+noxctl invoices pdf 1001                               # read-only, no prompt
+noxctl invoices pdf 1001 --mark-sent                   # prompts: also flags the invoice as sent
 noxctl customers update 42 --input customer.json       # prompts for confirmation
 noxctl vouchers create --input voucher.json --dry-run  # preview payload
 ```

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAcA,OAAO,EAOL,KAAK,eAAe,EACrB,MAAM,eAAe,CAAC;AAwHvB,wBAAgB,sBAAsB,IAAI,eAAe,CAExD"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAcA,OAAO,EAOL,KAAK,eAAe,EACrB,MAAM,eAAe,CAAC;AAmIvB,wBAAgB,sBAAsB,IAAI,eAAe,CAExD"}

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { Command, Option } from 'commander';
-import { readFileSync } from 'node:fs';
+import { readFileSync, writeFileSync } from 'node:fs';
 import { createInterface } from 'node:readline/promises';
 import { isJsonMode, outputList, outputDetail, outputConfirmation, formatTaxReport, formatFinancialReport, errorEnvelope, } from './formatter.js';
 import { readActivePointer, readActivePointerOutcome, writeActivePointer, deleteActivePointer, readProfileIndex, resolveProfile, } from './profiles.js';
@@ -9,10 +9,20 @@ import { applyPeriod } from './date-periods.js';
 import { DEFAULT_PROFILE, InvalidProfileNameError } from './profile-name.js';
 import { invoiceListColumns, invoiceDetailColumns, invoiceConfirmColumns, customerListColumns, customerDetailColumns, voucherListColumns, voucherDetailColumns, voucherRowColumns, accountListColumns, companyDetailColumns, articleListColumns, articleDetailColumns, supplierListColumns, supplierDetailColumns, supplierInvoiceListColumns, supplierInvoiceDetailColumns, supplierInvoiceConfirmColumns, invoicePaymentListColumns, invoicePaymentDetailColumns, supplierInvoicePaymentListColumns, supplierInvoicePaymentDetailColumns, offerListColumns, offerDetailColumns, orderListColumns, orderDetailColumns, projectListColumns, projectDetailColumns, costCenterListColumns, costCenterDetailColumns, taxReductionListColumns, taxReductionDetailColumns, priceListListColumns, priceListDetailColumns, priceListColumns, priceDetailColumns, financialYearListColumns, financialYearDetailColumns, lockedPeriodDetailColumns, contractListColumns, contractDetailColumns, topCustomerColumns, monthlyRevenueColumns, voucherAttachmentColumns, employeeListColumns, employeeDetailColumns, salaryTransactionListColumns, salaryTransactionDetailColumns, attendanceTransactionListColumns, attendanceTransactionDetailColumns, absenceTransactionListColumns, absenceTransactionDetailColumns, scheduleTimeDetailColumns, } from './views.js';
 const program = new Command();
+// A closed downstream pipe (`noxctl ... | head`, or a reader that exits early)
+// makes stdout emit EPIPE. That is normal for a CLI, and without this listener
+// Node reports it as an uncaught exception with a stack trace, bypassing the
+// command's own error handling.
+process.stdout.on('error', (err) => {
+    if (err.code === 'EPIPE') {
+        process.exit(0);
+    }
+    throw err;
+});
 program
     .name('noxctl')
     .description('CLI and MCP server for Fortnox accounting')
-    .version('0.4.1')
+    .version('0.5.0')
     .addOption(new Option('-o, --output <format>', 'Output format (default: table on TTY, json when piped)')
     .choices(['json', 'table'])
     .default(undefined))
@@ -1114,6 +1124,111 @@ invoices
     const data = await sendInvoice(documentNumber, opts.method, emailOptions);
     outputConfirmation(`Invoice ${documentNumber} sent via ${opts.method}.`, json(), data, invoiceConfirmColumns, 'Invoice');
 });
+invoices
+    .command('pdf <documentNumber>')
+    .description('Download an invoice as a PDF')
+    // Note: -o/--output is already taken globally for the output *format*
+    // (json|table), so the destination path is --file.
+    .option('-f, --file <path>', 'Write the PDF here (- for stdout)')
+    .option('--mark-sent', 'Also flag the invoice as sent in Fortnox (uses /print)')
+    .option('-y, --yes', 'Skip confirmation prompt (only needed with --mark-sent)')
+    .option('--dry-run', 'Preview the action without sending it')
+    .addHelpText('after', `
+The PDF always comes from Fortnox's /preview endpoint, which does not change the
+invoice. --mark-sent additionally calls /print afterwards to set Sent=true — the
+file is written first, so a failed write never leaves an invoice flagged as sent
+with no PDF to show for it.
+
+Without --file the PDF is written to invoice-<documentNumber>.pdf in the current
+directory.
+
+When writing to a file, --mark-sent replaces it with the document /print itself
+returned, so the saved copy matches the version that was marked. Streaming to
+stdout cannot do that — bytes already written cannot be recalled — so with
+--file - the streamed document is the /preview render.
+
+Examples:
+  noxctl invoices pdf 28
+  noxctl invoices pdf 28 --file ~/Desktop/faktura-28.pdf
+  noxctl invoices pdf 28 --file - > faktura.pdf
+  noxctl invoices pdf 28 --mark-sent --yes`)
+    .action(async (documentNumber, opts) => {
+    const { getInvoicePdf, markInvoicePrinted } = await import('./operations/invoices.js');
+    const toStdout = opts.file === '-';
+    // Only an *explicit* --output json conflicts here. json() alone is not the
+    // test: it defaults to true whenever stdout is piped, which is exactly how
+    // `--file -` is meant to be used.
+    if (toStdout && program.opts().output === 'json') {
+        throw new Error('--file - writes raw PDF bytes to stdout and cannot be combined with --output json.');
+    }
+    // Only --mark-sent mutates the invoice; a plain download needs no confirmation.
+    if (opts.markSent || opts.dryRun) {
+        const action = opts.markSent
+            ? `Download invoice ${documentNumber} as PDF and flag it as sent`
+            : `Download invoice ${documentNumber} as PDF`;
+        if (!(await confirmMutation(action, opts))) {
+            return;
+        }
+    }
+    const pdf = await getInvoicePdf(documentNumber);
+    if (toStdout) {
+        // Wait for the bytes to be flushed before mutating anything: a closed or
+        // broken pipe must not leave the invoice marked as sent.
+        await new Promise((resolve, reject) => {
+            process.stdout.write(pdf, (err) => (err ? reject(err) : resolve()));
+        });
+        if (opts.markSent)
+            await markInvoicePrinted(documentNumber);
+        return;
+    }
+    const path = opts.file ?? `invoice-${documentNumber}.pdf`;
+    writeFileSync(path, pdf);
+    // Only now that the PDF is safely on disk do we change Fortnox. If that
+    // fails, the download still succeeded — say so, or the user is left
+    // thinking the whole command achieved nothing.
+    let printed;
+    if (opts.markSent) {
+        try {
+            printed = await markInvoicePrinted(documentNumber);
+        }
+        catch (err) {
+            throw new Error(`Invoice ${documentNumber} saved to ${path} (${pdf.length} bytes), but marking it as sent failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // Prefer the document /print actually produced, so the saved copy matches
+    // the version that was marked as sent. Best-effort: the /preview copy is
+    // already written and the invoice is already flagged, so a failure here is
+    // reported as a note rather than raised as a failed operation.
+    let bytes = pdf.length;
+    let note = '';
+    if (printed?.pdf) {
+        try {
+            writeFileSync(path, printed.pdf);
+            bytes = printed.pdf.length;
+        }
+        catch (err) {
+            note += ` Saved file is the /preview copy; rewriting it with the printed version failed: ${err instanceof Error ? err.message : String(err)}`;
+        }
+    }
+    // Only claim the invoice is sent if Fortnox actually said so.
+    if (printed && !printed.confirmed) {
+        note += ` ${String(printed.invoice.Note)}`;
+    }
+    else if (printed && printed.invoice.Sent === true) {
+        note += ' Marked as sent.';
+    }
+    else if (printed) {
+        note += ' Warning: Fortnox still reports this invoice as not sent.';
+    }
+    outputConfirmation(`Invoice ${documentNumber} saved to ${path} (${bytes} bytes).${note}`, json(), {
+        DocumentNumber: documentNumber,
+        Path: path,
+        Bytes: bytes,
+        // Report what Fortnox says the invoice's state is, not what we asked
+        // for; undefined means "not checked" or "could not be confirmed".
+        Sent: printed?.confirmed ? printed.invoice.Sent : undefined,
+    });
+});
 invoices
     .command('bookkeep <documentNumber>')
     .description('Bookkeep an invoice')