@open-nav/mock-server 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,77 @@
+# @open-nav/mock-server
+
+A local stand-in for the NAV **Online Számla** invoice service, so an
+integration can be tested without a technical user.
+
+```sh
+npx @open-nav/mock-server
+```
+
+It prints a set of fake credentials and a base URL. Export them and the
+`open-nav` CLI — or your own code — talks to the mock exactly as it would to
+NAV.
+
+## Why not just stub `fetch`
+
+Because the parts that break are the parts a stub skips. This mock:
+
+- **Verifies the request signature the way NAV does**, recomputing the
+  SHA3-512 of `requestId + timestamp + signKey`, plus the concatenated
+  per-operation hashes in index order for a batch. A caller that builds the
+  signature wrongly finds out here, against a readable error, instead of
+  against the live service where the only clue is `INVALID_SIGNATURE`.
+- **Rejects a replayed `requestId`**, which is how a home-made identifier
+  scheme fails in production.
+- **Spends an exchange token exactly once.**
+- **Decides an invoice's fate with this project's validator**, so a broken
+  invoice comes back `ABORTED` carrying the same NAV fault code the service
+  would have reported.
+- Keeps the invoices, so `queryInvoiceDigest`, `queryInvoiceData` and
+  `queryInvoiceCheck` answer from what was actually submitted.
+
+## In tests
+
+```ts
+import { startMockServer } from '@open-nav/mock-server';
+import { NavClient, waitForTransaction } from '@open-nav/client';
+
+const mock = await startMockServer({ credentials, pollsBeforeDone: 2 });
+const client = new NavClient({ credentials, software, baseUrl: mock.url });
+
+const { transactionId } = await client.submitInvoices([{ operation: 'CREATE', invoice }]);
+const outcome = await waitForTransaction(client, transactionId);
+
+expect(outcome.accepted).toHaveLength(1);
+expect(mock.state.invoices.size).toBe(1); // assert on what the service received
+await mock.close();
+```
+
+`pollsBeforeDone` controls how many polls a transaction takes to settle, so a
+caller's polling loop can be exercised deliberately: it walks `RECEIVED` →
+`PROCESSING` → `DONE` rather than settling immediately.
+
+`mock.state` exposes everything received — invoices, transactions, issued
+tokens, and the raw body of every request — so a test can assert on what was
+sent, not only on what came back.
+
+## Options
+
+| Option            | Default             | Meaning                                         |
+| ----------------- | ------------------- | ----------------------------------------------- |
+| `credentials`     | —                   | The technical user the mock accepts             |
+| `taxpayers`       | `[]`                | Registry `queryTaxpayer` answers from           |
+| `port`            | `0` (any free port) | `8080` when run from the CLI                    |
+| `pollsBeforeDone` | `0`                 | Polls before a transaction settles              |
+| `validate`        | `true`              | Abort invoices this project's validator rejects |
+| `now`             | `() => new Date()`  | Injectable clock                                |
+
+## What it is not
+
+Not a reimplementation of NAV. It does not know your invoice history, will not
+tell you whether an invoice number was used two years ago, and its acceptance
+is not evidence that NAV will accept the same document. It exists to catch the
+mistakes that are decidable locally, early and cheaply.
+
+## 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,81 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { startMockServer } from './server.js';
+/**
+ * Run the mock service standalone, so the CLI and any other integration can
+ * be pointed at it without credentials.
+ */
+const { values } = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+        port: { type: 'string' },
+        host: { type: 'string' },
+        polls: { type: 'string' },
+        'no-validate': { type: 'boolean' },
+        help: { type: 'boolean', short: 'h' },
+    },
+    strict: true,
+});
+if (values.help === true) {
+    console.log(`open-nav-mock — a local stand-in for the NAV Online Számla invoice service
+
+  --port <n>       Port to listen on (default 8080; 0 picks a free one)
+  --host <host>    Interface to bind (default 127.0.0.1)
+  --polls <n>      Polls before a transaction settles (default 0, immediate)
+  --no-validate    Accept every invoice instead of validating it
+`);
+    process.exit(0);
+}
+// Obviously fake credentials, printed on startup so they can be copied.
+const credentials = {
+    login: 'mocklogin123',
+    password: 'mock-password',
+    signKey: 'mock-sign-key-0123456789',
+    exchangeKey: '0123456789abcdef',
+    taxNumber: '99999999',
+};
+const mock = await startMockServer({
+    credentials,
+    port: values.port === undefined ? 8080 : Number(values.port),
+    ...(values.host ? { host: values.host } : {}),
+    pollsBeforeDone: values.polls === undefined ? 0 : Number(values.polls),
+    validate: values['no-validate'] !== true,
+    taxpayers: [
+        {
+            taxNumber: '99999999',
+            name: 'Értékesítő Kft',
+            shortName: 'Értékesítő',
+            valid: true,
+            vatCode: '2',
+            countyCode: '41',
+        },
+        {
+            taxNumber: '99887764',
+            name: 'Beszerző Kft',
+            shortName: 'Beszerző',
+            valid: true,
+            vatCode: '2',
+            countyCode: '02',
+        },
+    ],
+});
+console.log(`Mock NAV invoice service listening on ${mock.url}`);
+console.log('');
+console.log('Point the CLI at it with these (fake) credentials:');
+console.log('');
+console.log(`  export NAV_BASE_URL=${mock.url}`);
+console.log(`  export NAV_LOGIN=${credentials.login}`);
+console.log(`  export NAV_PASSWORD=${credentials.password}`);
+console.log(`  export NAV_SIGN_KEY=${credentials.signKey}`);
+console.log(`  export NAV_EXCHANGE_KEY=${credentials.exchangeKey}`);
+console.log(`  export NAV_TAX_NUMBER=${credentials.taxNumber}`);
+console.log('  export NAV_SOFTWARE_ID=OPENNAVMOCK000001');
+console.log('');
+console.log('Then, for example:  open-nav token');
+console.log('Press Ctrl+C to stop.');
+const shutdown = () => {
+    void mock.close().then(() => process.exit(0));
+};
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":"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"}

package/dist/handlers.d.ts

@@ -0,0 +1,73 @@
+import type { MockState } from './state.js';
+/** Credentials the mock expects, mirroring a technical user. */
+export interface MockCredentials {
+    login: string;
+    password: string;
+    signKey: string;
+    exchangeKey: string;
+    taxNumber: string;
+}
+export interface HandlerConfig {
+    credentials: MockCredentials;
+    /**
+     * Polls before a transaction reaches a terminal state.
+     *
+     * Zero means the verdict is available immediately, which is what most tests
+     * want. A higher number exercises the caller's polling loop.
+     */
+    pollsBeforeDone: number;
+    /**
+     * Run the invoices through the validator and abort the invalid ones.
+     *
+     * On by default, so the mock rejects exactly what the library predicts NAV
+     * would reject. A test that submits a bad invoice sees it aborted.
+     */
+    validate: boolean;
+    /** Current time, injectable for deterministic tests. */
+    now: () => Date;
+}
+export interface RequestContext {
+    operation: string;
+    body: string;
+    document: {
+        root: string;
+        value: Record<string, unknown>;
+    };
+}
+export interface HandlerResult {
+    status: number;
+    body: string;
+}
+/** A NAV interface error code the mock can return. */
+type InterfaceError = 'INVALID_REQUEST' | 'INVALID_SECURITY_USER' | 'INVALID_SIGNATURE' | 'INVALID_REQUEST_ID' | 'INVALID_EXCHANGE_TOKEN' | 'OPERATION_FAILED';
+export declare class MockError extends Error {
+    readonly errorCode: InterfaceError;
+    readonly status: number;
+    constructor(errorCode: InterfaceError, message: string, status?: number);
+}
+export declare function errorResponse(config: HandlerConfig, errorCode: string, message: string): string;
+/**
+ * Verify the request the way NAV does.
+ *
+ * This is the reason a mock is worth having: it recomputes the signature from
+ * the request's own fields and the expected sign key, so a caller that builds
+ * the signature wrongly finds out here rather than against the live service,
+ * where the only clue is an opaque INVALID_SIGNATURE.
+ */
+export declare function authenticate(context: RequestContext, config: HandlerConfig, state: MockState, signedOperations?: Array<{
+    index: number;
+    operation: string;
+    base64Payload: string;
+}>): void;
+export declare function handleTokenExchange(context: RequestContext, config: HandlerConfig, state: MockState): HandlerResult;
+export declare function handleManageInvoice(context: RequestContext, config: HandlerConfig, state: MockState): HandlerResult;
+export declare function handleQueryTransactionStatus(context: RequestContext, config: HandlerConfig, state: MockState): HandlerResult;
+export declare function handleQueryTaxpayer(context: RequestContext, config: HandlerConfig, state: MockState): HandlerResult;
+export declare function handleQueryInvoiceCheck(context: RequestContext, config: HandlerConfig, state: MockState): HandlerResult;
+export declare function handleQueryInvoiceData(context: RequestContext, config: HandlerConfig, state: MockState): HandlerResult;
+export declare function handleQueryInvoiceDigest(context: RequestContext, config: HandlerConfig, state: MockState): HandlerResult;
+export declare function handleQueryTransactionList(context: RequestContext, config: HandlerConfig, state: MockState): HandlerResult;
+export declare function handleManageAnnulment(context: RequestContext, config: HandlerConfig, state: MockState): HandlerResult;
+export declare const HANDLERS: Record<string, (context: RequestContext, config: HandlerConfig, state: MockState) => HandlerResult>;
+export {};
+//# sourceMappingURL=handlers.d.ts.map

package/dist/handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../src/handlers.ts"],"names":[],"mappings":"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"}