payment-kit 1.23.11 → 1.24.0

package/api/src/routes/products.ts

@@ -72,14 +72,53 @@ const ProductAndPriceSchema = Joi.object({
   vendor_config: VendorConfigSchema,
 }).unknown(true);
 
+// Schedule configuration for credit delivery
+const CreditScheduleConfigSchema = Joi.object({
+  enabled: Joi.boolean().default(false),
+  delivery_mode: Joi.string().valid('invoice', 'schedule').default('invoice'),
+  interval_value: Joi.number().min(0.01).when('enabled', {
+    is: true,
+    then: Joi.required(),
+    otherwise: Joi.optional(),
+  }),
+  interval_unit: Joi.string().valid('hour', 'day', 'week', 'month').when('enabled', {
+    is: true,
+    then: Joi.required(),
+    otherwise: Joi.optional(),
+  }),
+  amount_per_grant: Joi.number().greater(0).when('enabled', {
+    is: true,
+    then: Joi.required(),
+    otherwise: Joi.optional(),
+  }),
+  first_grant_timing: Joi.string().valid('immediate', 'after_trial', 'after_first_payment').default('immediate'),
+  expire_with_next_grant: Joi.boolean().default(true),
+  max_grants_per_period: Joi.number().min(1).optional(),
+});
+
 const CreditConfigSchema = Joi.object({
   valid_duration_value: Joi.number().default(0).optional(),
   valid_duration_unit: Joi.string().valid('hours', 'days', 'weeks', 'months', 'years').default('days').optional(),
   priority: Joi.number().min(0).max(100).default(50).optional(),
   applicable_prices: Joi.array().items(Joi.string()).default([]).optional(),
-  credit_amount: Joi.number().greater(0).required(),
+  // credit_amount is required for one-time delivery, optional when schedule is enabled
+  credit_amount: Joi.number().greater(0).when('schedule.enabled', {
+    is: true,
+    then: Joi.optional(),
+    otherwise: Joi.required(),
+  }),
   currency_id: Joi.string().required(),
-});
+  schedule: CreditScheduleConfigSchema.optional(),
+})
+  .custom((value, helpers) => {
+    if (value?.schedule?.expire_with_next_grant && (value?.valid_duration_value || 0) > 0) {
+      return helpers.error('any.invalid');
+    }
+    return value;
+  }, 'credit config validation')
+  .messages({
+    'any.invalid': 'valid_duration_* is mutually exclusive with schedule.expire_with_next_grant',
+  });
 
 export async function createProductAndPrices(payload: any) {
   const raw: Partial<Product> = pick(payload, [

package/api/src/routes/subscriptions.ts

@@ -107,6 +107,223 @@ const schema = createListParamSchema<{
   showTotalCount: Joi.boolean().optional(),
 });
 
+// Create subscription directly (for SDK use)
+const createSchema = Joi.object({
+  customer_id: Joi.string().required(),
+  items: Joi.array()
+    .items(
+      Joi.object({
+        price_id: Joi.string().required(),
+        quantity: Joi.number().integer().min(1).default(1),
+        metadata: Joi.object().optional(),
+      })
+    )
+    .min(1)
+    .max(MAX_SUBSCRIPTION_ITEM_COUNT)
+    .required(),
+  // Optional: if not provided, subscription won't have automatic billing (for prepaid/gifted subscriptions)
+  default_payment_method_id: Joi.string().optional(),
+  currency_id: Joi.string().optional(),
+  trial_period_days: Joi.number().integer().min(0).optional(),
+  trial_end: Joi.number().integer().optional(),
+  description: Joi.string().optional(),
+  metadata: MetadataSchema,
+  days_until_due: Joi.number().integer().min(0).optional(),
+  days_until_cancel: Joi.number().integer().min(0).optional(),
+  billing_cycle_anchor: Joi.number().integer().optional(),
+  collection_method: Joi.string().valid('charge_automatically', 'send_invoice').default('charge_automatically'),
+  proration_behavior: Joi.string().valid('always_invoice', 'create_prorations', 'none').default('none'),
+  service_actions: Joi.array().items(Joi.object()).optional(),
+  livemode: Joi.boolean().optional(), // Required if no payment_method_id provided
+});
+
+router.post('/', auth, async (req, res) => {
+  try {
+    const value = await createSchema.validateAsync(req.body);
+    const {
+      customer_id: customerId,
+      items,
+      default_payment_method_id: paymentMethodId,
+      trial_period_days: trialPeriodDays = 0,
+      trial_end: trialEndInput = 0,
+      description,
+      metadata = {},
+      days_until_due: daysUntilDue,
+      days_until_cancel: daysUntilCancel,
+      billing_cycle_anchor: billingCycleAnchor,
+      collection_method: collectionMethod,
+      proration_behavior: prorationBehavior,
+      service_actions: serviceActions,
+      livemode: livemodeInput,
+    } = value;
+
+    // Validate customer exists
+    const customer = await Customer.findByPk(customerId);
+    if (!customer) {
+      return res.status(404).json({ error: `Customer ${customerId} not found` });
+    }
+
+    // Validate payment method if provided
+    let paymentMethod: PaymentMethod | null = null;
+    if (paymentMethodId) {
+      paymentMethod = await PaymentMethod.findByPk(paymentMethodId);
+      if (!paymentMethod) {
+        return res.status(404).json({ error: `Payment method ${paymentMethodId} not found` });
+      }
+    }
+
+    // If no payment method, automatic billing is disabled (for prepaid/gifted subscriptions)
+    const hasAutomaticBilling = !!paymentMethod;
+
+    // Determine livemode
+    let livemode = livemodeInput;
+    if (livemode === undefined) {
+      if (paymentMethod) {
+        livemode = paymentMethod.livemode;
+      } else {
+        livemode = true; // Default to livemode if not specified
+      }
+    }
+
+    // Expand and validate line items
+    const priceIds = items.map((item: any) => item.price_id);
+    const prices = await Price.findAll({
+      where: { id: priceIds },
+      include: [{ model: Product, as: 'product' }],
+    });
+
+    if (prices.length !== priceIds.length) {
+      const foundIds = prices.map((p) => p.id);
+      const missingIds = priceIds.filter((id: string) => !foundIds.includes(id));
+      return res.status(404).json({ error: `Prices not found: ${missingIds.join(', ')}` });
+    }
+
+    // Validate all items are recurring
+    const nonRecurringPrices = prices.filter((p) => p.type !== 'recurring');
+    if (nonRecurringPrices.length > 0) {
+      return res.status(400).json({
+        error: `Subscription only supports recurring prices. Non-recurring prices: ${nonRecurringPrices.map((p) => p.id).join(', ')}`,
+      });
+    }
+
+    // Determine currency from first price if not provided
+    let currencyId = value.currency_id;
+    const firstPrice = prices[0];
+    if (!currencyId && firstPrice) {
+      currencyId = firstPrice.currency_id;
+    }
+    if (!currencyId) {
+      return res.status(400).json({ error: 'currency_id is required' });
+    }
+
+    const paymentCurrency = await PaymentCurrency.findByPk(currencyId);
+    if (!paymentCurrency) {
+      return res.status(404).json({ error: `Payment currency ${currencyId} not found` });
+    }
+
+    // Build line items
+    const lineItems: TLineItemExpanded[] = items.map((item: any) => {
+      const price = prices.find((p) => p.id === item.price_id);
+      return {
+        price_id: item.price_id,
+        price: price!.toJSON(),
+        quantity: item.quantity || 1,
+        metadata: item.metadata || {},
+      };
+    });
+
+    // Calculate subscription setup (periods, trial, etc.)
+    const setup = getSubscriptionCreateSetup(lineItems, currencyId, trialPeriodDays, trialEndInput);
+
+    // Create subscription
+    const subscription = await Subscription.create({
+      livemode,
+      currency_id: currencyId,
+      customer_id: customerId,
+      status: 'active', // Direct creation starts as active
+      current_period_start: setup.period.start,
+      current_period_end: setup.period.end,
+      billing_cycle_anchor: billingCycleAnchor || setup.cycle.anchor,
+      start_date: dayjs().unix(),
+      trial_end: setup.trial.end || undefined,
+      trial_start: setup.trial.start || undefined,
+      trial_settings: setup.trial.end
+        ? {
+            end_behavior: {
+              missing_payment_method: hasAutomaticBilling ? 'create_invoice' : 'cancel',
+            },
+          }
+        : undefined,
+      pending_invoice_item_interval: setup.recurring,
+      default_payment_method_id: paymentMethodId || '',
+      cancel_at_period_end: false,
+      collection_method: hasAutomaticBilling ? collectionMethod : 'send_invoice',
+      description: description || lineItems.map((item) => item.price.product?.name).join(', '),
+      proration_behavior: prorationBehavior,
+      payment_behavior: 'default_incomplete',
+      days_until_due: daysUntilDue,
+      days_until_cancel: daysUntilCancel,
+      metadata: formatMetadata(metadata),
+      service_actions: serviceActions || [],
+    });
+
+    // Create subscription items
+    await Promise.all(
+      lineItems.map((item) =>
+        SubscriptionItem.create({
+          livemode,
+          subscription_id: subscription.id,
+          price_id: item.price_id,
+          quantity: item.quantity,
+          metadata: item.metadata || {},
+        })
+      )
+    );
+
+    // If has trial period, set status to trialing
+    if (setup.trial.end && setup.trial.end > dayjs().unix()) {
+      await subscription.update({ status: 'trialing' });
+      createEvent('Subscription', 'customer.subscription.trial_start', subscription).catch(console.error);
+    } else {
+      createEvent('Subscription', 'customer.subscription.started', subscription).catch(console.error);
+    }
+
+    // Schedule subscription cycle job only if has automatic billing
+    if (hasAutomaticBilling) {
+      await addSubscriptionJob(subscription, 'cycle', false, setup.trial.end || setup.period.end);
+    }
+
+    logger.info('Subscription created via API', {
+      subscriptionId: subscription.id,
+      customerId,
+      status: subscription.status,
+      hasAutomaticBilling,
+    });
+
+    // Return expanded subscription
+    const result = await Subscription.findOne({
+      where: { id: subscription.id },
+      include: [
+        { model: PaymentCurrency, as: 'paymentCurrency' },
+        { model: PaymentMethod, as: 'paymentMethod' },
+        { model: SubscriptionItem, as: 'items' },
+        { model: Customer, as: 'customer' },
+      ],
+    });
+
+    const products = (await Product.findAll()).map((x) => x.toJSON());
+    const allPrices = (await Price.findAll()).map((x) => x.toJSON());
+    const doc = result!.toJSON();
+    // @ts-ignore
+    expandLineItems(doc.items, products, allPrices);
+
+    return res.json(doc);
+  } catch (err: any) {
+    logger.error('Failed to create subscription', { error: err.message });
+    return res.status(400).json({ error: err.message });
+  }
+});
+
 router.get('/', authMine, async (req, res) => {
   const { page, pageSize, status, livemode, ...query } = await schema.validateAsync(req.query, {
     stripUnknown: false,

package/api/src/store/migrations/20251225-add-credit-schedule-state.ts

@@ -0,0 +1,33 @@
+import { DataTypes } from 'sequelize';
+import { Migration, safeApplyColumnChanges } from '../migrate';
+
+/**
+ * Migration: Add credit_schedule_state column to subscriptions table
+ *
+ * This column stores the credit schedule state for subscriptions with
+ * scheduled credit delivery, enabling features like:
+ * - Periodic credit grants (hourly, daily, weekly, monthly)
+ * - Trial period credit delivery
+ * - Refresh-style credits that expire with next grant
+ */
+export const up: Migration = async ({ context }) => {
+  await safeApplyColumnChanges(context, {
+    subscriptions: [
+      {
+        name: 'credit_schedule_state',
+        field: {
+          type: DataTypes.JSON,
+          allowNull: true,
+          defaultValue: null,
+        },
+      },
+    ],
+  });
+};
+
+export const down: Migration = async ({ context }) => {
+  const schema = await context.describeTable('subscriptions');
+  if (schema.credit_schedule_state) {
+    await context.removeColumn('subscriptions', 'credit_schedule_state');
+  }
+};

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

@@ -8,6 +8,7 @@ import logger from '../../libs/logger';
 import { createIdGenerator } from '../../libs/util';
 import { Invoice } from './invoice';
 import type {
+  CreditScheduleState,
   PaymentDetails,
   PaymentSettings,
   PriceRecurring,
@@ -138,6 +139,9 @@ export class Subscription extends Model<InferAttributes<Subscription>, InferCrea
     payment_details: PaymentDetails;
   };
 
+  // Credit schedule state for each price with schedule-based delivery
+  declare credit_schedule_state?: CreditScheduleState;
+
   public static readonly GENESIS_ATTRIBUTES = {
     id: {
       type: DataTypes.STRING(30),
@@ -326,6 +330,11 @@ export class Subscription extends Model<InferAttributes<Subscription>, InferCrea
             payment_details: null,
           },
         },
+        credit_schedule_state: {
+          type: DataTypes.JSON,
+          allowNull: true,
+          defaultValue: null,
+        },
       },
       {
         sequelize,

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

@@ -836,6 +836,48 @@ export type StructuredSourceDataField = {
 
 export type SourceData = SimpleSourceData | StructuredSourceDataField[];
 
+// Credit Schedule Configuration (embedded in Price.metadata.credit_config)
+export type CreditScheduleConfig = {
+  enabled: boolean;
+  delivery_mode: 'invoice' | 'schedule';
+  interval_value: number;
+  interval_unit: 'hour' | 'day' | 'week' | 'month';
+  amount_per_grant?: string; // Fixed amount per grant; if not set, divide total by period
+  first_grant_timing?: 'immediate' | 'after_trial' | 'after_first_payment';
+  expire_with_next_grant?: boolean; // Whether to expire previous grant when next grant is issued (refresh style)
+  max_grants_per_period?: number; // Protection: max grants per billing period
+};
+
+// Credit Config for Price metadata
+export type CreditConfig = {
+  // Existing fields
+  credit_amount: string;
+  currency_id: string;
+  applicable_prices?: string[];
+  valid_duration_value?: number;
+  valid_duration_unit?: 'hours' | 'days' | 'weeks' | 'months' | 'years';
+  priority?: number;
+
+  // New: schedule configuration
+  schedule?: CreditScheduleConfig;
+};
+
+// Credit Schedule State per Price (stored in Subscription.credit_schedule_state)
+export type CreditSchedulePriceState = {
+  enabled: boolean;
+  schedule_anchor_at: number; // Anchor point for stable seq calculation
+  next_grant_at: number; // Next scheduled grant time (scheduled_at)
+  last_grant_seq: number; // Last executed seq (for observation/stats)
+  grants_in_current_period: number; // Protection counter
+  last_grant_id?: string;
+  last_error?: string;
+};
+
+// Credit Schedule State map (keyed by priceId)
+export type CreditScheduleState = {
+  [priceId: string]: CreditSchedulePriceState;
+};
+
 // Credit Grant on-chain operation status (combined mint, burn and transfer status)
 export type CreditGrantChainStatus =
   | 'mint_pending'