payment-kit 1.28.0 → 1.29.0

package/api/src/store/models/entitlement-grant.ts

@@ -0,0 +1,118 @@
+/* eslint-disable @typescript-eslint/lines-between-class-members */
+import { CreationOptional, DataTypes, InferAttributes, InferCreationAttributes, Model } from 'sequelize';
+import type { LiteralUnion } from 'type-fest';
+
+import { createIdGenerator } from '../../libs/util';
+
+export const nextEntitlementGrantId = createIdGenerator('eg', 24);
+
+// One Subscription (or other source) grants an Entitlement to a Customer.
+// Multiple grants for the same (customer, entitlement) can coexist across channels;
+// the "currently effective" grant is determined by status + active_until.
+// eslint-disable-next-line prettier/prettier
+export class EntitlementGrant extends Model<InferAttributes<EntitlementGrant>, InferCreationAttributes<EntitlementGrant>> {
+  declare id: CreationOptional<string>;
+  declare livemode: boolean;
+
+  declare entitlement_id: string;
+  declare customer_id: string;
+
+  declare source_subscription_id?: string;
+  declare source_channel: LiteralUnion<
+    'stripe' | 'arcblock' | 'ethereum' | 'base' | 'app_store' | 'google_play',
+    string
+  >;
+
+  declare active_from: number;
+  declare active_until: number;
+
+  declare status: LiteralUnion<'active' | 'canceled' | 'expired' | 'voided', string>;
+
+  declare metadata?: Record<string, any>;
+
+  declare created_at: CreationOptional<Date>;
+  declare updated_at: CreationOptional<Date>;
+
+  public static readonly GENESIS_ATTRIBUTES = {
+    id: {
+      type: DataTypes.STRING(30),
+      primaryKey: true,
+      allowNull: false,
+      defaultValue: nextEntitlementGrantId,
+    },
+    livemode: {
+      type: DataTypes.BOOLEAN,
+      allowNull: false,
+    },
+    entitlement_id: {
+      type: DataTypes.STRING(30),
+      allowNull: false,
+    },
+    customer_id: {
+      type: DataTypes.STRING(18),
+      allowNull: false,
+    },
+    source_subscription_id: {
+      type: DataTypes.STRING(30),
+      allowNull: true,
+    },
+    source_channel: {
+      type: DataTypes.STRING(20),
+      allowNull: false,
+    },
+    active_from: {
+      type: DataTypes.INTEGER,
+      allowNull: false,
+    },
+    active_until: {
+      type: DataTypes.INTEGER,
+      allowNull: false,
+    },
+    status: {
+      type: DataTypes.STRING(20),
+      allowNull: false,
+      defaultValue: 'active',
+    },
+    metadata: {
+      type: DataTypes.JSON,
+      allowNull: true,
+    },
+    created_at: {
+      type: DataTypes.DATE,
+      defaultValue: DataTypes.NOW,
+      allowNull: false,
+    },
+    updated_at: {
+      type: DataTypes.DATE,
+      defaultValue: DataTypes.NOW,
+      allowNull: false,
+    },
+  };
+
+  public static initialize(sequelize: any) {
+    this.init(EntitlementGrant.GENESIS_ATTRIBUTES, {
+      sequelize,
+      modelName: 'EntitlementGrant',
+      tableName: 'entitlement_grants',
+      createdAt: 'created_at',
+      updatedAt: 'updated_at',
+    });
+  }
+
+  public static associate(models: any) {
+    this.belongsTo(models.Entitlement, {
+      foreignKey: 'entitlement_id',
+      as: 'entitlement',
+    });
+    this.belongsTo(models.Customer, {
+      foreignKey: 'customer_id',
+      as: 'customer',
+    });
+    this.belongsTo(models.Subscription, {
+      foreignKey: 'source_subscription_id',
+      as: 'subscription',
+    });
+  }
+}
+
+export type TEntitlementGrant = InferAttributes<EntitlementGrant>;

package/api/src/store/models/entitlement-product.ts

@@ -0,0 +1,48 @@
+/* eslint-disable @typescript-eslint/lines-between-class-members */
+import { CreationOptional, DataTypes, InferAttributes, InferCreationAttributes, Model } from 'sequelize';
+
+// Join table: which products unlock which entitlements (many-to-many)
+// eslint-disable-next-line prettier/prettier
+export class EntitlementProduct extends Model<InferAttributes<EntitlementProduct>, InferCreationAttributes<EntitlementProduct>> {
+  declare entitlement_id: string;
+  declare product_id: string;
+  declare created_at: CreationOptional<Date>;
+  declare updated_at: CreationOptional<Date>;
+
+  public static readonly GENESIS_ATTRIBUTES = {
+    entitlement_id: {
+      type: DataTypes.STRING(30),
+      primaryKey: true,
+      allowNull: false,
+    },
+    product_id: {
+      type: DataTypes.STRING(30),
+      primaryKey: true,
+      allowNull: false,
+    },
+    created_at: {
+      type: DataTypes.DATE,
+      defaultValue: DataTypes.NOW,
+      allowNull: false,
+    },
+    updated_at: {
+      type: DataTypes.DATE,
+      defaultValue: DataTypes.NOW,
+      allowNull: false,
+    },
+  };
+
+  public static initialize(sequelize: any) {
+    this.init(EntitlementProduct.GENESIS_ATTRIBUTES, {
+      sequelize,
+      modelName: 'EntitlementProduct',
+      tableName: 'entitlement_products',
+      createdAt: 'created_at',
+      updatedAt: 'updated_at',
+    });
+  }
+
+  public static associate() {}
+}
+
+export type TEntitlementProduct = InferAttributes<EntitlementProduct>;

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

@@ -0,0 +1,86 @@
+/* eslint-disable @typescript-eslint/lines-between-class-members */
+import { CreationOptional, DataTypes, InferAttributes, InferCreationAttributes, Model } from 'sequelize';
+
+import { createIdGenerator } from '../../libs/util';
+
+export const nextEntitlementId = createIdGenerator('ent', 24);
+
+// eslint-disable-next-line prettier/prettier
+export class Entitlement extends Model<InferAttributes<Entitlement>, InferCreationAttributes<Entitlement>> {
+  declare id: CreationOptional<string>;
+  declare livemode: boolean;
+
+  declare key: string;
+  declare name?: string;
+  declare description?: string;
+
+  declare metadata?: Record<string, any>;
+
+  declare created_at: CreationOptional<Date>;
+  declare updated_at: CreationOptional<Date>;
+
+  public static readonly GENESIS_ATTRIBUTES = {
+    id: {
+      type: DataTypes.STRING(30),
+      primaryKey: true,
+      allowNull: false,
+      defaultValue: nextEntitlementId,
+    },
+    livemode: {
+      type: DataTypes.BOOLEAN,
+      allowNull: false,
+    },
+    key: {
+      type: DataTypes.STRING(64),
+      allowNull: false,
+      unique: true,
+    },
+    name: {
+      type: DataTypes.STRING(255),
+      allowNull: true,
+    },
+    description: {
+      type: DataTypes.TEXT,
+      allowNull: true,
+    },
+    metadata: {
+      type: DataTypes.JSON,
+      allowNull: true,
+    },
+    created_at: {
+      type: DataTypes.DATE,
+      defaultValue: DataTypes.NOW,
+      allowNull: false,
+    },
+    updated_at: {
+      type: DataTypes.DATE,
+      defaultValue: DataTypes.NOW,
+      allowNull: false,
+    },
+  };
+
+  public static initialize(sequelize: any) {
+    this.init(Entitlement.GENESIS_ATTRIBUTES, {
+      sequelize,
+      modelName: 'Entitlement',
+      tableName: 'entitlements',
+      createdAt: 'created_at',
+      updatedAt: 'updated_at',
+    });
+  }
+
+  public static associate(models: any) {
+    this.belongsToMany(models.Product, {
+      through: models.EntitlementProduct,
+      foreignKey: 'entitlement_id',
+      otherKey: 'product_id',
+      as: 'products',
+    });
+    this.hasMany(models.EntitlementGrant, {
+      foreignKey: 'entitlement_id',
+      as: 'grants',
+    });
+  }
+}
+
+export type TEntitlement = InferAttributes<Entitlement>;

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

@@ -39,6 +39,9 @@ import { PriceQuote } from './price-quote';
 import { ArchiveMetadata } from './archive-metadata';
 import { ArchiveLock } from './archive-lock';
 import { RevenueSnapshot } from './revenue-snapshot';
+import { Entitlement } from './entitlement';
+import { EntitlementGrant } from './entitlement-grant';
+import { EntitlementProduct } from './entitlement-product';
 
 const models = {
   CheckoutSession,
@@ -81,6 +84,9 @@ const models = {
   ArchiveMetadata,
   ArchiveLock,
   RevenueSnapshot,
+  Entitlement,
+  EntitlementGrant,
+  EntitlementProduct,
 };
 
 export function initialize(sequelize: any) {
@@ -137,6 +143,9 @@ export * from './price-quote';
 export * from './archive-metadata';
 export * from './archive-lock';
 export * from './revenue-snapshot';
+export * from './entitlement';
+export * from './entitlement-grant';
+export * from './entitlement-product';
 
 export type TPriceExpanded = TPrice & {
   object: 'price';

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

@@ -84,6 +84,14 @@ export class Invoice extends Model<InferAttributes<Invoice>, InferCreationAttrib
   declare tax: string;
   declare total: string;
 
+  // Three-segment amounts for cross-channel accounting (D-001 A).
+  // gross_amount = what the user actually paid (= total for non-IAP channels).
+  // platform_fee = amount Apple / Google withheld (0 for Stripe / on-chain).
+  // net_amount   = what we actually received (= gross_amount - platform_fee).
+  declare gross_amount?: string;
+  declare platform_fee?: string;
+  declare net_amount?: string;
+
   declare amount_due: string; // total - amount_paid
   declare amount_paid: string;
   declare amount_remaining: string; // amount_due - amount_paid
@@ -250,6 +258,18 @@ export class Invoice extends Model<InferAttributes<Invoice>, InferCreationAttrib
       type: DataTypes.STRING(32),
       allowNull: false,
     },
+    gross_amount: {
+      type: DataTypes.STRING(32),
+      allowNull: true,
+    },
+    platform_fee: {
+      type: DataTypes.STRING(32),
+      defaultValue: '0',
+    },
+    net_amount: {
+      type: DataTypes.STRING(32),
+      allowNull: true,
+    },
     subtotal: {
       type: DataTypes.STRING(32),
       allowNull: false,

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

@@ -7,6 +7,8 @@ import { CreationOptional, DataTypes, InferAttributes, InferCreationAttributes,
 import Stripe from 'stripe';
 import type { LiteralUnion } from 'type-fest';
 
+import { AppStoreClient } from '../../integrations/app-store/client';
+import { GooglePlayClient } from '../../integrations/google-play/client';
 import { STRIPE_API_VERSION, createIdGenerator } from '../../libs/util';
 import { sequelize } from '../sequelize';
 import type { PaymentMethodSettings } from './types';
@@ -17,6 +19,8 @@ const nextId = createIdGenerator('pm', 24);
 const stripeClients = new Map<string, Stripe>();
 const evmClients = new Map<string, JsonRpcProvider>();
 const ocapClients = new Map<string, OcapClient>();
+const googlePlayClients = new Map<string, GooglePlayClient>();
+const appStoreClients = new Map<string, AppStoreClient>();
 
 // eslint-disable-next-line prettier/prettier
 export class PaymentMethod extends Model<InferAttributes<PaymentMethod>, InferCreationAttributes<PaymentMethod>> {
@@ -27,7 +31,10 @@ export class PaymentMethod extends Model<InferAttributes<PaymentMethod>, InferCr
   declare livemode: boolean;
   declare locked: boolean;
 
-  declare type: LiteralUnion<'stripe' | 'arcblock' | 'ethereum' | 'bitcoin' | 'base', string>;
+  declare type: LiteralUnion<
+    'stripe' | 'arcblock' | 'ethereum' | 'bitcoin' | 'base' | 'app_store' | 'google_play',
+    string
+  >;
 
   declare name: string;
 
@@ -153,6 +160,15 @@ export class PaymentMethod extends Model<InferAttributes<PaymentMethod>, InferCr
       tmp.stripe.secret_key = security.encrypt(tmp.stripe.secret_key);
       tmp.stripe.webhook_signing_secret = security.encrypt(tmp.stripe.webhook_signing_secret);
     }
+    if (tmp.google_play) {
+      tmp.google_play.service_account_json = security.encrypt(tmp.google_play.service_account_json);
+    }
+    if (tmp.app_store?.private_key_pem) {
+      tmp.app_store.private_key_pem = security.encrypt(tmp.app_store.private_key_pem);
+    }
+    if (tmp.app_store?.shared_secret) {
+      tmp.app_store.shared_secret = security.encrypt(tmp.app_store.shared_secret);
+    }
 
     return tmp;
   }
@@ -163,6 +179,15 @@ export class PaymentMethod extends Model<InferAttributes<PaymentMethod>, InferCr
       tmp.stripe.secret_key = security.decrypt(tmp.stripe.secret_key);
       tmp.stripe.webhook_signing_secret = security.decrypt(tmp.stripe.webhook_signing_secret);
     }
+    if (tmp.google_play) {
+      tmp.google_play.service_account_json = security.decrypt(tmp.google_play.service_account_json);
+    }
+    if (tmp.app_store?.private_key_pem) {
+      tmp.app_store.private_key_pem = security.decrypt(tmp.app_store.private_key_pem);
+    }
+    if (tmp.app_store?.shared_secret) {
+      tmp.app_store.shared_secret = security.decrypt(tmp.app_store.shared_secret);
+    }
 
     return tmp;
   }
@@ -240,6 +265,42 @@ export class PaymentMethod extends Model<InferAttributes<PaymentMethod>, InferCr
     return client as JsonRpcProvider;
   }
 
+  getGooglePlayClient() {
+    if (this.type !== 'google_play') {
+      throw new Error('payment method is not google_play');
+    }
+    if (!this.settings.google_play) {
+      throw new Error('payment method config insufficient for google_play');
+    }
+
+    if (googlePlayClients.has(this.id)) {
+      return googlePlayClients.get(this.id) as GooglePlayClient;
+    }
+
+    const settings = PaymentMethod.decryptSettings(this.settings);
+    const client = GooglePlayClient.fromSettings(settings.google_play!);
+    googlePlayClients.set(this.id, client);
+    return client;
+  }
+
+  getAppStoreClient() {
+    if (this.type !== 'app_store') {
+      throw new Error('payment method is not app_store');
+    }
+    if (!this.settings.app_store) {
+      throw new Error('payment method config insufficient for app_store');
+    }
+
+    if (appStoreClients.has(this.id)) {
+      return appStoreClients.get(this.id) as AppStoreClient;
+    }
+
+    const settings = PaymentMethod.decryptSettings(this.settings);
+    const client = AppStoreClient.fromSettings(settings.app_store!);
+    appStoreClients.set(this.id, client);
+    return client;
+  }
+
   public static async supportAutoCharge(id: string) {
     const method = await PaymentMethod.findByPk(id);
     return method && CHARGE_SUPPORTED_CHAIN_TYPES.includes(method.type);

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

@@ -68,6 +68,11 @@ export class Refund extends Model<InferAttributes<Refund>, InferCreationAttribut
   declare updated_at: CreationOptional<Date>;
   declare type: LiteralUnion<'refund' | 'stake_return', string>;
 
+  // Refund origin (added for IAP support).
+  //   merchant_initiated —商户主动调 API 退款 (Stripe / 链上)
+  //   platform_initiated — Apple/Google webhook 推过来的退款，我们被动接收
+  declare source?: LiteralUnion<'merchant_initiated' | 'platform_initiated', string>;
+
   public static readonly GENESIS_ATTRIBUTES = {
     id: {
       type: DataTypes.STRING(30),
@@ -192,6 +197,11 @@ export class Refund extends Model<InferAttributes<Refund>, InferCreationAttribut
           allowNull: true,
           defaultValue: 'refund',
         },
+        source: {
+          type: DataTypes.STRING(30),
+          allowNull: true,
+          defaultValue: 'merchant_initiated',
+        },
       },
       {
         sequelize,

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

@@ -129,6 +129,11 @@ export class Subscription extends Model<InferAttributes<Subscription>, InferCrea
 
   declare recovered_from?: string;
 
+  // Payment channel (D-005). Stripe / arcblock / ethereum / base / app_store / google_play
+  declare channel?: LiteralUnion<'stripe' | 'arcblock' | 'ethereum' | 'base' | 'app_store' | 'google_play', string>;
+  // IAP platform environment (D-005). Orthogonal to livemode.
+  declare environment?: LiteralUnion<'production' | 'sandbox', string>;
+
   // TODO: following fields not supported
   // application
   // application_fee_percent
@@ -346,6 +351,15 @@ export class Subscription extends Model<InferAttributes<Subscription>, InferCrea
           allowNull: true,
           defaultValue: null,
         },
+        channel: {
+          type: DataTypes.STRING(20),
+          allowNull: true,
+        },
+        environment: {
+          type: DataTypes.STRING(20),
+          allowNull: true,
+          defaultValue: 'production',
+        },
       },
       {
         sequelize,

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

@@ -310,6 +310,22 @@ export type PaymentMethodSettings = {
     native_symbol: string;
     confirmation: number;
   };
+  google_play?: {
+    package_name: string;
+    service_account_json: string; // encrypted JSON string of GCP service account credentials
+    pubsub_topic_name: string; // projects/<project>/topics/<topic>
+  };
+  app_store?: {
+    bundle_id: string;
+    environment: LiteralUnion<'production' | 'sandbox', string>;
+    /** App-Specific Shared Secret — only needed when verifying StoreKit 1 (legacy) receipts via Apple's verifyReceipt endpoint. StoreKit 2 JWS path does not use this. */
+    shared_secret?: string; // encrypted
+    // App Store Server API credentials — only needed when calling Apple back for state refresh.
+    // StoreKit 2 JWS verification (the happy path) does NOT need any of these.
+    issuer_id?: string;
+    key_id?: string;
+    private_key_pem?: string; // encrypted .p8 file contents
+  };
 };
 
 export type VaultConfig = {
@@ -366,6 +382,22 @@ export type PaymentDetails = {
     block_height: number;
     confirmations: number;
   };
+  google_play?: {
+    purchase_token: string;
+    order_id?: string;
+    product_id: string;
+    subscription_id?: string;
+    expiry_time_millis?: string;
+    environment?: LiteralUnion<'production' | 'sandbox', string>;
+  };
+  app_store?: {
+    original_transaction_id: string;
+    transaction_id?: string;
+    product_id: string;
+    web_order_line_item_id?: string;
+    environment?: LiteralUnion<'Production' | 'Sandbox', string>;
+    expires_at?: number; // unix seconds
+  };
 };
 
 export type PaymentBeneficiary = {