Financewolf TypeScript client

Review candidate @ironfang/financewolf 0.1.0, Node.js 20+ ESM, no runtime dependencies. Install the reviewed .tgz with npm install /path/to/package.tgz. Public npm publication is not claimed by this candidate.

import { readFile } from 'node:fs/promises';
import { Financewolf, FinancewolfError } from '@ironfang/financewolf';

const client = new Financewolf({ apiKey: process.env.FINANCEWOLF_API_KEY ?? '' });
const result = await client.validate(await readFile('invoice.xml'), {
  ruleset: 'fwrs_bis3_billing_invoice_2026_5_r3',
});
console.log(result.outcome);

Use a Financewolf key scoped to financewolf:einvoices:write. Keep it in a secret manager/environment variable; this is a server-side Node client, not a browser integration. Optional timeoutMs defaults to 30 seconds; signal supports cancellation. A timeout/cancel does not cancel work already accepted by the API.

The SDK snapshots the exact bytes before sending them, checks the returned hash and length, verifies completed validation layers and rejects a different pinned ruleset. PHIVE remains the validator: the SDK does not implement invoice rules, correct XML or reinterpret warnings. valid and invalid return structured results. Other failures throw FinancewolfError with safe code/HTTP status.

Pin an immutable document-type-specific ruleset for CI, or deliberately use latest (the default) for current active rules. CreditNote uses its own ruleset, for example fwrs_bis3_billing_creditnote_2026_5_r3. Retired/unavailable rulesets produce service errors, never a silently substituted version.

There is one HTTP attempt, no idempotency key and no automatic retry. Repeated calls can be billable. Redirects are refused, XML is capped at 5 MiB, and the streamed response at 4 MiB. The optional injected fetch is a trusted transport and receives the credential; use it only for tests or a reviewed integration.

Full results can contain invoice text. Do not log/store them without appropriate access and retention. XML is sent to Financewolf under the authenticated API's retention policy. Validation does not send invoices through Peppol, establish Access Point status, certify tax/legal compliance or guarantee acceptance.