Skip to content
ContractSpec
Start here

Package manual · domains

·Billing, finance and economic evidence

module.billing-os

CompanyOS composition module for governed BillingOS action plans, authority checks, autonomy classification, and operator inbox routing.

domainsmodulev4.0.5stableservernode
@lssm-tech/module.billing-os
bun add @lssm-tech/module.billing-os
Package source ↗Manifest ↗

Manifest declarations describe the current workspace; they do not verify registry publication or runtime execution.

Package guide

CompanyOS composition for BillingOS action plans. The module maps BillingOS action classifications into CompanyOS authority, autonomy, and operator inbox review artifacts without provider SDKs, credentials, network calls, France hard dependency, or authorized billing execution. It includes no production PA submission and no provider credentials.

The default surface is country-neutral. France readiness remains in @lssm-tech/lib.billing-france and can be composed by examples or optional adapters later.

Reusable UI

The ./ui export provides reusable, mobile-first BillingOS presentation surfaces for product shells and examples:

  • quote creation and edition workspace with deterministic VAT totals and wrapping mobile-safe line-item controls
  • invoice inbox and payment reconciliation workspaces with mobile-safe rows/actions
  • compliance readiness and CompanyOS review workspaces with approval controls that wrap at narrow widths
  • shared billing status badges, summary cards, cards, editor types, and currency helpers

Host packages should pass deterministic data into these components and keep provider execution, credentials, native/Expo rendering, and country-specific legal decisions outside the module. Expo/native hosts should render RN-safe adapters from deterministic view-model or proof data instead of importing @lssm-tech/module.billing-os/ui.

Safety

The module includes no production PA submission, no provider credentials, and no authorized billing execution. It only creates review metadata and operator approval routing.

FinanceOS lifecycle bridge

The additive ./finance surface links quote, invoice, payment, provider-actual, economic-evidence, and FinanceOS posting references. It fails closed on tenant, company, settlement, evidence, balance, and Connect-authorization checks and returns an authorized handoff rather than executing a ledger or provider call. prepareBillingFinanceLifecycleV2 is the exact-money surface: it binds the quote, account, invoice, payment, provider actual, posting units, and digest-authorized handoff. Authorization requires the exact billing.finance_posting.authorize capability and a tenant-, policy-, and canonical-plan-bound Connect decision. The original BillingFinanceLifecycleInput remains accepted additively, but fails closed with a review-required migration receipt; it cannot emit ledger evidence or an authorized handoff without the V2 fields.

Mobile and native proof boundary

The reusable UI is a web/React presentation surface that must remain usable on phone-width layouts, but it is not a React Native component library. The mobile monolith BillingOS proof renders the France SME summary/review path with RN primitives and deterministic proof constants, while keeping the same no-provider, no-network, no-production-submission safety boundary.

Internationalization

All user-facing strings rendered by ./ui are translated through the ./i18n export, which ships en, fr, and es catalogs under the billingOs.* key namespace (spec key billing-os.messages).

  • React components consume translations via useI18n from @lssm-tech/lib.design-system/i18n; the module never mounts a LocaleProvider. The host app/bundle owns the provider and supplies a runtime that binds these catalogs (e.g. wrapping createBillingOsI18n(locale)).
  • Without a provider, t(key) returns the key as-is (fail-open, never throws). Catalog completeness is enforced statically by the parity test and the repo i18n:check gate.
  • Non-React callers can build an instance directly with createBillingOsI18n(locale) from @lssm-tech/module.billing-os/i18n.
  • French and Spanish translations are LLM-generated and pending human review; the en catalog is the reference locale.

Locale-correct money formatting (readiness)

Readiness target locale set is en/fr/es (no de). Money/number formatting is locale-correct at every call site:

  • formatCurrency(amount, currency, locale) (./ui → src/ui/lib/format.ts) takes a required locale (no en-US fallback), so French/Spanish amounts render with locale-correct grouping and symbol placement (e.g. 1 234,56 €, not €1,234.56).
  • The PaymentCard organism takes a required locale prop and threads it through useI18n(locale) for per-component locale-aware formatting.
  • Resolve the active locale from useI18n() (or the host i18n context) and pass it at each call site.
  • France-specific VAT/compliance lives in @lssm-tech/lib.billing-france and is jurisdiction logic, not locale formatting — it is preserved independently of the locale.

Relationships

THIS PACKAGEmodule.billing-os86 import paths

Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.

15 declarations

Declared capabilities

Module Billing Os

CompanyOS composition module for governed BillingOS action plans, authority checks, autonomy classification, and operator inbox routing.

Scripts

  • publish:pkgbun publish --tolerate-republish --ignore-scripts --verbose
  • publish:pkg:canarybun publish:pkg --tag canary
  • buildcontractspec-bun-build build
  • build:bundlecontractspec-bun-build transpile
  • build:typescontractspec-bun-build types
  • devcontractspec-bun-build dev
  • cleanrimraf dist .turbo
  • lintbun lint:fix
  • lint:fixnode ../../../../scripts/biome.cjs check --write .
  • lint:checknode ../../../../scripts/biome.cjs check .
  • testbun test
  • prebuildcontractspec-bun-build prebuild
  • typechecktsgo --noEmit