@open-nav/cli 0.1.0

package/LICENSE

@@ -0,0 +1,29 @@
+MIT License
+
+Copyright (c) 2026 open-nav contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This repository vendors XML schemas, sample documents and validation message
+catalogues published by the Hungarian Tax and Customs Administration
+(Nemzeti Adó- és Vámhivatal) under the MIT license. Those files live under
+`schemas/` and `conformance/`, retain NAV's copyright, and are covered by
+`schemas/NAV-LICENCE.md`. See `schemas/README.md` for provenance.

package/README.md

@@ -0,0 +1,89 @@
+# @open-nav/cli
+
+Command line access to the NAV **Online Számla** invoice service.
+
+```sh
+npx @open-nav/cli --help
+# or
+npm install -g @open-nav/cli && open-nav --help
+```
+
+## Configuration
+
+Credentials come from the environment, or from a `.env` file found by walking
+up from the working directory. They are **never** accepted as command line
+arguments: that would put them in shell history, in process listings, and in
+the transcript of any agent that ran the command.
+
+```sh
+cp .env.example .env   # then fill it in
+open-nav config        # shows what is set, masks the secrets
+open-nav token         # end-to-end check: are the credentials real?
+```
+
+`open-nav help config` lists every variable.
+
+## Built for scripts and agents
+
+- **JSON by default when stdout is not a terminal.** No flag to remember; a
+  human at a terminal still gets readable text. `--json` and `--pretty`
+  override.
+- **One envelope for every result**, so a caller can branch on `ok` alone:
+  ```json
+  { "ok": true, "command": "validate", "data": { "valid": true } }
+  ```
+- **Exit codes that mean something**: `0` ok, `2` usage or configuration, `3`
+  the document failed local validation and was not sent, `4` NAV rejected it,
+  `5` no verdict reached (network, timeout, still processing).
+- **`--describe`** prints the whole command surface as JSON — names, usage,
+  options, exit codes, and whether each command needs credentials. An agent
+  can discover what the tool can do without a man page.
+
+```sh
+open-nav --describe | jq '.commands[] | select(.needsCredentials == false)'
+```
+
+## Commands
+
+| Command                    | Needs credentials | What it does                                               |
+| -------------------------- | ----------------- | ---------------------------------------------------------- |
+| `config`                   | no                | Report which variables are set, masking secrets            |
+| `validate <file>`          | no                | Check an invoice against schema and business rules         |
+| `fault <CODE>`             | no                | Look up NAV's description of a fault code                  |
+| `token`                    | yes               | Exchange credentials for a token — the quickest smoke test |
+| `taxpayer <taxNumber>`     | yes               | Look up a taxpayer; accepts the 11 digit written form      |
+| `submit <file...>`         | yes               | Validate, then submit; `--wait` polls for the verdict      |
+| `status <transactionId>`   | yes               | Processing status; `--wait` polls to a verdict             |
+| `digest --from --to`       | yes               | List invoices issued or received in a date range           |
+| `invoice <number>`         | yes               | Fetch one invoice in full; `--xml` prints the XML          |
+| `transactions --from --to` | yes               | List data submissions in a time window                     |
+
+## Validating without credentials
+
+`validate` and `fault` contact nothing. They are useful before you have a
+technical user at all, and they are the fastest way to find out why NAV
+rejected something:
+
+```sh
+open-nav validate invoice.xml --operation CREATE --pretty
+```
+
+```text
+invoice.xml: invalid (1 error, 0 warnings)
+
+  error  INCORRECT_SUMMARY_CALCULATION_INVOICE_VAT_AMOUNT_SUMMARY
+         invoiceSummary.summaryNormal.invoiceVatAmount
+         is 280000.00 but the lines total 280800.00
+         NAV: The amount of the tax VAT rates differs from the VAT of the invoice.
+```
+
+Findings carry NAV's own fault code and wording, in `en`, `hu` or `de` via
+`--language`, so a local failure reads like the rejection it prevents.
+
+`submit` validates before sending by default and refuses to submit a document
+with errors — a rejection costs a round trip and consumes the `requestId`.
+`--skip-validation` overrides that if you need it.
+
+## Licence
+
+MIT. Not affiliated with NAV.

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}

package/dist/bin.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { run } from './main.js';
+const exitCode = await run({
+    argv: process.argv.slice(2),
+    isTty: process.stdout.isTTY === true,
+});
+process.exitCode = exitCode;
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAEhC,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC;IACzB,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAC3B,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI;CACrC,CAAC,CAAC;AACH,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC"}

package/dist/commands.d.ts

@@ -0,0 +1,37 @@
+import { NavApiError } from '@open-nav/core';
+import { type ExitCode } from './errors.js';
+import { type LoadOptions } from './config.js';
+import { type Format, type Writer } from './output.js';
+export interface CommandContext {
+    format: Format;
+    writer: Writer;
+    load: LoadOptions;
+    /** Read a file, so tests need no filesystem. */
+    readFile?: (path: string) => string;
+    /** Write a file, creating parent directories. Injectable for tests. */
+    writeFile?: (path: string, contents: string) => void;
+    /** Write binary output, for PDFs. */
+    writeBinaryFile?: (path: string, contents: Buffer) => void;
+    /** Read binary input, for logos. */
+    readBinaryFile?: (path: string) => Buffer;
+    /** Whether a path already exists, so a download can resume. */
+    fileExists?: (path: string) => boolean;
+}
+export interface CommandDefinition {
+    name: string;
+    summary: string;
+    usage: string;
+    /** True when the command talks to NAV and therefore needs credentials. */
+    needsCredentials: boolean;
+    options?: Array<{
+        flag: string;
+        description: string;
+    }>;
+    run: (positionals: string[], flags: Record<string, string | boolean | undefined>, context: CommandContext) => Promise<ExitCode>;
+}
+export declare const COMMANDS: CommandDefinition[];
+export declare function findCommand(name: string): CommandDefinition | undefined;
+/** Machine-readable description of the whole surface, for tooling and agents. */
+export declare function describeCommands(): unknown;
+export { NavApiError };
+//# sourceMappingURL=commands.d.ts.map

package/dist/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,WAAW,EAQZ,MAAM,gBAAgB,CAAC;AAgBxB,OAAO,EAAoB,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAA+C,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAC5F,OAAO,EAA2C,KAAK,MAAM,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAEhG,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,WAAW,CAAC;IAClB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACpC,uEAAuE;IACvE,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACrD,qCAAqC;IACrC,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3D,oCAAoC;IACpC,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAC1C,+DAA+D;IAC/D,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CACxC;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,gBAAgB,EAAE,OAAO,CAAC;IAC1B,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvD,GAAG,EAAE,CACH,WAAW,EAAE,MAAM,EAAE,EACrB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,EACnD,OAAO,EAAE,cAAc,KACpB,OAAO,CAAC,QAAQ,CAAC,CAAC;CACxB;AA6GD,eAAO,MAAM,QAAQ,EAAE,iBAAiB,EA4pBvC,CAAC;AAEF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAEvE;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,IAAI,OAAO,CAc1C;AAED,OAAO,EAAE,WAAW,EAAE,CAAC"}