TEBEX-1314 Payment portal support

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "typescript.tsdk": "node_modules/typescript/lib"
+}

README.md

@@ -1,6 +1,6 @@
 # Tebex.js
 
-Integrate Tebex Checkout directly into your own website or game using our embedded checkout experience.
+Tebex.js allows developers to integrate Tebex's Checkout and Payment Portal experiences directly within their own websites.
 
 ## Demo
 
@@ -48,9 +48,19 @@ We recommend using `defer` on the script to prevent it from blocking your websit
 </script>
 ```
 
-### ⚙️ Config
+### 💻 API
 
-Before your checkout can be launched, it must first be configured by calling the ```Tebex.checkout.init()``` method:
+The `Tebex` object contains the following properties:
+- [`Tebex.checkout`](#-tebex-checkout)
+- [`Tebex.portal`](#-tebex-payment-portal)
+
+### 🛒 Tebex Checkout
+
+`Tebex.checkout` provides a seamless checkout experience where customers can purchase items directly from within your website or game.
+
+#### Config
+
+Before your checkout can be launched, it must first be configured by calling the `Tebex.checkout.init()` method:
 
 ```js
 Tebex.checkout.init({
@@ -62,11 +72,11 @@ The only required option is `ident`, which you must replace with the checkout re
 
 For further information regarding configuration options - such as checkout branding colors - please refer to the [Tebex.js Documentation](https://docs.tebex.io/developers/tebex.js).
 
-### 🚀 Launch
+#### Launch
 
 When you are ready to show the Tebex.js checkout to your user, you can call the `Tebex.checkout.launch()` method. On desktop devices this will open the checkout as a popup, while on mobile devices it will open as a new tab.
 
-### 🧩 Web Components
+#### Web Components
 
 As an alternative to using the `Tebex.checkout` JavaScript API, Tebex.js also provides a `tebex-checkout` [Web Component](https://developer.mozilla.org/en-US/docs/Web/API/Web_components).
 
@@ -89,6 +99,28 @@ In the example above, we also add a `<button>` element inside the `tebex-checkou
 
 The `tebex-checkout` element also has an "inline" mode for rendering the checkout directly inline with the rest of the page content, along with various HTML attributes for checkout configuration. For more details, please refer to the [Tebex.js Web Components Documentation](https://docs.tebex.io/developers/tebex.js).
 
+### 🧾 Tebex Payment Portal
+
+`Tebex.portal` provides a way for your customers to review their subscription and purchase history directly from within your website or game.
+
+#### Config
+
+Before your portal can be launched, it must first be configured by calling the `Tebex.portal.init()` method:
+
+```js
+Tebex.portal.init({
+    token: ""
+});
+```
+
+The only required option is `token`, which you must replace with your project's **Public Token** - this can be found on the [API Keys page](https://creator.tebex.io/developers/api-keys) in your project settings.
+
+For further information regarding configuration options - such as UI branding colors - please refer to the [Tebex.js Documentation](https://docs.tebex.io/developers/tebex.js).
+
+#### Launch
+
+When you are ready to show the Tebex.js Payment Portal to your user, you can call the `Tebex.portal.launch()` method. On desktop devices this will open the Payment Portal as a popup, while on mobile devices it will open as a new tab.
+
 ### ❓ What's Next?
 
 We recommend reading the full [Tebex.js Documentation](https://docs.tebex.io/developers/tebex.js) to get an overview of all available options, events, and advanced functionality.

dist/types/checkout.d.ts

@@ -1,7 +1,8 @@
 /// <reference path="../../src/types/zoid.d.ts" />
 import { type ZoidComponent, type ZoidComponentInstance } from "zoid";
 import { type Unsubscribe } from "nanoevents";
-import { Lightbox } from "./lightbox";
+import { type TebexColorConfig, type TebexColorDefinition, type TebexTheme } from "./common";
+import { Lightbox } from "./components/lightbox";
 import { type CssDimension, type Implements } from "./utils";
 export declare const THEME_NAMES: readonly ["auto", "default", "light", "dark"];
 export declare const COLOR_NAMES: readonly ["primary", "secondary", "background", "surface", "surface-variant", "success", "warning", "error", "green", "red", "fields", "field-border"];
@@ -15,20 +16,20 @@ export type CheckoutOptions = {
      */
     ident: string;
     /**
-     * The default language to use, defined as an ISO locale code - e.g. `"en_US" for American English, "de_DE" for German, etc.
+     * The default language to use, defined as an ISO locale code - e.g. `"en_US"` for American English, "de_DE" for German, etc.
      * @default `navigator.language`
      */
     locale?: string;
     /**
      * Tebex checkout panel color theme.
      * @default "light"
      */
-    theme?: CheckoutTheme;
+    theme?: TebexTheme;
     /**
      * Tebex checkout panel UI brand colors.
      * @default []
      */
-    colors?: CheckoutColorDefinition[];
+    colors?: TebexColorConfig;
     /**
      * Whether to close the Tebex.js popup when the user clicks outside of the modal.
      * @default false
@@ -61,17 +62,6 @@ export type CheckoutOptions = {
      */
     endpoint?: string;
 };
-/**
- * Color theme for the embedded Tebex checkout panel.
- */
-export type CheckoutTheme = typeof THEME_NAMES[number];
-/**
- * Color definition. The `color` property can be set to any valid CSS color, so long as it does not rely on CSS Variables.
- */
-export type CheckoutColorDefinition = {
-    name: typeof COLOR_NAMES[number];
-    color: string;
-};
 /**
  * Checkout event type. You can subscribe to checkout events with `Tebex.checkout.on()`.
  */
@@ -91,12 +81,12 @@ export type CheckoutEventMap = Implements<Record<CheckoutEvent, Function>, {
  */
 export type CheckoutZoidProps = {
     locale: string;
-    colors: CheckoutColorDefinition[];
+    colors: TebexColorConfig;
     closeOnClickOutside: boolean;
     closeOnEsc: boolean;
     closeOnPaymentComplete: boolean;
     defaultPaymentMethod?: string;
-    theme: CheckoutTheme;
+    theme: TebexTheme;
     onOpenWindow: (url: string) => void;
     onClosePopup: () => Promise<void>;
     onPaymentComplete: (e: any) => void;
@@ -116,8 +106,8 @@ export default class Checkout {
     #private;
     ident: string;
     locale: string;
-    theme: CheckoutTheme;
-    colors: CheckoutColorDefinition[];
+    theme: TebexTheme;
+    colors: TebexColorDefinition[];
     closeOnClickOutside: boolean;
     closeOnEsc: boolean;
     closeOnPaymentComplete: boolean;
@@ -132,7 +122,7 @@ export default class Checkout {
         "payment:error": (e: Event) => void;
     }>;
     lightbox: Lightbox;
-    component: ZoidComponent<CheckoutZoidProps>;
+    componentFactory: ZoidComponent<CheckoutZoidProps>;
     zoid: ZoidComponentInstance;
     /**
      * Configure the Tebex checkout settings.

dist/types/common.d.ts

@@ -0,0 +1,25 @@
+export declare const THEME_NAMES: readonly ["auto", "default", "light", "dark"];
+export declare const COLOR_NAMES: readonly ["primary", "secondary", "background", "surface", "surface-variant", "success", "warning", "error", "green", "red", "fields", "field-border"];
+/**
+ * Theme preset for the embedded Tebex UI.
+ */
+export type TebexTheme = typeof THEME_NAMES[number];
+/**
+ * Color name used for theming embedded Tebex UI.
+ */
+export type TebexColorName = typeof COLOR_NAMES[number];
+/**
+ * Color definition. The `color` property can be set to any valid CSS color, so long as it does not rely on CSS Variables.
+ */
+export type TebexColorDefinition = {
+    name: TebexColorName;
+    color: string;
+};
+/**
+ * Configuration for theming colors in the embedded Tebex UI.
+ *
+ * Accepts either:
+ * - an array of {@link TebexColorDefinition} objects, or
+ * - an object mapping {@link TebexColorName} keys mapped to string color values.
+ */
+export type TebexColorConfig = TebexColorDefinition[] | Partial<Record<TebexColorName, string>>;

dist/types/components/lightbox.d.ts

@@ -0,0 +1,25 @@
+export type LightboxCloseHandler = (e: MouseEvent | KeyboardEvent) => void;
+export type LightboxOptions = {
+    name: string;
+    closeOnClickOutside: boolean;
+    closeOnEsc: boolean;
+    closeHandler: LightboxCloseHandler;
+};
+export declare class Lightbox {
+    #private;
+    body: HTMLElement;
+    root: HTMLElement;
+    holder: HTMLElement;
+    constructor(options?: Partial<LightboxOptions>);
+    setOptions(options: Partial<LightboxOptions>): void;
+    render(): any;
+    show(): Promise<void>;
+    hide(transition?: boolean): Promise<void>;
+    destroy(): void;
+}
+/**
+ * Clears the global lightbox open state - used for testing.
+ * @internal
+ * @ignore
+ */
+export declare const __clearGlobalLightboxOpen: () => void;

dist/types/components/spinner.d.ts

@@ -0,0 +1,8 @@
+type SpinnerOptions = {
+    doc?: Document;
+    props: {
+        cspNonce?: string;
+    };
+};
+export declare const spinnerRender: ({ doc, props }: SpinnerOptions) => any;
+export {};

dist/types/index.d.ts

@@ -1,14 +1,21 @@
 import Checkout from "./checkout";
+import Portal from "./portal";
 import "./webComponents";
 /**
  * Current Tebex.js package version
  */
 export declare const version: string;
+export type { TebexTheme } from "./common";
 /**
  * Tebex checkout API
  */
 export declare const checkout: Checkout;
-export type { CheckoutOptions, CheckoutColorDefinition, CheckoutEvent, CheckoutEventMap, CheckoutTheme, CheckoutZoidProps } from "./checkout";
+export type { CheckoutOptions, CheckoutEvent, CheckoutEventMap, CheckoutZoidProps } from "./checkout";
+/**
+ * Tebex payment portal API
+ */
+export declare const portal: Portal;
+export type { PortalOptions, PortalEvent, PortalEventMap, PortalZoidProps } from "./portal";
 /**
  * Legacy APIs
  * @deprecated
@@ -17,11 +24,15 @@ export * from "./legacy";
 declare const _default: {
     events: {
         OPEN: string;
+        /**
+         * Current Tebex.js package version
+         */
         CLOSE: string;
         PAYMENT_COMPLETE: string;
         PAYMENT_ERROR: string;
     };
     version: string;
     checkout: Checkout;
+    portal: Portal;
 };
 export default _default;

dist/types/legacy/checkoutTypes.d.ts

@@ -0,0 +1,15 @@
+import type { TebexTheme, TebexColorDefinition } from "../common";
+/**
+ * Theme preset for the embedded Tebex UI.
+ * Replaced with {@link TebexTheme} since it is shared between portal and checkout.
+ *
+ * @deprecated use {@link TebexTheme}
+ */
+export type CheckoutTheme = TebexTheme;
+/**
+ * Color definition. The `color` property can be set to any valid CSS color, so long as it does not rely on CSS Variables.
+ * Replaced with {@link TebexColorDefinition} since it is shared between portal and checkout.
+ *
+ * @deprecated use {@link TebexColorDefinition}
+ */
+export type CheckoutColorDefinition = TebexColorDefinition;

dist/types/legacy/index.d.ts

@@ -1 +1,2 @@
 export * from './events';
+export * from './checkoutTypes';