Domain Model

The domain model is the set of TypeScript interfaces in src/domain/entities/. Entities are plain, fully readonly data contracts: they hold no methods and no behavior. Behavior lives in value objects, state machines, and the application layer. Persisted shapes and provider identifiers are part of the entity; invariants and transitions are enforced elsewhere.

Every entity field is declared readonly, so an entity instance is never mutated in place; state changes produce new records.

Shared building blocks

These mixins live in src/domain/entities/common.ts and are composed into the entities below.

Monetary amounts on entities (total, amountPaid, amountDue, amount, unitAmount, refundedAmount) are plain number values expressed in minor units (cents for two-decimal currencies). They are never floats representing major units. The currency: CurrencyCode field on the same entity tells you how to interpret them. See Value Objects for the no-floats rule and the Money helper that wraps these stored amounts.

Entity reference diagram

erDiagram
  CUSTOMER ||--o{ SUBSCRIPTION : has
  CUSTOMER ||--o{ INVOICE : billed
  CUSTOMER ||--o{ PAYMENT : pays
  CUSTOMER ||--o{ CUSTOMER_PROVIDER_BINDING : maps
  SUBSCRIPTION ||--o{ SUBSCRIPTION_ITEM : contains
  SUBSCRIPTION ||--o{ INVOICE : generates
  SUBSCRIPTION }o--|| PRICE : "priced by"
  SUBSCRIPTION_ITEM }o--|| PRICE : "priced by"
  PRODUCT ||--o{ PRICE : offers
  PAYMENT ||--o{ REFUND : "refunded by"

  CUSTOMER {
    string id PK
    string billableType
    string billableId
    string email
    string name
    string tenantId
  }
  CUSTOMER_PROVIDER_BINDING {
    string id PK
    string customerId FK
    string provider
    string providerCustomerId
  }
  SUBSCRIPTION {
    string id PK
    string customerId FK
    string status
    string priceId FK
    number quantity
    date trialEndsAt
    date endsAt
  }
  SUBSCRIPTION_ITEM {
    string id PK
    string subscriptionId FK
    string priceId FK
    number quantity
  }
  INVOICE {
    string id PK
    string customerId FK
    string subscriptionId FK
    string status
    string currency
    number total
    number amountPaid
    number amountDue
  }
  PAYMENT {
    string id PK
    string customerId FK
    string status
    string currency
    number amount
    number refundedAmount
  }
  REFUND {
    string id PK
    string paymentId FK
    string status
    string currency
    number amount
  }
  PRODUCT {
    string id PK
    string name
    boolean active
  }
  PRICE {
    string id PK
    string productId FK
    string currency
    number unitAmount
    string interval
    boolean active
  }

Relationships are expressed by foreign-key string fields (customerId, subscriptionId, priceId, productId, paymentId). There are no embedded references; entities only carry the id of related records.

Customer

src/domain/entities/customer.entity.ts. Extends TenantScoped, Timestamps.

Purpose: represents one host-application billable independently from any provider account.

Relationships: owns many CustomerProviderBinding, CustomerProviderSyncState, Subscription, Invoice, and Payment records. On Payment the link is customerId: string | null, so a payment can exist without a customer.

Invariant: (tenantId, billableType, billableId) identifies one logical customer.

Customer Provider Binding

src/domain/entities/customer-provider-binding.entity.ts. Extends Timestamps and inherits tenant ownership through its customer.

Purpose: maps one logical customer to one registered provider account.

Invariants: (customerId, provider) is unique, and (provider, providerCustomerId) is unique. The same opaque provider id may appear under different registered provider keys. Deleting a customer cascades to its bindings.

Customer Provider Sync State

src/domain/entities/customer-provider-sync-state.entity.ts. Extends TenantScoped, Timestamps.

Purpose: records synchronization attempts independently from provider bindings. No row means never attempted. pending, failed, synchronized, and reconciliation_required describe the durable lifecycle without storing provider messages or credentials.

The row is unique by (tenantId, customerId, provider). It stores attempts, lastAttemptedAt, synchronizedAt, a safe failureCode, and the provider customer id when known. Deleting the logical customer cascades to its sync states.

Subscription

src/domain/entities/subscription.entity.ts. Extends TenantScoped, Timestamps.

Purpose: a recurring billing agreement for a customer against a price.

Relationships: belongs to one Customer; contains many SubscriptionItem; may generate Invoice records (Invoice.subscriptionId); references a Price via priceId.

Lifecycle: status is governed by the Subscription state machine. The date fields (trialEndsAt, endsAt) drive the lifecycle predicates below.

Subscription state predicates

src/domain/entities/subscription-state.ts. Three pure functions read a Subscription plus an explicit now: Date and return a boolean. They compare epoch milliseconds via getTime().

Notes:

• onTrial uses a strict > comparison, so the exact trialEndsAt instant is no longer “on trial”.
• onGracePeriod and subscriptionEnded are complementary across endsAt: with a non-null endsAt, exactly one is true for any given now (the boundary instant counts as ended, not grace).
• All three return false when the relevant date is null.

Subscription Item

src/domain/entities/subscription-item.entity.ts. Extends Timestamps only (not tenant-scoped; it inherits tenancy through its parent subscription).

Purpose: a single priced line on a subscription, enabling multi-price subscriptions.

Relationships: belongs to one Subscription; references one Price.

Invoice

src/domain/entities/invoice.entity.ts. Extends TenantScoped, Timestamps.

Purpose: a billing document for a customer, optionally tied to a subscription.

Relationships: belongs to one Customer; optionally belongs to one Subscription.

Lifecycle: status is governed by the Invoice state machine. Amount fields are minor-unit integers interpreted by currency.

Payment

src/domain/entities/payment.entity.ts. Extends TenantScoped, Timestamps.

Purpose: a charge against a provider, optionally attributed to a customer.

Relationships: optionally belongs to one Customer; refunded by many Refund records (each references paymentId).

Lifecycle: status is governed by the Payment state machine. refundedAmount tracks cumulative refunds; the partially_refunded and refunded payment states correspond to partial vs. full refunds.

Refund

src/domain/entities/refund.entity.ts. Extends TenantScoped, Timestamps.

Purpose: a refund issued against a payment.

Relationships: belongs to one Payment (required paymentId).

Lifecycle: status is governed by the Refund state machine.

Canonical product and provider bindings

CanonicalProduct is the provider-neutral sellable product used by payable.products(). Its stable local ID, tenant, name, description, lifecycle state, and metadata do not depend on a remote provider. ProductProviderBinding stores one provider account name and remote product ID for that canonical product. A product can have multiple bindings.

CanonicalPrice belongs to a canonical product and stores amount, currency, one-time or recurring type, interval, interval count, description, lookup key, and lifecycle state. Billing terms are immutable after creation. PriceProviderBinding stores provider account and remote price identity.

Canonical subscription and provider bindings

A canonical Subscription belongs to a logical customer and snapshots the accepted canonical price, currency, unit amount, recurring interval, interval count, and quantity. Its local ID and accepted terms remain stable when a price is archived or a provider is attached later. Initial state and period boundaries are explicit, and collection responsibility never proves that payment occurred.

SubscriptionProviderBinding stores the tenant, local subscription ID, provider account name, remote subscription ID, and last provider synchronization time. A provider binding can be added without replacing the canonical ID or rewriting accepted terms. Local reads do not need a binding; provider operations do.

Legacy provider-first product

src/domain/entities/product.entity.ts. Extends TenantScoped, Timestamps.

Purpose: a sellable product that prices attach to.

Relationships: offers many Price records (each references productId).

Legacy provider-first price

src/domain/entities/price.entity.ts. Extends TenantScoped, Timestamps.

Purpose: a specific price (one-off or recurring) for a product.

Relationships: belongs to one Product; referenced by Subscription.priceId and SubscriptionItem.priceId.

Notes: a recurring price sets both interval and intervalCount; a one-off price leaves both null.

Webhook Event

src/domain/entities/webhook-event.entity.ts. Extends TenantScoped (note: not Timestamps - it carries its own receivedAt/processedAt fields).

Purpose: a received provider webhook, persisted for idempotent processing and reconciliation.

WebhookEventStatus = 'pending' | 'processed' | 'failed'.

Invariants (enforced outside the entity): (provider, providerEventId) uniquely identifies an event, supporting idempotent webhook handling. See Value Objects for IdempotencyKey.forWebhook.

Webhook Endpoint

src/domain/entities/webhook-endpoint.entity.ts. Extends TenantScoped, and carries its own createdAt/updatedAt (not the Timestamps mixin).

Purpose: an outbound webhook destination that the engine delivers normalized events to, with its own signing secret and event subscription set.

WebhookEndpointStatus = 'enabled' | 'disabled'.

Relationships: receives many WebhookDelivery records (each references endpointId).

Webhook Delivery

src/domain/entities/webhook-delivery.entity.ts. Extends TenantScoped, and carries its own createdAt/updatedAt (not the Timestamps mixin).

Purpose: a single delivery attempt of an event to an endpoint, persisted for observability and reconciliation.

WebhookDeliveryStatus = 'delivered' | 'failed'.

Relationships: belongs to one WebhookEndpoint (required endpointId); references the source event via eventId.

Audit Log

src/domain/entities/audit-log.entity.ts. Extends TenantScoped (carries its own createdAt, not Timestamps).

Purpose: an immutable record of a mutation to a domain resource, for audit and traceability.

Notes: before/after capture the diff of the audited mutation; correlationId ties the entry to the request and to related webhook events.

Errors

Domain errors live in src/domain/errors/. They all extend PayableError, a structured base built on the native Error.

PayableError

src/domain/errors/payable-error.ts. The base class. Beyond the message, it carries:

The constructor takes PayableErrorOptions ({ code?, context?, correlationId?, cause? }); cause is forwarded to the native Error cause. toJSON() serializes { name, code, message, correlationId, context } and redacts any context key matching authorization, password, secret, token, signature, api[-_]?key, cookie, card, cvv, cvc, or pin (replacing the value with [redacted]). The static PayableError.notImplemented(symbol) returns a NOT_IMPLEMENTED-coded error.

Error catalog

Each subclass sets a fixed code and a populated context, and accepts the same PayableErrorOptions.

The HTTP status each code maps to (for example IDEMPOTENCY_CONFLICT -> 409, PROVIDER_CAPABILITY_NOT_SUPPORTED -> 422) is documented in Troubleshooting.

DTOs

The input/output shapes in src/domain/dtos/ are the boundary types: the plain interfaces that builders and actions accept and return, and that the PaymentProvider contract is defined in terms of. Monetary fields on these DTOs use the Money value object (not raw integers), unlike the persisted entity shapes above. They are re-exported from src/domain/dtos/index.ts.

Representative shapes:

export interface CreateCustomerInput {
  email: string;
  name?: string;
  billableType: string;
  billableId: string;
  metadata?: Metadata;
}

export interface ChargeInput {
  providerCustomerId?: string;
  amount: Money;
  reference?: string;
  description?: string;
}

export interface OperationContext {
  correlationId: string;
  idempotencyKey?: string;
  tenantId?: string | null;
}

See the source files for the full field lists.