feat: build subscription pause and resume with billing adjustment (#961)

Author: senmalong

contracts/subscription/src/lib.rs

@@ -283,6 +283,7 @@ fn check_and_resume_internal(env: &Env, sub: &mut Subscription) -> bool {
         let now = env.ledger().timestamp();
         if now >= sub.paused_at + sub.pause_duration {
             sub.status = SubscriptionStatus::Active;
+            sub.next_charge_at = sub.next_charge_at.saturating_add(sub.pause_duration);
             sub.paused_at = 0;
             sub.pause_duration = 0;
             return true;
@@ -935,11 +936,17 @@ impl SubTrackrSubscription {
         );
 
         let now = env.ledger().timestamp();
-        let plan: Plan = storage_persistent_get(&env, &storage, StorageKey::Plan(sub.plan_id))
-            .expect("Plan not found");
+
+        let elapsed_pause = if sub.paused_at > 0 && now > sub.paused_at {
+            (now - sub.paused_at).min(sub.pause_duration)
+        } else {
+            0
+        };
 
         sub.status = SubscriptionStatus::Active;
-        sub.next_charge_at = now + plan.interval.seconds();
+        if elapsed_pause > 0 {
+            sub.next_charge_at = sub.next_charge_at.saturating_add(elapsed_pause);
+        }
         sub.paused_at = 0;
         sub.pause_duration = 0;
 
@@ -1654,6 +1661,39 @@ pub fn preview_proration(
     proration::preview_proration(&env, &sub, old_plan.price, new_plan.price, effective)
 }
 
+/// Preview pause adjustment before resuming or pausing a subscription
+pub fn preview_pause_adjustment(
+    env: Env,
+    proxy: Address,
+    storage: Address,
+    subscription_id: u64,
+    resume_timestamp: u64,
+) -> ProrationResult {
+    proxy.require_auth();
+
+    let sub: Subscription =
+        storage_persistent_get(&env, &storage, StorageKey::Subscription(subscription_id))
+            .expect("Subscription not found");
+
+    let plan: Plan = storage_persistent_get(&env, &storage, StorageKey::Plan(sub.plan_id))
+        .expect("Plan not found");
+
+    let adjustment = proration::calculate_pause_adjustment(&env, &sub, plan.price, resume_timestamp);
+
+    let period_days = (plan.interval.seconds() / 86400).max(1);
+    let old_daily_rate = plan.price / period_days as i128;
+
+    ProrationResult {
+        amount: adjustment.prorated_credit,
+        remaining_days: (adjustment.adjusted_next_charge_at.saturating_sub(resume_timestamp)) / 86400,
+        period_days,
+        old_daily_rate,
+        new_daily_rate: old_daily_rate,
+        is_credit: adjustment.prorated_credit > 0,
+        description: adjustment.description,
+    }
+}
+
 /// Execute a plan change with proration
 pub fn change_plan(
     env: Env,

contracts/subscription/src/proration.rs

@@ -220,4 +220,63 @@ pub fn is_zero_proration(result: &ProrationResult) -> bool {
 pub fn round_proration_amount(amount: i128, decimals: u32) -> i128 {
     let factor = 10i128.pow(decimals);
     (amount + factor / 2) / factor * factor
+}
+
+/// Result of a pause/resume billing adjustment calculation
+#[derive(Clone, Debug)]
+pub struct PauseAdjustmentResult {
+    /// The adjusted timestamp when the next charge will occur
+    pub adjusted_next_charge_at: u64,
+    /// Total duration in seconds the subscription was paused
+    pub elapsed_pause_seconds: u64,
+    /// Prorated credit amount credited for the paused time (if applicable)
+    pub prorated_credit: i128,
+    /// Description of the adjustment
+    pub description: String,
+}
+
+/// Calculate billing adjustment for pause and resume
+///
+/// Returns `PauseAdjustmentResult` containing the shifted `next_charge_at`
+/// and prorated credit details.
+pub fn calculate_pause_adjustment(
+    env: &Env,
+    subscription: &Subscription,
+    plan_price: i128,
+    resume_timestamp: u64,
+) -> PauseAdjustmentResult {
+    let paused_at = subscription.paused_at;
+    let max_duration = subscription.pause_duration;
+
+    // Effective pause time cannot exceed max pause duration or start before paused_at
+    let raw_elapsed = if resume_timestamp > paused_at && paused_at > 0 {
+        resume_timestamp - paused_at
+    } else {
+        0
+    };
+
+    let elapsed_pause_seconds = if max_duration > 0 {
+        raw_elapsed.min(max_duration)
+    } else {
+        raw_elapsed
+    };
+
+    let adjusted_next_charge_at = subscription.next_charge_at.saturating_add(elapsed_pause_seconds);
+
+    // Prorated credit value of paused time based on subscription period duration
+    let period_seconds = subscription.next_charge_at.saturating_sub(subscription.last_charged_at);
+    let prorated_credit = if period_seconds > 0 && plan_price > 0 {
+        (plan_price * elapsed_pause_seconds as i128) / period_seconds as i128
+    } else {
+        0
+    };
+
+    let description = String::from_str(env, "Billing cycle adjusted for subscription pause duration");
+
+    PauseAdjustmentResult {
+        adjusted_next_charge_at,
+        elapsed_pause_seconds,
+        prorated_credit,
+        description,
+    }
 }

docs/SUBSCRIPTION_PAUSE_RESUME.md

@@ -0,0 +1,65 @@
+# Subscription Pause/Resume with Billing Adjustment
+
+This document details the architecture, formulas, and integration patterns for subscription pause and resume functionality with billing adjustment in SubTrackr.
+
+## Overview
+
+SubTrackr allows subscribers to pause an active subscription for up to 30 days (`MAX_PAUSE_DURATION = 2,592,000` seconds). During the pause period:
+- Automatic recurring billing is suspended.
+- Unused prepaid service time is preserved.
+- When the subscription is resumed (manually or via auto-resume expiration), the billing schedule (`next_charge_at` / `nextBillingDate`) is shifted forward by the actual elapsed pause duration.
+
+---
+
+## Technical Architecture
+
+### 1. Smart Contract Implementation (`contracts/subscription/src/`)
+
+- **State Fields**:
+  - `status: SubscriptionStatus` (`Active`, `Paused`, `Cancelled`, `PastDue`)
+  - `paused_at: u64` (ledger timestamp when pause was requested)
+  - `pause_duration: u64` (requested pause duration in seconds)
+  - `next_charge_at: u64` (timestamp for next charge)
+
+- **Billing Adjustment Formula**:
+  $$\text{elapsed\_pause} = \min(\text{resume\_timestamp} - \text{paused\_at}, \text{pause\_duration})$$
+  $$\text{adjusted\_next\_charge\_at} = \text{next\_charge\_at} + \text{elapsed\_pause}$$
+
+- **Contract Methods**:
+  - `pause_subscription(env, proxy, storage, subscriber, subscription_id)`: Pauses subscription for default max duration (30 days).
+  - `pause_by_subscriber(env, proxy, storage, subscriber, subscription_id, duration)`: Pauses subscription for custom duration $\le 30$ days.
+  - `resume_subscription(env, proxy, storage, subscriber, subscription_id)`: Resumes subscription and adjusts `next_charge_at` by actual elapsed pause duration.
+  - `preview_pause_adjustment(env, proxy, storage, subscription_id, resume_timestamp)`: Previews billing adjustments, credit amount, and shifted next charge date.
+
+### 2. Frontend State Management (`src/store/subscriptionStore.ts`)
+
+- **Store Actions**:
+  - `pauseSubscription(id, durationDays)`: Sets `isPaused: true`, `isActive: false`, records `pausedAt`, `pauseDurationDays`, and `pausedUntil`.
+  - `resumeSubscription(id)`: Calculates elapsed pause duration, shifts `nextBillingDate` forward by `pauseMs`, and reactivates subscription.
+  - `previewPauseAdjustment(id, resumeDate)`: Returns `{ adjustedNextBillingDate, elapsedPauseDays, creditAmount }` preview.
+
+---
+
+## Events & Auditing
+
+When a subscription is paused or resumed, contracts publish on-chain events:
+- `("subscription_paused", subscriber)`: Payload `(subscription_id, paused_at, duration)`
+- `("subscription_resumed", subscriber)`: Payload `subscription_id`
+
+---
+
+## API & Store Usage Examples
+
+```typescript
+import { useSubscriptionStore } from '../store/subscriptionStore';
+
+// Pause a subscription for 14 days
+await useSubscriptionStore.getState().pauseSubscription('sub_123', 14);
+
+// Preview billing adjustment before resuming
+const preview = useSubscriptionStore.getState().previewPauseAdjustment('sub_123');
+console.log(`Adjusted next billing date: ${preview.adjustedNextBillingDate}`);
+
+// Resume subscription
+await useSubscriptionStore.getState().resumeSubscription('sub_123');
+```

src/store/subscriptionStore.ts

@@ -168,6 +168,9 @@ interface SubscriptionState {
   updateSubscription: (id: string, data: Partial<Subscription>) => Promise<void>;
   deleteSubscription: (id: string) => Promise<void>;
   toggleSubscriptionStatus: (id: string) => Promise<void>;
+  pauseSubscription: (id: string, durationDays?: number) => Promise<void>;
+  resumeSubscription: (id: string) => Promise<void>;
+  previewPauseAdjustment: (id: string, resumeDate?: Date) => { adjustedNextBillingDate: Date; elapsedPauseDays: number; creditAmount: number };
   // new actions added
   previewPlanChange: (id: string, newPrice: number, effectiveDate: 'immediate' | 'end_of_period') => ProrationPreview;
   executePlanChange: (id: string, newPlanData: Partial<Subscription>, effectiveDate: 'immediate' | 'end_of_period') => Promise<void>;
@@ -395,6 +398,119 @@ export const useSubscriptionStore = create<SubscriptionState>()(
         }
       },
 
+      pauseSubscription: async (id: string, durationDays: number = 30) => {
+        set({ isLoading: true, error: null });
+        try {
+          const now = new Date();
+          const pausedUntil = new Date(now.getTime() + durationDays * 86400 * 1000);
+          set((state) => ({
+            subscriptions: state.subscriptions.map((sub) =>
+              sub.id === id
+                ? {
+                    ...sub,
+                    isActive: false,
+                    isPaused: true,
+                    pausedAt: now,
+                    pauseDurationDays: durationDays,
+                    pausedUntil,
+                    updatedAt: now,
+                  }
+                : sub
+            ),
+            isLoading: false,
+          }));
+
+          get().calculateStats();
+          await syncRenewalReminders(get().subscriptions);
+          const updatedSubscription = get().subscriptions.find((sub) => sub.id === id);
+          if (updatedSubscription) {
+            await useCalendarStore.getState().syncSubscriptionToCalendars(updatedSubscription);
+          }
+        } catch (error) {
+          const appError = errorHandler.handleError(error as Error, {
+            action: 'pauseSubscription',
+            subscriptionId: id,
+          });
+          set({ error: appError, isLoading: false });
+        }
+      },
+
+      resumeSubscription: async (id: string) => {
+        set({ isLoading: true, error: null });
+        try {
+          const sub = get().subscriptions.find((s) => s.id === id);
+          if (!sub) throw new Error('Subscription not found');
+
+          const now = new Date();
+          let pauseMs = 0;
+          if (sub.pausedAt) {
+            const pausedAtTime = new Date(sub.pausedAt).getTime();
+            const elapsed = now.getTime() - pausedAtTime;
+            const maxPauseMs = (sub.pauseDurationDays || 30) * 86400 * 1000;
+            pauseMs = Math.max(0, Math.min(elapsed, maxPauseMs));
+          }
+
+          const oldNextBilling = new Date(sub.nextBillingDate).getTime();
+          const adjustedNextBillingDate = new Date(oldNextBilling + pauseMs);
+
+          set((state) => ({
+            subscriptions: state.subscriptions.map((s) =>
+              s.id === id
+                ? {
+                    ...s,
+                    isActive: true,
+                    isPaused: false,
+                    pausedAt: undefined,
+                    pauseDurationDays: undefined,
+                    pausedUntil: undefined,
+                    nextBillingDate: adjustedNextBillingDate,
+                    updatedAt: now,
+                  }
+                : s
+            ),
+            isLoading: false,
+          }));
+
+          get().calculateStats();
+          await syncRenewalReminders(get().subscriptions);
+          const updatedSubscription = get().subscriptions.find((s) => s.id === id);
+          if (updatedSubscription) {
+            await useCalendarStore.getState().syncSubscriptionToCalendars(updatedSubscription);
+          }
+        } catch (error) {
+          const appError = errorHandler.handleError(error as Error, {
+            action: 'resumeSubscription',
+            subscriptionId: id,
+          });
+          set({ error: appError, isLoading: false });
+        }
+      },
+
+      previewPauseAdjustment: (id: string, resumeDate?: Date) => {
+        const sub = get().subscriptions.find((s) => s.id === id);
+        if (!sub) throw new Error('Subscription not found');
+
+        const now = resumeDate || new Date();
+        let pauseMs = 0;
+        if (sub.pausedAt) {
+          const pausedAtTime = new Date(sub.pausedAt).getTime();
+          const elapsed = now.getTime() - pausedAtTime;
+          const maxPauseMs = (sub.pauseDurationDays || 30) * 86400 * 1000;
+          pauseMs = Math.max(0, Math.min(elapsed, maxPauseMs));
+        }
+
+        const elapsedPauseDays = Math.round(pauseMs / (86400 * 1000));
+        const adjustedNextBillingDate = new Date(new Date(sub.nextBillingDate).getTime() + pauseMs);
+        const dailyRate = sub.price / 30;
+        const creditAmount = Math.round(dailyRate * elapsedPauseDays * 100) / 100;
+
+        return {
+          adjustedNextBillingDate,
+          elapsedPauseDays,
+          creditAmount,
+        };
+      },
+
       recordBillingOutcome: async (id: string, outcome: 'success' | 'failed') => {
         const sub = get().subscriptions.find((s) => s.id === id);
         if (!sub) return;

src/types/subscription.ts

@@ -8,6 +8,11 @@ export interface Subscription {
   billingCycle: BillingCycle;
   nextBillingDate: Date;
   isActive: boolean;
+  isPaused?: boolean;
+  pausedAt?: Date;
+  pauseDurationDays?: number;
+  pausedUntil?: Date;
+  billingAdjustmentAmount?: number;
   /** When false, skip renewal reminders and charge alerts for this subscription */
   notificationsEnabled?: boolean;
   isCryptoEnabled: boolean;