@open-nav/client 0.1.0

package/src/client.ts

@@ -0,0 +1,338 @@
+import {
+  BASE_URLS,
+  HEADER_VERSION,
+  MAX_INVOICE_BATCH_SIZE,
+  NavValidationError,
+  PASSWORD_HASH_CRYPTO_TYPE,
+  REQUEST_VERSION,
+  SIGNATURE_CRYPTO_TYPE,
+  createRequestId,
+  decodeExchangeToken,
+  encodeInvoiceAnnulment,
+  encodeInvoiceData,
+  passwordHash,
+  requestSignature,
+  serializeDocument,
+  toHeaderTimestamp,
+  type InvoiceAnnulment,
+  type InvoiceData,
+  type ManageAnnulmentRequest,
+  type ManageAnnulmentResponse,
+  type ManageInvoiceRequest,
+  type ManageInvoiceResponse,
+  type NavEnvironment,
+  type QueryInvoiceChainDigestRequest,
+  type QueryInvoiceChainDigestResponse,
+  type QueryInvoiceCheckRequest,
+  type QueryInvoiceCheckResponse,
+  type QueryInvoiceDataRequest,
+  type QueryInvoiceDataResponse,
+  type QueryInvoiceDigestRequest,
+  type QueryInvoiceDigestResponse,
+  type QueryTaxpayerRequest,
+  type QueryTaxpayerResponse,
+  type QueryTransactionListRequest,
+  type QueryTransactionListResponse,
+  type QueryTransactionStatusRequest,
+  type QueryTransactionStatusResponse,
+  type SignedOperation,
+  type SoftwareType,
+  type TokenExchangeResponse,
+  type ValidationIssue,
+} from '@open-nav/core';
+import { assertCredentials, type NavCredentials } from './credentials.js';
+import { postXml, type TransportOptions } from './transport.js';
+
+/**
+ * A request body with the parts the client fills in removed.
+ *
+ * Deriving these from the generated request types means there is no
+ * hand-maintained parameter list to fall out of step with the schema.
+ */
+export type RequestBody<T> = Omit<T, 'header' | 'user' | 'software'>;
+
+/** A manage request body; the exchange token is obtained by the client. */
+export type ManageBody<T> = Omit<RequestBody<T>, 'exchangeToken'>;
+
+export interface NavClientOptions {
+  credentials: NavCredentials;
+  /**
+   * Identification of the invoicing software, which NAV requires on every
+   * request and uses for its own statistics and support.
+   */
+  software: SoftwareType;
+  /** `test` (the default) or `production`. */
+  environment?: NavEnvironment;
+  /** Overrides `environment`; useful for a mock server. */
+  baseUrl?: string;
+  /** Prefix for generated request identifiers, for tracing. */
+  requestIdPrefix?: string;
+  /** Injectable clock, for deterministic tests. */
+  now?: () => Date;
+  transport?: TransportOptions;
+}
+
+export interface InvoiceOperationInput {
+  /** `CREATE`, `MODIFY` or `STORNO`. */
+  operation: 'CREATE' | 'MODIFY' | 'STORNO';
+  /** The invoice, or an already base64 encoded payload. */
+  invoice: InvoiceData | { base64: string };
+}
+
+export interface SubmitInvoicesOptions {
+  /** Gzip each payload. The flag applies to the whole batch. */
+  compress?: boolean;
+}
+
+/**
+ * Client for the NAV Online Számla 3.0 invoice service.
+ *
+ * Every method corresponds to one service operation and takes the generated
+ * request type minus the header, user and software blocks, which the client
+ * builds and signs.
+ *
+ * ```ts
+ * const client = new NavClient({ credentials, software, environment: 'test' });
+ * const taxpayer = await client.queryTaxpayer({ taxNumber: '12345678' });
+ * ```
+ */
+export class NavClient {
+  private readonly baseUrl: string;
+  private readonly credentials: NavCredentials;
+  private readonly software: SoftwareType;
+  private readonly requestIdPrefix: string | undefined;
+  private readonly now: () => Date;
+  private readonly transport: TransportOptions;
+
+  constructor(options: NavClientOptions) {
+    assertCredentials(options.credentials);
+    this.credentials = options.credentials;
+    this.software = options.software;
+    this.baseUrl = options.baseUrl ?? BASE_URLS[options.environment ?? 'test'];
+    this.requestIdPrefix = options.requestIdPrefix;
+    this.now = options.now ?? (() => new Date());
+    this.transport = options.transport ?? {};
+  }
+
+  /**
+   * Exchange credentials for a single-use token required by the manage
+   * operations.
+   *
+   * The token arrives AES-128-ECB encrypted under the exchange key and is
+   * decrypted here. NAV keeps it valid for a few minutes; this client fetches
+   * a fresh one per manage call rather than caching, because a token consumed
+   * by a submission cannot be reused and a stale one fails opaquely.
+   */
+  async tokenExchange(): Promise<{
+    token: string;
+    validityFrom: string;
+    validityTo: string;
+    response: TokenExchangeResponse;
+  }> {
+    const response = await this.execute<TokenExchangeResponse>(
+      'tokenExchange',
+      'TokenExchangeRequest',
+      {},
+    );
+    return {
+      token: decodeExchangeToken(response.encodedExchangeToken, this.credentials.exchangeKey),
+      validityFrom: response.tokenValidityFrom,
+      validityTo: response.tokenValidityTo,
+      response,
+    };
+  }
+
+  /** Submit invoice data. Returns the transaction to poll for the outcome. */
+  async manageInvoice(body: ManageBody<ManageInvoiceRequest>): Promise<ManageInvoiceResponse> {
+    assertBatchSize(body.invoiceOperations.invoiceOperation.length, 'invoiceOperations');
+    const { token } = await this.tokenExchange();
+    const signed: SignedOperation[] = body.invoiceOperations.invoiceOperation.map((operation) => ({
+      index: operation.index,
+      operation: operation.invoiceOperation,
+      base64Payload: operation.invoiceData,
+    }));
+    return this.execute<ManageInvoiceResponse>(
+      'manageInvoice',
+      'ManageInvoiceRequest',
+      { ...body, exchangeToken: token },
+      { signed, retryable: false },
+    );
+  }
+
+  /** Technically annul a previously submitted, erroneous data report. */
+  async manageAnnulment(
+    body: ManageBody<ManageAnnulmentRequest>,
+  ): Promise<ManageAnnulmentResponse> {
+    assertBatchSize(body.annulmentOperations.annulmentOperation.length, 'annulmentOperations');
+    const { token } = await this.tokenExchange();
+    const signed: SignedOperation[] = body.annulmentOperations.annulmentOperation.map(
+      (operation) => ({
+        index: operation.index,
+        operation: operation.annulmentOperation,
+        base64Payload: operation.invoiceAnnulment,
+      }),
+    );
+    return this.execute<ManageAnnulmentResponse>(
+      'manageAnnulment',
+      'ManageAnnulmentRequest',
+      { ...body, exchangeToken: token },
+      { signed, retryable: false },
+    );
+  }
+
+  /** Processing state and validation messages of a submitted transaction. */
+  queryTransactionStatus(
+    body: RequestBody<QueryTransactionStatusRequest>,
+  ): Promise<QueryTransactionStatusResponse> {
+    return this.execute('queryTransactionStatus', 'QueryTransactionStatusRequest', body);
+  }
+
+  /** Transactions submitted in a time window, paged. */
+  queryTransactionList(
+    body: RequestBody<QueryTransactionListRequest>,
+  ): Promise<QueryTransactionListResponse> {
+    return this.execute('queryTransactionList', 'QueryTransactionListRequest', body);
+  }
+
+  /** Full invoice data of one invoice, inbound or outbound. */
+  queryInvoiceData(body: RequestBody<QueryInvoiceDataRequest>): Promise<QueryInvoiceDataResponse> {
+    return this.execute('queryInvoiceData', 'QueryInvoiceDataRequest', body);
+  }
+
+  /** Paged summary list of invoices matching a query. */
+  queryInvoiceDigest(
+    body: RequestBody<QueryInvoiceDigestRequest>,
+  ): Promise<QueryInvoiceDigestResponse> {
+    return this.execute('queryInvoiceDigest', 'QueryInvoiceDigestRequest', body);
+  }
+
+  /** Modification chain of an invoice. */
+  queryInvoiceChainDigest(
+    body: RequestBody<QueryInvoiceChainDigestRequest>,
+  ): Promise<QueryInvoiceChainDigestResponse> {
+    return this.execute('queryInvoiceChainDigest', 'QueryInvoiceChainDigestRequest', body);
+  }
+
+  /** Whether an invoice number exists in NAV's records. */
+  queryInvoiceCheck(
+    body: RequestBody<QueryInvoiceCheckRequest>,
+  ): Promise<QueryInvoiceCheckResponse> {
+    return this.execute('queryInvoiceCheck', 'QueryInvoiceCheckRequest', body);
+  }
+
+  /** Validity and registered data of a Hungarian taxpayer. */
+  queryTaxpayer(body: RequestBody<QueryTaxpayerRequest>): Promise<QueryTaxpayerResponse> {
+    return this.execute('queryTaxpayer', 'QueryTaxpayerRequest', body);
+  }
+
+  /**
+   * Encode invoices and submit them as one batch.
+   *
+   * Encoding happens once and the same base64 is both sent and hashed, which
+   * is the only safe way to do it: hashing a separately serialised copy of the
+   * same invoice is a signature failure waiting to happen.
+   */
+  async submitInvoices(
+    invoices: InvoiceOperationInput[],
+    options: SubmitInvoicesOptions = {},
+  ): Promise<ManageInvoiceResponse> {
+    assertBatchSize(invoices.length, 'invoices');
+    return this.manageInvoice({
+      invoiceOperations: {
+        compressedContent: options.compress ?? false,
+        invoiceOperation: invoices.map((entry, position) => ({
+          index: position + 1,
+          invoiceOperation: entry.operation,
+          invoiceData:
+            'base64' in entry.invoice
+              ? entry.invoice.base64
+              : encodeInvoiceData(entry.invoice, { compress: options.compress }),
+        })),
+      },
+    });
+  }
+
+  /** Annul one or more previously reported invoices. */
+  async submitAnnulments(
+    annulments: Array<InvoiceAnnulment | { base64: string }>,
+    options: SubmitInvoicesOptions = {},
+  ): Promise<ManageAnnulmentResponse> {
+    assertBatchSize(annulments.length, 'annulments');
+    return this.manageAnnulment({
+      annulmentOperations: {
+        annulmentOperation: annulments.map((entry, position) => ({
+          index: position + 1,
+          annulmentOperation: 'ANNUL',
+          invoiceAnnulment:
+            'base64' in entry
+              ? entry.base64
+              : encodeInvoiceAnnulment(entry, { compress: options.compress }),
+        })),
+      },
+    });
+  }
+
+  /** Build, sign and send one request. */
+  private async execute<TResponse>(
+    operation: string,
+    rootName: string,
+    body: object,
+    options: { signed?: SignedOperation[]; retryable?: boolean } = {},
+  ): Promise<TResponse> {
+    const requestId = createRequestId(this.requestIdPrefix);
+    const timestamp = toHeaderTimestamp(this.now());
+
+    const request = {
+      header: {
+        requestId,
+        timestamp,
+        requestVersion: REQUEST_VERSION,
+        headerVersion: HEADER_VERSION,
+      },
+      user: {
+        login: this.credentials.login,
+        passwordHash: {
+          value: passwordHash(this.credentials.password),
+          cryptoType: PASSWORD_HASH_CRYPTO_TYPE,
+        },
+        taxNumber: this.credentials.taxNumber,
+        requestSignature: {
+          value: requestSignature(
+            requestId,
+            timestamp,
+            this.credentials.signKey,
+            options.signed ?? [],
+          ),
+          cryptoType: SIGNATURE_CRYPTO_TYPE,
+        },
+      },
+      software: this.software,
+      ...body,
+    };
+
+    const xml = serializeDocument(rootName, request);
+    const response = await postXml(
+      this.baseUrl,
+      operation,
+      xml,
+      this.transport,
+      options.retryable ?? true,
+    );
+    return response.value as TResponse;
+  }
+}
+
+function assertBatchSize(size: number, path: string): void {
+  const issues: ValidationIssue[] = [];
+  if (size === 0) {
+    issues.push({ path, code: 'EMPTY_BATCH', message: 'must contain at least one operation' });
+  }
+  if (size > MAX_INVOICE_BATCH_SIZE) {
+    issues.push({
+      path,
+      code: 'BATCH_TOO_LARGE',
+      message: `NAV accepts at most ${MAX_INVOICE_BATCH_SIZE} operations per request, got ${size}`,
+    });
+  }
+  if (issues.length > 0) throw new NavValidationError('Invalid batch', issues);
+}

package/src/credentials.ts

@@ -0,0 +1,57 @@
+import { NavValidationError, type ValidationIssue } from '@open-nav/core';
+
+/**
+ * Credentials of a technical user (technikai felhasználó), created in the
+ * Online Számla portal under the taxpayer whose data is being reported.
+ *
+ * These are secrets. Load them from the environment or a secret manager —
+ * never from source control — and note that the test and production systems
+ * issue separate, non-interchangeable users.
+ */
+export interface NavCredentials {
+  /** Technical user login, 6–15 alphanumeric characters. */
+  login: string;
+  /** Technical user password, in clear; it is hashed before transmission. */
+  password: string;
+  /** Signature key (aláírókulcs) used to sign requests. */
+  signKey: string;
+  /** Exchange key (cserekulcs) used to decrypt the exchange token. */
+  exchangeKey: string;
+  /** Tax number of the taxpayer being reported for, 8 digits, no VAT suffix. */
+  taxNumber: string;
+}
+
+/**
+ * Check credentials locally before the first request.
+ *
+ * NAV answers every credential problem with the same opaque
+ * `INVALID_SECURITY_USER`, so catching shape errors here saves real debugging
+ * time. The most common cause is pasting the 11-digit tax number instead of
+ * the 8-digit core.
+ */
+export function assertCredentials(credentials: NavCredentials): void {
+  const issues: ValidationIssue[] = [];
+  const require = (
+    field: keyof NavCredentials,
+    pattern: RegExp,
+    message: string,
+    code: string,
+  ): void => {
+    const value = credentials[field];
+    if (typeof value !== 'string' || value.length === 0) {
+      issues.push({ path: `credentials.${field}`, code: 'REQUIRED', message: 'is required' });
+    } else if (!pattern.test(value)) {
+      issues.push({ path: `credentials.${field}`, code, message });
+    }
+  };
+
+  require('login', /^[a-zA-Z0-9]{6,15}$/, 'must be 6-15 alphanumeric characters', 'INVALID_LOGIN');
+  require('password', /^.+$/, 'must not be empty', 'INVALID_PASSWORD');
+  require('signKey', /^.+$/, 'must not be empty', 'INVALID_SIGN_KEY');
+  require('exchangeKey', /^.{16}$/, 'must be exactly 16 characters', 'INVALID_EXCHANGE_KEY');
+  require('taxNumber', /^\d{8}$/, 'must be the 8 digit core tax number, without the VAT and county digits', 'INVALID_TAX_NUMBER');
+
+  if (issues.length > 0) {
+    throw new NavValidationError('Invalid NAV credentials', issues);
+  }
+}

package/src/download.ts

@@ -0,0 +1,238 @@
+import {
+  QUERY_PAGE_SIZE,
+  decodeInvoiceData,
+  serializeDocument,
+  type InvoiceDataResultType,
+  type InvoiceData,
+  type InvoiceDigestType,
+  type InvoiceDirectionType,
+} from '@open-nav/core';
+import type { NavClient } from './client.js';
+
+/**
+ * Bulk retrieval of invoices from NAV.
+ *
+ * Two things make this more than a loop. NAV caps a digest query at **35
+ * days** — `BAD_QUERY_PARAM_RANGE_EXCEEDED`, "Date interval defined by the
+ * query parameters must not exceed 35 days" — so any useful range has to be
+ * split. And an inbound invoice must be fetched with the supplier's tax
+ * number, which is only knowable from the digest entry that named it.
+ */
+
+/** Longest interval NAV accepts in one digest query. */
+export const MAX_QUERY_DAYS = 35;
+
+export interface DownloadOptions {
+  /** `INBOUND` for invoices issued to you, `OUTBOUND` for your own. */
+  direction?: InvoiceDirectionType;
+  /** First issue date, inclusive, as `yyyy-mm-dd`. */
+  dateFrom: string;
+  /** Last issue date, inclusive, as `yyyy-mm-dd`. */
+  dateTo: string;
+  /**
+   * Pause between requests, in milliseconds. Defaults to 250.
+   *
+   * NAV rate limits per taxpayer, and a download makes one request per
+   * invoice. Pacing is cheaper than being throttled.
+   */
+  delayMs?: number;
+  /** Called before each invoice is fetched, for progress reporting. */
+  onProgress?: (progress: DownloadProgress) => void;
+  /** Injectable sleep, for tests. */
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export interface DownloadProgress {
+  /** The window currently being queried. */
+  window: DateWindow;
+  windowIndex: number;
+  windowCount: number;
+  /** Digest entries seen so far, across all windows. */
+  seen: number;
+  /** Invoices fetched so far. */
+  fetched: number;
+}
+
+export interface DateWindow {
+  dateFrom: string;
+  dateTo: string;
+}
+
+export interface DownloadedInvoice {
+  /** The digest entry that led to this invoice. */
+  digest: InvoiceDigestType;
+  /** The decoded invoice. */
+  invoice: InvoiceData;
+  /** The invoice re-serialised, for writing to disk. */
+  xml: string;
+  /** NAV's own record of when and how the data arrived. */
+  auditData: InvoiceDataResultType['auditData'];
+}
+
+/**
+ * Split a date range into windows NAV will accept.
+ *
+ * Inclusive at both ends, so a 35 day window spans `dateFrom` to
+ * `dateFrom + 34 days`: NAV compares the two dates given, and 35 days apart
+ * is already over the line.
+ */
+export function chunkDateRange(
+  dateFrom: string,
+  dateTo: string,
+  maxDays = MAX_QUERY_DAYS,
+): DateWindow[] {
+  const start = parseDate(dateFrom, 'dateFrom');
+  const end = parseDate(dateTo, 'dateTo');
+  if (start > end) {
+    throw new RangeError(`dateFrom ${dateFrom} is after dateTo ${dateTo}`);
+  }
+
+  const windows: DateWindow[] = [];
+  const dayMs = 86_400_000;
+  for (let cursor = start; cursor <= end; cursor += maxDays * dayMs) {
+    const windowEnd = Math.min(cursor + (maxDays - 1) * dayMs, end);
+    windows.push({ dateFrom: formatDate(cursor), dateTo: formatDate(windowEnd) });
+  }
+  return windows;
+}
+
+function parseDate(value: string, field: string): number {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+    throw new RangeError(`${field} must be yyyy-mm-dd, got ${JSON.stringify(value)}`);
+  }
+  const timestamp = Date.parse(`${value}T00:00:00Z`);
+  if (Number.isNaN(timestamp)) throw new RangeError(`${field} is not a real date: ${value}`);
+  return timestamp;
+}
+
+function formatDate(timestamp: number): string {
+  return new Date(timestamp).toISOString().slice(0, 10);
+}
+
+/**
+ * Walk every digest entry in a date range, across windows and pages.
+ *
+ * A digest is a summary. It is enough to decide what to fetch, and cheap:
+ * one request per hundred invoices.
+ */
+export async function* iterateInvoiceDigests(
+  client: NavClient,
+  options: DownloadOptions,
+): AsyncGenerator<{ digest: InvoiceDigestType; window: DateWindow }> {
+  const direction = options.direction ?? 'INBOUND';
+  const windows = chunkDateRange(options.dateFrom, options.dateTo);
+  const pause = pauser(options);
+  let seen = 0;
+
+  for (const [windowIndex, window] of windows.entries()) {
+    let page = 1;
+    let availablePage = 1;
+
+    do {
+      if (seen > 0 || page > 1) await pause();
+      const response = await client.queryInvoiceDigest({
+        page,
+        invoiceDirection: direction,
+        invoiceQueryParams: {
+          mandatoryQueryParams: {
+            invoiceIssueDate: { dateFrom: window.dateFrom, dateTo: window.dateTo },
+          },
+        },
+      });
+
+      const result = response.invoiceDigestResult;
+      availablePage = result.availablePage;
+      const entries = result.invoiceDigest ?? [];
+
+      for (const digest of entries) {
+        seen += 1;
+        options.onProgress?.({
+          window,
+          windowIndex,
+          windowCount: windows.length,
+          seen,
+          fetched: 0,
+        });
+        yield { digest, window };
+      }
+
+      // NAV reports 0 available pages for an empty result.
+      if (entries.length < QUERY_PAGE_SIZE) break;
+      page += 1;
+    } while (page <= availablePage);
+  }
+}
+
+/**
+ * Walk every invoice in a date range, fetching each in full.
+ *
+ * One request per invoice, so this is the expensive one; pace it with
+ * `delayMs` and consider whether the digest alone answers your question.
+ */
+export async function* iterateInvoices(
+  client: NavClient,
+  options: DownloadOptions,
+): AsyncGenerator<DownloadedInvoice> {
+  const direction = options.direction ?? 'INBOUND';
+  const pause = pauser(options);
+  let fetched = 0;
+  let seen = 0;
+
+  for await (const { digest, window } of iterateInvoiceDigests(client, {
+    ...options,
+    // Progress is reported here instead, where the counts are complete.
+    ...(options.onProgress ? { onProgress: undefined } : {}),
+  })) {
+    seen += 1;
+    await pause();
+
+    const response = await client.queryInvoiceData({
+      invoiceNumberQuery: {
+        invoiceNumber: digest.invoiceNumber,
+        invoiceDirection: direction,
+        // Only meaningful when querying as the customer: NAV answers
+        // BAD_QUERY_PARAM_SUPPLIER_NOT_EXPECTED if it is sent otherwise.
+        ...(direction === 'INBOUND' ? { supplierTaxNumber: digest.supplierTaxNumber } : {}),
+        ...(digest.batchIndex !== undefined ? { batchIndex: digest.batchIndex } : {}),
+      },
+    });
+
+    const result = response.invoiceDataResult;
+    if (!result) continue; // Listed in the digest but no longer retrievable.
+
+    const invoice = decodeInvoiceData(result.invoiceData, {
+      compressed: result.compressedContentIndicator,
+    });
+    fetched += 1;
+    options.onProgress?.({
+      window,
+      windowIndex: 0,
+      windowCount: 0,
+      seen,
+      fetched,
+    });
+
+    yield {
+      digest,
+      invoice,
+      xml: serializeDocument('InvoiceData', invoice, { indent: '  ' }),
+      auditData: result.auditData,
+    };
+  }
+}
+
+/** Collect a whole range into memory. Convenient, but unbounded. */
+export async function downloadInvoices(
+  client: NavClient,
+  options: DownloadOptions,
+): Promise<DownloadedInvoice[]> {
+  const collected: DownloadedInvoice[] = [];
+  for await (const entry of iterateInvoices(client, options)) collected.push(entry);
+  return collected;
+}
+
+function pauser(options: DownloadOptions): () => Promise<void> {
+  const delayMs = options.delayMs ?? 250;
+  const sleep = options.sleep ?? ((ms: number) => new Promise((r) => setTimeout(r, ms)));
+  return () => (delayMs > 0 ? sleep(delayMs) : Promise.resolve());
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './client.js';
+export * from './credentials.js';
+export * from './transport.js';
+export * from './transaction.js';
+export * from './download.js';