@nehorai/credits 1.7.0 → 2.1.0

package/dist/index.d.cts

@@ -1,10 +1,10 @@
-import { S as SubscriptionTier, T as TierConfig, c as PortableReservation } from './types-CjLj3GW5.cjs';
-export { A as AIProviderType, B as BuiltinTier, g as CreditCheckResult, a as CreditOperationType, C as CreditSource, D as DeductCreditsResult, J as JournalReferenceType, M as MonthlyResetResult, f as PortableJournalEntry, P as PortableTransaction, d as PortableUsageLog, b as PortableUserCredits, R as ReservationStatus, h as ResourceType, g as SDKCreditCheckResult, e as SubscriptionExpiryResult, i as TransactionType, U as UsageHistoryEntry, j as UsageHistoryResponse, b as UserCredits, W as WithCreditsOptions, k as calculateAvailableCredits, t as toDate, l as toPortableTimestamp } from './types-CjLj3GW5.cjs';
-export { CreditError, CreditErrorCode, CreditErrorCodeType, commitReservationWithJournal, createInsufficientCreditsError, createInvalidOperationTypeError, createReservationAlreadyProcessedError, createReservationExpiredError, createReservationNotFoundError, createUserNotFoundError, isCreditError, isInsufficientCreditsError, releaseReservationWithJournal, reserveCreditsForOperation } from './core/index.cjs';
+import { S as SubscriptionTier, T as TierConfig, a as PortableReservation } from './types-Dzc443vy.cjs';
+export { A as AIProviderType, B as BuiltinTier, g as CreditCheckResult, C as CreditOperationType, b as CreditSource, D as DeductCreditsResult, J as JournalReferenceType, M as MonthlyResetResult, f as PortableJournalEntry, P as PortableTransaction, d as PortableUsageLog, c as PortableUserCredits, R as ReservationStatus, h as ResourceType, g as SDKCreditCheckResult, e as SubscriptionExpiryResult, i as TransactionType, U as UsageHistoryEntry, j as UsageHistoryResponse, c as UserCredits, W as WithCreditsOptions, k as calculateAvailableCredits, t as toDate, l as toPortableTimestamp } from './types-Dzc443vy.cjs';
+export { A as AddCreditsAtomicOptions, a as AddCreditsOutcome, b as AddCreditsV2Input, C as CommitOutcome, c as CreateJournalEntryInput, d as CreateReservationInput, e as CreateTransactionInput, f as CreateUsageLogInput, g as CreditBalanceUpdate, h as CreditRepositoryFactory, E as ExpireOutcome, i as ExpireReservationV2Options, I as ICreditRepository, j as ICreditRepositoryCreditsV2, k as ICreditRepositoryV2, J as JournalEntryQuery, R as ReleaseOutcome, l as ReservationTransitionOptions, m as ReserveCreditsV2Input, n as ReserveOutcome, T as TerminalReservationStatus, o as TierUpdateInput, U as UsageLogQuery, p as isCreditedOutcome, q as isReservedOutcome, r as isWinningOutcome, s as reservationJournalKey, t as supportsCreditsV2, u as supportsIdempotentCredit, v as toClientUserCredits } from './types-wtksMa4n.cjs';
+export { CREDIT_AMOUNT_MAX, CREDIT_AMOUNT_SCALE, CreditError, CreditErrorCode, CreditErrorCodeType, PaymentEventPayload, RESERVATION_STATUSES, RESERVED_JOURNAL_KEY_PREFIX, ReservationIntegrityView, StoredPaymentEvent, TERMINAL_RESERVATION_STATUSES, assertDirectStatusWriteAllowed, assertHoldPlaced, assertKnownReservationStatus, assertPublicJournalKey, assertRepresentableAmount, assertRepresentableFields, assertRepresentableTierAmount, assertUnkeyedDirectReservation, assertUnreferencedDirectTransaction, assertValidCreditAmount, assertValidIdempotencyKey, assertValidStoredAmount, assertValidStoredAmountRaw, backedBalanceFloor, classifyDatabaseError, commitReservationWithJournal, createIdempotencyConflictError, createInsufficientCreditsError, createInvalidAmountError, createInvalidOperationTypeError, createPaymentRefConflictError, createReservationAlreadyProcessedError, createReservationExpiredError, createReservationNotFoundError, createTransientError, createUnsupportedOperationError, createUserNotFoundError, describePaymentMismatch, getSqlState, hasPlacedHold, isCreditError, isIdempotencyConflictError, isInsufficientCreditsError, isRepresentableAmount, isReservationStatus, isReservedJournalKey, isTerminalReservationStatus, isTransientDatabaseError, isTransientError, isUniqueViolation, isValidCreditAmount, isValidIdempotencyKey, normalizePaymentRef, numericToCents, releaseReservationWithJournal, reserveCreditsForOperation, sameAmount, storedMonthlyLimit, sumAmounts, terminalStatusOf, toCents } from './core/index.cjs';
 export { D as DeferredExecutor, c as createDeferredExecutor, g as genericDeferred, n as noopDeferred, s as synchronousDeferred } from './deferred-C7rrRfkm.cjs';
 import { z } from 'zod';
-export { A as AddCreditsAtomicOptions, C as CreateJournalEntryInput, a as CreateReservationInput, b as CreateTransactionInput, c as CreateUsageLogInput, d as CreditBalanceUpdate, e as CreditRepositoryFactory, I as ICreditRepository, J as JournalEntryQuery, T as TierUpdateInput, U as UsageLogQuery, t as toClientUserCredits } from './types-DFe5BoJY.cjs';
-export { InMemoryCreditRepository, createInMemoryCreditRepository, generateId, getNextMonthlyReset } from './repository/index.cjs';
+export { InMemoryCreditRepository, addCreditsThroughRepository, commitThroughRepository, createInMemoryCreditRepository, generateId, getNextMonthlyReset, releaseThroughRepository, reserveThroughRepository } from './repository/index.cjs';
 export { C as CreditsAuthProviderFactory, a as CreditsUser, I as ICreditsAuthProvider } from './types-OZU3I5OM.cjs';
 export { ApiKeyCreditsProvider, createApiKeyProvider, verifyAdminApiKey, verifyBearerToken } from './auth/index.cjs';
 export { CreditsService, DeductCreditsOptions, LowBalanceNotificationCallback, ReserveCreditsOptions, SubscriptionExpiredNotificationCallback, createCreditsService } from './service/index.cjs';
@@ -18,7 +18,9 @@ declare const creditSystemConfigSchema: z.ZodObject<{
     /**
      * Operation costs in credits
      * Keys are operation type names (any non-empty string)
-     * Values are positive numbers representing credit cost
+     * Values are non-negative numbers representing credit cost. 0 marks a free
+     * operation: `withCredits` runs it without touching the ledger. Amounts that
+     * move credits stay strictly positive, so `reserveCredits` refuses a 0.
      */
     operationCosts: z.ZodRecord<z.ZodString, z.ZodNumber>;
     /**
@@ -212,6 +214,41 @@ declare const UNLIMITED_BALANCE_SENTINEL = 999999;
  * Get the magic balance assigned to unlimited tiers on upgrade.
  */
 declare function getUnlimitedSentinelBalance(): number;
+/**
+ * What a monthly reset must leave in `balance`, as a storable instruction.
+ *
+ * This is the one place the unlimited contract is defined, because it is the
+ * one thing the two adapters kept disagreeing about. The canonical persisted
+ * representation of an unlimited tier is:
+ *
+ * - `monthlyLimit` = `storedMonthlyLimit(Infinity)`, i.e. the top of the
+ *   representable range. Never `0`, which reads as *no* allowance.
+ * - `balance` = at least {@link UNLIMITED_BALANCE_SENTINEL}, which is what
+ *   `updateTier` writes on upgrade.
+ *
+ * The reset used to leave an unlimited balance strictly alone ("`Infinity` is
+ * not storable, so change nothing"), which is correct for a healthy account and
+ * a trap for a degraded one: an unlimited user whose balance had been driven to
+ * `0` — by a spend, or by the older code that stored `0` as the limit — stayed
+ * at `0` through every subsequent reset and could never buy anything again. So
+ * the instruction is `atLeast`, not "leave alone": it restores a degraded
+ * balance to the sentinel and leaves a topped-up one (a purchase on top of an
+ * unlimited plan) untouched. It is expressed as a floor rather than as a number
+ * so the SQL adapter can apply it as `greatest(balance, n)` inside its guarded
+ * UPDATE instead of writing a literal read before the lock.
+ */
+type MonthlyResetBalance = 
+/** Store exactly this value. */
+{
+    kind: "absolute";
+    value: number;
+}
+/** Raise the stored balance to this value; leave anything higher alone. */
+ | {
+    kind: "atLeast";
+    value: number;
+};
+declare function monthlyResetBalance(tier: SubscriptionTier): MonthlyResetBalance;
 /**
  * Get tier configuration from configuration.
  * Falls back to the default tier (with a warning) if the tier is unknown.
@@ -493,4 +530,4 @@ declare function isPreviewMode(data: unknown): boolean;
  */
 declare function createDummyReservation(userId: string, operationType: string): PortableReservation;
 
-export { ConsoleNotificationHandler, type CreditErrorInfo, type CreditNotificationEvent, PortableReservation as CreditReservation, type CreditSystemConfig, type ICreditConfigProvider, type ICreditNotificationHandler, type OperationCostInfo, PortableReservation, SubscriptionTier as SDKSubscriptionTier, SubscriptionTier, TierConfig, UNLIMITED_BALANCE_SENTINEL, checkAndNotifyLowBalance, clearConfigProvider, clearCooldownState, clearNotificationHandlers, createDummyReservation, generateRequestId, getConfig, getConfigMonthlyLimit, getConfigOperationCost, getConfigProvider, getConfigTierConfig, getDefaultFreeCredits, getDefaultTier, getMonthlyLimit, getOperationCost, getOperationCosts, getOperationCostsWithLabels, getOperationLabel, getOperationLabels, getReservationExpiryMs, getTierConfig, getTotalCredits, getUnlimitedSentinelBalance, getValidOperationTypes, getValidTiers, initializeConfig, isCreditErrorMessage, isFeatureEnabled, isFreeTier, isPreviewMode, isUnlimitedTier, isValidOperationType, isValidTier, loadConfigFromEnv, notifySubscriptionExpired, notifySubscriptionExpiring, parseCreditError, parseTier, registerConfigProvider, registerNotificationHandler, resetConfig, tierSchema };
+export { ConsoleNotificationHandler, type CreditErrorInfo, type CreditNotificationEvent, PortableReservation as CreditReservation, type CreditSystemConfig, type ICreditConfigProvider, type ICreditNotificationHandler, type MonthlyResetBalance, type OperationCostInfo, PortableReservation, SubscriptionTier as SDKSubscriptionTier, SubscriptionTier, TierConfig, UNLIMITED_BALANCE_SENTINEL, checkAndNotifyLowBalance, clearConfigProvider, clearCooldownState, clearNotificationHandlers, createDummyReservation, generateRequestId, getConfig, getConfigMonthlyLimit, getConfigOperationCost, getConfigProvider, getConfigTierConfig, getDefaultFreeCredits, getDefaultTier, getMonthlyLimit, getOperationCost, getOperationCosts, getOperationCostsWithLabels, getOperationLabel, getOperationLabels, getReservationExpiryMs, getTierConfig, getTotalCredits, getUnlimitedSentinelBalance, getValidOperationTypes, getValidTiers, initializeConfig, isCreditErrorMessage, isFeatureEnabled, isFreeTier, isPreviewMode, isUnlimitedTier, isValidOperationType, isValidTier, loadConfigFromEnv, monthlyResetBalance, notifySubscriptionExpired, notifySubscriptionExpiring, parseCreditError, parseTier, registerConfigProvider, registerNotificationHandler, resetConfig, tierSchema };

package/dist/index.d.ts

@@ -1,10 +1,10 @@
-import { S as SubscriptionTier, T as TierConfig, c as PortableReservation } from './types-CjLj3GW5.js';
-export { A as AIProviderType, B as BuiltinTier, g as CreditCheckResult, a as CreditOperationType, C as CreditSource, D as DeductCreditsResult, J as JournalReferenceType, M as MonthlyResetResult, f as PortableJournalEntry, P as PortableTransaction, d as PortableUsageLog, b as PortableUserCredits, R as ReservationStatus, h as ResourceType, g as SDKCreditCheckResult, e as SubscriptionExpiryResult, i as TransactionType, U as UsageHistoryEntry, j as UsageHistoryResponse, b as UserCredits, W as WithCreditsOptions, k as calculateAvailableCredits, t as toDate, l as toPortableTimestamp } from './types-CjLj3GW5.js';
-export { CreditError, CreditErrorCode, CreditErrorCodeType, commitReservationWithJournal, createInsufficientCreditsError, createInvalidOperationTypeError, createReservationAlreadyProcessedError, createReservationExpiredError, createReservationNotFoundError, createUserNotFoundError, isCreditError, isInsufficientCreditsError, releaseReservationWithJournal, reserveCreditsForOperation } from './core/index.js';
+import { S as SubscriptionTier, T as TierConfig, a as PortableReservation } from './types-Dzc443vy.js';
+export { A as AIProviderType, B as BuiltinTier, g as CreditCheckResult, C as CreditOperationType, b as CreditSource, D as DeductCreditsResult, J as JournalReferenceType, M as MonthlyResetResult, f as PortableJournalEntry, P as PortableTransaction, d as PortableUsageLog, c as PortableUserCredits, R as ReservationStatus, h as ResourceType, g as SDKCreditCheckResult, e as SubscriptionExpiryResult, i as TransactionType, U as UsageHistoryEntry, j as UsageHistoryResponse, c as UserCredits, W as WithCreditsOptions, k as calculateAvailableCredits, t as toDate, l as toPortableTimestamp } from './types-Dzc443vy.js';
+export { A as AddCreditsAtomicOptions, a as AddCreditsOutcome, b as AddCreditsV2Input, C as CommitOutcome, c as CreateJournalEntryInput, d as CreateReservationInput, e as CreateTransactionInput, f as CreateUsageLogInput, g as CreditBalanceUpdate, h as CreditRepositoryFactory, E as ExpireOutcome, i as ExpireReservationV2Options, I as ICreditRepository, j as ICreditRepositoryCreditsV2, k as ICreditRepositoryV2, J as JournalEntryQuery, R as ReleaseOutcome, l as ReservationTransitionOptions, m as ReserveCreditsV2Input, n as ReserveOutcome, T as TerminalReservationStatus, o as TierUpdateInput, U as UsageLogQuery, p as isCreditedOutcome, q as isReservedOutcome, r as isWinningOutcome, s as reservationJournalKey, t as supportsCreditsV2, u as supportsIdempotentCredit, v as toClientUserCredits } from './types-BhCdep_t.js';
+export { CREDIT_AMOUNT_MAX, CREDIT_AMOUNT_SCALE, CreditError, CreditErrorCode, CreditErrorCodeType, PaymentEventPayload, RESERVATION_STATUSES, RESERVED_JOURNAL_KEY_PREFIX, ReservationIntegrityView, StoredPaymentEvent, TERMINAL_RESERVATION_STATUSES, assertDirectStatusWriteAllowed, assertHoldPlaced, assertKnownReservationStatus, assertPublicJournalKey, assertRepresentableAmount, assertRepresentableFields, assertRepresentableTierAmount, assertUnkeyedDirectReservation, assertUnreferencedDirectTransaction, assertValidCreditAmount, assertValidIdempotencyKey, assertValidStoredAmount, assertValidStoredAmountRaw, backedBalanceFloor, classifyDatabaseError, commitReservationWithJournal, createIdempotencyConflictError, createInsufficientCreditsError, createInvalidAmountError, createInvalidOperationTypeError, createPaymentRefConflictError, createReservationAlreadyProcessedError, createReservationExpiredError, createReservationNotFoundError, createTransientError, createUnsupportedOperationError, createUserNotFoundError, describePaymentMismatch, getSqlState, hasPlacedHold, isCreditError, isIdempotencyConflictError, isInsufficientCreditsError, isRepresentableAmount, isReservationStatus, isReservedJournalKey, isTerminalReservationStatus, isTransientDatabaseError, isTransientError, isUniqueViolation, isValidCreditAmount, isValidIdempotencyKey, normalizePaymentRef, numericToCents, releaseReservationWithJournal, reserveCreditsForOperation, sameAmount, storedMonthlyLimit, sumAmounts, terminalStatusOf, toCents } from './core/index.js';
 export { D as DeferredExecutor, c as createDeferredExecutor, g as genericDeferred, n as noopDeferred, s as synchronousDeferred } from './deferred-C7rrRfkm.js';
 import { z } from 'zod';
-export { A as AddCreditsAtomicOptions, C as CreateJournalEntryInput, a as CreateReservationInput, b as CreateTransactionInput, c as CreateUsageLogInput, d as CreditBalanceUpdate, e as CreditRepositoryFactory, I as ICreditRepository, J as JournalEntryQuery, T as TierUpdateInput, U as UsageLogQuery, t as toClientUserCredits } from './types-_bSybQnb.js';
-export { InMemoryCreditRepository, createInMemoryCreditRepository, generateId, getNextMonthlyReset } from './repository/index.js';
+export { InMemoryCreditRepository, addCreditsThroughRepository, commitThroughRepository, createInMemoryCreditRepository, generateId, getNextMonthlyReset, releaseThroughRepository, reserveThroughRepository } from './repository/index.js';
 export { C as CreditsAuthProviderFactory, a as CreditsUser, I as ICreditsAuthProvider } from './types-OZU3I5OM.js';
 export { ApiKeyCreditsProvider, createApiKeyProvider, verifyAdminApiKey, verifyBearerToken } from './auth/index.js';
 export { CreditsService, DeductCreditsOptions, LowBalanceNotificationCallback, ReserveCreditsOptions, SubscriptionExpiredNotificationCallback, createCreditsService } from './service/index.js';
@@ -18,7 +18,9 @@ declare const creditSystemConfigSchema: z.ZodObject<{
     /**
      * Operation costs in credits
      * Keys are operation type names (any non-empty string)
-     * Values are positive numbers representing credit cost
+     * Values are non-negative numbers representing credit cost. 0 marks a free
+     * operation: `withCredits` runs it without touching the ledger. Amounts that
+     * move credits stay strictly positive, so `reserveCredits` refuses a 0.
      */
     operationCosts: z.ZodRecord<z.ZodString, z.ZodNumber>;
     /**
@@ -212,6 +214,41 @@ declare const UNLIMITED_BALANCE_SENTINEL = 999999;
  * Get the magic balance assigned to unlimited tiers on upgrade.
  */
 declare function getUnlimitedSentinelBalance(): number;
+/**
+ * What a monthly reset must leave in `balance`, as a storable instruction.
+ *
+ * This is the one place the unlimited contract is defined, because it is the
+ * one thing the two adapters kept disagreeing about. The canonical persisted
+ * representation of an unlimited tier is:
+ *
+ * - `monthlyLimit` = `storedMonthlyLimit(Infinity)`, i.e. the top of the
+ *   representable range. Never `0`, which reads as *no* allowance.
+ * - `balance` = at least {@link UNLIMITED_BALANCE_SENTINEL}, which is what
+ *   `updateTier` writes on upgrade.
+ *
+ * The reset used to leave an unlimited balance strictly alone ("`Infinity` is
+ * not storable, so change nothing"), which is correct for a healthy account and
+ * a trap for a degraded one: an unlimited user whose balance had been driven to
+ * `0` — by a spend, or by the older code that stored `0` as the limit — stayed
+ * at `0` through every subsequent reset and could never buy anything again. So
+ * the instruction is `atLeast`, not "leave alone": it restores a degraded
+ * balance to the sentinel and leaves a topped-up one (a purchase on top of an
+ * unlimited plan) untouched. It is expressed as a floor rather than as a number
+ * so the SQL adapter can apply it as `greatest(balance, n)` inside its guarded
+ * UPDATE instead of writing a literal read before the lock.
+ */
+type MonthlyResetBalance = 
+/** Store exactly this value. */
+{
+    kind: "absolute";
+    value: number;
+}
+/** Raise the stored balance to this value; leave anything higher alone. */
+ | {
+    kind: "atLeast";
+    value: number;
+};
+declare function monthlyResetBalance(tier: SubscriptionTier): MonthlyResetBalance;
 /**
  * Get tier configuration from configuration.
  * Falls back to the default tier (with a warning) if the tier is unknown.
@@ -493,4 +530,4 @@ declare function isPreviewMode(data: unknown): boolean;
  */
 declare function createDummyReservation(userId: string, operationType: string): PortableReservation;
 
-export { ConsoleNotificationHandler, type CreditErrorInfo, type CreditNotificationEvent, PortableReservation as CreditReservation, type CreditSystemConfig, type ICreditConfigProvider, type ICreditNotificationHandler, type OperationCostInfo, PortableReservation, SubscriptionTier as SDKSubscriptionTier, SubscriptionTier, TierConfig, UNLIMITED_BALANCE_SENTINEL, checkAndNotifyLowBalance, clearConfigProvider, clearCooldownState, clearNotificationHandlers, createDummyReservation, generateRequestId, getConfig, getConfigMonthlyLimit, getConfigOperationCost, getConfigProvider, getConfigTierConfig, getDefaultFreeCredits, getDefaultTier, getMonthlyLimit, getOperationCost, getOperationCosts, getOperationCostsWithLabels, getOperationLabel, getOperationLabels, getReservationExpiryMs, getTierConfig, getTotalCredits, getUnlimitedSentinelBalance, getValidOperationTypes, getValidTiers, initializeConfig, isCreditErrorMessage, isFeatureEnabled, isFreeTier, isPreviewMode, isUnlimitedTier, isValidOperationType, isValidTier, loadConfigFromEnv, notifySubscriptionExpired, notifySubscriptionExpiring, parseCreditError, parseTier, registerConfigProvider, registerNotificationHandler, resetConfig, tierSchema };
+export { ConsoleNotificationHandler, type CreditErrorInfo, type CreditNotificationEvent, PortableReservation as CreditReservation, type CreditSystemConfig, type ICreditConfigProvider, type ICreditNotificationHandler, type MonthlyResetBalance, type OperationCostInfo, PortableReservation, SubscriptionTier as SDKSubscriptionTier, SubscriptionTier, TierConfig, UNLIMITED_BALANCE_SENTINEL, checkAndNotifyLowBalance, clearConfigProvider, clearCooldownState, clearNotificationHandlers, createDummyReservation, generateRequestId, getConfig, getConfigMonthlyLimit, getConfigOperationCost, getConfigProvider, getConfigTierConfig, getDefaultFreeCredits, getDefaultTier, getMonthlyLimit, getOperationCost, getOperationCosts, getOperationCostsWithLabels, getOperationLabel, getOperationLabels, getReservationExpiryMs, getTierConfig, getTotalCredits, getUnlimitedSentinelBalance, getValidOperationTypes, getValidTiers, initializeConfig, isCreditErrorMessage, isFeatureEnabled, isFreeTier, isPreviewMode, isUnlimitedTier, isValidOperationType, isValidTier, loadConfigFromEnv, monthlyResetBalance, notifySubscriptionExpired, notifySubscriptionExpiring, parseCreditError, parseTier, registerConfigProvider, registerNotificationHandler, resetConfig, tierSchema };