[checkout] [new] Add method to create upgrade link or config

Also make the sandbox setter method consistent.

Author: swashata

.changeset/slick-symbols-act.md

@@ -0,0 +1,5 @@
+---
+'@freemius/sdk': minor
+---
+
+New feature to generate checkout upgrade flow

packages/sdk/src/Freemius.ts

@@ -39,7 +39,7 @@ export class Freemius {
         this.auth = new AuthService(productId, secretKey);
         this.pricing = new PricingService(this.api);
         this.purchase = new PurchaseService(this.api);
-        this.checkout = new CheckoutService(productId, publicKey, secretKey, this.purchase, this.pricing);
+        this.checkout = new CheckoutService(this.api, productId, publicKey, secretKey, this.purchase, this.pricing);
         this.customerPortal = new CustomerPortalService(this.api, this.checkout, this.auth, this.purchase);
         this.webhook = new WebhookService(this.api, secretKey);
     }

packages/sdk/src/__tests__/manual/checkout.ts

@@ -1,10 +1,14 @@
 import { freemius } from './fs';
 
 async function main() {
-    const checkoutLink = (await freemius.checkout.create()).setSandbox().getLink();
+    const checkoutLink = (await freemius.checkout.create())
+        .setSandbox(await freemius.checkout.getSandboxParams())
+        .getLink();
     console.log('Checkout Link:', checkoutLink);
 
-    const checkoutOptions = (await freemius.checkout.create()).setSandbox().getOptions();
+    const checkoutOptions = (await freemius.checkout.create())
+        .setSandbox(await freemius.checkout.getSandboxParams())
+        .getOptions();
     console.log('Checkout Options:', checkoutOptions);
 
     const checkout = await freemius.checkout.create({
@@ -18,6 +22,12 @@ async function main() {
 
     const pricingData = await freemius.pricing.retrieve();
     console.log('Pricing Data:', pricingData);
+
+    const checkoutUpgrader = (await freemius.checkout.create()).setLicenseAuthorization(
+        await freemius.checkout.getLicenseUpgradeParams('6')
+    );
+    checkoutUpgrader.setPlan('383');
+    console.log('License Upgrade Link:', checkoutUpgrader.getLink());
 }
 
 main();

packages/sdk/src/checkout/Checkout.ts

@@ -4,16 +4,18 @@ import {
     convertCheckoutOptionsToQueryParams,
     buildFreemiusQueryFromOptions,
 } from '@freemius/checkout';
-import { createHash } from 'crypto';
 import { isTestServer, splitName } from '../utils/ops';
 import { CheckoutBuilderUserOptions } from '../contracts/checkout';
+import { FSId } from '../api/types';
 
 export type CheckoutSerialized = {
     options: CheckoutOptions;
     link: string;
     baseUrl: string;
 };
 
+export type CheckoutLicenseAuthorization = { licenseId: FSId; authorization: string };
+
 /**
  * A builder class for constructing checkout parameters. This class provides a fluent
  * API to create Checkout parameters for a product with various configurations.
@@ -22,20 +24,6 @@ export type CheckoutSerialized = {
  * The final `getOptions()` method returns the constructed `CheckoutOptions` object.
  */
 export class Checkout {
-    static createSandboxToken(
-        productId: string,
-        secretKey: string,
-        publicKey: string
-    ): NonNullable<CheckoutPopupParams['sandbox']> {
-        const timestamp = Math.floor(Date.now() / 1000).toString();
-        const token = `${timestamp}${productId}${secretKey}${publicKey}checkout`;
-
-        return {
-            ctx: timestamp,
-            token: createHash('md5').update(token).digest('hex'),
-        };
-    }
-
     private options: CheckoutOptions;
 
     constructor(
@@ -51,10 +39,10 @@ export class Checkout {
      *
      * @returns A new builder instance with sandbox configuration
      */
-    setSandbox(): Checkout {
+    setSandbox(sandbox: NonNullable<CheckoutPopupParams['sandbox']>): Checkout {
         this.options = {
             ...this.options,
-            sandbox: Checkout.createSandboxToken(this.productId, this.secretKey!, this.publicKey!),
+            sandbox,
         };
 
         return this;
@@ -406,7 +394,7 @@ export class Checkout {
      * @param licenseKey The license key to renew
      * @returns A new builder instance configured for renewal
      */
-    setLicenseRenewal(licenseKey: string): Checkout {
+    setLicenseRenewalByKey(licenseKey: string): Checkout {
         this.options = {
             ...this.options,
             license_key: licenseKey,
@@ -415,6 +403,16 @@ export class Checkout {
         return this;
     }
 
+    setLicenseAuthorization(params: CheckoutLicenseAuthorization): Checkout {
+        this.options = {
+            ...this.options,
+            license_id: params.licenseId,
+            authorization: params.authorization,
+        };
+
+        return this;
+    }
+
     /**
      * Builds and returns the final checkout options to be used with the `@freemius/checkout` package.
      *

packages/sdk/src/contracts/checkout.ts

@@ -145,6 +145,12 @@ export type CheckoutBuilderOptions = {
      * If not provided, the checkout will not have a trial period.
      */
     trial?: CheckoutOptions['trial'];
+    /**
+     * Optional license ID for license upgrade scenarios.
+     *
+     * When provided, the checkout will be configured for upgrading the specified license. Use this to generate upgrade links for existing users.
+     */
+    licenseId?: string;
 };
 
 /**

packages/sdk/src/services/CheckoutService.ts

@@ -1,17 +1,20 @@
 import { CheckoutPopupParams } from '@freemius/checkout';
 import { FSId } from '../api/types';
 import { idToString } from '../api/parser';
-import { Checkout } from '../checkout/Checkout';
+import { Checkout, CheckoutLicenseAuthorization } from '../checkout/Checkout';
 import { CheckoutBuilderOptions } from '../contracts/checkout';
 import { PurchaseService } from './PurchaseService';
 import { PricingService } from './PricingService';
 import { CheckoutRequestProcessor } from '../checkout/CheckoutRequestProcessor';
 import { RedirectProcessor } from '../checkout/RedirectProcessor';
+import { createHash } from 'crypto';
+import { ApiService } from './ApiService';
 
 export class CheckoutService {
     public readonly request: CheckoutRequestProcessor;
 
     constructor(
+        private readonly api: ApiService,
         private readonly productId: FSId,
         private readonly publicKey: string,
         private readonly secretKey: string,
@@ -54,7 +57,17 @@ export class CheckoutService {
      * @example
      */
     async create(options: CheckoutBuilderOptions = {}): Promise<Checkout> {
-        const { user, isSandbox = false, withRecommendation = true, title, image, planId, quota, trial } = options;
+        const {
+            user,
+            isSandbox = false,
+            withRecommendation = true,
+            title,
+            image,
+            planId,
+            quota,
+            trial,
+            licenseId,
+        } = options;
 
         const builder = new Checkout(idToString(this.productId), this.publicKey, this.secretKey);
 
@@ -67,7 +80,7 @@ export class CheckoutService {
         }
 
         if (isSandbox) {
-            builder.setSandbox();
+            builder.setSandbox(await this.getSandboxParams());
         }
 
         if (title) {
@@ -90,6 +103,11 @@ export class CheckoutService {
             builder.setTrial(trial);
         }
 
+        if (licenseId) {
+            const authorization = await this.getLicenseUpgradeParams(licenseId);
+            builder.setLicenseAuthorization(authorization);
+        }
+
         return builder;
     }
 
@@ -99,12 +117,34 @@ export class CheckoutService {
      * This shouldn't be used in production, but is useful for testing purposes.
      *
      * @note This is intentionally set as `async` because we would use the API in the future to generate more fine grained sandbox params (for example for a specific email address only).
-     *
-     * @todo - This has a duplication with the `inSandbox` method in the builder. Consider refactoring to avoid this duplication.
-     *         Also think about whether we should make the builder's `inSandbox` method async as well.
      */
     async getSandboxParams(): Promise<NonNullable<CheckoutPopupParams['sandbox']>> {
-        return Checkout.createSandboxToken(idToString(this.productId), this.secretKey, this.publicKey);
+        const productId = idToString(this.productId);
+        const timestamp = Math.floor(Date.now() / 1000).toString();
+        const token = `${timestamp}${productId}${this.secretKey}${this.publicKey}checkout`;
+
+        return {
+            ctx: timestamp,
+            token: createHash('md5').update(token).digest('hex'),
+        };
+    }
+
+    /**
+     * Retrieves the license upgrade authorization for a given license ID.
+     *
+     * This is used to authorize a license upgrade during the checkout process. Useful when creating upgrade links for existing users.
+     */
+    async getLicenseUpgradeParams(licenseId: FSId): Promise<CheckoutLicenseAuthorization> {
+        const auth = await this.api.license.retrieveCheckoutUpgradeAuthorization(licenseId);
+
+        if (!auth) {
+            throw new Error('Failed to retrieve license upgrade authorization');
+        }
+
+        return {
+            licenseId,
+            authorization: auth,
+        };
     }
 
     /**