payment-kit 1.24.3 → 1.25.0

package/api/src/store/models/index.ts

@@ -34,6 +34,8 @@ import { MeterEvent, TMeterEvent } from './meter-event';
 import { AutoRechargeConfig } from './auto-recharge-config';
 import { ProductVendor } from './product-vendor';
 import { TaxRate } from './tax-rate';
+import { ExchangeRateProvider } from './exchange-rate-provider';
+import { PriceQuote } from './price-quote';
 
 const models = {
   CheckoutSession,
@@ -71,6 +73,8 @@ const models = {
   AutoRechargeConfig,
   ProductVendor,
   TaxRate,
+  ExchangeRateProvider,
+  PriceQuote,
 };
 
 export function initialize(sequelize: any) {
@@ -122,6 +126,8 @@ export * from './meter-event';
 export * from './auto-recharge-config';
 export * from './product-vendor';
 export * from './tax-rate';
+export * from './exchange-rate-provider';
+export * from './price-quote';
 
 export type TPriceExpanded = TPrice & {
   object: 'price';

package/api/src/store/models/payment-intent.ts

@@ -80,6 +80,8 @@ export class PaymentIntent extends Model<InferAttributes<PaymentIntent>, InferCr
 
   declare setup_future_usage?: LiteralUnion<'off_session' | 'on_session', string>;
 
+  declare quote_locked_at?: Date;
+
   // how to split the payment from this link
   declare beneficiaries?: PaymentBeneficiary[];
 
@@ -222,6 +224,10 @@ export class PaymentIntent extends Model<InferAttributes<PaymentIntent>, InferCr
       type: DataTypes.ENUM('on_session', 'off_session'),
       allowNull: true,
     },
+    quote_locked_at: {
+      type: DataTypes.DATE,
+      allowNull: true,
+    },
     created_at: {
       type: DataTypes.DATE,
       defaultValue: DataTypes.NOW,

package/api/src/store/models/price-quote.ts

@@ -0,0 +1,284 @@
+import { CreationOptional, DataTypes, InferAttributes, InferCreationAttributes, Model, Transaction } from 'sequelize';
+import type { LiteralUnion } from 'type-fest';
+
+import { createEvent } from '../../libs/audit';
+import { createIdGenerator } from '../../libs/util';
+import { QuoteMetadata, QuoteStatus } from './types';
+
+export const nextPriceQuoteId = createIdGenerator('pq', 24);
+
+/**
+ * Create Quote Input (Final Freeze Architecture)
+ *
+ * Quote is created only at Submit time, directly as 'used' status.
+ * @see Intent: blocklets/core/ai/intent/20260112-dynamic-price.md
+ */
+export interface CreateQuoteInput {
+  price_id: string;
+  session_id?: string;
+  invoice_id?: string;
+  idempotency_key: string;
+  base_currency?: string;
+  base_amount: string;
+  target_currency_id: string;
+  rate_currency_symbol: string;
+  exchange_rate: string;
+  quoted_amount: string;
+  rate_provider_id: string;
+  rate_provider_name: string;
+  rate_timestamp_ms: number;
+  slippage_percent?: number;
+  max_payable_token?: string;
+  min_acceptable_rate?: string;
+  metadata?: QuoteMetadata;
+}
+
+export class PriceQuote extends Model<InferAttributes<PriceQuote>, InferCreationAttributes<PriceQuote>> {
+  declare id: CreationOptional<string>;
+  declare price_id: string;
+  declare session_id?: string;
+  declare invoice_id?: string;
+  declare idempotency_key: string;
+
+  // Base currency (always USD in P0)
+  declare base_currency: string;
+  declare base_amount: string;
+
+  // Target currency and rate
+  declare target_currency_id: string;
+  declare rate_currency_symbol: string;
+  declare exchange_rate: string; // USD per token
+  declare quoted_amount: string; // in smallest unit
+
+  // Rate provider info
+  declare rate_provider_id: string;
+  declare rate_provider_name: string;
+  declare rate_timestamp_ms: number;
+
+  // Lifecycle
+  declare expires_at: number; // Unix timestamp
+  declare status: CreationOptional<LiteralUnion<QuoteStatus, string>>;
+
+  // Metadata
+  declare metadata: QuoteMetadata | null;
+
+  // Slippage snapshot (derived when quote is used)
+  declare slippage_percent?: number;
+  declare max_payable_token?: string;
+  declare min_acceptable_rate?: string;
+  declare slippage_derived_at_ms?: number;
+
+  declare created_at: CreationOptional<Date>;
+
+  public static initialize(sequelize: any) {
+    this.init(
+      {
+        id: {
+          type: DataTypes.STRING(32),
+          primaryKey: true,
+          allowNull: false,
+          defaultValue: nextPriceQuoteId,
+        },
+        price_id: {
+          type: DataTypes.STRING(32),
+          allowNull: false,
+        },
+        session_id: {
+          type: DataTypes.STRING(32),
+          allowNull: true,
+        },
+        invoice_id: {
+          type: DataTypes.STRING(32),
+          allowNull: true,
+        },
+        idempotency_key: {
+          type: DataTypes.STRING(128),
+          allowNull: false,
+          unique: true,
+        },
+        base_currency: {
+          type: DataTypes.STRING(8),
+          allowNull: false,
+          defaultValue: 'USD',
+        },
+        base_amount: {
+          type: DataTypes.STRING(32),
+          allowNull: false,
+        },
+        target_currency_id: {
+          type: DataTypes.STRING(16),
+          allowNull: false,
+        },
+        rate_currency_symbol: {
+          type: DataTypes.STRING(16),
+          allowNull: false,
+        },
+        exchange_rate: {
+          type: DataTypes.STRING(32),
+          allowNull: false,
+        },
+        quoted_amount: {
+          type: DataTypes.STRING(64),
+          allowNull: false,
+        },
+        rate_provider_id: {
+          type: DataTypes.STRING(32),
+          allowNull: false,
+        },
+        rate_provider_name: {
+          type: DataTypes.STRING(64),
+          allowNull: false,
+        },
+        rate_timestamp_ms: {
+          type: DataTypes.BIGINT,
+          allowNull: false,
+        },
+        expires_at: {
+          type: DataTypes.INTEGER,
+          allowNull: false,
+        },
+        status: {
+          // Final Freeze: Only 3 statuses - used/paid/payment_failed
+          type: DataTypes.ENUM('used', 'paid', 'payment_failed'),
+          allowNull: false,
+          defaultValue: 'used',
+        },
+        metadata: {
+          type: DataTypes.JSON,
+          allowNull: true,
+        },
+        slippage_percent: {
+          type: DataTypes.DECIMAL(5, 2),
+          allowNull: true,
+        },
+        max_payable_token: {
+          type: DataTypes.STRING(64),
+          allowNull: true,
+        },
+        min_acceptable_rate: {
+          type: DataTypes.STRING(32),
+          allowNull: true,
+        },
+        slippage_derived_at_ms: {
+          type: DataTypes.BIGINT,
+          allowNull: true,
+        },
+        created_at: {
+          type: DataTypes.DATE,
+          defaultValue: DataTypes.NOW,
+          allowNull: false,
+        },
+      },
+      {
+        sequelize,
+        modelName: 'PriceQuote',
+        tableName: 'price_quotes',
+        createdAt: 'created_at',
+        updatedAt: false,
+        hooks: {
+          afterCreate: (model: PriceQuote, options) => {
+            // Async event creation - don't block transaction
+            if (options.transaction) {
+              // Defer until after transaction commits
+              options.transaction.afterCommit(() => {
+                createEvent('PriceQuote', 'price_quote.created', model, options).catch(console.error);
+              });
+            } else {
+              // No transaction, create immediately
+              createEvent('PriceQuote', 'price_quote.created', model, options).catch(console.error);
+            }
+          },
+          afterUpdate: (model: PriceQuote, options) => {
+            // Async event creation - don't block transaction
+            if (options.transaction) {
+              // Defer until after transaction commits
+              options.transaction.afterCommit(() => {
+                createEvent('PriceQuote', 'price_quote.updated', model, options).catch(console.error);
+              });
+            } else {
+              // No transaction, create immediately
+              createEvent('PriceQuote', 'price_quote.updated', model, options).catch(console.error);
+            }
+          },
+        },
+      }
+    );
+  }
+
+  public static associate(models: any) {
+    this.belongsTo(models.Price, {
+      foreignKey: 'price_id',
+      as: 'price',
+    });
+  }
+
+  /**
+   * Check if Quote is usable for payment
+   * Final Freeze: 'used' status means Quote is ready for payment
+   */
+  public isUsable(): boolean {
+    return this.status === 'used';
+  }
+
+  /**
+   * Check if Quote can be retried (payment_failed can be retried)
+   */
+  public canRetry(): boolean {
+    return this.status === 'used' || this.status === 'payment_failed';
+  }
+
+  /**
+   * Find Quote by idempotency key (for idempotent Submit)
+   * Returns any Quote with the given key regardless of status
+   */
+  public static findByIdempotencyKey(idempotencyKey: string): Promise<PriceQuote | null> {
+    return this.findOne({
+      where: {
+        idempotency_key: idempotencyKey,
+      },
+    });
+  }
+
+  /**
+   * Create Quote directly as 'used' (Final Freeze architecture)
+   *
+   * This is the ONLY way to create Quotes in the new architecture.
+   * Quotes are created at Submit time, never during Preview.
+   */
+  public static async createUsedQuote(input: CreateQuoteInput, transaction?: Transaction): Promise<PriceQuote> {
+    const now = Math.floor(Date.now() / 1000);
+    const quote = await this.create(
+      {
+        ...input,
+        base_currency: input.base_currency || 'USD',
+        status: 'used',
+        // expires_at kept for backward compatibility but not used for validation
+        expires_at: now + 180, // 3 minutes (flow SLA, not Quote validity)
+        slippage_derived_at_ms: Date.now(),
+      },
+      { transaction }
+    );
+    return quote;
+  }
+
+  /**
+   * Mark Quote as paid (payment completed successfully)
+   * Idempotent: if already paid, returns silently
+   */
+  public async markAsPaid(transaction?: any): Promise<void> {
+    if (this.status === 'paid') {
+      return;
+    }
+    await this.update({ status: 'paid' }, { transaction });
+  }
+
+  /**
+   * Mark Quote as payment_failed
+   * Note: payment_failed does NOT mean Quote is invalid, can be retried
+   */
+  public async markAsPaymentFailed(transaction?: any): Promise<void> {
+    await this.update({ status: 'payment_failed' }, { transaction });
+  }
+}
+
+export type TPriceQuote = InferAttributes<PriceQuote>;

package/api/src/store/models/price.ts

@@ -101,6 +101,12 @@ export class Price extends Model<InferAttributes<Price>, InferCreationAttributes
 
   declare tax_behavior?: LiteralUnion<'inclusive' | 'exclusive', string>;
 
+  // Dynamic pricing fields
+  declare pricing_type: LiteralUnion<'fixed' | 'dynamic', string>;
+  declare base_currency: string | null;
+  declare base_amount: string | null;
+  declare dynamic_pricing_config: { lock_duration?: number } | null;
+
   public static readonly GENESIS_ATTRIBUTES = {
     id: {
       type: DataTypes.STRING(32),
@@ -218,6 +224,23 @@ export class Price extends Model<InferAttributes<Price>, InferCreationAttributes
           allowNull: false,
           defaultValue: 'inclusive',
         },
+        pricing_type: {
+          type: DataTypes.ENUM('fixed', 'dynamic'),
+          allowNull: false,
+          defaultValue: 'fixed',
+        },
+        base_currency: {
+          type: DataTypes.STRING(8),
+          allowNull: true,
+        },
+        base_amount: {
+          type: DataTypes.STRING(32),
+          allowNull: true,
+        },
+        dynamic_pricing_config: {
+          type: DataTypes.JSON,
+          allowNull: true,
+        },
       },
       {
         sequelize,
@@ -273,6 +296,25 @@ export class Price extends Model<InferAttributes<Price>, InferCreationAttributes
   }
 
   public static formatBeforeSave(price: Partial<TPrice & { model: string }>) {
+    // Validate dynamic pricing fields
+    if (price.pricing_type === 'dynamic') {
+      if (!price.base_currency || !price.base_amount) {
+        throw new Error('base_currency and base_amount are required for dynamic pricing');
+      }
+      if (price.base_currency !== 'USD') {
+        throw new Error('Only USD is supported as base_currency');
+      }
+      // Set default lock_duration if not provided
+      if (!price.dynamic_pricing_config) {
+        price.dynamic_pricing_config = { lock_duration: 30 };
+      }
+    } else if (price.pricing_type === 'fixed') {
+      // Clear dynamic pricing fields for fixed prices
+      price.base_currency = null;
+      price.base_amount = null;
+      price.dynamic_pricing_config = null;
+    }
+
     if (price.type) {
       if (price.type === 'recurring') {
         if (!price.recurring) {
@@ -413,11 +455,17 @@ export class Price extends Model<InferAttributes<Price>, InferCreationAttributes
     }
 
     // @ts-ignore
-    return items.map((x) => ({
-      ...x,
-      price: prices.find((p) => p.id === x.price_id),
-      upsell_price: x.upsell_price_id ? prices.find((p) => p.id === x.upsell_price_id) : null,
-    })) as TLineItemExpanded[];
+    return items.map((x) => {
+      const price = prices.find((p) => p.id === x.price_id);
+      if (!price) {
+        logger.warn('Price not found for line item', { priceId: x.price_id });
+      }
+      return {
+        ...x,
+        price,
+        upsell_price: x.upsell_price_id ? prices.find((p) => p.id === x.upsell_price_id) : null,
+      };
+    }) as TLineItemExpanded[];
   }
 
   public static async insert(price: TPrice & { model: string }) {

package/api/src/store/models/subscription.ts

@@ -114,6 +114,13 @@ export class Subscription extends Model<InferAttributes<Subscription>, InferCrea
 
   // 3rd party payment tx hash
   declare payment_details?: PaymentDetails;
+  declare slippage_config?: {
+    mode?: 'percent' | 'rate';
+    percent?: number;
+    min_acceptable_rate?: string;
+    base_currency?: string;
+    updated_at_ms?: number;
+  } | null;
 
   declare proration_behavior?: LiteralUnion<'always_invoice' | 'create_prorations' | 'none', string>;
   declare payment_behavior?: LiteralUnion<'allow_incomplete' | 'error_if_incomplete' | 'pending_if_incomplete', string>;
@@ -223,6 +230,10 @@ export class Subscription extends Model<InferAttributes<Subscription>, InferCrea
       type: DataTypes.ENUM('charge_automatically', 'send_invoice'),
       allowNull: false,
     },
+    slippage_config: {
+      type: DataTypes.JSON,
+      allowNull: true,
+    },
     days_until_due: {
       type: DataTypes.NUMBER,
       allowNull: true,

package/api/src/store/models/types.ts

@@ -730,7 +730,9 @@ export type EventType = LiteralUnion<
   | 'customer.credit.insufficient'
   | 'customer.credit.low_balance'
   | 'customer.credit_grant.granted'
-  | 'customer.credit_grant.depleted',
+  | 'customer.credit_grant.depleted'
+  | 'exchange_rate.providers_unavailable'
+  | 'exchange_rate.spread_exceeded',
   string
 >;
 
@@ -925,3 +927,61 @@ export type CreditGrantChainDetail = {
   // Voided reason
   voided_reason?: 'refund' | 'expired' | 'manual';
 };
+
+/**
+ * Quote Status (Final Freeze)
+ *
+ * - used: Quote created and consumed at Submit
+ * - paid: Payment completed successfully
+ * - payment_failed: Payment flow failed (does NOT mean Quote is invalid)
+ *
+ * Legacy statuses (deprecated, for backward compatibility only):
+ * - active, expired, cancelled, failed
+ *
+ * @see Intent: blocklets/core/ai/intent/20260112-dynamic-price.md
+ */
+/**
+ * Final Freeze: Quote only has 3 statuses
+ * - used: Quote created at Submit, ready for payment
+ * - paid: Payment completed successfully
+ * - payment_failed: Payment process failed (Quote still valid for retry)
+ */
+export type QuoteStatus = 'used' | 'paid' | 'payment_failed';
+
+export interface QuoteMetadata {
+  calculation?: {
+    token_amount_raw?: string; // Deprecated: use total_base_amount_scaled + rate_scaled instead
+    unit_amount_raw?: string; // Deprecated: use quoted_amount_unit instead
+    total_base_amount_scaled?: string; // BN: total USD amount scaled by 10^8
+    rate_scaled?: string; // BN: exchange rate scaled by 10^8
+    quoted_amount_unit?: string; // BN: final quoted amount in smallest token unit
+  };
+  rounding?: {
+    mode?: string;
+    token_decimals?: number;
+  };
+  risk?: {
+    anomaly_detected?: boolean;
+    deviation_percent?: number;
+    degraded?: boolean;
+    degraded_reason?: string | null;
+  };
+  rate?: {
+    consensus_method?: string;
+    providers?: Array<{
+      id?: string;
+      name?: string;
+      rate?: string;
+      timestamp_ms?: number;
+      degraded?: boolean;
+      degraded_reason?: string;
+    }>;
+  };
+  slippage?: {
+    percent?: number;
+    max_payable_token?: string;
+    min_acceptable_rate?: string;
+    derived_at_ms?: number;
+  };
+  context?: Record<string, any>;
+}