paymob-widget-alpha 1.0.16 → 1.0.17

package/README.md

@@ -1,108 +1,120 @@
-# `paymob-widget-alpha`
-Paymob Installments Widget that can be embedded in any web page to display installment plans and (optionally) let the user select a plan.
+# Paymob Installments Widget
 
-## Installing
+`paymob-widget`
 
-### CDN
+A drop-in widget you embed in any web page (product page, cart, or checkout) to show your customers the **installment plans** available for a given amount. You can use it purely to display plans, or let customers pick a plan and hand the selection back to your code.
 
-Using jsDelivr:
+No framework required — it works on any HTML page with a single `<script>` tag,
+and it also drops into React, Angular or Vue apps (see
+[Use in a framework](#use-in-a-framework-react-angular-vue)).
+
+---
+
+## How it works
+
+1. You add the script and a container element to your page.
+2. You create a `PaymobWidget` with your public key and the order amount.
+3. The widget calls Paymob, fetches the installment plans for that amount, and renders them inside your container.
+
+There are two modes:
+
+| Mode | What the customer sees | When to use it |
+| --- | --- | --- |
+| **Display only** (default) | A read-only list of available installment plans. | You just want to promote installments (e.g. "Pay in 12 months") on a product page. |
+| **Selectable** (`customerCanSelect: true`) | The same plans, but the customer can **select** one and click **Buy now**. | You want the customer to choose a plan and continue the purchase in your own flow. |
+
+---
+
+## Quick start
+
+### 1. Add the script
+
+Using the jsDelivr CDN:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/paymob-widget-alpha@latest/main.js" type="module"></script>
+<script src="https://cdn.jsdelivr.net/npm/paymob-widget@latest/main.js" type="module"></script>
 ```
 
-## Usage
+### 2. Add a container
 
-Create a container element in your page:
+Place an empty element wherever you want the widget to appear:
 
 ```html
 <div id="paymob-widget"></div>
 ```
 
-Then instantiate the widget:
+### 3. Create the widget
 
 ```js
 new PaymobWidget({
   publicKey: 'egy_pk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
   elementId: 'paymob-widget',
-  amount: 100000, // required — order total in cents (1000 EGP)
+  amount: 100000, // order total in cents — this is 1,000 EGP
   currency: 'EGP',
-  integrationId: 123 || [123456, 2233], // optional — single number or array
 });
 ```
 
-If `amount` is missing, invalid, or not a positive finite number, the widget **will not initialize** and an error is logged to the console.
-
-### When the widget is shown or hidden
+That's it. If installment plans are available for that amount, the widget renders them.
 
-The widget is **only rendered** when all of the following are true:
+> **⚠️ `amount` is in cents, not whole currency units.**
+> To show plans for **1,000 EGP**, pass `amount: 100000` (1,000 × 100).
+> If `amount` is missing, zero, negative, or not a number, the widget will **not** render and an error is logged to the browser console.
 
-- `amount` is valid (positive finite number in **cents**)
-- The installment-plans request returns a **2xx** status
-- At least one installment plan is available after processing the response
+---
 
-The widget is **not shown** when:
+## Options
 
-- `amount` is missing, `≤ 0`, or not a finite number → constructor stops and logs `console.error`
-- The API request **fails** (any non-2xx status, e.g. `400`) → widget hidden; `console.error` includes the status code
-- The API **succeeds** but returns **no plans** (e.g. invalid integration, amount below minimum, no bank installment configured) → widget hidden; `console.error` is logged
+| Option | Type | Required | Description |
+| --- | --- | --- | --- |
+| `publicKey` | `string` | **Yes** | Your Paymob public key. Authenticates requests and selects the correct regional API (based on the key's country prefix, e.g. `egy_`, `are_`, `sau_`, `pak_`, `omn_`). |
+| `elementId` | `string` | **Yes** | The `id` of the HTML element the widget renders into. |
+| `amount` | `number` | **Yes** | The order total **in cents** (a positive number). No default — the widget won't render without it. |
+| `currency` | `string` | No | Currency code. Default: `"EGP"`. |
+| `integrationId` | `number \| number[]` | No | One or more Paymob integration IDs. When provided, plans are fetched for those integrations only. |
+| `theme` | `"primary" \| "light" \| "dark"` | No | Visual theme. Default: `"primary"`. |
+| `customerCanSelect` | `boolean` | No | Set to `true` to let the customer select a plan and enable **Buy now**. Default: `false` (read-only). |
+| `onSubmit` | `function` | No | Called when the customer clicks **Buy now**. See [Handling the selection](#handling-the-selection). |
 
-**End users do not see error messages** on the page or in the modal. Errors are for developers in the **browser console** only (`[PaymobWidget] ...`).
+---
 
-### Selectable mode example
+## Letting customers select a plan
 
-To let the user select an installment plan and handle the selection in your app, enable `customerCanSelect` and pass an `onSubmit` callback.
+Set `customerCanSelect: true` and provide an `onSubmit` callback. Your callback runs when the customer picks a plan and clicks **Buy now**, so you can continue the purchase in your own flow.
 
 ```js
 new PaymobWidget({
   publicKey: 'egy_pk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
   elementId: 'paymob-widget',
-  amount: 100000, // required — order total in cents (1000 EGP)
+  amount: 100000, // 1,000 EGP
   currency: 'EGP',
-  integrationId: 123 || [123456, 2233], // optional — single number or array
   theme: 'primary',
   customerCanSelect: true,
   onSubmit: (plan) => {
-    // Called when the user clicks **Buy now**.
-    // With customerCanSelect: true, plan is provided after the user selects a plan.
-    // plan = { id: 123, tenure: 12, amount: 25000 } // amount = monthly installment in cents
-    // With customerCanSelect: false, onSubmit is called with no payload.
+    // plan = { id: 123, tenure: 12, amount: 25000 }
+    console.log('Customer selected plan', plan);
+    // → continue your purchase flow here
   },
 });
 ```
 
-## Properties
-
-| Property | Type | Required | Definition |
-| --- | --- | --- | --- |
-| publicKey | String | Yes | Your public key (used to resolve API base URL and authenticate requests). |
-| elementId | String | Yes | ID of the HTML element where the widget will be rendered. |
-| theme | `"primary" \| "light" \| "dark"` | No | Widget theme. Default: `"primary"`. |
-| amount | Number | Yes | Order total in **cents** (positive finite number). **Required** — no default. The widget will not initialize without it. |
-| currency | String | No | Currency code. Default: `"EGP"`. |
-| integrationId | Number \| Number[] | No | Paymob integration ID(s). If provided, sent when fetching installment plans. |
-| customerCanSelect | Boolean | No | If `true`, the user can select a plan and **Buy now** is enabled. Default: `false`. |
-| onSubmit | Function | No | Called when the user clicks **Buy now**. With `customerCanSelect: true`, receives `{ id, tenure, amount }`. With `false`, called with no payload. |
-
-### `customerCanSelect` and Learn more
-
-| Value | Behavior |
-| --- | --- |
-| `true` | User can **select** a plan. Learn more includes the **Select Installment Plan** step. |
-| `false` | Plans are **read-only**. Learn more omits the selection step and uses different copy on the final payment step. |
-
-### `onSubmit` payload
+### Handling the selection
 
-When `customerCanSelect` is `true`:
+When `customerCanSelect` is `true`, `onSubmit` receives the selected plan:
 
 ```js
 {
-  id: string | number,   // installment plan id
+  id: string | number,   // the installment plan ID
   tenure: number,        // number of months
-  amount: number         // monthly installment amount in cents
+  amount: number         // monthly installment amount, in cents
 }
 ```
 
+When `customerCanSelect` is `false`, the plans are read-only. **Buy now** is not part of that flow, and if `onSubmit` is called it receives no payload.
+
+The built-in **Learn more** dialog also adapts: with `customerCanSelect: true` it includes a "Select installment plan" step; with `false` it omits that step.
+
+---
+
 ## Full HTML example
 
 ```html
@@ -127,14 +139,14 @@ When `customerCanSelect` is `true`:
   <body>
     <div id="paymob-widget"></div>
 
-    <script src="https://cdn.jsdelivr.net/npm/paymob-widget-alpha@latest/main.js" type="module"></script>
+    <script src="https://cdn.jsdelivr.net/npm/paymob-widget@latest/main.js" type="module"></script>
 
     <script>
       window.onload = () => {
         new PaymobWidget({
           publicKey: 'egy_pk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
           elementId: 'paymob-widget',
-          amount: 100000, // required — order total in cents (1000 EGP)
+          amount: 100000, // 1,000 EGP
           currency: 'EGP',
           integrationId: 123,
           theme: 'primary',
@@ -149,7 +161,151 @@ When `customerCanSelect` is `true`:
 </html>
 ```
 
-## Notes
+---
+
+## Use in a framework (React, Angular, Vue)
+
+The SDK ships as a single self-contained `main.js` — styles, fonts and icons are
+bundled in, so there are **no extra CSS files to import**. Loading the bundle
+registers the widget on `window.PaymobWidget`; you then create it against a
+container element from your component's lifecycle hook.
+
+You can load the bundle in either of two ways:
+
+- **npm** — `npm install paymob-widget`, then `import 'paymob-widget';` (a
+  side-effect import that registers `window.PaymobWidget`).
+- **CDN** — add `<script src="https://cdn.jsdelivr.net/npm/paymob-widget@latest/main.js" type="module"></script>` once (e.g. in `index.html`); no import needed.
+
+> The published bundle exposes the class on `window` (it does **not** provide a
+> named ESM export), so always construct it as `new window.PaymobWidget({...})`.
+> Use a **unique `elementId` per instance** if you render more than one widget.
+
+**TypeScript:** add this once (e.g. `paymob-widget.d.ts`) so `window.PaymobWidget` is typed:
+
+```ts
+interface PaymobWidgetPlan {
+  id: string | number;
+  tenure: number;
+  amount: number;
+}
+
+interface PaymobWidgetOptions {
+  publicKey: string;
+  elementId: string;
+  amount: number;
+  currency?: string;
+  integrationId?: number | number[];
+  theme?: 'primary' | 'light' | 'dark';
+  customerCanSelect?: boolean;
+  onSubmit?: (plan?: PaymobWidgetPlan) => void;
+}
+
+declare global {
+  interface Window {
+    PaymobWidget: new (options: PaymobWidgetOptions) => unknown;
+  }
+}
+
+export {};
+```
+
+### React
+
+```tsx
+import { useEffect } from 'react';
+import 'paymob-widget'; // registers window.PaymobWidget
+
+export function InstallmentsWidget() {
+  useEffect(() => {
+    new window.PaymobWidget({
+      publicKey: 'egy_pk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
+      elementId: 'paymob-widget',
+      amount: 100000, // 1,000 EGP
+      currency: 'EGP',
+      customerCanSelect: true,
+      onSubmit: (plan) => console.log('Selected plan', plan),
+    });
+  }, []);
+
+  return <div id="paymob-widget" />;
+}
+```
+
+### Angular
+
+Add `import 'paymob-widget';` (or the CDN `<script>` in `index.html`), then
+initialise the widget after the view is ready:
+
+```ts
+import { Component, AfterViewInit } from '@angular/core';
+import 'paymob-widget'; // registers window.PaymobWidget
+
+@Component({
+  selector: 'app-installments',
+  template: '<div id="paymob-widget"></div>',
+})
+export class InstallmentsComponent implements AfterViewInit {
+  ngAfterViewInit(): void {
+    new (window as any).PaymobWidget({
+      publicKey: 'egy_pk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
+      elementId: 'paymob-widget',
+      amount: 100000, // 1,000 EGP
+      currency: 'EGP',
+      customerCanSelect: true,
+      onSubmit: (plan: unknown) => console.log('Selected plan', plan),
+    });
+  }
+}
+```
+
+### Vue 3
+
+```vue
+<script setup lang="ts">
+import { onMounted } from 'vue';
+import 'paymob-widget'; // registers window.PaymobWidget
+
+onMounted(() => {
+  new window.PaymobWidget({
+    publicKey: 'egy_pk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
+    elementId: 'paymob-widget',
+    amount: 100000, // 1,000 EGP
+    currency: 'EGP',
+    customerCanSelect: true,
+    onSubmit: (plan) => console.log('Selected plan', plan),
+  });
+});
+</script>
+
+<template>
+  <div id="paymob-widget"></div>
+</template>
+```
+
+---
+
+## Troubleshooting — "the widget isn't showing"
+
+The widget renders **only** when all of these are true:
+
+- `amount` is a valid positive number (in cents).
+- The plans request to Paymob succeeds (returns a `2xx` status).
+- At least one installment plan is available for that amount.
+
+If any of these fail, the widget stays hidden and the reason is logged to the **browser console** (prefixed with `[PaymobWidget]`):
+
+| Symptom | Likely cause |
+| --- | --- |
+| Nothing renders, console shows an `amount` error | `amount` is missing, `0`, negative, or not a number. |
+| Nothing renders, console shows a status code (e.g. `400`) | The request to Paymob failed — check your `publicKey`, `integrationId`, and `currency`. |
+| Request succeeds but nothing renders | No plans are available — e.g. the amount is below the minimum, the integration has no bank installments configured, or the `integrationId` is invalid. |
+
+> **Note:** These errors are for developers only. Your customers never see error messages on the page or in the dialog.
+
+---
+
+## Good to know
 
-- **Rendering**: The widget renders into your `elementId` container only when eligible plans are available (see [When the widget is shown or hidden](#when-the-widget-is-shown-or-hidden)).
-- **Isolation**: UI is rendered inside a Shadow DOM wrapper to reduce CSS conflicts with the host page.
+- **Self-contained:** everything — CSS, the widget font, and icons — is inlined into `main.js`. There are no extra files to host or import; the single file is all you ship. (At runtime the widget still calls the Paymob API, and the design system may pull a few supplementary web fonts from Google Fonts, with graceful fallback.)
+- **Style isolation:** the widget renders inside a Shadow DOM, so its styles won't clash with your page's CSS (and your CSS won't bleed into it).
+- **Region:** the API region is chosen automatically from your public key's country prefix (`egy_`, `are_`, `sau_`, `pak_`, `omn_`).