@carlonicora/nextjs-jsonapi 1.15.0 → 1.16.0

package/src/features/billing/stripe-subscription/components/widgets/ProrationPreview.tsx

@@ -0,0 +1,41 @@
+"use client";
+
+import { ProrationPreviewInterface } from "../../../stripe-invoice/data/stripe-invoice.interface";
+import { formatCurrency, formatDate } from "../../../components/utils";
+
+type ProrationPreviewProps = {
+  preview: ProrationPreviewInterface;
+};
+
+export function ProrationPreview({ preview }: ProrationPreviewProps) {
+  return (
+    <div className="bg-blue-50 border border-blue-200 rounded-lg p-4">
+      <h4 className="font-semibold text-blue-900 mb-3">Proration Breakdown</h4>
+
+      <div className="space-y-2">
+        {preview.lineItems.map((item, index) => (
+          <div key={index} className="flex justify-between text-sm">
+            <span className="text-blue-800">{item.description}</span>
+            <span className={`font-medium ${item.amount < 0 ? "text-green-600" : "text-blue-900"}`}>
+              {formatCurrency(item.amount, preview.currency)}
+            </span>
+          </div>
+        ))}
+
+        <div className="border-t border-blue-200 pt-2 mt-2">
+          <div className="flex justify-between font-semibold">
+            <span className="text-blue-900">Net Due Today</span>
+            <span className="text-blue-900">{formatCurrency(preview.immediateCharge, preview.currency)}</span>
+          </div>
+        </div>
+
+        {preview.lineItems.length > 0 && preview.lineItems[0].period && (
+          <div className="text-xs text-blue-700 mt-2">
+            Next invoice on {formatDate(preview.lineItems[0].period.end)} for{" "}
+            {formatCurrency(preview.amountDue, preview.currency)}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/features/billing/stripe-subscription/components/widgets/SubscriptionStatusBadge.tsx

@@ -0,0 +1,60 @@
+"use client";
+
+import { SubscriptionStatus } from "../../data";
+
+type SubscriptionStatusBadgeProps = {
+  status: SubscriptionStatus;
+  cancelAtPeriodEnd?: boolean;
+};
+
+type StatusConfig = {
+  label: string;
+  color: string;
+};
+
+const statusConfig: Record<SubscriptionStatus, StatusConfig> = {
+  [SubscriptionStatus.ACTIVE]: {
+    label: "Active",
+    color: "bg-green-100 text-green-800",
+  },
+  [SubscriptionStatus.TRIALING]: {
+    label: "Trial",
+    color: "bg-blue-100 text-blue-800",
+  },
+  [SubscriptionStatus.PAST_DUE]: {
+    label: "Past Due",
+    color: "bg-red-100 text-red-800",
+  },
+  [SubscriptionStatus.CANCELED]: {
+    label: "Canceled",
+    color: "bg-gray-100 text-gray-800",
+  },
+  [SubscriptionStatus.PAUSED]: {
+    label: "Paused",
+    color: "bg-yellow-100 text-yellow-800",
+  },
+  [SubscriptionStatus.UNPAID]: {
+    label: "Unpaid",
+    color: "bg-orange-100 text-orange-800",
+  },
+  [SubscriptionStatus.INCOMPLETE]: {
+    label: "Incomplete",
+    color: "bg-gray-100 text-gray-800",
+  },
+  [SubscriptionStatus.INCOMPLETE_EXPIRED]: {
+    label: "Expired",
+    color: "bg-gray-100 text-gray-800",
+  },
+};
+
+const cancelingConfig: StatusConfig = {
+  label: "Canceling",
+  color: "bg-amber-100 text-amber-800",
+};
+
+export function SubscriptionStatusBadge({ status, cancelAtPeriodEnd }: SubscriptionStatusBadgeProps) {
+  // Show "Canceling" when subscription is set to cancel at period end
+  const config = cancelAtPeriodEnd ? cancelingConfig : statusConfig[status] || statusConfig[SubscriptionStatus.CANCELED];
+
+  return <span className={`${config.color} text-xs px-2 py-1 rounded-full font-medium`}>{config.label}</span>;
+}

package/src/features/billing/stripe-subscription/components/widgets/index.ts

@@ -0,0 +1,4 @@
+export * from "./PricingCard";
+export * from "./PricingCardsGrid";
+export * from "./ProrationPreview";
+export * from "./SubscriptionStatusBadge";

package/src/features/billing/stripe-subscription/data/index.ts

@@ -0,0 +1,3 @@
+export * from "./stripe-subscription";
+export * from "./stripe-subscription.interface";
+export * from "./stripe-subscription.service";

package/src/features/billing/stripe-subscription/data/stripe-subscription.interface.ts

@@ -0,0 +1,66 @@
+// ============================================================================
+// Subscription Enums
+// ============================================================================
+
+import { ApiDataInterface, StripePriceInterface } from "../../../../core";
+
+export enum SubscriptionStatus {
+  ACTIVE = "active",
+  PAST_DUE = "past_due",
+  UNPAID = "unpaid",
+  CANCELED = "canceled",
+  INCOMPLETE = "incomplete",
+  INCOMPLETE_EXPIRED = "incomplete_expired",
+  TRIALING = "trialing",
+  PAUSED = "paused",
+}
+
+// ============================================================================
+// Subscription Interfaces
+// ============================================================================
+
+export interface StripeSubscriptionInterface extends ApiDataInterface {
+  get stripeSubscriptionId(): string;
+  get status(): SubscriptionStatus;
+  get currentPeriodStart(): Date;
+  get currentPeriodEnd(): Date;
+  get cancelAtPeriodEnd(): boolean;
+  get canceledAt(): Date | undefined;
+  get trialStart(): Date | undefined;
+  get trialEnd(): Date | undefined;
+  get price(): StripePriceInterface | undefined;
+}
+
+// ============================================================================
+// Subscription Input DTOs
+// ============================================================================
+
+export type StripeSubscriptionInput = {
+  id: string;
+  // For CREATE - goes to relationships.stripePrice
+  priceId?: string;
+  // For CHANGE-PLAN - goes to attributes.priceId
+  newPriceId?: string;
+  // For CANCEL - goes to attributes.cancelImmediately
+  cancelImmediately?: boolean;
+  // Shared optional fields
+  quantity?: number;
+  trialPeriodDays?: number;
+  paymentMethodId?: string;
+  metadata?: Record<string, any>;
+};
+
+// ============================================================================
+// Subscription Response Types (for SCA payment confirmation)
+// ============================================================================
+
+export interface StripeSubscriptionCreateMeta {
+  clientSecret: string | null;
+  paymentIntentId: string | null;
+  requiresAction: boolean;
+}
+
+export interface StripeSubscriptionCreateResponse {
+  subscription: StripeSubscriptionInterface;
+  meta: StripeSubscriptionCreateMeta;
+}

package/src/features/billing/stripe-subscription/data/stripe-subscription.service.ts

@@ -0,0 +1,193 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules, NextRef, PreviousRef } from "../../../../core";
+import { ProrationPreviewInterface } from "../../stripe-invoice/data/stripe-invoice.interface";
+import {
+  StripeSubscriptionCreateMeta,
+  StripeSubscriptionCreateResponse,
+  StripeSubscriptionInput,
+  StripeSubscriptionInterface,
+} from "./stripe-subscription.interface";
+
+/**
+ * Customer-facing billing service for managing subscriptions, payments, and usage
+ */
+export class StripeSubscriptionService extends AbstractService {
+  // ============================================================================
+  // Subscription Methods
+  // ============================================================================
+
+  /**
+   * List all subscriptions for the current user
+   */
+  static async listSubscriptions(params?: {
+    next?: NextRef;
+    prev?: PreviousRef;
+  }): Promise<StripeSubscriptionInterface[]> {
+    const endpoint = new EndpointCreator({
+      endpoint: Modules.StripeSubscription,
+    });
+
+    return this.callApi({
+      type: Modules.StripeSubscription,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+      next: params?.next,
+      previous: params?.prev,
+    });
+  }
+
+  /**
+   * Get a specific subscription by ID
+   */
+  static async getSubscription(params: { subscriptionId: string }): Promise<StripeSubscriptionInterface> {
+    const endpoint = new EndpointCreator({
+      endpoint: Modules.StripeSubscription,
+      id: params.subscriptionId,
+    });
+
+    return this.callApi<StripeSubscriptionInterface>({
+      type: Modules.StripeSubscription,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+    });
+  }
+
+  /**
+   * Create a new subscription
+   * Returns subscription data along with meta containing SCA payment confirmation details
+   */
+  static async createSubscription(params: StripeSubscriptionInput): Promise<StripeSubscriptionCreateResponse> {
+    const endpoint = new EndpointCreator({
+      endpoint: Modules.StripeSubscription,
+    });
+
+    const result = await this.callApiWithMeta<StripeSubscriptionInterface>({
+      type: Modules.StripeSubscription,
+      method: HttpMethod.POST,
+      endpoint: endpoint.generate(),
+      input: params,
+    });
+
+    return {
+      subscription: result.data,
+      meta: (result.meta as StripeSubscriptionCreateMeta) ?? {
+        clientSecret: null,
+        paymentIntentId: null,
+        requiresAction: false,
+      },
+    };
+  }
+
+  /**
+   * Change the plan of an existing subscription
+   */
+  static async changePlan(params: StripeSubscriptionInput): Promise<StripeSubscriptionInterface> {
+    const endpoint = new EndpointCreator({
+      endpoint: Modules.StripeSubscription,
+      id: params.id,
+      childEndpoint: "change-plan",
+    });
+
+    return this.callApi<StripeSubscriptionInterface>({
+      type: Modules.StripeSubscription,
+      method: HttpMethod.PUT,
+      endpoint: endpoint.generate(),
+      input: params,
+    });
+  }
+
+  /**
+   * Get a proration preview for a plan change
+   */
+  static async getProrationPreview(params: {
+    subscriptionId: string;
+    newPriceId: string;
+    quantity?: number;
+  }): Promise<ProrationPreviewInterface> {
+    const endpoint = new EndpointCreator({
+      endpoint: Modules.StripeSubscription,
+      id: params.subscriptionId,
+      childEndpoint: "proration-preview",
+    });
+
+    endpoint.addAdditionalParam("newPriceId", params.newPriceId);
+    if (params.quantity) {
+      endpoint.addAdditionalParam("quantity", params.quantity.toString());
+    }
+
+    return this.callApi({
+      type: Modules.StripeSubscription,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+    });
+  }
+
+  /**
+   * Cancel a subscription
+   */
+  static async cancelSubscription(params: StripeSubscriptionInput): Promise<StripeSubscriptionInterface> {
+    const endpoint = new EndpointCreator({
+      endpoint: Modules.StripeSubscription,
+      id: params.id,
+      childEndpoint: "cancel",
+    });
+
+    return this.callApi<StripeSubscriptionInterface>({
+      type: Modules.StripeSubscription,
+      method: HttpMethod.POST,
+      endpoint: endpoint.generate(),
+      input: params,
+    });
+  }
+
+  /**
+   * Pause a subscription
+   */
+  static async pauseSubscription(params: { subscriptionId: string }): Promise<StripeSubscriptionInterface> {
+    const endpoint = new EndpointCreator({
+      endpoint: Modules.StripeSubscription,
+      id: params.subscriptionId,
+      childEndpoint: "pause",
+    });
+
+    return this.callApi<StripeSubscriptionInterface>({
+      type: Modules.StripeSubscription,
+      method: HttpMethod.POST,
+      endpoint: endpoint.generate(),
+    });
+  }
+
+  /**
+   * Resume a paused subscription
+   */
+  static async resumeSubscription(params: { subscriptionId: string }): Promise<StripeSubscriptionInterface> {
+    const endpoint = new EndpointCreator({
+      endpoint: Modules.StripeSubscription,
+      id: params.subscriptionId,
+      childEndpoint: "resume",
+    });
+
+    return this.callApi<StripeSubscriptionInterface>({
+      type: Modules.StripeSubscription,
+      method: HttpMethod.POST,
+      endpoint: endpoint.generate(),
+    });
+  }
+
+  /**
+   * Sync a subscription with the latest data from Stripe
+   * This is useful after payment confirmation to get the updated status
+   */
+  static async syncSubscription(params: { subscriptionId: string }): Promise<StripeSubscriptionInterface> {
+    const endpoint = new EndpointCreator({
+      endpoint: Modules.StripeSubscription,
+      id: params.subscriptionId,
+      childEndpoint: "sync",
+    });
+
+    return this.callApi<StripeSubscriptionInterface>({
+      type: Modules.StripeSubscription,
+      method: HttpMethod.POST,
+      endpoint: endpoint.generate(),
+    });
+  }
+}

package/src/features/billing/stripe-subscription/data/stripe-subscription.ts

@@ -0,0 +1,135 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../../core";
+import { StripePriceInterface } from "../../stripe-price";
+import {
+  StripeSubscriptionInput,
+  StripeSubscriptionInterface,
+  SubscriptionStatus,
+} from "./stripe-subscription.interface";
+
+export class StripeSubscription extends AbstractApiData implements StripeSubscriptionInterface {
+  private _stripeSubscriptionId?: string;
+  private _status?: SubscriptionStatus;
+  private _currentPeriodStart?: Date;
+  private _currentPeriodEnd?: Date;
+  private _cancelAtPeriodEnd: boolean = false;
+  private _canceledAt?: Date;
+  private _trialStart?: Date;
+  private _trialEnd?: Date;
+  private _price?: StripePriceInterface;
+
+  get stripeSubscriptionId(): string {
+    if (!this._stripeSubscriptionId) throw new Error("stripeSubscriptionId is not defined");
+    return this._stripeSubscriptionId;
+  }
+
+  get status(): SubscriptionStatus {
+    if (!this._status) throw new Error("status is not defined");
+    return this._status;
+  }
+
+  get currentPeriodStart(): Date {
+    if (!this._currentPeriodStart) throw new Error("currentPeriodStart is not defined");
+    return this._currentPeriodStart;
+  }
+
+  get currentPeriodEnd(): Date {
+    if (!this._currentPeriodEnd) throw new Error("currentPeriodEnd is not defined");
+    return this._currentPeriodEnd;
+  }
+
+  get cancelAtPeriodEnd(): boolean {
+    return this._cancelAtPeriodEnd;
+  }
+
+  get canceledAt(): Date | undefined {
+    return this._canceledAt;
+  }
+
+  get trialStart(): Date | undefined {
+    return this._trialStart;
+  }
+
+  get trialEnd(): Date | undefined {
+    return this._trialEnd;
+  }
+
+  get price(): StripePriceInterface | undefined {
+    return this._price;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    this._stripeSubscriptionId = data.jsonApi.attributes.stripeSubscriptionId;
+    this._status = data.jsonApi.attributes.status;
+
+    this._currentPeriodStart = data.jsonApi.attributes.currentPeriodStart
+      ? new Date(data.jsonApi.attributes.currentPeriodStart)
+      : undefined;
+    this._currentPeriodEnd = data.jsonApi.attributes.currentPeriodEnd
+      ? new Date(data.jsonApi.attributes.currentPeriodEnd)
+      : undefined;
+
+    this._cancelAtPeriodEnd = data.jsonApi.attributes.cancelAtPeriodEnd ?? false;
+    this._canceledAt = data.jsonApi.attributes.canceledAt ? new Date(data.jsonApi.attributes.canceledAt) : undefined;
+
+    this._trialStart = data.jsonApi.attributes.trialStart ? new Date(data.jsonApi.attributes.trialStart) : undefined;
+    this._trialEnd = data.jsonApi.attributes.trialEnd ? new Date(data.jsonApi.attributes.trialEnd) : undefined;
+
+    // Hydrate price relationship
+    this._price = this._readIncluded(data, "price", Modules.StripePrice) as StripePriceInterface;
+
+    return this;
+  }
+
+  createJsonApi(data: StripeSubscriptionInput): any {
+    const response: any = {
+      data: {
+        type: Modules.StripeSubscription.name,
+        id: data.id,
+        attributes: {},
+      },
+    };
+
+    // CREATE: priceId goes to relationships
+    if (data.priceId) {
+      response.data.relationships = {
+        stripePrice: {
+          data: {
+            type: Modules.StripePrice.name,
+            id: data.priceId,
+          },
+        },
+      };
+    }
+
+    // CHANGE-PLAN: newPriceId goes to attributes.priceId
+    if (data.newPriceId) {
+      response.data.attributes.priceId = data.newPriceId;
+    }
+
+    // CANCEL: cancelImmediately goes to attributes
+    if (data.cancelImmediately !== undefined) {
+      response.data.attributes.cancelImmediately = data.cancelImmediately;
+    }
+
+    // Shared optional fields
+    if (data.quantity !== undefined) {
+      response.data.attributes.quantity = data.quantity;
+    }
+
+    if (data.trialPeriodDays !== undefined) {
+      response.data.attributes.trialPeriodDays = data.trialPeriodDays;
+    }
+
+    if (data.paymentMethodId) {
+      response.data.attributes.paymentMethodId = data.paymentMethodId;
+    }
+
+    if (data.metadata) {
+      response.data.attributes.metadata = data.metadata;
+    }
+
+    return response;
+  }
+}

package/src/features/billing/stripe-subscription/hooks/index.ts

@@ -0,0 +1 @@
+export * from "./useConfirmSubscriptionPayment";

package/src/features/billing/stripe-subscription/hooks/useConfirmSubscriptionPayment.ts

@@ -0,0 +1,111 @@
+"use client";
+
+import { useStripe } from "@stripe/react-stripe-js";
+import { useCallback, useState } from "react";
+
+export interface ConfirmPaymentResult {
+  success: boolean;
+  error?: string;
+}
+
+export interface UseConfirmSubscriptionPaymentReturn {
+  confirmPayment: (clientSecret: string) => Promise<ConfirmPaymentResult>;
+  isConfirming: boolean;
+}
+
+/**
+ * Hook for confirming subscription payments using Stripe's SCA-compliant flow.
+ *
+ * This hook wraps stripe.confirmCardPayment() and handles:
+ * - Loading state during confirmation
+ * - Error handling for Stripe errors
+ * - 3D Secure authentication popups (handled automatically by Stripe)
+ *
+ * @example
+ * ```tsx
+ * const { confirmPayment, isConfirming } = useConfirmSubscriptionPayment();
+ *
+ * const handleCreateSubscription = async () => {
+ *   const result = await StripeSubscriptionService.createSubscription({ priceId });
+ *
+ *   if (result.meta.requiresAction && result.meta.clientSecret) {
+ *     const confirmation = await confirmPayment(result.meta.clientSecret);
+ *     if (!confirmation.success) {
+ *       setError(confirmation.error);
+ *       return;
+ *     }
+ *   }
+ *
+ *   // Subscription is now active
+ * };
+ * ```
+ */
+export function useConfirmSubscriptionPayment(): UseConfirmSubscriptionPaymentReturn {
+  const stripe = useStripe();
+  const [isConfirming, setIsConfirming] = useState(false);
+
+  const confirmPayment = useCallback(
+    async (clientSecret: string): Promise<ConfirmPaymentResult> => {
+      if (!stripe) {
+        console.error("[useConfirmSubscriptionPayment] Stripe not initialized");
+        return {
+          success: false,
+          error: "Payment system not initialized. Please refresh the page and try again.",
+        };
+      }
+
+      if (!clientSecret) {
+        console.error("[useConfirmSubscriptionPayment] No client secret provided");
+        return {
+          success: false,
+          error: "Payment confirmation failed. Missing payment details.",
+        };
+      }
+
+      setIsConfirming(true);
+
+      try {
+        const { error: stripeError, paymentIntent } = await stripe.confirmCardPayment(clientSecret);
+
+        if (stripeError) {
+          console.error("[useConfirmSubscriptionPayment] Stripe error:", stripeError);
+          return {
+            success: false,
+            error: stripeError.message || "Payment confirmation failed. Please try again.",
+          };
+        }
+
+        if (paymentIntent?.status === "succeeded") {
+          return { success: true };
+        }
+
+        if (paymentIntent?.status === "requires_action") {
+          // This shouldn't happen as Stripe handles 3DS inline, but handle it just in case
+          return {
+            success: false,
+            error: "Additional authentication required. Please complete the verification.",
+          };
+        }
+
+        return {
+          success: false,
+          error: "Payment could not be completed. Please try again.",
+        };
+      } catch (err: any) {
+        console.error("[useConfirmSubscriptionPayment] Unexpected error:", err);
+        return {
+          success: false,
+          error: err.message || "An unexpected error occurred during payment confirmation.",
+        };
+      } finally {
+        setIsConfirming(false);
+      }
+    },
+    [stripe],
+  );
+
+  return {
+    confirmPayment,
+    isConfirming,
+  };
+}

package/src/features/billing/stripe-subscription/index.ts

@@ -0,0 +1,5 @@
+export * from "./data";
+export * from "./stripe-subscription.module";
+
+// Note: hooks are not exported from barrel to avoid bundling client code into server components.
+// Import hooks directly: import { useConfirmSubscriptionPayment } from "./hooks";

package/src/features/billing/stripe-subscription/stripe-subscription.module.ts

@@ -0,0 +1,9 @@
+import { ModuleFactory } from "../../../permissions";
+import { StripeSubscription } from "./data";
+
+export const StripeSubscriptionModule = (factory: ModuleFactory) =>
+  factory({
+    name: "stripe-subscriptions",
+    model: StripeSubscription,
+    moduleId: "5e8797ef-650b-4dd5-ac79-a2e530a6c7ba",
+  });