Skip to main content
Version: 2.x

Class: PostgresStore

Defined in: javascript/src/credits/postgres/store.ts:123

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.

Extends​

Constructors​

Constructor​

new PostgresStore(options): PostgresStore

Defined in: javascript/src/credits/postgres/store.ts:192

Parameters​

options​

PostgresStoreOptions

Returns​

PostgresStore

Overrides​

CreditStore.constructor

Properties​

providerEnvironment​

readonly providerEnvironment: NonNullable<"live" | "test" | "sandbox" | undefined>

Defined in: javascript/src/credits/postgres/store.ts:124

Optional provider namespace exposed by environment-aware stores.

Overrides​

CreditStore.providerEnvironment

Methods​

activateCatalogRevision()​

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

Defined in: javascript/src/credits/postgres/store.ts:625

Parameters​

version​

number

rollout?​

CatalogRollout | null

Returns​

Promise<string>

Overrides​

CreditStore.activateCatalogRevision

addCredits()​

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

Defined in: javascript/src/credits/postgres/store.ts:267

Parameters​

userId​

string

amount​

Decimal

options​

AddCreditsOptions

Returns​

Promise<AddCreditsResult>

Overrides​

CreditStore.addCredits

addTeamMember()​

addTeamMember(teamId, userId, role?, spendCap?): Promise<AddTeamMemberResult>

Defined in: javascript/src/credits/postgres/store.ts:1047

Parameters​

teamId​

string

userId​

string

role?​

TeamRole = "member"

spendCap?​

Decimal | null

Returns​

Promise<AddTeamMemberResult>

Overrides​

CreditStore.addTeamMember

aggregateStats()​

aggregateStats(start, end): Promise<AggregateStats>

Defined in: javascript/src/credits/postgres/store.ts:891

Parameters​

start​

Date

end​

Date

Returns​

Promise<AggregateStats>

Overrides​

CreditStore.aggregateStats

applyDuePlanChanges()​

applyDuePlanChanges(limit?): Promise<number>

Defined in: javascript/src/credits/postgres/store.ts:762

Parameters​

limit?​

number = 100

Returns​

Promise<number>

Overrides​

CreditStore.applyDuePlanChanges

checkAllowance()​

checkAllowance(userId): Promise<AllowanceResult | null>

Defined in: javascript/src/credits/postgres/store.ts:836

Parameters​

userId​

string

Returns​

Promise<AllowanceResult | null>

Overrides​

CreditStore.checkAllowance

checkFeature()​

checkFeature(userId, feature): Promise<CheckFeatureResult>

Defined in: javascript/src/credits/postgres/store.ts:723

Parameters​

userId​

string

feature​

string

Returns​

Promise<CheckFeatureResult>

Overrides​

CreditStore.checkFeature

close()​

close(): Promise<void>

Defined in: javascript/src/credits/postgres/store.ts:221

Returns​

Promise<void>

createLease()​

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

Defined in: javascript/src/credits/postgres/store.ts:395

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>

Overrides​

CreditStore.createLease

createTeam()​

createTeam(ownerSubjectId, name, options): Promise<CreateTeamResult>

Defined in: javascript/src/credits/postgres/store.ts:1015

Parameters​

ownerSubjectId​

string

name​

string

options​

CreateTeamOptions

Returns​

Promise<CreateTeamResult>

Overrides​

CreditStore.createTeam

dailySpend()​

dailySpend(start, end): Promise<DailySpendRow[]>

Defined in: javascript/src/credits/postgres/store.ts:931

Parameters​

start​

Date

end​

Date

Returns​

Promise<DailySpendRow[]>

Overrides​

CreditStore.dailySpend

deductTeam()​

deductTeam(teamId, userId, amount, options): Promise<TeamDeductionResult>

Defined in: javascript/src/credits/postgres/store.ts:1080

Parameters​

teamId​

string

userId​

string

amount​

Decimal

options​

DeductTeamOptions

Returns​

Promise<TeamDeductionResult>

Overrides​

CreditStore.deductTeam

deductWithAllowance()​

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

Defined in: javascript/src/credits/postgres/store.ts:300

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>

Overrides​

CreditStore.deductWithAllowance

executeGrantProgram()​

executeGrantProgram(request): Promise<GrantProgramAwardResult[]>

Defined in: javascript/src/credits/postgres/store.ts:1144

Execute one configured grant-program event.

Parameters​

request​

ExecuteGrantProgramRequest

Returns​

Promise<GrantProgramAwardResult[]>

Overrides​

CreditStore.executeGrantProgram

expireLeases()​

expireLeases(limit?): Promise<number>

Defined in: javascript/src/credits/postgres/store.ts:550

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

Parameters​

limit?​

number = 100

Returns​

Promise<number>

Overrides​

CreditStore.expireLeases

getActiveCatalog()​

getActiveCatalog(): Promise<CatalogRevision | null>

Defined in: javascript/src/credits/postgres/store.ts:570

Returns​

Promise<CatalogRevision | null>

Overrides​

CreditStore.getActiveCatalog

getAvailable()​

getAvailable(userId): Promise<AvailableResult>

Defined in: javascript/src/credits/postgres/store.ts:557

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>

Overrides​

CreditStore.getAvailable

getBalance()​

getBalance(userId): Promise<BalanceResult>

Defined in: javascript/src/credits/postgres/store.ts:255

Parameters​

userId​

string

Returns​

Promise<BalanceResult>

Overrides​

CreditStore.getBalance

getBucketBalances()​

getBucketBalances(userId): Promise<BucketBalancesResult>

Defined in: javascript/src/credits/postgres/store.ts:1132

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>

Overrides​

CreditStore.getBucketBalances

getCatalogHistory()​

getCatalogHistory(): Promise<CatalogRevisionSummary[]>

Defined in: javascript/src/credits/postgres/store.ts:609

Returns​

Promise<CatalogRevisionSummary[]>

Overrides​

CreditStore.getCatalogHistory

getCatalogRevision()​

getCatalogRevision(version): Promise<CatalogRevision | null>

Defined in: javascript/src/credits/postgres/store.ts:620

Parameters​

version​

number

Returns​

Promise<CatalogRevision | null>

Overrides​

CreditStore.getCatalogRevision

getLeasePricingContext()​

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

Defined in: javascript/src/credits/postgres/store.ts:492

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

Parameters​

userId​

string

leaseId​

string

Returns​

Promise<LeasePricingContext | null>

Overrides​

CreditStore.getLeasePricingContext

getLedgerEntry()​

getLedgerEntry(userId, entryId): Promise<LedgerEntry | null>

Defined in: javascript/src/credits/postgres/store.ts:940

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>

Overrides​

CreditStore.getLedgerEntry

getQuotaState()​

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

Defined in: javascript/src/credits/postgres/store.ts:789

Parameters​

userId​

string

quotaKey?​

string | null

Returns​

Promise<QuotaState[]>

Overrides​

CreditStore.getQuotaState

getTeamBalance()​

getTeamBalance(teamId): Promise<TeamBalanceResult | null>

Defined in: javascript/src/credits/postgres/store.ts:1036

Parameters​

teamId​

string

Returns​

Promise<TeamBalanceResult | null>

Overrides​

CreditStore.getTeamBalance

getTeamMembers()​

getTeamMembers(teamId): Promise<TeamMember[]>

Defined in: javascript/src/credits/postgres/store.ts:1066

Parameters​

teamId​

string

Returns​

Promise<TeamMember[]>

Overrides​

CreditStore.getTeamMembers

getUserPlan()​

getUserPlan(userId): Promise<GetUserPlanResult>

Defined in: javascript/src/credits/postgres/store.ts:638

Parameters​

userId​

string

Returns​

Promise<GetUserPlanResult>

Overrides​

CreditStore.getUserPlan

listLedgerEntries()​

listLedgerEntries(userId, options?): Promise<LedgerPage>

Defined in: javascript/src/credits/postgres/store.ts:980

Parameters​

userId​

string

options?​

ListLedgerEntriesOptions

Returns​

Promise<LedgerPage>

Overrides​

CreditStore.listLedgerEntries

listQuotaEvents()​

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

Defined in: javascript/src/credits/postgres/store.ts:808

Parameters​

userId​

string

options?​

ListQuotaEventsOptions

Returns​

Promise<QuotaEvent[]>

Overrides​

CreditStore.listQuotaEvents

listUsageCharges()​

listUsageCharges(userId, options?): Promise<UsageChargePage>

Defined in: javascript/src/credits/postgres/store.ts:988

Read metered usage charges, including allowance-covered events.

Parameters​

userId​

string

options?​

ListUsageChargesOptions

Returns​

Promise<UsageChargePage>

Overrides​

CreditStore.listUsageCharges

listUsageEntries()​

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

Defined in: javascript/src/credits/postgres/store.ts:984

Parameters​

userId​

string

options?​

ListUsageEntriesOptions

Returns​

Promise<LedgerPage>

Overrides​

CreditStore.listUsageEntries

migratePlanBatch()​

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

Defined in: javascript/src/credits/postgres/store.ts:777

Parameters​

migrationId​

string

batchSize?​

number

Returns​

Promise<PlanMigrationBatchResult>

Overrides​

CreditStore.migratePlanBatch

publishAndActivateCatalog()​

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

Defined in: javascript/src/credits/postgres/store.ts:579

Parameters​

config​

JsonObject | BursarConfig

label?​

string | null

rollout?​

CatalogRollout | null

Returns​

Promise<string>

Overrides​

CreditStore.publishAndActivateCatalog

publishCatalogDraft()​

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

Defined in: javascript/src/credits/postgres/store.ts:597

Parameters​

config​

JsonObject | BursarConfig

label?​

string | null

Returns​

Promise<string>

Overrides​

CreditStore.publishCatalogDraft

recordUsage()​

recordUsage(userId, operation, amount, options): Promise<UsageRecordResult>

Defined in: javascript/src/credits/postgres/store.ts:358

Append priced usage telemetry without debiting the account again.

Parameters​

userId​

string

operation​

string

amount​

Decimal

options​

DeductWithAllowanceOptions

Returns​

Promise<UsageRecordResult>

Overrides​

CreditStore.recordUsage

refundCredits()​

refundCredits(entryId, options): Promise<RefundResult>

Defined in: javascript/src/credits/postgres/store.ts:860

Parameters​

entryId​

string

options​

RefundCreditsOptions

Returns​

Promise<RefundResult>

Overrides​

CreditStore.refundCredits

releaseLease()​

releaseLease(userId, leaseId): Promise<ReleaseResult>

Defined in: javascript/src/credits/postgres/store.ts:506

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>

Overrides​

CreditStore.releaseLease

removeTeamMember()​

removeTeamMember(teamId, userId): Promise<boolean>

Defined in: javascript/src/credits/postgres/store.ts:1076

Parameters​

teamId​

string

userId​

string

Returns​

Promise<boolean>

Overrides​

CreditStore.removeTeamMember

renewLease()​

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

Defined in: javascript/src/credits/postgres/store.ts:516

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>

Overrides​

CreditStore.renewLease

revokeCreditsByEntryType()​

revokeCreditsByEntryType(userId, entryType): Promise<RevokeCreditsResult>

Defined in: javascript/src/credits/postgres/store.ts:847

Parameters​

userId​

string

entryType​

string

Returns​

Promise<RevokeCreditsResult>

Overrides​

CreditStore.revokeCreditsByEntryType

setPlanRevisionPin()​

setPlanRevisionPin(userId, pinned): Promise<boolean>

Defined in: javascript/src/credits/postgres/store.ts:758

Parameters​

userId​

string

pinned​

boolean

Returns​

Promise<boolean>

Overrides​

CreditStore.setPlanRevisionPin

settleLease()​

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

Defined in: javascript/src/credits/postgres/store.ts:443

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>

Overrides​

CreditStore.settleLease

setUserPlan()​

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

Defined in: javascript/src/credits/postgres/store.ts:734

Parameters​

userId​

string

planKey​

string

planAssignedAt?​

Date | null

Returns​

Promise<SetUserPlanResult>

Overrides​

CreditStore.setUserPlan

spendByModel()​

spendByModel(start, end): Promise<SpendByModelRow[]>

Defined in: javascript/src/credits/postgres/store.ts:914

Parameters​

start​

Date

end​

Date

Returns​

Promise<SpendByModelRow[]>

Overrides​

CreditStore.spendByModel

spendByUser()​

spendByUser(start, end): Promise<SpendByUserRow[]>

Defined in: javascript/src/credits/postgres/store.ts:905

Parameters​

start​

Date

end​

Date

Returns​

Promise<SpendByUserRow[]>

Overrides​

CreditStore.spendByUser

startPlanMigration()​

startPlanMigration(fromPlanId, toPlanId): Promise<PlanMigrationStartResult>

Defined in: javascript/src/credits/postgres/store.ts:769

Parameters​

fromPlanId​

string | null

toPlanId​

string

Returns​

Promise<PlanMigrationStartResult>

Overrides​

CreditStore.startPlanMigration

sweepExpiredCredits()​

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

Defined in: javascript/src/credits/postgres/store.ts:1120

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 = false

userId?​

string

limit?​

number = 100

Returns​

Promise<SweepResult>

Overrides​

CreditStore.sweepExpiredCredits

topUsers()​

topUsers(limit, start, end): Promise<TopUserRow[]>

Defined in: javascript/src/credits/postgres/store.ts:923

Parameters​

limit​

number

start​

Date

end​

Date

Returns​

Promise<TopUserRow[]>

Overrides​

CreditStore.topUsers

unsetUserPlan()​

unsetUserPlan(userId): Promise<UnsetUserPlanResult>

Defined in: javascript/src/credits/postgres/store.ts:753

Parameters​

userId​

string

Returns​

Promise<UnsetUserPlanResult>

Overrides​

CreditStore.unsetUserPlan