@xpayeg/react 1.0.0

package/dist/index.mjs

@@ -0,0 +1,568 @@
+import { createContext, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/context.tsx
+const XPayContext = createContext(null);
+const ElementsContext = createContext(null);
+/** Build a minimal XPayError for SDK-level failures (elements not initialized, etc.) */
+function notInitializedError() {
+	return {
+		type: "api_error",
+		code: null,
+		message: "Elements not initialized",
+		param: null,
+		docUrl: null,
+		declineCode: null,
+		adviceCode: null,
+		chargeId: null,
+		paymentMethodId: null,
+		paymentMethodType: null,
+		paymentMethod: null
+	};
+}
+const CheckoutContext = createContext(null);
+/**
+* Provides XPay context to all child components.
+*
+* Accepts either a resolved XPay instance or a Promise (from `loadXPay()`).
+* When `options` (with `clientSecret`) is provided, creates an Elements instance
+* and fetches session data. Use `useCheckout()` in child components to access
+* session data and action methods.
+*
+* @example
+* ```tsx
+* import { loadXPay } from "@xpayeg/sdk";
+* import { XPayProvider, useCheckout, PaymentElement } from "@xpayeg/react";
+*
+* const xpayPromise = loadXPay("pk_test_xxx");
+*
+* function App() {
+*   return (
+*     <XPayProvider xpay={xpayPromise} options={{ clientSecret }}>
+*       <CheckoutForm />
+*     </XPayProvider>
+*   );
+* }
+* ```
+*/
+function XPayProvider({ xpay: xpayProp, options, children }) {
+	const [resolvedXPay, setResolvedXPay] = useState(xpayProp && !(xpayProp instanceof Promise) ? xpayProp : null);
+	const [xpayError, setXpayError] = useState(null);
+	useEffect(() => {
+		if (!xpayProp) return;
+		if (!(xpayProp instanceof Promise)) {
+			setResolvedXPay(xpayProp);
+			return;
+		}
+		let cancelled = false;
+		xpayProp.then((instance) => {
+			if (!cancelled) setResolvedXPay(instance);
+		}).catch((err) => {
+			if (!cancelled) setXpayError(err instanceof Error ? err.message : "Failed to load XPay");
+		});
+		return () => {
+			cancelled = true;
+		};
+	}, [xpayProp]);
+	const elements = useMemo(() => {
+		if (!resolvedXPay || !options?.clientSecret) return null;
+		return resolvedXPay.elements(options);
+	}, [resolvedXPay, options?.clientSecret]);
+	const [session, setSession] = useState(null);
+	const [sessionError, setSessionError] = useState(null);
+	useEffect(() => {
+		if (!elements) return;
+		const onReady = (data) => {
+			setSession(data.session);
+		};
+		const onChange = (data) => {
+			const newSession = data;
+			if (newSession) setSession(newSession);
+		};
+		const onError = (data) => {
+			const d = data;
+			setSessionError(d.message || d.error || "Failed to load session");
+		};
+		elements.on("ready", onReady);
+		elements.on("change", onChange);
+		elements.on("loaderror", onError);
+	}, [elements]);
+	const checkoutState = useMemo(() => {
+		const errorMsg = xpayError || sessionError;
+		if (errorMsg) return {
+			type: "error",
+			error: { message: errorMsg }
+		};
+		if (!resolvedXPay || !elements || !session) return { type: "loading" };
+		return {
+			type: "success",
+			session,
+			elements,
+			xpay: resolvedXPay
+		};
+	}, [
+		resolvedXPay,
+		elements,
+		session,
+		xpayError,
+		sessionError
+	]);
+	const xpayValue = useMemo(() => resolvedXPay, [resolvedXPay]);
+	const elementsValue = useMemo(() => elements, [elements]);
+	return /* @__PURE__ */ jsx(XPayContext.Provider, {
+		value: xpayValue,
+		children: /* @__PURE__ */ jsx(ElementsContext.Provider, {
+			value: elementsValue,
+			children: /* @__PURE__ */ jsx(CheckoutContext.Provider, {
+				value: checkoutState,
+				children
+			})
+		})
+	});
+}
+/**
+* Access the checkout state — a tagged union of `loading`, `error`, or `success`.
+*
+* On success, returns a `checkout` object (type `Checkout`) that merges
+* session data with action methods (confirm, promo codes, quantities, etc.).
+*
+* @returns `UseCheckoutResult` — narrow the type by checking `result.type`
+* @throws Error if used outside of `<XPayProvider>`
+*
+* @example
+* ```tsx
+* function CheckoutForm() {
+*   const state = useCheckout();
+*
+*   if (state.type === "loading") return <Skeleton />;
+*   if (state.type === "error") return <p>{state.error.message}</p>;
+*
+*   const { checkout } = state;
+*   return <button onClick={() => checkout.confirm()}>
+*     Pay {checkout.currency} {checkout.amountTotal}
+*   </button>;
+* }
+* ```
+*/
+function useCheckout() {
+	const ctx = useContext(CheckoutContext);
+	if (!ctx) throw new Error("Could not find XPay context. Wrap the part of your app that calls useCheckout() in an <XPayProvider> provider.");
+	const { confirmFn, applyPromoFn, removePromoFn, updateLineItemQtyFn, submitFn, fetchUpdatesFn, changeAppearanceFn, onChangeFn, getElementsFn } = useCheckoutActions(ctx);
+	return useMemo(() => {
+		if (ctx.type === "loading") return { type: "loading" };
+		if (ctx.type === "error") return {
+			type: "error",
+			error: ctx.error
+		};
+		return {
+			type: "success",
+			checkout: {
+				...ctx.session,
+				confirm: confirmFn,
+				applyPromotionCode: applyPromoFn,
+				removePromotionCode: removePromoFn,
+				updateLineItemQuantity: updateLineItemQtyFn,
+				submit: submitFn,
+				fetchUpdates: fetchUpdatesFn,
+				changeAppearance: changeAppearanceFn,
+				on: onChangeFn,
+				getElements: getElementsFn
+			}
+		};
+	}, [
+		ctx,
+		confirmFn,
+		applyPromoFn,
+		removePromoFn,
+		updateLineItemQtyFn,
+		submitFn,
+		fetchUpdatesFn,
+		changeAppearanceFn,
+		onChangeFn,
+		getElementsFn
+	]);
+}
+/** Build stable action callbacks from internal state */
+function useCheckoutActions(ctx) {
+	const elements = ctx.type === "success" ? ctx.elements : null;
+	const xpay = ctx.type === "success" ? ctx.xpay : null;
+	return {
+		confirmFn: useCallback(async (opts) => {
+			if (!xpay || !elements) return {
+				type: "error",
+				error: {
+					type: "invalid_request_error",
+					code: null,
+					declineCode: null,
+					adviceCode: null,
+					message: "XPay not initialized",
+					docUrl: null,
+					chargeId: null,
+					paymentMethodId: null,
+					paymentMethodType: null,
+					paymentMethod: null
+				}
+			};
+			return xpay.confirmPayment({
+				...opts,
+				elements
+			});
+		}, [xpay, elements]),
+		applyPromoFn: useCallback(async (code) => {
+			if (!elements) return {
+				type: "error",
+				error: notInitializedError()
+			};
+			return elements.applyPromotionCode(code);
+		}, [elements]),
+		removePromoFn: useCallback(async () => {
+			if (!elements) return {
+				type: "error",
+				error: notInitializedError()
+			};
+			return elements.removePromotionCode();
+		}, [elements]),
+		updateLineItemQtyFn: useCallback(async (args) => {
+			if (!elements) return {
+				type: "error",
+				error: notInitializedError()
+			};
+			return elements.updateLineItemQuantity(args);
+		}, [elements]),
+		submitFn: useCallback(async () => {
+			if (!elements) return { error: notInitializedError() };
+			return elements.submit();
+		}, [elements]),
+		fetchUpdatesFn: useCallback(async () => {
+			if (!elements) return {
+				type: "error",
+				error: notInitializedError()
+			};
+			return elements.fetchUpdates();
+		}, [elements]),
+		changeAppearanceFn: useCallback((appearance) => {
+			elements?.changeAppearance(appearance);
+		}, [elements]),
+		onChangeFn: useCallback(((event, handler) => {
+			elements?.on(event, handler);
+		}), [elements]),
+		getElementsFn: useCallback(() => {
+			if (!elements) throw new Error("Elements not initialized");
+			return elements;
+		}, [elements])
+	};
+}
+/**
+* Access the raw XPay SDK instance. Returns `null` while the SDK is loading.
+*
+* Most merchants should use `useCheckout()` instead. Use `useXPay()` only when
+* you need direct access to `xpay.confirmPayment()` or `xpay.checkout()`.
+*/
+function useXPay() {
+	return useContext(XPayContext);
+}
+/**
+* Access the Elements instance. Returns `null` while the session is loading.
+*
+* Use this for direct element management. In most cases, use `useCheckout()` instead
+* which provides both session data and action methods.
+*/
+function useElements() {
+	return useContext(ElementsContext);
+}
+//#endregion
+//#region src/hooks.ts
+/**
+* Convenience hook for payment confirmation.
+*
+* @example
+* ```tsx
+* const { confirmPayment, isConfirming } = useConfirmPayment();
+* ```
+*/
+function useConfirmPayment() {
+	const result = useCheckout();
+	if (result.type !== "success") return {
+		confirmPayment: async () => ({
+			type: "error",
+			error: {
+				message: "Checkout not ready",
+				code: null
+			}
+		}),
+		isConfirming: false
+	};
+	return {
+		confirmPayment: result.checkout.confirm,
+		isConfirming: false
+	};
+}
+//#endregion
+//#region src/utils/useAttachEvent.ts
+/**
+* Attach an event listener to an element without causing listener churn on re-renders.
+*
+* Stores the callback in a ref so the actual listener remains stable.
+* Inspired by Stripe's useAttachEvent pattern.
+*/
+function useAttachEvent(element, event, cb) {
+	const cbDefined = !!cb;
+	const cbRef = useRef(cb);
+	useEffect(() => {
+		cbRef.current = cb;
+	}, [cb]);
+	useEffect(() => {
+		if (!cbDefined || !element) return;
+		const decoratedCb = (...args) => {
+			if (cbRef.current) cbRef.current(...args);
+		};
+		element.on(event, decoratedCb);
+		return () => {
+			element.off(event, decoratedCb);
+		};
+	}, [
+		cbDefined,
+		event,
+		element
+	]);
+}
+//#endregion
+//#region src/utils/usePrevious.ts
+/**
+* Returns the previous value of a variable.
+* Useful for detecting prop changes between renders.
+*/
+function usePrevious(value) {
+	const ref = useRef(void 0);
+	useEffect(() => {
+		ref.current = value;
+	}, [value]);
+	return ref.current;
+}
+//#endregion
+//#region src/utils/extractAllowedOptionsUpdates.ts
+/**
+* Extract only the changed, mutable options from a new options object.
+*
+* Returns null if nothing changed. Warns if immutable keys are modified.
+* Inspired by Stripe's extractAllowedOptionsUpdates pattern.
+*/
+function extractAllowedOptionsUpdates(options, prevOptions, immutableKeys) {
+	if (!options) return null;
+	let updates = null;
+	for (const key of Object.keys(options)) {
+		const isUpdated = !prevOptions || !isEqual(options[key], prevOptions[key]);
+		if (immutableKeys.includes(key)) {
+			if (isUpdated && prevOptions) console.warn(`Unsupported prop change: options.${key} is not a mutable property.`);
+			continue;
+		}
+		if (!isUpdated) continue;
+		updates = {
+			...updates || {},
+			[key]: options[key]
+		};
+	}
+	return updates;
+}
+function isEqual(a, b) {
+	if (a === b) return true;
+	if (a == null || b == null) return false;
+	if (typeof a !== typeof b) return false;
+	if (Array.isArray(a) && Array.isArray(b)) {
+		if (a.length !== b.length) return false;
+		return a.every((v, i) => isEqual(v, b[i]));
+	}
+	if (typeof a === "object" && typeof b === "object") {
+		const aObj = a;
+		const bObj = b;
+		const aKeys = Object.keys(aObj);
+		const bKeys = Object.keys(bObj);
+		if (aKeys.length !== bKeys.length) return false;
+		return aKeys.every((key) => isEqual(aObj[key], bObj[key]));
+	}
+	return false;
+}
+//#endregion
+//#region src/utils/isServer.ts
+/** True when running in a server environment (SSR/RSC) */
+const isServer = typeof window === "undefined";
+//#endregion
+//#region src/PaymentElement.tsx
+const IMMUTABLE_OPTS$1 = [];
+const PaymentElementClient = ({ options, onReady, onChange, onLoaderStart, onLoadError, className, id }) => {
+	const elements = useElements();
+	const containerRef = useRef(null);
+	const elementRef = useRef(null);
+	const [element, setElement] = useState(null);
+	const prevOptions = usePrevious(options);
+	useLayoutEffect(() => {
+		if (elementRef.current !== null || !elements || !containerRef.current) return;
+		const el = elements.create("payment", options);
+		elementRef.current = el;
+		setElement(el);
+		el.mount(containerRef.current);
+	}, [elements]);
+	useLayoutEffect(() => {
+		return () => {
+			if (elementRef.current) {
+				try {
+					elementRef.current.destroy();
+				} catch {}
+				elementRef.current = null;
+			}
+			setElement(null);
+		};
+	}, []);
+	useEffect(() => {
+		if (!element || !options) return;
+		const updates = extractAllowedOptionsUpdates(options, prevOptions, IMMUTABLE_OPTS$1);
+		if (updates && "update" in element) element.update(updates);
+	}, [
+		options,
+		prevOptions,
+		element
+	]);
+	useAttachEvent(element, "ready", onReady);
+	useAttachEvent(element, "change", onChange);
+	useAttachEvent(element, "loaderstart", onLoaderStart);
+	useAttachEvent(element, "loaderror", onLoadError);
+	return /* @__PURE__ */ jsx("div", {
+		ref: containerRef,
+		className,
+		id
+	});
+};
+/** SSR placeholder — renders an empty div for hydration */
+const PaymentElementServer = ({ className, id }) => {
+	return /* @__PURE__ */ jsx("div", {
+		className,
+		id
+	});
+};
+/**
+* Renders the XPay Payment Element — a full payment method selector with card form.
+*
+* Must be used inside `<XPayProvider>` with an `options` prop containing `clientSecret`.
+* Handles mount/unmount lifecycle, StrictMode, and SSR automatically.
+*
+* @example
+* ```tsx
+* <XPayProvider xpay={xpayPromise} options={{ clientSecret }}>
+*   <PaymentElement
+*     onChange={(e) => setPaymentReady(e.complete)}
+*     onLoadError={(e) => console.error(e.message)}
+*   />
+* </XPayProvider>
+* ```
+*/
+const PaymentElement = isServer ? PaymentElementServer : PaymentElementClient;
+//#endregion
+//#region src/CardElement.tsx
+const IMMUTABLE_OPTS = [];
+const CardElementClient = ({ options, onReady, onChange, onLoaderStart, onLoadError, className, id }) => {
+	const elements = useElements();
+	const containerRef = useRef(null);
+	const elementRef = useRef(null);
+	const [element, setElement] = useState(null);
+	const prevOptions = usePrevious(options);
+	useLayoutEffect(() => {
+		if (elementRef.current !== null || !elements || !containerRef.current) return;
+		const el = elements.create("card", options);
+		elementRef.current = el;
+		setElement(el);
+		el.mount(containerRef.current);
+	}, [elements]);
+	useLayoutEffect(() => {
+		return () => {
+			if (elementRef.current) {
+				try {
+					elementRef.current.destroy();
+				} catch {}
+				elementRef.current = null;
+			}
+			setElement(null);
+		};
+	}, []);
+	useEffect(() => {
+		if (!element || !options) return;
+		const updates = extractAllowedOptionsUpdates(options, prevOptions, IMMUTABLE_OPTS);
+		if (updates && "update" in element) element.update(updates);
+	}, [
+		options,
+		prevOptions,
+		element
+	]);
+	useAttachEvent(element, "ready", onReady);
+	useAttachEvent(element, "change", onChange);
+	useAttachEvent(element, "loaderstart", onLoaderStart);
+	useAttachEvent(element, "loaderror", onLoadError);
+	return /* @__PURE__ */ jsx("div", {
+		ref: containerRef,
+		className,
+		id
+	});
+};
+const CardElementServer = ({ className, id }) => {
+	return /* @__PURE__ */ jsx("div", {
+		className,
+		id
+	});
+};
+/**
+* Renders the XPay Card Element — a card-only form (number, expiry, CVV).
+*
+* Use this when you handle payment method selection yourself.
+* Must be used inside `<XPayProvider>` with an `options` prop containing `clientSecret`.
+*
+* @example
+* ```tsx
+* <CardElement
+*   onChange={(e) => setCardReady(e.complete)}
+* />
+* ```
+*/
+const CardElement = isServer ? CardElementServer : CardElementClient;
+//#endregion
+//#region src/CheckoutButton.tsx
+/**
+* Button that opens the drop-in checkout modal on click.
+*
+* Must be inside XPayProvider.
+*
+* @example
+* ```tsx
+* <XPayProvider xpay={xpay}>
+*   <CheckoutButton
+*     clientSecret="cs_test_abc_secret_xyz"
+*     checkoutOptions={{
+*       onComplete: (result) => router.push('/success'),
+*       onClose: () => console.log('Closed'),
+*     }}
+*   >
+*     Pay Now
+*   </CheckoutButton>
+* </XPayProvider>
+* ```
+*/
+const CheckoutButton = ({ clientSecret, children = "Pay", checkoutOptions, className, disabled }) => {
+	const xpay = useXPay();
+	return /* @__PURE__ */ jsx("button", {
+		type: "button",
+		onClick: useCallback(() => {
+			if (!xpay) return;
+			xpay.checkout({
+				clientSecret,
+				mode: "modal",
+				...checkoutOptions
+			}).open();
+		}, [
+			xpay,
+			clientSecret,
+			checkoutOptions
+		]),
+		disabled: disabled || !xpay,
+		className,
+		children
+	});
+};
+//#endregion
+export { CardElement, CheckoutButton, PaymentElement, XPayProvider, useCheckout, useConfirmPayment, useElements, useXPay };

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@xpayeg/react",
+  "version": "1.0.0",
+  "description": "XPay React components — PaymentElement, CardElement, CheckoutButton, and hooks",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsdown && rollup -c rollup.dts.config.mjs",
+    "lint:pkg": "publint && attw --pack .",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@xpayeg/sdk": "workspace:*",
+    "react": "^18 || ^19",
+    "react-dom": "^18 || ^19"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.2",
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
+    "@xpay/tsconfig": "workspace:*",
+    "@xpayeg/sdk": "workspace:*",
+    "publint": "^0.3.21",
+    "react": "catalog:",
+    "react-dom": "catalog:",
+    "rollup": "^4.60.4",
+    "rollup-plugin-dts": "^6.4.1",
+    "tsdown": "^0.22.0",
+    "typescript": "catalog:"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xpayeg/xpay-react.git"
+  },
+  "bugs": {
+    "url": "https://github.com/xpayeg/xpay-react/issues"
+  },
+  "homepage": "https://github.com/xpayeg/xpay-react#readme",
+  "keywords": [
+    "xpay",
+    "react",
+    "payments",
+    "egypt",
+    "checkout",
+    "sdk"
+  ]
+}