payment-kit 1.13.15

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

@@ -0,0 +1,307 @@
+/* eslint-disable @typescript-eslint/indent */
+/* eslint-disable @typescript-eslint/lines-between-class-members */
+import { CreationOptional, DataTypes, InferAttributes, InferCreationAttributes, Model } from 'sequelize';
+import type { LiteralUnion } from 'type-fest';
+
+import { createEvent, createStatusEvent } from '../../libs/audit';
+import { createIdGenerator } from '../../libs/util';
+import type { PaymentSettings, PriceRecurring } from './types';
+
+const nextId = createIdGenerator('sub', 24);
+
+// eslint-disable-next-line prettier/prettier
+export class Subscription extends Model<InferAttributes<Subscription>, InferCreationAttributes<Subscription>> {
+  declare id: CreationOptional<string>;
+
+  declare livemode: boolean;
+
+  declare currency_id: string;
+  declare customer_id: string;
+
+  declare current_period_end: number;
+  declare current_period_start: number;
+
+  declare default_payment_method_id: string;
+  declare description?: string;
+  declare latest_invoice_id?: string;
+
+  declare metadata: Record<string, any>;
+
+  declare pending_setup_intent?: string;
+  declare pending_update?: {
+    billing_cycle_anchor?: number;
+    expires_at?: number;
+    subscription_items?: any[];
+    trial_end?: number;
+  };
+
+  declare status: LiteralUnion<
+    'active' | 'past_due' | 'unpaid' | 'canceled' | 'incomplete' | 'incomplete_expired' | 'trialing' | 'paused',
+    string
+  >;
+
+  declare cancel_at_period_end: boolean;
+  declare cancel_at: CreationOptional<number>;
+  declare canceled_at: CreationOptional<number>;
+  declare cancelation_details?: {
+    comment: string;
+    feedback: LiteralUnion<
+      | 'too_expensive'
+      | 'missing_features'
+      | 'switched_service'
+      | 'unused'
+      | 'customer_service'
+      | 'too_complex'
+      | 'low_quality'
+      | 'other',
+      string
+    >;
+    reason: LiteralUnion<'cancellation_requested' | 'payment_disputed' | 'payment_failed', string>;
+  };
+
+  declare billing_cycle_anchor: number;
+  declare billing_thresholds?: {
+    amount_gte: number;
+    reset_billing_cycle_anchor: boolean;
+  };
+
+  declare collection_method: LiteralUnion<'charge_automatically' | 'send_invoice', string>;
+
+  // Number of days a customer has to pay invoices generated by this subscription. This value will be null for subscriptions where collection_method=charge_automatically.
+  declare days_until_due?: number;
+
+  declare discount_id?: string;
+
+  declare next_pending_invoice_item_invoice?: number;
+
+  declare pause_collection?: {
+    behavior: LiteralUnion<'keep_as_draft' | 'mark_uncollectible' | 'void', string>;
+    resumes_at: number;
+  };
+
+  declare payment_settings?: PaymentSettings;
+
+  declare pending_invoice_item_interval: PriceRecurring;
+
+  declare schedule_id?: string;
+
+  // If the subscription has ended, the date the subscription ended.
+  declare ended_at?: number;
+  declare start_date: number;
+  declare trail_end?: number;
+  declare trail_start?: number;
+  declare trail_settings?: {
+    end_behavior: {
+      missing_payment_method: LiteralUnion<'cancel' | 'pause' | 'create_invoice', string>;
+    };
+  };
+
+  // 3rd party payment tx hash
+  declare payment_details?: {
+    tx_hash?: string;
+    payer?: string;
+  };
+
+  // TODO: following fields not supported
+  // application
+  // application_fee_percent
+  // automatic_tax
+  // default_tax_rates
+  // on_behalf_of
+  // transfer_data
+
+  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: nextId,
+    },
+    livemode: {
+      type: DataTypes.BOOLEAN,
+      allowNull: false,
+    },
+    currency_id: {
+      type: DataTypes.STRING(15),
+      allowNull: false,
+    },
+    customer_id: {
+      type: DataTypes.STRING(18),
+      allowNull: false,
+    },
+    cancel_at_period_end: {
+      type: DataTypes.BOOLEAN,
+      allowNull: false,
+    },
+    current_period_end: {
+      type: DataTypes.INTEGER,
+      allowNull: false,
+    },
+    current_period_start: {
+      type: DataTypes.INTEGER,
+      allowNull: false,
+    },
+    default_payment_method_id: {
+      type: DataTypes.STRING(30),
+      allowNull: true,
+    },
+    description: {
+      type: DataTypes.STRING(512),
+      allowNull: true,
+    },
+    latest_invoice_id: {
+      type: DataTypes.STRING(30),
+      allowNull: true,
+    },
+    pending_setup_intent: {
+      type: DataTypes.STRING(30),
+      allowNull: true,
+    },
+    pending_update: {
+      type: DataTypes.JSON,
+      allowNull: true,
+    },
+    status: {
+      type: DataTypes.ENUM('active', 'canceled', 'incomplete', 'incomplete_expired', 'past_due', 'trialing', 'unpaid'),
+      allowNull: false,
+    },
+    cancel_at: {
+      type: DataTypes.INTEGER,
+      allowNull: true,
+    },
+    canceled_at: {
+      type: DataTypes.INTEGER,
+      allowNull: true,
+    },
+    cancelation_details: {
+      type: DataTypes.JSON,
+      allowNull: true,
+    },
+    billing_cycle_anchor: {
+      type: DataTypes.INTEGER,
+      allowNull: false,
+    },
+    billing_thresholds: {
+      type: DataTypes.JSON,
+      allowNull: true,
+    },
+    collection_method: {
+      type: DataTypes.ENUM('charge_automatically', 'send_invoice'),
+    },
+    days_until_due: {
+      type: DataTypes.NUMBER,
+      allowNull: true,
+    },
+    discount_id: {
+      type: DataTypes.STRING(30),
+      allowNull: true,
+    },
+    next_pending_invoice_item_invoice_id: {
+      type: DataTypes.STRING(30),
+      allowNull: true,
+    },
+    pause_collection: {
+      type: DataTypes.JSON,
+      allowNull: true,
+    },
+    payment_settings: {
+      type: DataTypes.JSON,
+      allowNull: true,
+    },
+    pending_invoice_item_interval: {
+      type: DataTypes.JSON,
+      allowNull: false,
+    },
+    schedule_id: {
+      type: DataTypes.STRING(30),
+      allowNull: true,
+    },
+    end_at: {
+      type: DataTypes.INTEGER,
+      allowNull: true,
+    },
+    start_date: {
+      type: DataTypes.INTEGER,
+      allowNull: false,
+    },
+    trail_end: {
+      type: DataTypes.INTEGER,
+      allowNull: true,
+    },
+    trail_start: {
+      type: DataTypes.INTEGER,
+      allowNull: true,
+    },
+    trail_settings: {
+      type: DataTypes.JSON,
+      allowNull: true,
+    },
+    payment_details: {
+      type: DataTypes.JSON,
+      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(Subscription.GENESIS_ATTRIBUTES, {
+      sequelize,
+      modelName: 'Subscription',
+      tableName: 'subscriptions',
+      createdAt: 'created_at',
+      updatedAt: 'updated_at',
+      hooks: {
+        afterCreate: (model: Subscription, options) =>
+          createEvent('Subscription', 'customer.subscription.created', model, options).catch(console.error),
+        afterUpdate: (model: Subscription, options) => {
+          createEvent('Subscription', 'customer.subscription.updated', model, options).catch(console.error);
+          createStatusEvent('Subscription', 'customer.subscription', { canceled: 'canceled' }, model, options).catch(
+            console.error
+          );
+        },
+        afterDestroy: (model: Subscription, options) =>
+          createEvent('Subscription', 'customer.subscription.deleted', model, options).catch(console.error),
+      },
+    });
+  }
+
+  public static associate(models: any) {
+    this.hasOne(models.PaymentCurrency, {
+      sourceKey: 'currency_id',
+      foreignKey: 'id',
+      as: 'paymentCurrency',
+    });
+    this.hasOne(models.PaymentMethod, {
+      sourceKey: 'default_payment_method_id',
+      foreignKey: 'id',
+      as: 'paymentMethod',
+    });
+    this.hasOne(models.Customer, {
+      sourceKey: 'customer_id',
+      foreignKey: 'id',
+      as: 'customer',
+    });
+    this.hasMany(models.SubscriptionItem, {
+      foreignKey: 'subscription_id',
+      as: 'items',
+    });
+  }
+}
+
+export type TSubscription = InferAttributes<Subscription>;

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

@@ -0,0 +1,406 @@
+/* eslint-disable @typescript-eslint/indent */
+import type { LiteralUnion } from 'type-fest';
+
+export type Pagination<T = any> = T & {
+  // offset based
+  page?: number;
+  size?: number;
+  // TODO: cursor based
+  limit?: number;
+  starting_after?: string;
+  ending_before?: string;
+
+  // extra
+  [key: string]: any;
+};
+
+export type Paginated<T = any> = {
+  count: number;
+  list: T[];
+};
+
+export type InferFormType<T> = Omit<
+  T,
+  'id' | 'created_at' | 'created_via' | 'updated_at' | 'active' | 'livemode' | 'metadata'
+> & {
+  metadata: { key: string; value: string }[];
+};
+
+export type PriceRecurring = {
+  interval: LiteralUnion<'hour' | 'day' | 'week' | 'month' | 'year', string>;
+  interval_count: number;
+  aggregate_usage?: LiteralUnion<'sum' | 'last_during_period' | 'max' | 'last_ever', string>;
+  usage_type?: LiteralUnion<'licensed' | 'metered', string>;
+  metered?: boolean;
+};
+
+export type CustomUnitAmount = {
+  maximum: string;
+  minimum: string;
+  preset: string;
+};
+
+export type PriceTier = {
+  // The flat billing amount for an entire tier, regardless of the number of units in the tier.
+  flat_amount?: number;
+
+  // The per unit billing amount for each individual unit for which this tier applies.
+  unit_amount?: string;
+
+  // The upper bound of this tier.
+  up_to?: number;
+};
+
+export type TransformQuantity = {
+  divide_by: number;
+  round: LiteralUnion<'up' | 'down', string>;
+};
+
+export type CustomField = {
+  key: string;
+  label: string;
+  type: LiteralUnion<'text' | 'numeric' | 'dropdown', string>;
+  optional: boolean;
+  text?: {
+    maximum_length: number;
+    minimum_length: number;
+  };
+  numeric?: {
+    maximum_length: number;
+    minimum_length: number;
+  };
+  dropdown?: {
+    options: { label: string; value: string }[];
+  };
+};
+
+export type AfterPayment = {
+  type: LiteralUnion<'redirect' | 'hosted_confirmation', string>;
+  redirect?: {
+    url: string;
+  };
+  hosted_confirmation?: {
+    custom_message: string;
+  };
+};
+
+export type SimpleCustomField = {
+  name: string;
+  value: string;
+};
+
+export type DiscountAmount = {
+  amount: number;
+  discount: string;
+};
+
+export type CustomerAddress = {
+  city?: string;
+  country?: string;
+  line1?: string;
+  line2?: string;
+  postal_code?: string;
+  state?: string;
+};
+
+export type CustomerShipping = {
+  address: CustomerAddress;
+  name: string;
+  phone: string;
+};
+
+export type CustomerDetail = {
+  address?: CustomerAddress;
+  email?: string;
+  name?: string;
+  phone?: string;
+  // TODO: following are not supported
+  // tax_exempt: any;
+  // tax_ids: any
+};
+
+export type PaymentError = {
+  type: LiteralUnion<'api_error' | 'card_error' | 'idempotency_error' | 'invalid_request_error', string>;
+  charge?: string;
+  code?: string;
+  decline_code?: string;
+  doc_url?: string;
+  message?: string;
+  param?: string;
+  payment_settings?: any;
+  payment_method_id?: string;
+  payment_method_type?: string;
+};
+
+export type LineItem = {
+  price_id: string;
+  quantity: number;
+  adjustable_quantity?: {
+    enabled: boolean;
+    maximum: number;
+    minimum: number;
+  };
+  // TODO: following are not supported
+  // price_data?: any;
+  // dynamic_tax_rates?: any;
+  // tax_rates?: any;
+};
+
+export type InvoiceData = Record<string, any>;
+
+// @see https://stripe.com/docs/currencies/conversions
+// If presentment currency is different from settlement currency, this is the exchange rate snapshot used.
+export type CurrencyConversion = {
+  amount_subtotal: string;
+  amount_total: string;
+  fx_rate: string;
+  source_currency: string;
+};
+
+export type SubscriptionSchedulePhase = {
+  billing_cycle_anchor: LiteralUnion<'phase_start' | 'automatic', string>;
+  billing_thresholds?: {
+    amount_gte: string;
+    reset_billing_cycle_anchor: boolean;
+  };
+  collection_method: LiteralUnion<'charge_automatically' | 'send_invoice', string>;
+  coupon_id?: string;
+  currency_id?: string;
+  description?: string;
+  start_date?: number;
+  end_date?: number;
+  trail_end?: number;
+  invoice_settings?: {
+    days_until_due?: number;
+  };
+  items: {
+    price: string;
+    quantity?: number;
+    billing_thresholds?: {
+      usage_gte: number;
+    };
+    // tax_rates?: string[];
+  }[];
+  metadata?: Record<string, any>;
+  // TODO: following fields not supported
+  // application_fee_percent?: number;
+  // default_payment_method?: string;
+  // default_tax_rates?: string[];
+  // on_behalf_of?: string;
+  // transfer_data?: any;
+};
+
+export type PaymentMethodOptions = {
+  arcblock?: {
+    payer: string;
+  };
+  ethereum?: {
+    payer: string;
+  };
+  stripe?: {
+    payer: string;
+  };
+};
+
+export type PaymentSettings = {
+  payment_method_options: PaymentMethodOptions;
+  payment_method_types: string[];
+};
+
+export type EventType = LiteralUnion<
+  | 'account.application.authorized'
+  | 'account.application.deauthorized'
+  | 'account.external_account.created'
+  | 'account.external_account.deleted'
+  | 'account.external_account.updated'
+  | 'account.updated'
+  | 'application_fee.created'
+  | 'application_fee.refund.updated'
+  | 'application_fee.refunded'
+  | 'balance.available'
+  | 'billing_portal.configuration.created'
+  | 'billing_portal.configuration.updated'
+  | 'billing_portal.session.created'
+  | 'capability.updated'
+  | 'cash_balance.funds_available'
+  | 'charge.captured'
+  | 'charge.dispute.closed'
+  | 'charge.dispute.created'
+  | 'charge.dispute.funds_reinstated'
+  | 'charge.dispute.funds_withdrawn'
+  | 'charge.dispute.updated'
+  | 'charge.expired'
+  | 'charge.failed'
+  | 'charge.pending'
+  | 'charge.refund.updated'
+  | 'charge.refunded'
+  | 'charge.succeeded'
+  | 'charge.updated'
+  | 'checkout.session.async_payment_failed'
+  | 'checkout.session.async_payment_succeeded'
+  | 'checkout.session.completed'
+  | 'checkout.session.expired'
+  | 'coupon.created'
+  | 'coupon.deleted'
+  | 'coupon.updated'
+  | 'credit_note.created'
+  | 'credit_note.updated'
+  | 'credit_note.voided'
+  | 'customer_cash_balance_transaction.created'
+  | 'customer.created'
+  | 'customer.deleted'
+  | 'customer.discount.created'
+  | 'customer.discount.deleted'
+  | 'customer.discount.updated'
+  | 'customer.source.created'
+  | 'customer.source.deleted'
+  | 'customer.source.expiring'
+  | 'customer.source.updated'
+  | 'customer.subscription.created'
+  | 'customer.subscription.deleted'
+  | 'customer.subscription.paused'
+  | 'customer.subscription.pending_update_applied'
+  | 'customer.subscription.pending_update_expired'
+  | 'customer.subscription.resumed'
+  | 'customer.subscription.trial_will_end'
+  | 'customer.subscription.updated'
+  | 'customer.tax_id.created'
+  | 'customer.tax_id.deleted'
+  | 'customer.tax_id.updated'
+  | 'customer.updated'
+  | 'file.created'
+  | 'financial_connections.account.created'
+  | 'financial_connections.account.deactivated'
+  | 'financial_connections.account.disconnected'
+  | 'financial_connections.account.reactivated'
+  | 'financial_connections.account.refreshed_balance'
+  | 'identity.verification_session.canceled'
+  | 'identity.verification_session.created'
+  | 'identity.verification_session.processing'
+  | 'identity.verification_session.redacted'
+  | 'identity.verification_session.requires_input'
+  | 'identity.verification_session.verified'
+  | 'invoice.created'
+  | 'invoice.deleted'
+  | 'invoice.finalization_failed'
+  | 'invoice.finalized'
+  | 'invoice.marked_uncollectible'
+  | 'invoice.paid'
+  | 'invoice.payment_action_required'
+  | 'invoice.payment_failed'
+  | 'invoice.payment_succeeded'
+  | 'invoice.sent'
+  | 'invoice.upcoming'
+  | 'invoice.updated'
+  | 'invoice.voided'
+  | 'invoiceitem.created'
+  | 'invoiceitem.deleted'
+  | 'issuing_authorization.created'
+  | 'issuing_authorization.request'
+  | 'issuing_authorization.updated'
+  | 'issuing_card.created'
+  | 'issuing_card.updated'
+  | 'issuing_cardholder.created'
+  | 'issuing_cardholder.updated'
+  | 'issuing_dispute.closed'
+  | 'issuing_dispute.created'
+  | 'issuing_dispute.funds_reinstated'
+  | 'issuing_dispute.submitted'
+  | 'issuing_dispute.updated'
+  | 'issuing_transaction.created'
+  | 'issuing_transaction.updated'
+  | 'mandate.updated'
+  | 'order.created'
+  | 'payment_intent.amount_capturable_updated'
+  | 'payment_intent.canceled'
+  | 'payment_intent.created'
+  | 'payment_intent.partially_funded'
+  | 'payment_intent.payment_failed'
+  | 'payment_intent.processing'
+  | 'payment_intent.requires_action'
+  | 'payment_intent.succeeded'
+  | 'payment_link.created'
+  | 'payment_link.updated'
+  | 'payment_method.attached'
+  | 'payment_method.automatically_updated'
+  | 'payment_method.detached'
+  | 'payment_method.updated'
+  | 'payout.canceled'
+  | 'payout.created'
+  | 'payout.failed'
+  | 'payout.paid'
+  | 'payout.reconciliation_completed'
+  | 'payout.updated'
+  | 'person.created'
+  | 'person.deleted'
+  | 'person.updated'
+  | 'plan.created'
+  | 'plan.deleted'
+  | 'plan.updated'
+  | 'price.created'
+  | 'price.deleted'
+  | 'price.updated'
+  | 'product.created'
+  | 'product.deleted'
+  | 'product.updated'
+  | 'promotion_code.created'
+  | 'promotion_code.updated'
+  | 'quote.accepted'
+  | 'quote.canceled'
+  | 'quote.created'
+  | 'quote.finalized'
+  | 'radar.early_fraud_warning.created'
+  | 'radar.early_fraud_warning.updated'
+  | 'recipient.created'
+  | 'recipient.deleted'
+  | 'recipient.updated'
+  | 'refund.created'
+  | 'refund.updated'
+  | 'reporting.report_run.failed'
+  | 'reporting.report_run.succeeded'
+  | 'reporting.report_type.updated'
+  | 'review.closed'
+  | 'review.opened'
+  | 'setup_intent.canceled'
+  | 'setup_intent.created'
+  | 'setup_intent.requires_action'
+  | 'setup_intent.setup_failed'
+  | 'setup_intent.succeeded'
+  | 'sigma.scheduled_query_run.created'
+  | 'sku.created'
+  | 'sku.deleted'
+  | 'sku.updated'
+  | 'source.canceled'
+  | 'source.chargeable'
+  | 'source.failed'
+  | 'source.mandate_notification'
+  | 'source.refund_attributes_required'
+  | 'source.transaction.created'
+  | 'source.transaction.updated'
+  | 'subscription_schedule.aborted'
+  | 'subscription_schedule.canceled'
+  | 'subscription_schedule.completed'
+  | 'subscription_schedule.created'
+  | 'subscription_schedule.expiring'
+  | 'subscription_schedule.released'
+  | 'subscription_schedule.updated'
+  | 'tax_rate.created'
+  | 'tax_rate.updated'
+  | 'tax.settings.updated'
+  | 'terminal.reader.action_failed'
+  | 'terminal.reader.action_succeeded'
+  | 'test_helpers.test_clock.advancing'
+  | 'test_helpers.test_clock.created'
+  | 'test_helpers.test_clock.deleted'
+  | 'test_helpers.test_clock.internal_failure'
+  | 'test_helpers.test_clock.ready'
+  | 'topup.canceled'
+  | 'topup.created'
+  | 'topup.failed'
+  | 'topup.reversed'
+  | 'topup.succeeded'
+  | 'transfer.created'
+  | 'transfer.reversed'
+  | 'transfer.updated',
+  string
+>;