[options] [update] Add new product_id and make plugin_id as alias.

README.md

@@ -10,7 +10,7 @@
     -   [Instantiate the class](#instantiate-the-class)
     -   [Calling the method](#calling-the-method)
 -   [Use with React](#use-with-react)
--   [Testing with Sandbox](#testing-with-sandbox)
+-   [Testing with Sandbox](#testing-with-the-sandbox)
 -   [Migration guide](#migration-guide)
 -   [Contributing](#contributing)
 
@@ -50,7 +50,7 @@ function getSelectedLicenses() {
 }
 
 const handler = new Checkout({
-    plugin_id: '311',
+    product_id: '311',
     public_key: 'pk_a42d2ee6de0b31c389d5d11e36211',
 });
 
@@ -104,7 +104,7 @@ need to hook into the `load` event of `window` or use `window.onload`.
 <script type="text/javascript">
     window.addEventListener('load', () => {
         const handler = new FS.Checkout({
-            plugin_id: '1234',
+            product_id: '1234',
             public_key: 'pk_xxxx',
         });
 
@@ -179,7 +179,7 @@ available under the global `FS` namespace.
 
 ```js
 const handler = new FS.Checkout({
-    plugin_id: '1234',
+    product_id: '1234',
     public_key: 'pk_xxxx',
 });
 ```
@@ -191,12 +191,12 @@ import { Checkout } from 'freemius-checkout-js';
 
 // instantiate
 const handler = new Checkout({
-    plugin_id: '0001',
+    product_id: '0001',
     public_key: 'pk_xxxx',
 });
 ```
 
-Note that the `plugin_id` and `public_key` are required parameters and must be
+Note that the `product_id` and `public_key` are required parameters and must be
 supplied during instantiation.
 
 ### Calling the method
@@ -233,8 +233,8 @@ handle.close();
 
 ## Use with React
 
-We will make a small react hook. Here we assume the `plugin_id` and `public_key`
-are available in
+We will make a small react hook. Here we assume the `product_id` and
+`public_key` are available in
 [some environment variable](https://vite.dev/guide/env-and-mode).
 
 **checkout.ts**
@@ -244,7 +244,7 @@ import { Checkout, CheckoutOptions } from '@freemius/checkout';
 import { useState, useEffect } from 'react';
 
 export const checkoutConfig: CheckoutOptions = {
-    plugin_id: import.meta.env.VITE_FS_PLUGIN_ID as string,
+    product_id: import.meta.env.VITE_FS_PLUGIN_ID as string,
     public_key: import.meta.env.VITE_FS_PUBLIC_KEY as string,
 };
 
@@ -347,6 +347,10 @@ context. In this repository we use the `.env` file for storing sandbox data.
 
 The rest of the code will continue to work exactly as it is with no changes.
 
+Optionally you can also change `plugin_id` to `product_id`, but we support both
+(giving preference to `product_id` if both are set) and we don't plan to remove
+it the near future.
+
 ```js
 document.querySelector('#purchase').addEventListener('click', (e) => {
     handler.open({
@@ -372,7 +376,7 @@ page, just create a new checkout:
 
 ```js
 const anotherHandler = new FS.Checkout({
-    plugin_id: '4321',
+    product_id: '4321',
     plan_id: '9876',
     public_key: 'pk_....nnn',
     image: 'https://your-plugin-site.com/logo-100x100.png',

src/adapter.ts

@@ -2,15 +2,15 @@
  * Backward compatible adapter for the checkout service.
  */
 import './global';
-import { CheckoutOptions, Checkout } from '.';
+import { CheckoutPopupOptions, Checkout } from '.';
 import { IFSOldCheckout } from './lib/contracts/IFSOldCheckout';
 
 class FSOldCheckout implements IFSOldCheckout {
     private checkout: Checkout | null = null;
 
-    private options: CheckoutOptions | null = null;
+    private options: CheckoutPopupOptions | null = null;
 
-    configure(options: CheckoutOptions, baseUrl?: string): IFSOldCheckout {
+    configure(options: CheckoutPopupOptions, baseUrl?: string): IFSOldCheckout {
         if (!this.checkout) {
             this.checkout = new Checkout(options, false, baseUrl);
 
@@ -32,9 +32,9 @@ class FSOldCheckout implements IFSOldCheckout {
         return this;
     }
 
-    public open(options: Partial<CheckoutOptions> = {}) {
+    public open(options: Partial<CheckoutPopupOptions> = {}) {
         const checkout =
-            this.checkout ?? this.configure(options as CheckoutOptions);
+            this.checkout ?? this.configure(options as CheckoutPopupOptions);
 
         checkout.open({
             ...(this.options ?? {}),

src/lib/checkout.spec.ts

@@ -207,4 +207,23 @@ describe('CheckoutPopup', () => {
             new URL(iFrame.src).searchParams.get('license_key')
         ).toMatchInlineSnapshot(`"sk_R-5E2+%20BD:.kp*(Oq2aodhzZ1Jw"`);
     });
+
+    test('supports product_id instead of plugin_id', () => {
+        const checkout = new Checkout({
+            product_id: 1,
+            public_key: 'pk_123456',
+            license_key: 'sk_R-5E2+%20BD:.kp*(Oq2aodhzZ1Jw',
+        });
+        checkout.open();
+
+        const guid = checkout.getGuid();
+
+        const iFrame = screen.queryByTestId(
+            `fs-checkout-page-${guid}`
+        ) as HTMLIFrameElement;
+
+        expect(iFrame).toBeInTheDocument();
+
+        expect(new URL(iFrame.src).searchParams.get('plugin_id')).toBe('1');
+    });
 });

src/lib/checkout.ts

@@ -14,7 +14,7 @@ import { Cart } from './services/cart';
 export type { PostmanEvents, CheckoutOptions };
 
 export class Checkout {
-    private readonly options: CheckoutOptions = {
+    private readonly options: CheckoutPopupOptions = {
         plugin_id: 0,
         public_key: '',
     };
@@ -36,14 +36,22 @@ export class Checkout {
         recoverCart: boolean = true,
         private readonly baseUrl: string = 'https://checkout.freemius.com'
     ) {
-        if (!options.plugin_id) {
-            throw new Error('Must provide a plugin_id to options.');
+        const { plugin_id, product_id, public_key, ...popupOptions } = options;
+
+        if (!plugin_id && !product_id) {
+            throw new Error('Must provide a product_id to options.');
         }
-        if (!options.public_key) {
+
+        if (!public_key) {
             throw new Error('Must provide the public_key to options.');
         }
 
-        this.options = options;
+        this.options = {
+            ...popupOptions,
+            public_key,
+            plugin_id: plugin_id ?? product_id,
+        };
+
         this.guid = generateGuid();
 
         if (isSsr()) {
@@ -54,9 +62,8 @@ export class Checkout {
 
         this.loader = new Loader(
             this.style,
-            this.options.loadingImageUrl ??
-                `${this.baseUrl}/assets/img/spinner.svg`,
-            this.options.loadingImageAlt
+            options.loadingImageUrl ?? `${this.baseUrl}/assets/img/spinner.svg`,
+            options.loadingImageAlt
         );
 
         this.exitIntent = new ExitIntent(this.style);

src/lib/contracts/IFSOldCheckout.ts

@@ -1,14 +1,17 @@
-import { CheckoutOptions } from '../types';
+import { CheckoutPopupOptions } from './CheckoutPopupOptions';
 
 export interface IFSOldCheckout {
     /**
      * Configure context plugin.
      */
-    configure: (options: CheckoutOptions, baseUrl?: string) => IFSOldCheckout;
+    configure: (
+        options: CheckoutPopupOptions,
+        baseUrl?: string
+    ) => IFSOldCheckout;
     /**
      * Open checkout.
      */
-    open: (options?: Partial<CheckoutOptions>) => void;
+    open: (options?: Partial<CheckoutPopupOptions>) => void;
     /**
      * Close checkout.
      */

src/lib/types.ts

@@ -1,6 +1,13 @@
 import { CheckoutPopupOptions } from './contracts/CheckoutPopupOptions';
 
-export interface CheckoutOptions extends CheckoutPopupOptions {
+/**
+ * All options required and supported by the Freemius Checkout.
+ *
+ * @see https://freemius.com/help/documentation/selling-with-freemius/freemius-checkout-buy-button/
+ *
+ * @note The `public_key` and either of `plugin_id` or `product_id` are required.
+ */
+export type CheckoutOptions = Omit<CheckoutPopupOptions, 'plugin_id'> & {
     /**
      * The URL of the image to display while the checkout is loading. By default a loading indicator from Freemius will be used.
      */
@@ -9,4 +16,21 @@ export interface CheckoutOptions extends CheckoutPopupOptions {
      * The alt text for the loading image. By default 'Loading Freemius Checkout' will be used.
      */
     loadingImageAlt?: string;
-}
+} & (
+        | {
+              /**
+               * Required product ID (whether it’s a plugin, theme, add-on, bundle, or SaaS).
+               */
+              product_id: number | string;
+              plugin_id?: never;
+          }
+        | {
+              /**
+               * Required product ID (whether it’s a plugin, theme, add-on, bundle, or SaaS).
+               *
+               * @deprecated Use `product_id` instead.
+               */
+              plugin_id: number | string;
+              product_id?: never;
+          }
+    );