Abstract Class: CreditStore

Defined in: javascript/src/credits/store.ts:112

Abstract base for credit storage backends.

Split into two tiers:

• Core (abstract, must be implemented): balance/credit ops, the atomic lease lifecycle, bursar-config versioning, plan management, refunds, and expiry sweeping. Every backend needs these.
• Optional capabilities (concrete, default-throwing): usage analytics, ledger listing, and shared team-balance pools. A custom store that doesn't need these can skip them entirely — the default implementation throws CapabilityNotSupportedError instead of forcing a stub.

Extended by

• PostgresStore

Constructors

Constructor

new CreditStore(): CreditStore

Defined in: javascript/src/credits/store.ts:115

Returns

CreditStore

Properties

providerEnvironment?

readonly optional providerEnvironment?: "live" | "test" | "sandbox"

Defined in: javascript/src/credits/store.ts:114

Optional provider namespace exposed by environment-aware stores.

Methods

activateCatalogRevision()

abstract activateCatalogRevision(version, rollout?): Promise<string>

Defined in: javascript/src/credits/store.ts:225

Parameters

version

number

rollout?

CatalogRollout | null

Returns

Promise<string>

---

addCredits()

abstract addCredits(userId, amount, options): Promise<AddCreditsResult>

Defined in: javascript/src/credits/store.ts:118

Parameters

userId

string

amount

Decimal

options

AddCreditsOptions

Returns

Promise<AddCreditsResult>

---

addTeamMember()

addTeamMember(_teamId, _userId, _role?, _spendCap?): Promise<AddTeamMemberResult>

Defined in: javascript/src/credits/store.ts:356

Parameters

_teamId

string

_userId

string

_role?

TeamRole

_spendCap?

Decimal | null

Returns

Promise<AddTeamMemberResult>

---

aggregateStats()

aggregateStats(_start, _end): Promise<AggregateStats>

Defined in: javascript/src/credits/store.ts:305

Parameters

_start

Date

_end

Date

Returns

Promise<AggregateStats>

---

applyDuePlanChanges()

abstract applyDuePlanChanges(limit?): Promise<number>

Defined in: javascript/src/credits/store.ts:238

Parameters

limit?

number

Returns

Promise<number>

---

checkAllowance()

abstract checkAllowance(userId): Promise<AllowanceResult | null>

Defined in: javascript/src/credits/store.ts:250

Parameters

userId

string

Returns

Promise<AllowanceResult | null>

---

checkFeature()

abstract checkFeature(userId, feature): Promise<CheckFeatureResult>

Defined in: javascript/src/credits/store.ts:247

Parameters

userId

string

feature

string

Returns

Promise<CheckFeatureResult>

---

createLease()

abstract createLease(userId, amount, operationType, options): Promise<LeaseResult>

Defined in: javascript/src/credits/store.ts:153

Atomically acquire a lease (hold) — the only authoritative admission control.

Under one critical section the store: (1) ensures the balance row exists; (2) enforces maxConcurrent by counting active leases for (userId, operationType); (3) enforces plan entitlements and quotas; (4) computes available = balance − Σ active holds and rejects with error="insufficient_credits" if available − amount < floor; (5) inserts an active lease expiring after ttlSeconds. Business failures are returned via LeaseResult.error; the store never raises domain exceptions.

Parameters

userId

string

amount

Decimal

operationType

string

options

CreateLeaseOptions

Returns

Promise<LeaseResult>

---

createTeam()

createTeam(_ownerSubjectId, _name, _options): Promise<CreateTeamResult>

Defined in: javascript/src/credits/store.ts:346

Parameters

_ownerSubjectId

string

_name

string

_options

CreateTeamOptions

Returns

Promise<CreateTeamResult>

---

dailySpend()

dailySpend(_start, _end): Promise<DailySpendRow[]>

Defined in: javascript/src/credits/store.ts:302

Parameters

_start

Date

_end

Date

Returns

Promise<DailySpendRow[]>

---

deductTeam()

deductTeam(_teamId, _userId, _amount, _options): Promise<TeamDeductionResult>

Defined in: javascript/src/credits/store.ts:370

Parameters

_teamId

string

_userId

string

_amount

Decimal

_options

DeductTeamOptions

Returns

Promise<TeamDeductionResult>

---

deductWithAllowance()

abstract deductWithAllowance(userId, amount, options): Promise<DeductionResult>

Defined in: javascript/src/credits/store.ts:128

Atomically calculate-and-charge in one server-side transaction: consume free allowance, enforce plan policy and quotas, and debit the net amount, idempotency-keyed end-to-end.

Parameters

userId

string

amount

Decimal

options

DeductWithAllowanceOptions

Returns

Promise<DeductionResult>

---

executeGrantProgram()

executeGrantProgram(_request): Promise<GrantProgramAwardResult[]>

Defined in: javascript/src/credits/store.ts:286

Execute one configured grant-program event.

Parameters

_request

ExecuteGrantProgramRequest

Returns

Promise<GrantProgramAwardResult[]>

---

expireLeases()

expireLeases(_limit?): Promise<number>

Defined in: javascript/src/credits/store.ts:199

Expire a bounded batch of abandoned leases and release their reservations.

Parameters

_limit?

number

Returns

Promise<number>

---

getActiveCatalog()

abstract getActiveCatalog(): Promise<CatalogRevision | null>

Defined in: javascript/src/credits/store.ts:211

Returns

Promise<CatalogRevision | null>

---

getAvailable()

abstract getAvailable(userId): Promise<AvailableResult>

Defined in: javascript/src/credits/store.ts:209

Advisory, non-locking read of available = balance − Σ active holds.

For UI only — never an admission gate; may be stale the instant it is read.

Parameters

userId

string

Returns

Promise<AvailableResult>

---

getBalance()

abstract getBalance(userId): Promise<BalanceResult>

Defined in: javascript/src/credits/store.ts:117

Parameters

userId

string

Returns

Promise<BalanceResult>

---

getBucketBalances()

abstract getBucketBalances(userId): Promise<BucketBalancesResult>

Defined in: javascript/src/credits/store.ts:283

Per-bucket credit balances for a user (credit buckets).

Sorted by priority ascending. When no buckets are configured, synthesizes a single "default" entry from the aggregate balance so the shape is uniform either way.

Parameters

userId

string

Returns

Promise<BucketBalancesResult>

---

getCatalogHistory()

abstract getCatalogHistory(): Promise<CatalogRevisionSummary[]>

Defined in: javascript/src/credits/store.ts:223

Returns

Promise<CatalogRevisionSummary[]>

---

getCatalogRevision()

abstract getCatalogRevision(version): Promise<CatalogRevision | null>

Defined in: javascript/src/credits/store.ts:224

Parameters

version

number

Returns

Promise<CatalogRevision | null>

---

getLeasePricingContext()

abstract getLeasePricingContext(userId, leaseId): Promise<LeasePricingContext | null>

Defined in: javascript/src/credits/store.ts:177

Read the immutable catalog and rate card captured at lease admission.

Parameters

userId

string

leaseId

string

Returns

Promise<LeasePricingContext | null>

---

getLedgerEntry()

getLedgerEntry(_userId, _entryId): Promise<LedgerEntry | null>

Defined in: javascript/src/credits/store.ts:341

Fetch a single transaction by ID. Returns null when the transaction does not exist or belongs to a different user.

Parameters

_userId

string

_entryId

string

Returns

Promise<LedgerEntry | null>

---

getQuotaState()

abstract getQuotaState(userId, quotaKey?): Promise<QuotaState[]>

Defined in: javascript/src/credits/store.ts:248

Parameters

userId

string

quotaKey?

string | null

Returns

Promise<QuotaState[]>

---

getTeamBalance()

getTeamBalance(_teamId): Promise<TeamBalanceResult | null>

Defined in: javascript/src/credits/store.ts:353

Parameters

_teamId

string

Returns

Promise<TeamBalanceResult | null>

---

getTeamMembers()

getTeamMembers(_teamId): Promise<TeamMember[]>

Defined in: javascript/src/credits/store.ts:364

Parameters

_teamId

string

Returns

Promise<TeamMember[]>

---

getUserPlan()

abstract getUserPlan(userId): Promise<GetUserPlanResult>

Defined in: javascript/src/credits/store.ts:230

Parameters

userId

string

Returns

Promise<GetUserPlanResult>

---

listLedgerEntries()

listLedgerEntries(_userId, _options?): Promise<LedgerPage>

Defined in: javascript/src/credits/store.ts:310

Parameters

_userId

string

_options?

ListLedgerEntriesOptions

Returns

Promise<LedgerPage>

---

listQuotaEvents()

abstract listQuotaEvents(userId, options?): Promise<QuotaEvent[]>

Defined in: javascript/src/credits/store.ts:249

Parameters

userId

string

options?

ListQuotaEventsOptions

Returns

Promise<QuotaEvent[]>

---

listUsageCharges()

listUsageCharges(_userId, _options?): Promise<UsageChargePage>

Defined in: javascript/src/credits/store.ts:319

Read metered usage charges, including allowance-covered events.

Parameters

_userId

string

_options?

ListUsageChargesOptions

Returns

Promise<UsageChargePage>

---

listUsageEntries()

abstract listUsageEntries(userId, options?): Promise<LedgerPage>

Defined in: javascript/src/credits/store.ts:316

Parameters

userId

string

options?

ListUsageEntriesOptions

Returns

Promise<LedgerPage>

---

migratePlanBatch()

abstract migratePlanBatch(migrationId, batchSize?): Promise<PlanMigrationBatchResult>

Defined in: javascript/src/credits/store.ts:243

Parameters

migrationId

string

batchSize?

number

Returns

Promise<PlanMigrationBatchResult>

---

publishAndActivateCatalog()

abstract publishAndActivateCatalog(config, label?, rollout?): Promise<string>

Defined in: javascript/src/credits/store.ts:212

Parameters

config

JsonObject | BursarConfig

label?

string | null

rollout?

CatalogRollout | null

Returns

Promise<string>

---

publishCatalogDraft()

abstract publishCatalogDraft(config, label?): Promise<string>

Defined in: javascript/src/credits/store.ts:217

Parameters

config

JsonObject | BursarConfig

label?

string | null

Returns

Promise<string>

---

recordUsage()

recordUsage(_userId, _operation, _requested, _options): Promise<UsageRecordResult>

Defined in: javascript/src/credits/store.ts:327

Append priced usage telemetry without debiting the account again.

Parameters

_userId

string

_operation

string

_requested

Decimal

_options

DeductWithAllowanceOptions

Returns

Promise<UsageRecordResult>

---

refundCredits()

abstract refundCredits(entryId, options): Promise<RefundResult>

Defined in: javascript/src/credits/store.ts:258

Parameters

entryId

string

options

RefundCreditsOptions

Returns

Promise<RefundResult>

---

releaseLease()

abstract releaseLease(userId, leaseId): Promise<ReleaseResult>

Defined in: javascript/src/credits/store.ts:188

Release a lease without charging; safe to repeat after failed or aborted work.

Transitions an active/expired lease to released and reports released=true; otherwise reports released=false with a reason.

Parameters

userId

string

leaseId

string

Returns

Promise<ReleaseResult>

---

removeTeamMember()

removeTeamMember(_teamId, _userId): Promise<boolean>

Defined in: javascript/src/credits/store.ts:367

Parameters

_teamId

string

_userId

string

Returns

Promise<boolean>

---

renewLease()

abstract renewLease(userId, leaseId, ttlSeconds): Promise<LeaseResult>

Defined in: javascript/src/credits/store.ts:196

Extend an active lease's TTL (long batch/agentic jobs, resolves B4).

Returns error="lease_expired" if the TTL already elapsed and error="lease_not_found" if missing/other-user/finalized.

Parameters

userId

string

leaseId

string

ttlSeconds

number

Returns

Promise<LeaseResult>

---

revokeCreditsByEntryType()

abstract revokeCreditsByEntryType(userId, entryType): Promise<RevokeCreditsResult>

Defined in: javascript/src/credits/store.ts:252

Parameters

userId

string

entryType

string

Returns

Promise<RevokeCreditsResult>

---

setPlanRevisionPin()

abstract setPlanRevisionPin(userId, pinned): Promise<boolean>

Defined in: javascript/src/credits/store.ts:237

Parameters

userId

string

pinned

boolean

Returns

Promise<boolean>

---

settleLease()

abstract settleLease(userId, leaseId, amount, options?): Promise<DeductionResult>

Defined in: javascript/src/credits/store.ts:169

Charge the actual cost against a lease, then mark it settled.

De-clamped: charges amount even if it exceeds the lease hold (overdraft) and never clamps to the reserved ceiling. The balance may go negative in overdraft. amount === 0 releases the lease without charging. Lease-state failures (lease_not_found/lease_expired) are returned via DeductionResult.error; a replay returns the original result idempotently.

Parameters

userId

string

leaseId

string

amount

Decimal

options?

SettleLeaseOptions

Returns

Promise<DeductionResult>

---

setUserPlan()

abstract setUserPlan(userId, planKey, planAssignedAt?): Promise<SetUserPlanResult>

Defined in: javascript/src/credits/store.ts:231

Parameters

userId

string

planKey

string

planAssignedAt?

Date | null

Returns

Promise<SetUserPlanResult>

---

spendByModel()

spendByModel(_start, _end): Promise<SpendByModelRow[]>

Defined in: javascript/src/credits/store.ts:296

Parameters

_start

Date

_end

Date

Returns

Promise<SpendByModelRow[]>

---

spendByUser()

spendByUser(_start, _end): Promise<SpendByUserRow[]>

Defined in: javascript/src/credits/store.ts:293

Parameters

_start

Date

_end

Date

Returns

Promise<SpendByUserRow[]>

---

startPlanMigration()

abstract startPlanMigration(fromPlanId, toPlanId): Promise<PlanMigrationStartResult>

Defined in: javascript/src/credits/store.ts:239

Parameters

fromPlanId

string | null

toPlanId

string

Returns

Promise<PlanMigrationStartResult>

---

sweepExpiredCredits()

abstract sweepExpiredCredits(dryRun?, userId?, limit?): Promise<SweepResult>

Defined in: javascript/src/credits/store.ts:269

Sweep expired credit grants and debit the aggregate/tier balances.

When userId is omitted (default), sweeps globally across every user — unchanged behaviour/output shape from before this parameter existed. When given, restricts the scan/expiry to that user's transactions only (used by bounded expiry sweep operation).

Parameters

dryRun?

boolean

userId?

string

limit?

number

Returns

Promise<SweepResult>

---

topUsers()

topUsers(_limit, _start, _end): Promise<TopUserRow[]>

Defined in: javascript/src/credits/store.ts:299

Parameters

_limit

number

_start

Date

_end

Date

Returns

Promise<TopUserRow[]>

---

unsetUserPlan()

abstract unsetUserPlan(userId): Promise<UnsetUserPlanResult>

Defined in: javascript/src/credits/store.ts:236

Parameters

userId

string

Returns

Promise<UnsetUserPlanResult>