Class: CartService

Defined in: server/checkout/cart-service.ts:99

The cart aggregate (proposal §Cart — state machine, seam & pricing injection). Carts are mutable, disposable, INPUT-only: items store consumer inputs, never prices — pricing is computed on read through the injected priceCart adapter. finalize is the one-way seam to an order.

ExtendsCopy Anchor Link

• BaseCheckoutService

ConstructorsCopy Anchor Link

ConstructorCopy Anchor Link

new CartService(deps: CheckoutFeatureDeps): CartService;

Defined in: server/checkout/base-checkout-service.ts:43

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

CartService

Inherited fromCopy Anchor Link

BaseCheckoutService.constructor

PropertiesCopy Anchor Link

depsCopy Anchor Link

protected readonly deps: CheckoutFeatureDeps;

Defined in: server/checkout/base-checkout-service.ts:43

Inherited fromCopy Anchor Link

BaseCheckoutService.deps

AccessorsCopy Anchor Link

actorIdCopy Anchor Link

Get SignatureCopy Anchor Link

get protected actorId(): string | null;

Defined in: server/checkout/base-checkout-service.ts:45

ReturnsCopy Anchor Link

string | null

Inherited fromCopy Anchor Link

BaseCheckoutService.actorId

MethodsCopy Anchor Link

addItem()Copy Anchor Link

addItem(
   scope: CartAccessScope, 
   cartId: string, 
   input: AddItemInput
): Promise<{
  cartId: string;
  createdAt: Date;
  createdBy: string | null;
  deletedAt: Date | null;
  deletedBy: string | null;
  id: string;
  metadata: JsonValue;
  organizationId: string;
  quantity: number;
  referenceId: string | null;
  referenceType: string;
  updatedAt: Date;
  updatedBy: string | null;
}>;

Defined in: server/checkout/cart-service.ts:133

Add an input line to an open cart. Items carry INPUTS only (referenceType/referenceId/quantity/metadata) — no price field: prices are computed on read. Requires trusted cart scope, refreshes activity, and advances the cart version.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<{ cartId: string; createdAt: Date; createdBy: string | null; deletedAt: Date | null; deletedBy: string | null; id: string; metadata: JsonValue; organizationId: string; quantity: number; referenceId: string | null; referenceType: string; updatedAt: Date; updatedBy: string | null; }>

createCart()Copy Anchor Link

createCart(scope: CartAccessScope, input?: CreateCartInput): Promise<{
  createdAt: Date;
  createdBy: string | null;
  currencyCode: string;
  customerId: string | null;
  deletedAt: Date | null;
  deletedBy: string | null;
  expiresAt: Date | null;
  externalRef: string | null;
  guestEmail: string | null;
  id: string;
  lastActivityAt: Date;
  metadata: JsonValue;
  organizationId: string;
  status: CartStatus;
  updatedAt: Date;
  updatedBy: string | null;
  version: number;
}>;

Defined in: server/checkout/cart-service.ts:101

Create an open cart from trusted identity scope.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<{ createdAt: Date; createdBy: string | null; currencyCode: string; customerId: string | null; deletedAt: Date | null; deletedBy: string | null; expiresAt: Date | null; externalRef: string | null; guestEmail: string | null; id: string; lastActivityAt: Date; metadata: JsonValue; organizationId: string; status: CartStatus; updatedAt: Date; updatedBy: string | null; version: number; }>

expireCarts()Copy Anchor Link

expireCarts(organizationId: string, cartIds: string[]): Promise<number>;

Defined in: server/checkout/cart-service.ts:302

Mark the given carts expired (the expires_at inventory-hold lapse). Skips any cart already in a terminal state — only open carts transition. Returns the number transitioned.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<number>

expireStaleCarts()Copy Anchor Link

expireStaleCarts(organizationId: string, before: Date): Promise<number>;

Defined in: server/checkout/cart-service.ts:312

Sweep: mark one organization's open carts idle past before as abandoned (proposal §Cart state machine: "cleanup job: idle > threshold → abandoned"). The consumer runs this on a cron — taproot runs no background jobs.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<number>

finalize()Copy Anchor Link

finalize(
   scope: CartAccessScope, 
   cartId: string, 
   opts: FinalizeOptions
): Promise<BigIntsAsNumbers<{
  anomalyAt: Date | null;
  applicationFeeTotalCents: bigint | null;
  authorizedTotalCents: bigint;
  authorizeStatus: OrderAuthorizeStatus;
  capturedTotalCents: bigint;
  cartId: string | null;
  chargeStatus: OrderChargeStatus;
  closedAt: Date | null;
  code: string;
  createdAt: Date;
  createdBy: string | null;
  currencyCode: string;
  customerEmail: string | null;
  customerId: string | null;
  customerTotalCents: bigint;
  disputedTotalCents: bigint;
  externalRef: string | null;
  id: string;
  idempotencyKey: string | null;
  metadata: JsonValue;
  notes: string | null;
  operatorId: string | null;
  organizationId: string;
  orgBorneTotalCents: bigint;
  origin: string;
  placedAt: Date | null;
  platformBorneTotalCents: bigint;
  processingFeeTotalCents: bigint | null;
  refundedTotalCents: bigint;
  requestHash: string | null;
  status: OrderStatus;
  statusUpdatedAt: Date;
  statusUpdatedBy: string | null;
  subtotalCents: bigint;
  updatedAt: Date;
  updatedBy: string | null;
}>>;

Defined in: server/checkout/cart-service.ts:225

The one-way seam (proposal §finalize): open cart → row lock → version bump → re-price → expected-total guard → createOrder → cart converted → append order.placed. Returns the created (or, on re-entry, existing) order.

RE-ENTRY (proposal §finalize step 1): a converted cart + a matching (organizationId, idempotencyKey) order returns that prior order unconditionally — no request-hash check, because the priced payload doesn't exist until step 2 re-prices, so the converted-cart + key hit IS the idempotent handle. Any other non-open status, or converted with a different / absent key → CartNotOpenError(status).

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<BigIntsAsNumbers<{ anomalyAt: Date | null; applicationFeeTotalCents: bigint | null; authorizedTotalCents: bigint; authorizeStatus: OrderAuthorizeStatus; capturedTotalCents: bigint; cartId: string | null; chargeStatus: OrderChargeStatus; closedAt: Date | null; code: string; createdAt: Date; createdBy: string | null; currencyCode: string; customerEmail: string | null; customerId: string | null; customerTotalCents: bigint; disputedTotalCents: bigint; externalRef: string | null; id: string; idempotencyKey: string | null; metadata: JsonValue; notes: string | null; operatorId: string | null; organizationId: string; orgBorneTotalCents: bigint; origin: string; placedAt: Date | null; platformBorneTotalCents: bigint; processingFeeTotalCents: bigint | null; refundedTotalCents: bigint; requestHash: string | null; status: OrderStatus; statusUpdatedAt: Date; statusUpdatedBy: string | null; subtotalCents: bigint; updatedAt: Date; updatedBy: string | null; }>>

findStaleCarts()Copy Anchor Link

findStaleCarts(organizationId: string, before: Date): Promise<{
  createdAt: Date;
  createdBy: string | null;
  currencyCode: string;
  customerId: string | null;
  deletedAt: Date | null;
  deletedBy: string | null;
  expiresAt: Date | null;
  externalRef: string | null;
  guestEmail: string | null;
  id: string;
  lastActivityAt: Date;
  metadata: JsonValue;
  organizationId: string;
  status: CartStatus;
  updatedAt: Date;
  updatedBy: string | null;
  version: number;
}[]>;

Defined in: server/checkout/cart-service.ts:293

One organization's open carts idle before the cutoff.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<{ createdAt: Date; createdBy: string | null; currencyCode: string; customerId: string | null; deletedAt: Date | null; deletedBy: string | null; expiresAt: Date | null; externalRef: string | null; guestEmail: string | null; id: string; lastActivityAt: Date; metadata: JsonValue; organizationId: string; status: CartStatus; updatedAt: Date; updatedBy: string | null; version: number; }[]>

getCart()Copy Anchor Link

getCart(scope: CartAccessScope, cartId: string): Promise<{
  createdAt: Date;
  createdBy: string | null;
  currencyCode: string;
  customerId: string | null;
  deletedAt: Date | null;
  deletedBy: string | null;
  expiresAt: Date | null;
  externalRef: string | null;
  guestEmail: string | null;
  id: string;
  lastActivityAt: Date;
  metadata: JsonValue;
  organizationId: string;
  status: CartStatus;
  updatedAt: Date;
  updatedBy: string | null;
  version: number;
}>;

Defined in: server/checkout/cart-service.ts:121

Fetch a scoped cart; missing, foreign, or deleted → not found.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<{ createdAt: Date; createdBy: string | null; currencyCode: string; customerId: string | null; deletedAt: Date | null; deletedBy: string | null; expiresAt: Date | null; externalRef: string | null; guestEmail: string | null; id: string; lastActivityAt: Date; metadata: JsonValue; organizationId: string; status: CartStatus; updatedAt: Date; updatedBy: string | null; version: number; }>

getPricedCart()Copy Anchor Link

getPricedCart(scope: CartAccessScope, cartId: string): Promise<PricedCartSnapshot>;

Defined in: server/checkout/cart-service.ts:191

Re-price the cart through the injected priceCart adapter (proposal §Pricing injection). The adapter owns the consumer catalog + classify policy — taproot only hands it the cart and its live items.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<PricedCartSnapshot>

recomputeTenderFromLedger()Copy Anchor Link

protected recomputeTenderFromLedger(
   repos: CheckoutRepositories, 
   payment: PaymentRow, 
   overrides?: Partial<Pick<TenderFacts, "clientActionRequired" | "clientActionRequiredAt">>
): Promise<{
  fold: TenderComputation;
  patch: TenderBucketPatch;
}>;

Defined in: server/checkout/base-checkout-service.ts:94

Re-project a tender from its persisted ledger without writing it. Explicit clientActionRequiredAt: null clears the stored timestamp.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<{ fold: TenderComputation; patch: TenderBucketPatch; }>

Inherited fromCopy Anchor Link

BaseCheckoutService.recomputeTenderFromLedger

reconcileClosedAt()Copy Anchor Link

protected reconcileClosedAt(
   repos: CheckoutRepositories, 
   order: OrderRow, 
   now: Date
): Promise<void>;

Defined in: server/checkout/base-checkout-service.ts:121

Reconcile closedAt and the once-per-order order.paid event after a money write. The caller must hold the order lock in an ambient transaction.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<void>

Inherited fromCopy Anchor Link

BaseCheckoutService.reconcileClosedAt

recordCanonicalTransactions()Copy Anchor Link

protected recordCanonicalTransactions(
   repos: CheckoutRepositories, 
   context: RecordTxnContext, 
   transactions: CanonicalTxn[]
): Promise<RecordedCanonicalTxn[]>;

Defined in: server/checkout/base-checkout-service.ts:61

Record canonical transactions sequentially and identify both fresh inserts and pending rows resolved in place. Callers own the resulting side effects.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<RecordedCanonicalTxn[]>

Inherited fromCopy Anchor Link

BaseCheckoutService.recordCanonicalTransactions

removeItem()Copy Anchor Link

removeItem(
   scope: CartAccessScope, 
   cartId: string, 
   itemId: string
): Promise<void>;

Defined in: server/checkout/cart-service.ts:174

Soft-delete an open cart's item; refresh activity and advance version.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<void>

transaction()Copy Anchor Link

protected transaction<T>(fn: (deps: CheckoutFeatureDeps) => Promise<T>): Promise<T>;

Defined in: server/checkout/base-checkout-service.ts:49

Type ParametersCopy Anchor Link

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<T>

Inherited fromCopy Anchor Link

BaseCheckoutService.transaction

updateItem()Copy Anchor Link

updateItem(
   scope: CartAccessScope, 
   cartId: string, 
   itemId: string, 
   input: UpdateItemInput
): Promise<{
  cartId: string;
  createdAt: Date;
  createdBy: string | null;
  deletedAt: Date | null;
  deletedBy: string | null;
  id: string;
  metadata: JsonValue;
  organizationId: string;
  quantity: number;
  referenceId: string | null;
  referenceType: string;
  updatedAt: Date;
  updatedBy: string | null;
}>;

Defined in: server/checkout/cart-service.ts:155

Update an open cart's item; refresh activity and advance version.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<{ cartId: string; createdAt: Date; createdBy: string | null; deletedAt: Date | null; deletedBy: string | null; id: string; metadata: JsonValue; organizationId: string; quantity: number; referenceId: string | null; referenceType: string; updatedAt: Date; updatedBy: string | null; }>