@open-nav/mock-server 0.1.0

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './server.js';
+export * from './state.js';
+export type { MockCredentials } from './handlers.js';

package/src/server.ts

@@ -0,0 +1,192 @@
+import { createServer, type Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { encodeInvoiceData, parseDocument, type InvoiceData } from '@open-nav/core';
+import {
+  HANDLERS,
+  MockError,
+  errorResponse,
+  type HandlerConfig,
+  type MockCredentials,
+} from './handlers.js';
+import { createState, type MockState, type MockTaxpayer } from './state.js';
+
+export interface MockServerOptions {
+  /** Credentials the mock accepts. Anything else is INVALID_SECURITY_USER. */
+  credentials: MockCredentials;
+  /**
+   * Invoices issued *to* this taxpayer, answered by an INBOUND query.
+   *
+   * Submitting an invoice makes it outbound; there is no way to receive one,
+   * so inbound invoices are seeded here.
+   */
+  inboundInvoices?: InvoiceData[];
+  /** Taxpayers `queryTaxpayer` knows about. */
+  taxpayers?: MockTaxpayer[];
+  /** Port to listen on. 0, the default, picks a free one. */
+  port?: number;
+  host?: string;
+  /** Polls before a transaction settles. 0 means immediately. */
+  pollsBeforeDone?: number;
+  /** Validate submitted invoices and abort the invalid ones. Default true. */
+  validate?: boolean;
+  /** Injectable clock. */
+  now?: () => Date;
+}
+
+export interface MockServer {
+  /** Base URL to hand to a `NavClient`, including the service path. */
+  url: string;
+  port: number;
+  /** Everything the mock has recorded, for assertions. */
+  state: MockState;
+  close: () => Promise<void>;
+  server: Server;
+}
+
+/**
+ * Start a local stand-in for the Online Számla invoice service.
+ *
+ * It speaks the real XML on the real paths, verifies the request signature
+ * the way NAV does, and decides an invoice's fate by running it through this
+ * project's validator. That last part is what makes it useful: a test that
+ * submits a broken invoice sees a realistic ABORTED result with the fault
+ * code NAV would have reported.
+ *
+ * ```ts
+ * const mock = await startMockServer({ credentials });
+ * const client = new NavClient({ credentials, software, baseUrl: mock.url });
+ * ```
+ */
+export async function startMockServer(options: MockServerOptions): Promise<MockServer> {
+  const state = createState(options.taxpayers ?? []);
+  seedInbound(state, options.inboundInvoices ?? [], options.now ?? (() => new Date()));
+  const config: HandlerConfig = {
+    credentials: options.credentials,
+    pollsBeforeDone: options.pollsBeforeDone ?? 0,
+    validate: options.validate ?? true,
+    now: options.now ?? (() => new Date()),
+  };
+
+  const server = createServer((request, response) => {
+    const chunks: Buffer[] = [];
+    request.on('data', (chunk: Buffer) => chunks.push(chunk));
+    request.on('end', () => {
+      const body = Buffer.concat(chunks).toString('utf8');
+      const { status, body: responseBody } = dispatch(
+        request.method ?? '',
+        request.url ?? '',
+        body,
+        config,
+        state,
+      );
+      response.writeHead(status, { 'content-type': 'application/xml; charset=utf-8' });
+      response.end(responseBody);
+    });
+  });
+
+  await new Promise<void>((resolve) => {
+    server.listen(options.port ?? 0, options.host ?? '127.0.0.1', resolve);
+  });
+
+  const address = server.address() as AddressInfo;
+  const host = options.host ?? '127.0.0.1';
+
+  return {
+    url: `http://${host}:${address.port}/invoiceService/v1`,
+    port: address.port,
+    state,
+    server,
+    close: () =>
+      new Promise<void>((resolve, reject) => {
+        server.close((error) => (error ? reject(error) : resolve()));
+      }),
+  };
+}
+
+/** Store seeded invoices as if they had been received. */
+function seedInbound(state: MockState, invoices: InvoiceData[], now: () => Date): void {
+  for (const [index, invoice] of invoices.entries()) {
+    const head = invoice.invoiceMain.invoice?.invoiceHead;
+    state.inbound.set(invoice.invoiceNumber, {
+      invoiceNumber: invoice.invoiceNumber,
+      operation: 'CREATE',
+      supplierTaxNumber: head?.supplierInfo.supplierTaxNumber.taxpayerId ?? '',
+      ...(head?.customerInfo?.customerVatData?.customerTaxNumber?.taxpayerId
+        ? { customerTaxNumber: head.customerInfo.customerVatData.customerTaxNumber.taxpayerId }
+        : {}),
+      issueDate: invoice.invoiceIssueDate,
+      base64: encodeInvoiceData(invoice),
+      compressed: false,
+      invoice,
+      transactionId: `MOCKIN${(index + 1).toString().padStart(6, '0')}`,
+      index: index + 1,
+      insDate: now().toISOString(),
+    });
+  }
+}
+
+function dispatch(
+  method: string,
+  url: string,
+  body: string,
+  config: HandlerConfig,
+  state: MockState,
+): { status: number; body: string } {
+  if (method !== 'POST') {
+    return {
+      status: 405,
+      body: errorResponse(config, 'INVALID_REQUEST', 'only POST is supported'),
+    };
+  }
+
+  const operation = url.split('?')[0]?.split('/').filter(Boolean).pop() ?? '';
+  const handler = HANDLERS[operation];
+  if (!handler) {
+    return {
+      status: 404,
+      body: errorResponse(config, 'INVALID_REQUEST', `unknown operation ${operation}`),
+    };
+  }
+
+  let document;
+  try {
+    // Lenient, because a caller's extra element should surface as a specific
+    // complaint from a handler rather than as an opaque parse failure.
+    document = parseDocument(body, { unknownElements: 'ignore' });
+  } catch (cause) {
+    return {
+      status: 400,
+      body: errorResponse(
+        config,
+        'INVALID_REQUEST',
+        `request XML could not be parsed: ${(cause as Error).message}`,
+      ),
+    };
+  }
+
+  state.requests.push({
+    operation,
+    requestId: (document.value as { header?: { requestId?: string } }).header?.requestId ?? '',
+    body,
+  });
+
+  try {
+    return handler(
+      {
+        operation,
+        body,
+        document: { root: document.root, value: document.value as Record<string, unknown> },
+      },
+      config,
+      state,
+    );
+  } catch (error) {
+    if (error instanceof MockError) {
+      return { status: error.status, body: errorResponse(config, error.errorCode, error.message) };
+    }
+    return {
+      status: 500,
+      body: errorResponse(config, 'OPERATION_FAILED', (error as Error).message),
+    };
+  }
+}

package/src/state.ts

@@ -0,0 +1,80 @@
+import type { InvoiceData, InvoiceStatusType } from '@open-nav/core';
+
+/**
+ * Everything the mock service remembers.
+ *
+ * Held in memory and exposed on the server handle, so a test can assert on
+ * what was actually received rather than only on what came back.
+ */
+export interface MockState {
+  /** Invoices accepted, keyed by invoice number. */
+  invoices: Map<string, StoredInvoice>;
+  /** Invoices issued *to* this taxpayer, seeded by the test. */
+  inbound: Map<string, StoredInvoice>;
+  /** Transactions, keyed by transaction id. */
+  transactions: Map<string, StoredTransaction>;
+  /** Every `requestId` seen, since NAV rejects a replayed one. */
+  requestIds: Set<string>;
+  /** Exchange tokens issued and not yet spent. */
+  tokens: Map<string, { issuedAt: number; spent: boolean }>;
+  /** Taxpayers the mock knows about, keyed by 8 digit core tax number. */
+  taxpayers: Map<string, MockTaxpayer>;
+  /** Requests received, newest last, for assertions. */
+  requests: Array<{ operation: string; requestId: string; body: string }>;
+}
+
+export interface StoredInvoice {
+  invoiceNumber: string;
+  /** `CREATE`, `MODIFY` or `STORNO`. */
+  operation: string;
+  supplierTaxNumber: string;
+  customerTaxNumber?: string;
+  issueDate: string;
+  /** The payload exactly as submitted, still base64. */
+  base64: string;
+  compressed: boolean;
+  invoice: InvoiceData;
+  transactionId: string;
+  index: number;
+  insDate: string;
+}
+
+export interface StoredTransaction {
+  transactionId: string;
+  insDate: string;
+  /** Poll count, used to simulate asynchronous processing. */
+  polls: number;
+  results: Array<{
+    index: number;
+    invoiceStatus: InvoiceStatusType;
+    /** Findings, mirroring NAV's split between technical and business faults. */
+    businessValidationMessages: Array<{
+      validationResultCode: 'ERROR' | 'WARN' | 'INFO';
+      validationErrorCode?: string;
+      message?: string;
+    }>;
+  }>;
+  /** Status the results settle on once processing finishes. */
+  finalStatuses: InvoiceStatusType[];
+}
+
+export interface MockTaxpayer {
+  taxNumber: string;
+  name: string;
+  shortName?: string;
+  valid: boolean;
+  vatCode?: string;
+  countyCode?: string;
+}
+
+export function createState(taxpayers: MockTaxpayer[] = []): MockState {
+  return {
+    invoices: new Map(),
+    inbound: new Map(),
+    transactions: new Map(),
+    requestIds: new Set(),
+    tokens: new Map(),
+    taxpayers: new Map(taxpayers.map((taxpayer) => [taxpayer.taxNumber, taxpayer])),
+    requests: [],
+  };
+}