payment-kit 1.23.10 → 1.24.0

package/api/src/queues/notification.ts

@@ -608,13 +608,19 @@ export async function startNotificationQueue() {
   });
 
   events.on('customer.credit_grant.granted', (creditGrant: CreditGrant) => {
-    addNotificationJob(
-      'customer.credit_grant.granted',
-      {
-        creditGrantId: creditGrant.id,
-      },
-      [creditGrant.id]
-    );
+    // Only send notification for non-recurring grants or the first grant of recurring schedule
+    const isScheduleGrant = creditGrant.metadata?.delivery_mode === 'schedule';
+    const isFirstScheduleGrant = isScheduleGrant && creditGrant.metadata?.schedule_seq === 1;
+
+    if (!isScheduleGrant || isFirstScheduleGrant) {
+      addNotificationJob(
+        'customer.credit_grant.granted',
+        {
+          creditGrantId: creditGrant.id,
+        },
+        [creditGrant.id]
+      );
+    }
   });
 
   events.on('customer.credit.low_balance', (customer: Customer, { metadata }: { metadata: any }) => {

package/api/src/queues/subscription.ts

@@ -28,6 +28,7 @@ import {
   shouldCancelSubscription,
   slashOverdraftProtectionStake,
 } from '../libs/subscription';
+import { resetPeriodGrantCounter } from '../libs/credit-schedule';
 import { ensureInvoiceAndItems, migrateSubscriptionPaymentMethodInvoice } from '../libs/invoice';
 import { PaymentCurrency, PaymentIntent, PaymentMethod, Refund, SetupIntent, UsageRecord } from '../store/models';
 import { Customer } from '../store/models/customer';
@@ -368,6 +369,7 @@ const handleSubscriptionWhenActive = async (subscription: Subscription) => {
   // get setup for next subscription period
   const previousPeriodEnd =
     subscription.status === 'trialing' ? subscription.trial_end : subscription.current_period_end;
+  const previousPeriodStart = subscription.current_period_start;
   const setup = getSubscriptionCycleSetup(subscription.pending_invoice_item_interval, previousPeriodEnd as number);
 
   // Check if this is a credit subscription
@@ -424,6 +426,9 @@ const handleSubscriptionWhenActive = async (subscription: Subscription) => {
       current_period_start: nextPeriod.period.start,
       current_period_end: nextPeriod.period.end,
     });
+    if (subscription.credit_schedule_state && previousPeriodStart !== nextPeriod.period.start) {
+      await resetPeriodGrantCounter(subscription);
+    }
 
     if (subscription.isActive()) {
       logger.info(`Credit subscription updated for billing cycle: ${subscription.id}`, {
@@ -485,6 +490,9 @@ const handleSubscriptionWhenActive = async (subscription: Subscription) => {
       current_period_start: setup.period.start,
       current_period_end: setup.period.end,
     });
+    if (subscription.credit_schedule_state && previousPeriodStart !== setup.period.start) {
+      await resetPeriodGrantCounter(subscription);
+    }
     logger.info(`Subscription updated for new billing cycle: ${subscription.id}`);
   }
 
@@ -1273,6 +1281,7 @@ export const handleCreditSubscriptionRecovery = async () => {
       creditSubscriptions.map(async (subscription) => {
         // Check if subscription period has ended
         if (subscription.current_period_end && now > subscription.current_period_end) {
+          const previousPeriodStart = subscription.current_period_start;
           const previousPeriodEnd =
             subscription.status === 'trialing' ? subscription.trial_end : subscription.current_period_end;
 
@@ -1296,6 +1305,9 @@ export const handleCreditSubscriptionRecovery = async () => {
               current_period_start: setup.period.start,
               current_period_end: setup.period.end,
             });
+            if (subscription.credit_schedule_state && previousPeriodStart !== setup.period.start) {
+              await resetPeriodGrantCounter(subscription);
+            }
 
             // Schedule next billing cycle
             await addSubscriptionJob(subscription, 'cycle', true, setup.period.end);

package/api/src/routes/credit-grants.ts

@@ -11,6 +11,7 @@ import {
   AutoRechargeConfig,
   CreditGrant,
   Customer,
+  Invoice,
   MeterEvent,
   PaymentCurrency,
   PaymentMethod,
@@ -60,12 +61,14 @@ const creditGrantSchema = Joi.object({
 
 const listSchema = createListParamSchema<{
   customer_id?: string;
+  subscription_id?: string;
   currency_id?: string;
   status?: string;
   livemode?: boolean;
   q?: string;
 }>({
   customer_id: Joi.string().optional(),
+  subscription_id: Joi.string().optional(),
   currency_id: Joi.string().optional(),
   status: Joi.string().optional(),
   livemode: Joi.boolean().optional(),
@@ -95,6 +98,21 @@ router.get('/', authMine, async (req, res) => {
       }
       where.customer_id = customer.id;
     }
+    if (query.subscription_id) {
+      const invoices = await Invoice.findAll({
+        where: {
+          subscription_id: query.subscription_id,
+          ...(where.customer_id ? { customer_id: where.customer_id } : {}),
+        },
+        attributes: ['id'],
+      });
+      const invoiceIds = invoices.map((invoice) => invoice.id);
+      const subscriptionFilters = [{ 'metadata.subscription_id': query.subscription_id }];
+      if (invoiceIds.length > 0) {
+        subscriptionFilters.push({ 'metadata.invoice_id': { [Op.in]: invoiceIds } } as any);
+      }
+      where[Op.and] = [...(where[Op.and] || []), { [Op.or]: subscriptionFilters }];
+    }
     if (query.currency_id) {
       where.currency_id = query.currency_id;
     }

package/api/src/routes/credit-transactions.ts

@@ -133,7 +133,7 @@ router.get('/', authMine, async (req, res) => {
       // Grant where conditions
       const grantWhere: any = {
         customer_id: query.customer_id,
-        status: ['granted', 'depleted'],
+        status: ['granted', 'depleted', 'expired'],
       };
       if (query.start) {
         grantWhere.created_at = {

package/api/src/routes/meter-events.ts

@@ -327,7 +327,6 @@ router.post('/', auth, async (req, res) => {
 router.get('/pending-amount', authMine, async (req, res) => {
   try {
     const params: any = {
-      status: ['requires_action', 'requires_capture'],
       livemode: !!req.livemode,
     };
     if (req.query.subscription_id) {

package/api/src/routes/prices.ts

@@ -18,14 +18,53 @@ const router = Router();
 
 const auth = authenticate<Price>({ component: true, roles: ['owner', 'admin'] });
 
+// 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 getExpandedPrice(id: string) {
   const price = await Price.findByPkOrLookupKey(id, {
@@ -361,7 +400,8 @@ router.put('/:id', auth, async (req, res) => {
   }
 
   if (product.type === 'credit' && updates.metadata) {
-    const creditConfig = updates.metadata.credit_config;
+    // Merge with existing credit_config if not provided
+    const creditConfig = updates.metadata.credit_config || doc.metadata?.credit_config;
     if (!creditConfig) {
       return res.status(400).json({ error: 'credit_config is required' });
     }

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/meter-event.ts

@@ -427,7 +427,7 @@ export class MeterEvent extends Model<InferAttributes<MeterEvent>, InferCreation
     subscriptionId,
     livemode,
     currencyId,
-    status = ['requires_action', 'requires_capture'],
+    status,
     customerId,
   }: {
     subscriptionId?: string;

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'