@devly-cl/billing-core

Pure financial contracts and durable billing work orchestration. CommonJS with an explicit public entrypoint and TypeScript declarations; Node 24 is the tested consumer runtime. No runtime dependencies, Node builtins, DOM types, framework, database, environment access or payment provider implementation. Published releases are installed from npm; local npm pack only creates a candidate tarball.

Install

npm install @devly-cl/billing-core

The current financial model supports exact integer CLP amounts and monthly/yearly subscriptions. FinancialQuote contains financial terms and customer dimensions. An integrator can extend LocalSubscription<Quote> with its own quote type; commercial contract IDs, quote serialization and hash generation remain outside this package.

Public API

• BillingError and SubscriptionGatewayError: single constructors shared by CommonJS, ESM and host compatibility exports. Codes, kind and uncertain retain their meaning.
• billingKey, termsInput, validateCheckout, validateTermsConfirmation: validate the existing financial contracts. Confirmation compares an existing version/hash; it never computes or serializes a fingerprint.
• validateInvoiceDimensions, validateInvoice, invoiceFinancialStatus: validate remote identity, frozen amount/currency/environment, quantity, finite period bounds, normalized period evidence and payment/credit settlement. An external or unconfirmed payment remains review. Explicit zero-amount credit settlement requires a positive recurring amount and affirmative adapter evidence.
• BillingProviderRegistry: resolves explicit persisted ProviderBinding values and capabilities. resolve never calls new-subscription selection. forNewSubscription is an explicit, separate operation.
• BillingWorker: executes checkout, reconciliation, cancellation, invoice and notice work through structural ports. BillingProviderResolver can be implemented without a registry class. Subscription, provider, recurring-change, one-off invoice, payment-method and managed-plan-change contracts are exported as types; the package does not implement those provider capabilities.

Worker integration

import { BillingWorker } from '@devly-cl/billing-core';
import type {
  BillingWorkerStore, BillingProviderResolver, BillingWorkerAvailability,
  BillingMail, BillingWorkerPolicy,
} from '@devly-cl/billing-core';

declare const store: BillingWorkerStore;
declare const resolver: BillingProviderResolver;
declare const availability: BillingWorkerAvailability;
declare const mail: BillingMail;
declare const policy: BillingWorkerPolicy;
const worker = new BillingWorker(store, resolver, availability, mail, policy);
await worker.tick();

The host supplies persisted subscription/event binding resolution, an execution profile and canonical invoice-period evidence. Profiles explicitly state checkout/cancellation retry windows and whether deferred cancellation is confirmed. null retry windows require a provider implementation with durable safe resumption; they are not permission to repeat an uncertain POST. The worker compares no provider names and never consults new-sale routing for old work.

invoiceEvidence must validate provider calendar/timezone/DST and original canonical period evidence before returning normalized InvoicePeriodEvidence. The core checks invoice dimensions before invoking that policy and checks the resulting interval and exact boundaries. The host transaction must revalidate against the current/historical frozen quote before writing.

claim owns durable lease acquisition and must honor maintenanceOnly; each subsequent store operation must fence by BillingWork.leaseToken. tick processes at most 30 work items. Cursor continuation, eight-attempt exhaustion, review classification, saas-checkout:<workId>, saas-cancel:<workId> and mail idempotency keys remain stable. Eligibility and the dynamic sales gate are checked before a new checkout mutation; maintenance reconciliation, cancellation and notices remain available with sales disabled. Provider adapters must also gate each actual POST where required.

The store owns resource/tenant authorization, locks, transactions, remote-operation journals, invoice/cycle uniqueness, monotonic paid state, historical quote lookup, audit and durable notifications. Mail delivery must honor the provided idempotency key. No in-memory production store or retry scheduler is provided. A browser return is never financial evidence.

Verification and development

From this repository root: npm run build:packages, npm run test:packages, npm run test:package-boundaries, npm run test:package-artifacts. The artifact smoke installs this package alone, offline outside the repository, then executes validation, resolver, financial worker and notice behavior with a fictitious provider/store/mail. It also checks CommonJS/ESM error identity and strict NodeNext .cts/.mts consumers with types: [], lib: ["ES2023"].

The integrating application owns its exact quote JSON and SHA-256 fingerprints, calendar policies, legacy binding fallback, controllers, permissions, database and framework integration. Package behavior is locally verified; no real provider, production deployment or external mail delivery is certified by these tests.

Rebuild packages and restart Nest after source changes. Automatic package hot reload has not been validated.