Class: PostgresStore
Defined in: javascript/src/stores/postgres-store.ts:161
Credit store backed by a raw Postgres connection.
Uses dependency injection for the PG pool — supply a real pg.Pool class
for production, a mock constructor for tests, or a pre-created pool instance
to share across stores (avoids exhausting Postgres connections).
Args:
databaseUrl: Postgres connection string.
poolOrCtor: A pre-created PgPool instance, a PgPoolConstructor, or omitted
(loads pg on first use).
Extends
Constructors
Constructor
new PostgresStore(
databaseUrl,poolOrCtor?):PostgresStore
Defined in: javascript/src/stores/postgres-store.ts:167
Parameters
databaseUrl
string
poolOrCtor?
PgPool | PgPoolConstructor
Returns
PostgresStore
Overrides
Methods
activatePricing()
activatePricing(
version):Promise<string>
Defined in: javascript/src/stores/postgres-store.ts:611
Parameters
version
number
Returns
Promise<string>
Overrides
addCredits()
addCredits(
userId,amount,type?,metadata?,expiresAt?,tier?,idempotencyKey?):Promise<AddCreditsResult>
Defined in: javascript/src/stores/postgres-store.ts:266
Parameters
userId
string
amount
Decimal
type?
string = "adjustment"
metadata?
CreditMetadata | null
expiresAt?
Date | null
tier?
string | null
idempotencyKey?
string | null
Returns
Promise<AddCreditsResult>
Overrides
addTeamMember()
addTeamMember(
teamId,userId,role?,spendCap?):Promise<AddTeamMemberResult>
Defined in: javascript/src/stores/postgres-store.ts:938
Parameters
teamId
string
userId
string
role?
string = "member"
spendCap?
Decimal | null
Returns
Promise<AddTeamMemberResult>
Overrides
aggregateStats()
aggregateStats(
start,end):Promise<AggregateStats>
Defined in: javascript/src/stores/postgres-store.ts:898
Parameters
start
Date
end
Date
Returns
Promise<AggregateStats>
Overrides
checkAllowance()
checkAllowance(
userId,periodStart?):Promise<AllowanceResult>
Defined in: javascript/src/stores/postgres-store.ts:663
Parameters
userId
string
periodStart?
Date | null
Returns
Promise<AllowanceResult>
Overrides
checkFeature()
checkFeature(
userId,feature):Promise<CheckFeatureResult>
Defined in: javascript/src/stores/postgres-store.ts:641
Parameters
userId
string
feature
string
Returns
Promise<CheckFeatureResult>
Overrides
checkFeatureLimit()
checkFeatureLimit(
userId,feature,maxCalls,periodStart,periodEnd):Promise<FeatureLimitResult>
Defined in: javascript/src/stores/postgres-store.ts:685
Advisory, non-locking read of invocation-count usage (UI only). Mirrors checkSpendCap.
Parameters
userId
string
feature
string
maxCalls
number
periodStart
Date
periodEnd
Date
Returns
Promise<FeatureLimitResult>
Overrides
checkSpendCap()
checkSpendCap(
userId,model?,amount?):Promise<CapCheckResult>
Defined in: javascript/src/stores/postgres-store.ts:728
Parameters
userId
string
model?
string | null
amount?
Decimal
Returns
Promise<CapCheckResult>
Overrides
close()
close():
Promise<void>
Defined in: javascript/src/stores/postgres-store.ts:201
Returns
Promise<void>
createLease()
createLease(
userId,amount,operationType,options?):Promise<LeaseResult>
Defined in: javascript/src/stores/postgres-store.ts:375
Atomically acquire a lease (hold) — the only admission control (D4).
Under one critical section the store: (1) ensures the balance row exists;
(2) enforces maxConcurrent by counting active leases for (userId, operationType); (3) enforces deny spend caps for amount; (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?
Returns
Promise<LeaseResult>
Overrides
createTeam()
createTeam(
name,initialBalance?):Promise<CreateTeamResult>
Defined in: javascript/src/stores/postgres-store.ts:912
Parameters
name
string
initialBalance?
Decimal = ZERO
Returns
Promise<CreateTeamResult>
Overrides
dailySpend()
dailySpend(
start,end):Promise<DailySpendRow[]>
Defined in: javascript/src/stores/postgres-store.ts:823
Parameters
start
Date
end
Date
Returns
Promise<DailySpendRow[]>
Overrides
deductTeam()
deductTeam(
teamId,userId,amount,metadata?,idempotencyKey?):Promise<TeamDeductionResult>
Defined in: javascript/src/stores/postgres-store.ts:971
Parameters
teamId
string
userId
string
amount
Decimal
metadata?
CreditMetadata | null
idempotencyKey?
string | null
Returns
Promise<TeamDeductionResult>
Overrides
deductWithAllowance()
deductWithAllowance(
userId,amount,options?):Promise<DeductionResult>
Defined in: javascript/src/stores/postgres-store.ts:306
Atomically calculate-and-charge in one server-side transaction: consume free allowance, enforce spend caps, apply the balance floor, and debit the net amount — idempotency-keyed end-to-end. See contract §2.
Parameters
userId
string
amount
Decimal
options?
Returns
Promise<DeductionResult>
Overrides
CreditStore.deductWithAllowance
getActivePricing()
getActivePricing():
Promise<PricingConfigResult|null>
Defined in: javascript/src/stores/postgres-store.ts:568
Returns
Promise<PricingConfigResult | null>
Overrides
getAvailable()
getAvailable(
userId):Promise<AvailableResult>
Defined in: javascript/src/stores/postgres-store.ts:557
Advisory, non-locking read of available = balance − Σ active holds.
For UI only — never an admission gate (D4/H3); may be stale the instant read.
Parameters
userId
string
Returns
Promise<AvailableResult>
Overrides
getBalance()
getBalance(
userId):Promise<BalanceResult>
Defined in: javascript/src/stores/postgres-store.ts:253
Parameters
userId
string
Returns
Promise<BalanceResult>
Overrides
getCreditTiers()
getCreditTiers(
userId):Promise<TierBalancesResult>
Defined in: javascript/src/stores/postgres-store.ts:1026
Per-tier credit balances for a user (credit tiers).
Sorted by priority ascending. When no tiers are configured, synthesizes
a single "default" entry from the aggregate balance so the shape is
uniform either way.
Parameters
userId
string
Returns
Promise<TierBalancesResult>
Overrides
getPricingConfig()
getPricingConfig(
version):Promise<PricingConfigResult|null>
Defined in: javascript/src/stores/postgres-store.ts:599
Parameters
version
number
Returns
Promise<PricingConfigResult | null>
Overrides
getPricingHistory()
getPricingHistory():
Promise<PricingConfigHistoryItem[]>
Defined in: javascript/src/stores/postgres-store.ts:587
Returns
Promise<PricingConfigHistoryItem[]>
Overrides
getTeamBalance()
getTeamBalance(
teamId):Promise<TeamBalanceResult>
Defined in: javascript/src/stores/postgres-store.ts:921
Parameters
teamId
string
Returns
Promise<TeamBalanceResult>
Overrides
getTeamMembers()
getTeamMembers(
teamId):Promise<TeamMember[]>
Defined in: javascript/src/stores/postgres-store.ts:958
Parameters
teamId
string
Returns
Promise<TeamMember[]>
Overrides
getUserPlan()
getUserPlan(
userId):Promise<GetUserPlanResult>
Defined in: javascript/src/stores/postgres-store.ts:619
Parameters
userId
string
Returns
Promise<GetUserPlanResult>
Overrides
incrementUsageWindow()
incrementUsageWindow(
userId,planId,amount):Promise<void>
Defined in: javascript/src/stores/postgres-store.ts:680
Parameters
userId
string
planId
string
amount
Decimal
Returns
Promise<void>
Overrides
CreditStore.incrementUsageWindow
listUsageEvents()
listUsageEvents(
userId,options?):Promise<PaginatedTransactions>
Defined in: javascript/src/stores/postgres-store.ts:867
Parameters
userId
string
options?
Returns
Promise<PaginatedTransactions>
Overrides
listUserTransactions()
listUserTransactions(
userId,options?):Promise<PaginatedTransactions>
Defined in: javascript/src/stores/postgres-store.ts:837
Parameters
userId
string
options?
Returns
Promise<PaginatedTransactions>
Overrides
CreditStore.listUserTransactions
refundCredits()
refundCredits(
transactionId,amount?,reason?,metadata?):Promise<RefundResult>
Defined in: javascript/src/stores/postgres-store.ts:753
Parameters
transactionId
string
amount?
Decimal
reason?
string
metadata?
CreditMetadata | null
Returns
Promise<RefundResult>
Overrides
releaseLease()
releaseLease(
userId,leaseId):Promise<ReleaseResult>
Defined in: javascript/src/stores/postgres-store.ts:520
Release a lease without charging (work failed/aborted) — idempotent (H1).
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
renewLease()
renewLease(
userId,leaseId,ttlSeconds):Promise<LeaseResult>
Defined in: javascript/src/stores/postgres-store.ts:531
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
setActivePricing()
setActivePricing(
config,label?):Promise<string>
Defined in: javascript/src/stores/postgres-store.ts:576
Parameters
config
label?
string | null
Returns
Promise<string>
Overrides
settleLease()
settleLease(
userId,leaseId,amount,options?):Promise<DeductionResult>
Defined in: javascript/src/stores/postgres-store.ts:447
Charge the actual cost against a lease, then mark it settled (D5).
De-clamped: charges amount even if it exceeds the lease hold (overdraft),
and never clamps to the reserved ceiling. Spend caps are advisory at settle (a
breach sets capWarning but never blocks); no floor block, so 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?
Returns
Promise<DeductionResult>
Overrides
setup()
setup(
_databaseUrl?):Promise<SetupResult>
Defined in: javascript/src/stores/postgres-store.ts:240
Parameters
_databaseUrl?
string | null
Returns
Promise<SetupResult>
Overrides
setUserPlan()
setUserPlan(
userId,planId):Promise<SetUserPlanResult>
Defined in: javascript/src/stores/postgres-store.ts:654
Parameters
userId
string
planId
string
Returns
Promise<SetUserPlanResult>
Overrides
spendByModel()
spendByModel(
start,end):Promise<SpendByModelRow[]>
Defined in: javascript/src/stores/postgres-store.ts:800
Parameters
start
Date
end
Date
Returns
Promise<SpendByModelRow[]>
Overrides
spendByUser()
spendByUser(
start,end):Promise<SpendByUserRow[]>
Defined in: javascript/src/stores/postgres-store.ts:788
Parameters
start
Date
end
Date
Returns
Promise<SpendByUserRow[]>
Overrides
sweepExpiredCredits()
sweepExpiredCredits(
dryRun?,userId?):Promise<SweepResult>
Defined in: javascript/src/stores/postgres-store.ts:1008
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
CreditManager's lazy-on-read expiry, options.lazyExpiry).
Parameters
dryRun?
boolean = false
userId?
string
Returns
Promise<SweepResult>
Overrides
CreditStore.sweepExpiredCredits
topUsers()
topUsers(
limit,start,end):Promise<TopUserRow[]>
Defined in: javascript/src/stores/postgres-store.ts:812
Parameters
limit
number
start
Date
end
Date
Returns
Promise<TopUserRow[]>