Usage and constraints

Regional presets, usage and limitations

Ownership and migration

Japanese document presets, legal-text parsing/PDF data, invoice workbook layout, legacy Japanese EDI validation/labels, holiday data, 10% invoice and ja-JP CSV/date presets are canonical here. Generic EDI types/UBL construction, document data interfaces, date arithmetic, CSV serialization and configurable calculation stay in data-engine. This package uses engine only through optional integration entries; engine has no runtime/peer dependency back to business-jp and does not load Japanese holiday data.

Before the first public release, Japanese engine entry points were moved here: engine /legal-document → business-jp /legal-document, PDF presets/legal PDF data → /pdf, Excel invoice layout → /excel, Japanese EDI factories/checker/converters → /edi, Japanese date/holiday → /date-utils, implicit invoice/CSV defaults → /finance and /csv. Generic engine APIs now require an explicit EDI currency/ profile context and invoice tax/rounding policy. Update direct engine imports. The private app-core/react-tools compatibility facades retain their original paths and Japanese defaults. AI/graph engine compatibility exports use explicit optional integration entries.

Documents and workbook data

japaneseDocumentPresets contains Japanese quote/invoice/credit-note/order/delivery text, staff/approver seal fields and table labels. They are templates, not evidence of legal sufficiency. Supply real issuer/customer data, company settings and review content. PDF helpers produce data; the host owns rendering, storage and printing. The NotoSansJP font name is a preset, not an embedded licensed font. Supply the font and its notices in the host. Generic engine themes use a neutral sans-serif name.

Legal parsing recognizes Japanese article/party layouts and boilerplate. It cannot establish legal meaning, enforceability, signature authenticity or completeness. Unrecognized layouts may need a dedicated parser. Returned text remains untrusted input for the target renderer; use its safe text APIs.

createInvoiceExcelWorkbook returns Japanese cells/formulas and a default 0.1 tax fraction; taxRate is configurable. That fraction differs from calculateInvoiceAmounts, which takes percentage points (10 means 10%). Workbook tax uses ROUNDDOWN while the legacy amount helper uses Math.round. Select/reconcile a policy explicitly; these are separate legacy presets, not one automatic tax policy. The host workbook adapter must evaluate formulas. Empty-item handling and business rounding need review for actual documents; emitting workbook data is not a computed invoice.

EDI identifiers, defaults and compatibility

The standard /edi factories target the represented JP PINT 1.1.3 fields with JPY, customization urn:peppol:pint:billing-1@jp-1 and process urn:peppol:bis:billing. These defaults select identifiers, not certification. Participant/endpoint schemes are 0221 (qualified issuer, T+13 digits), 0188 (corporate number) and 0088 (GLN). createQualifiedInvoicePartyId creates 0221; createCorporateNumber creates 0188. createTaxId produces the distinct tax scheme VAT, not an endpoint code. The checker accepts aligned categories S/AA/E/G/O, including AA (lower rate); category and percentage are separate. VATEX_CATEGORIES is a historical API name for tax categories, not the exemption-reason code list. The represented-field checker does not implement every JP PINT business rule and does not certify that every category/rate combination is sendable. Validate against the target version’s full rules before transmission.

For old application records import /edi/legacy, or its /factory, /types, /validator subpaths. Only this explicitly named compatibility entry preserves the former 9914/9925 and EU-style profile values; those are not Japanese official scheme assignments. Private app-core facades use this legacy entry so existing records and API paths are preserved. Migrate persisted identity/profile fields deliberately before switching to the standard entry.

Zero tax-inclusive/payable amounts and fully prepaid invoices are valid inputs. The checker covers represented field/identifier/amount rules, not complete JP PINT Schematron, registry lookups, signatures or legal/tax review. Engine’s four UBL document roots are checked with official UBL 2.1 XSD; XSD validity is separate from profile/business-rule conformance. Use target-profile tooling before transmission.

References: JP PINT, identifier schemes.

Dates, CSV and money

Japanese date helpers default to ja-JP; most timezone defaults remain the host’s local zone for compatibility. Pass Asia/Tokyo or another required zone explicitly. Holiday dates are supplied by the installed holiday-jp data version; coverage and future changes are not inferred. A public holiday does not determine every organization’s working day. Generic engine calendars instead require an injected HolidayCalendar provider and contain no country data.

Japanese CSVGenerator defaults Date cells to ja-JP. dateLocale/dateOptions can select another locale/timezone; dateFormatter can emit ISO or machine formats. Formula escaping is opt-in and can alter string data; it is not universal protection across spreadsheet re-import/save behavior. For ordinary interchange use the generic engine CSV generator with explicit formatting choices.

calculateInvoiceAmounts preserves the previous fallback 10% rate and Math.round and permits an explicit defaultTaxRate/roundTax override. Zero values remain valid; invalid/null/empty optional values fall back. It uses JavaScript number arithmetic, not an exact decimal engine. Select applicable rates, minor units, grouping, negative/credit handling and rounding for the business process. These defaults do not determine legal requirements. The generic engine helper requires a policy.

Verification and publication

Tests cover legacy invoice behavior, known Japanese holiday dates, locale overrides, workbook/preset data, EDI delegation and legal parsing. Isolated packed consumers check all exports in Node/Bun ESM/CJS, strict NodeNext types with/without Node types and browser bundling. Emitted invoice workbook formulas are evaluated with a test-only Excel formula evaluator, including empty items and explicit zero amounts. No real PDF rendering, Excel application interoperability, legal review, Peppol endpoint or compliance certification is included in these checks. Release data-engine first, then generate this repository’s real registry lockfile and run verify. Local tarball fixtures are opt-in development checks, never production lock. Feature JSDoc/README/guides remain here; apps/docs reads local workspace Markdown.

The public payment table uses UNCL4461 D.16B meanings: 1 = instrument not defined, 10 = cash, 30 = credit transfer, 42 = payment to bank account. Earlier labels incorrectly described 1 as cash, 10 as netting and 42 as a bill of exchange. Stored code values are not automatically rewritten: review records using those old labels before migration. Sources: JP PINT 1.1.3 aligned categories and UNCL4461, May 2026.

Cohesive Japanese business package

Documents, seals, Japanese legal text and JP PINT rules live in this single package; there are no separate invoice/seal/legal micro-packages. Dependencies point from business-jp to generic engine, never back. Seal label and fallback SVG/data URL helpers moved from engine to @alneas/business-jp/pdf/stamp (also /pdf). These generate visual seals, not electronic signatures or identity verification. Private PDF/stamp compatibility entries keep their established API. Installing business-jp does not install AI, graph, database or storage packages. Optional engine integrations require their explicit peer and entry.

import { resolveSealLabel } from '@alneas/business-jp/pdf/stamp';
const label = resolveSealLabel('山田 太郎'); // 山田

Japanese payment/inventory notification text and yen presentation are owned by /notifications as japaneseNotificationMessages. Pass this policy as the second argument to a generic notification adapter. Private notification facades use the same policy to preserve their established Japanese presentation.

import { japaneseNotificationMessages } from '@alneas/business-jp/notifications';
import { SlackNotificationAdapter, SlackClient } from '@alneas/data-engine/notifications/slack';
const adapter = new SlackNotificationAdapter(new SlackClient({ botToken: 'host-supplied-token' }), japaneseNotificationMessages);

Standalone use and optional engine integration

Root, /pdf/stamp, /holidays, /legal-document and /notifications run and type-check without data-engine. Ordinary dependencies remain holiday-jp/YAML only. The Japanese holiday provider accepts a civil date with a zero-based month; callers own timezone conversion. Notification payload types describe only the presentation inputs and are structurally compatible with the generic engine policy; type conformance is tested without importing engine from public declarations.

Install @alneas/data-engine@0.1.0 explicitly for /integrations/data-engine, date arithmetic/formatting, finance, CSV, PDF themes/document models, EDI/UBL and Excel integration entries. JP PINT validation subpaths currently share engine’s EDI data types/constants, so those entries also require the peer even when a caller only wants the checker. No generic algorithms/types are copied into business-jp to remove that relationship.

The old root’s date/finance exports and pdf/edi/excel/csv namespaces move to /integrations/data-engine; domain subpaths and private compatibility facades retain their behavior. An isolated npm consumer checks engine/AJV/Zod and other ALNEAS packages are absent while running seals, legal parsing, holidays and notifications. A second consumer explicitly adds engine and checks all entries and their strict ESM/CJS declarations. Node support starts at 24.0.0; quality CI covers Node 24/26.