[IDM-209] - feat: stripe checkout

packages/common/types/payment.ts

@@ -40,3 +40,10 @@ export type Product = {
   // Array of price objects.
   prices: Price[];
 };
+
+// General checkout parameters type. Can be extended by specific payment providers, e.g. Stripe
+export type CheckoutParams = {
+  price_id: string;
+  success_url: string;
+  cancel_url: string;
+};

packages/common/types/stripe.ts

@@ -1,9 +1,6 @@
-export type StripeCheckoutRequestParams = {
-  access_plan_id: string;
-  price_id: string;
-  redirect_url: string;
-};
+import type { CheckoutParams } from './payment';
 
-export type StripeCheckoutResponse = {
-  url: string;
+// Extend the CheckoutParams type with Stripe-specific fields
+export type StripeCheckoutParams = CheckoutParams & {
+  mode: 'payment' | 'subscription';
 };

platforms/access-bridge/README.md

@@ -89,6 +89,27 @@ You can also copy and paste the contents of `.env.example` into `.env.local` and
   ]
   ```
 
+#### URL: `/v2/sites/{site_id}/checkout`
+
+- **Method:** POST
+- **Authorization:** Valid SIMS token
+- **Summary:** Creates Payment Checkout Session URL where the viewer will be redirected to complete the payment.
+- **Request:**
+  ```json
+  {
+    "price_id": "string", // id of the price that is about to be paid
+    "mode": "string", // subscription (recurring) | payment (one time purchases)
+    "success_url": "string", // redirect after successful payment
+    "cancel_url": "string" // redirect after cancel / invalid payment
+  }
+  ```
+- **Response:**
+  ```json
+  {
+    "url": "string" // url where the viewer will be redirected to complete the payment.
+  }
+  ```
+
 ## Developer guidelines
 
 - Read the workspace guidelines here [../../docs/developer-guidelines.md](../../docs/developer-guidelines.md).

platforms/access-bridge/src/controllers/checkout-controller.ts

@@ -0,0 +1,43 @@
+import { Request, Response, NextFunction } from 'express';
+
+import { ErrorDefinitions, sendErrors } from '../errors.js';
+import { IdentityService } from '../services/identity-service.js';
+import { PaymentService } from '../services/payment-service.js';
+import { StripePaymentService } from '../services/stripe-payment-service.js';
+
+/**
+ * Controller class responsible for handling payment checkout session URLs, where the viewers can complete the payment.
+ */
+export class CheckoutController {
+  private readonly identityService: IdentityService;
+  private readonly paymentService: PaymentService;
+
+  constructor() {
+    this.identityService = new IdentityService();
+    this.paymentService = new StripePaymentService();
+  }
+
+  /**
+   * Service handler for initiating a Payment Checkout session based on the provided checkout params.
+   * @returns A Promise that resolves with a response containing the URL for the Payment Provider Checkout session.
+   */
+  async initiateCheckout(req: Request, res: Response, next: NextFunction): Promise<void> {
+    const authorization = req.headers['authorization'];
+    if (!authorization) {
+      sendErrors(res, ErrorDefinitions.UnauthorizedError.create());
+      return;
+    }
+
+    const checkoutParams = req.body;
+    const validationError = this.paymentService.validateCheckoutParams(checkoutParams);
+    if (validationError) {
+      sendErrors(res, ErrorDefinitions.ParameterMissingError.create({ parameterName: validationError }));
+      return;
+    }
+
+    const viewer = await this.identityService.getAccount({ authorization });
+    const checkoutSessionUrl = await this.paymentService.createCheckoutSessionUrl(viewer, checkoutParams);
+
+    res.json({ url: checkoutSessionUrl });
+  }
+}

platforms/access-bridge/src/controllers/products-controller.ts

@@ -4,7 +4,7 @@ import { PlansService } from '../services/plans-service.js';
 import { StripePaymentService } from '../services/stripe-payment-service.js';
 import { PaymentService } from '../services/payment-service.js';
 /**
- * Controller class responsible for handling Stripe-related services.
+ * Controller class responsible for handling AC plans and Stripe products.
  */
 export class ProductsController {
   private readonly plansService: PlansService;

platforms/access-bridge/src/errors.ts

@@ -164,13 +164,13 @@ export function handleJWError(error: JWErrorResponse): AccessBridgeError {
 // Utility function to handle Stripe errors
 export function handleStripeError(error: Stripe.errors.StripeError): AccessBridgeError {
   if (error.type === 'StripeInvalidRequestError') {
-    return ErrorDefinitions.BadRequestError.create({ description: error.message });
+    throw ErrorDefinitions.BadRequestError.create({ description: error.message });
   } else if (error.type === 'StripeAuthenticationError') {
-    return ErrorDefinitions.UnauthorizedError.create({ description: error.message });
+    throw ErrorDefinitions.UnauthorizedError.create({ description: error.message });
   } else if (error.type === 'StripePermissionError') {
-    return ErrorDefinitions.ForbiddenError.create({ description: error.message });
-  } else {
-    // Fallback to a generic InternalError for unexpected Stripe errors
-    return ErrorDefinitions.InternalError.create({ description: error.message });
+    throw ErrorDefinitions.ForbiddenError.create({ description: error.message });
   }
+
+  // Fallback to a generic BadRequestError for unexpected Stripe errors
+  throw ErrorDefinitions.BadRequestError.create({ description: error.message });
 }

platforms/access-bridge/src/pipeline/routes.ts

@@ -2,18 +2,21 @@ import { Express, Request, Response, NextFunction } from 'express';
 
 import { AccessController } from '../controllers/access-controller.js';
 import { ProductsController } from '../controllers/products-controller.js';
+import { CheckoutController } from '../controllers/checkout-controller.js';
 
 import { Middleware } from './middleware.js';
 
 const middleware = new Middleware();
 const accessController = new AccessController();
 const productsController = new ProductsController();
+const checkoutController = new CheckoutController();
 
 export function initializeRoutes(app: Express) {
   // Register routes with their respective controller methods
   addRoute(app, 'put', '/v2/sites/:site_id/access/generate', accessController.generatePassport.bind(accessController));
   addRoute(app, 'put', '/v2/sites/:site_id/access/refresh', accessController.refreshPassport.bind(accessController));
   addRoute(app, 'get', '/v2/sites/:site_id/products', productsController.getProducts.bind(productsController));
+  addRoute(app, 'post', '/v2/sites/:site_id/checkout', checkoutController.initiateCheckout.bind(checkoutController));
 }
 
 // Adds a route to the Express application with the specified HTTP method, path, and handler.

platforms/access-bridge/src/services/payment-service.ts

@@ -1,9 +1,12 @@
-import type { Product } from '@jwp/ott-common/types/payment.js';
+import type { CheckoutParams, Product } from '@jwp/ott-common/types/payment.js';
+
+import { Viewer } from './identity-service';
 /**
- * PaymentService interface defines the contract for payment service implementations. *
- * Any class implementing this should handle products and prices from a specific payment provider (e.g., Stripe).
+ * PaymentService interface defines the contract for payment service implementations.
+ * Any class implementing this should handle products, prices, checkout and payment,
+ * from a specific payment provider (e.g., Stripe, Google, Apple).
  */
-export interface PaymentService {
+export interface PaymentService<T extends CheckoutParams = CheckoutParams> {
   /**
    * Retrieves products with prices based on the provided product IDs.
    * The implementation should interact with the payment provider's API to fetch products and prices details.
@@ -12,4 +15,21 @@ export interface PaymentService {
    * @returns A Promise that resolves to an array of products, each containing associated price details.
    */
   getProductsWithPrices(productIds: string[]): Promise<Product[]>;
+
+  /**
+   * Creates a checkout session based on the provided viewer and checkout parameters.
+   * This method should be implemented by each provider's payment service.
+   *
+   * @param viewer The viewer making the payment (e.g., their email and ID).
+   * @param params The generic checkout parameters that will be customized for each payment provider.
+   * @returns A Promise resolving to a checkout session URL depending on the provider.
+   */
+  createCheckoutSessionUrl(viewer: Viewer, params: T): Promise<string | null>;
+
+  /**
+   * Validates the provided checkout parameters based on the specific provider's requirements.
+   * @param params - The checkout parameters to validate.
+   * @returns An error string if validation fails, or null if validation succeeds.
+   */
+  validateCheckoutParams(params: T): string | null;
 }

platforms/access-bridge/src/services/stripe-payment-service.ts

@@ -1,9 +1,11 @@
 import Stripe from 'stripe';
 import { Product, Price } from '@jwp/ott-common/types/payment.js';
+import { StripeCheckoutParams } from '@jwp/ott-common/types/stripe.js';
 
 import { STRIPE_SECRET } from '../app-config.js';
 
 import { PaymentService } from './payment-service.js';
+import { Viewer } from './identity-service.js';
 
 /**
  * Service class responsible for interacting with the Stripe API to fetch products.
@@ -61,6 +63,59 @@ export class StripePaymentService implements PaymentService {
     return productsWithPrices.filter((product) => product !== null) as Product[];
   }
 
+  /**
+   * Creates a Stripe Checkout session URL, where the viewer will be redirected to complete the payment.
+   * @param viewer Email address and viewer id from the auth token used for creating the checkout session.
+   * @param params Stripe checkout params to use for creating the checkout session.
+   * @returns A Promise resolving to a Stripe Checkout Session URL for the checkout page.
+   */
+  async createCheckoutSessionUrl(viewer: Viewer, params: StripeCheckoutParams): Promise<string | null> {
+    const sessionParams: Stripe.Checkout.SessionCreateParams = {
+      payment_method_types: ['card'],
+      line_items: [
+        {
+          price: params.price_id,
+          quantity: 1,
+        },
+      ],
+      metadata: {
+        // This is very important as it's our only way of connecting the payment back to the viewer
+        viewer_id: viewer.id,
+      },
+      customer_email: viewer.email,
+      mode: params.mode,
+      success_url: params.success_url,
+      cancel_url: params.cancel_url,
+
+      // Conditionally include `subscription_data` only if mode is `subscription`
+      ...(params.mode === 'subscription' && {
+        subscription_data: {
+          metadata: {
+            // This is very important as it's our only way of connecting the payment back to the viewer
+            viewer_id: viewer.id,
+          },
+        },
+      }),
+    };
+
+    const checkoutSession = await this.stripe.checkout.sessions.create(sessionParams);
+    return checkoutSession.url;
+  }
+
+  /**
+   * Validates the provided checkout parameters.
+   * Checks for the presence of required fields: 'price_id', 'mode', 'success_url', and 'cancel_url'.
+   * If any required parameter is missing, returns an error message; otherwise, returns null.
+   * @param params - The checkout parameters to validate.
+   * @returns A string containing the name of the missing parameter if validation fails,
+   * or null if all required parameters are present.
+   */
+  validateCheckoutParams(params: StripeCheckoutParams): string | null {
+    const requiredParams: (keyof StripeCheckoutParams)[] = ['price_id', 'mode', 'success_url', 'cancel_url'];
+    const missingParam = requiredParams.find((param) => !params[param]);
+    return missingParam ? `Missing required parameter: ${missingParam}` : null;
+  }
+
   /**
    * Maps the Stripe product to our custom Product type.
    * @param product The Stripe product object.

platforms/access-bridge/test/fixtures.ts

@@ -21,6 +21,7 @@ export const ENDPOINTS = {
   GENERATE_PASSPORT: '/v2/sites/:site_id/access/generate',
   REFRESH_PASSPORT: '/v2/sites/:site_id/access/refresh',
   PRODUCTS: '/v2/sites/:site_id/products',
+  CHECKOUT: '/v2/sites/:site_id/checkout',
 };
 
 // mock data for access tokens
@@ -122,6 +123,7 @@ export const SITE_ID = {
 export const AUTHORIZATION = {
   VALID: 'Bearer valid-authorization',
   INVALID: 'Bearer invalid-authorization',
+  MISSING: '',
 };
 
 // Store price mock
@@ -189,3 +191,6 @@ export const STRIPE_ERRORS = [
     statusCode: 400,
   },
 ];
+
+// mock of stripe session url
+export const STRIPE_SESSION_URL = 'https://example.com';