@xpayeg/react 1.0.0 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @xpayeg/react
 
+## 2.0.0
+### Major Changes
+
+
+
+- [#331](https://github.com/xpayeg/xpay/pull/331) [`bdc6a48`](https://github.com/xpayeg/xpay/commit/bdc6a4865f8c0326a4c0eb3dd20808e1207d682a) Thanks [@Elmosh](https://github.com/Elmosh)! - **Breaking:** `returnUrl` is removed from `confirmPayment()` options. The return destination is always the checkout session's `afterCompletion.redirect.url`, set server-side at session creation.
+  
+  The URL is sent to the bank during authentication, before the browser leaves your page, so a value passed at confirm time could only ever conflict with what the bank already received. Delete `returnUrl` from `confirmPayment()` and set `afterCompletion.redirect.url` on `createSession`. `redirect: "always"` now follows that destination.
+  
+  **Breaking:** `afterCompletion` is now required for `uiMode: "embedded"` and `uiMode: "custom"`, and must be `type: "redirect"`. That URL is where the bank returns when authentication takes over the full page, which happens in in-app browsers where an embedded challenge cannot run. `hosted_confirmation` is rejected for these modes since those integrations run on your own site and there is no XPay page to return to.
+  
+  Also fixed: the 3DS challenge now renders at the size declared to the issuer (previously cropped or oversized), the overlay waits for the issuer's page to paint instead of showing an empty frame, and a challenge that cannot run in an iframe takes over the full tab instead of failing silently.
+
+### Patch Changes
+
+
+
+- [#333](https://github.com/xpayeg/xpay/pull/333) [`3dcea81`](https://github.com/xpayeg/xpay/commit/3dcea81b3e3f67267624105560c38f2615c35d96) Thanks [@Elmosh](https://github.com/Elmosh)! - Documentation: the `redirect: "always"` tables and examples now state that the destination is the checkout session's `afterCompletion.redirect.url`, set server-side at session creation.
+
+- Updated dependencies [[`3dcea81`](https://github.com/xpayeg/xpay/commit/3dcea81b3e3f67267624105560c38f2615c35d96), [`bdc6a48`](https://github.com/xpayeg/xpay/commit/bdc6a4865f8c0326a4c0eb3dd20808e1207d682a)]:
+  - @xpayeg/sdk@2.0.0
+
+## 1.0.1
+### Patch Changes
+
+
+
+- [#103](https://github.com/xpayeg/xpay/pull/103) [`7402e27`](https://github.com/xpayeg/xpay/commit/7402e27cde482148f126b2073694ef38386ea87a) Thanks [@Elmosh](https://github.com/Elmosh)! - Remove `CardElement` from both SDKs — `PaymentElement` is the only supported element going forward. It handles every payment method (Card, ValU, Fawry, etc.) through one unified UI and renders the appropriate fields based on the customer's choice.
+  
+  This release also republishes both packages through the proper `pnpm publish` flow, which fixes the `workspace:*` protocol leak in 1.0.0's `devDependencies` and `peerDependencies`. `npm install @xpayeg/sdk` and `npm install @xpayeg/react` now work cleanly.
+  
+  **Migration:** replace `elements.create("card")` with `elements.create("payment")`. If you previously rendered `<CardElement>` only when the user selected "Card" from your own picker, switch to `<PaymentElement>` which provides both the picker and the card form together.
+  
+  ```ts
+  // Before
+  const cardElement = elements.create("card");
+  cardElement.mount("#card");
+  
+  // After
+  const paymentElement = elements.create("payment");
+  paymentElement.mount("#payment");
+  ```
+- Updated dependencies [[`7402e27`](https://github.com/xpayeg/xpay/commit/7402e27cde482148f126b2073694ef38386ea87a)]:
+  - @xpayeg/sdk@1.0.1
+
 ## 1.0.0
 ### Major Changes
 

package/README.md

@@ -633,14 +633,6 @@ Renders the payment method selector and card form.
 | `className` | `string` | CSS class for the container div |
 | `id` | `string` | ID for the container div |
 
-### `<CardElement>`
-
-Card form only (no payment method selector).
-
-```tsx
-<CardElement onChange={(e) => console.log(e.complete, e.value.brand)} />
-```
-
 ### `<CheckoutButton>`
 
 Opens the drop-in checkout modal on click.
@@ -680,44 +672,6 @@ A button that opens the full checkout in a modal overlay. No form needed.
 </XPayProvider>
 ```
 
-### Card Element with Custom Payment Method Selector
-
-Build your own selector. Mount card form only when "Card" is selected.
-
-```tsx
-function CustomCheckout() {
-  const checkoutState = useCheckout();
-  const [method, setMethod] = useState("card");
-
-  if (checkoutState.type !== "success") return <div>Loading...</div>;
-
-  const { checkout } = checkoutState;
-
-  return (
-    <div>
-      <div className="flex gap-2">
-        {checkout.paymentMethods.map((pm) => (
-          <button
-            key={pm.type}
-            onClick={() => setMethod(pm.type)}
-            className={method === pm.type ? "border-blue-500 border-2" : "border-gray-200 border"}
-          >
-            {pm.displayName}
-          </button>
-        ))}
-      </div>
-
-      {method === "card" && <CardElement />}
-      {method !== "card" && <p>You will complete payment in a secure form.</p>}
-
-      <button onClick={() => checkout.confirm({ paymentMethod: method })}>
-        {method === "card" ? "Pay" : `Continue with ${method}`}
-      </button>
-    </div>
-  );
-}
-```
-
 ### Dark Mode Toggle
 
 Sync XPay appearance with your site's theme at runtime using `changeAppearance()`.
@@ -754,21 +708,16 @@ await checkout.confirm({
   redirect: "always",
 });
 // ^ If successful, the page navigates away. Code below only runs on error.
-
-// Override the redirect URL from the client:
-await checkout.confirm({
-  customerDetails: { email, name },
-  redirect: "always",
-  returnUrl: "https://mysite.com/custom-success",
-});
 ```
 
 | `redirect` | Behavior |
 |---|---|
 | Not set (default) | `"if_required"` — returns result to your code |
-| `"always"` | Redirects to `returnUrl` (client) → server's `afterCompletion.redirect.url` |
+| `"always"` | Redirects to the session's `afterCompletion.redirect.url` |
 | `"if_required"` | Returns result to your code — no redirect |
 
+Your server sets that URL when it creates the session. XPay navigates there unchanged, appending nothing.
+
 ---
 
 ## Appearance

package/dist/index.cjs

@@ -388,7 +388,7 @@ function isEqual(a, b) {
 const isServer = typeof window === "undefined";
 //#endregion
 //#region src/PaymentElement.tsx
-const IMMUTABLE_OPTS$1 = [];
+const IMMUTABLE_OPTS = [];
 const PaymentElementClient = ({ options, onReady, onChange, onLoaderStart, onLoadError, className, id }) => {
 	const elements = useElements();
 	const containerRef = (0, react.useRef)(null);
@@ -415,7 +415,7 @@ const PaymentElementClient = ({ options, onReady, onChange, onLoaderStart, onLoa
 	}, []);
 	(0, react.useEffect)(() => {
 		if (!element || !options) return;
-		const updates = extractAllowedOptionsUpdates(options, prevOptions, IMMUTABLE_OPTS$1);
+		const updates = extractAllowedOptionsUpdates(options, prevOptions, IMMUTABLE_OPTS);
 		if (updates && "update" in element) element.update(updates);
 	}, [
 		options,
@@ -457,72 +457,6 @@ const PaymentElementServer = ({ className, id }) => {
 */
 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 = (0, react.useRef)(null);
-	const elementRef = (0, react.useRef)(null);
-	const [element, setElement] = (0, react.useState)(null);
-	const prevOptions = usePrevious(options);
-	(0, react.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]);
-	(0, react.useLayoutEffect)(() => {
-		return () => {
-			if (elementRef.current) {
-				try {
-					elementRef.current.destroy();
-				} catch {}
-				elementRef.current = null;
-			}
-			setElement(null);
-		};
-	}, []);
-	(0, react.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__ */ (0, react_jsx_runtime.jsx)("div", {
-		ref: containerRef,
-		className,
-		id
-	});
-};
-const CardElementServer = ({ className, id }) => {
-	return /* @__PURE__ */ (0, react_jsx_runtime.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.
@@ -566,7 +500,6 @@ const CheckoutButton = ({ clientSecret, children = "Pay", checkoutOptions, class
 	});
 };
 //#endregion
-exports.CardElement = CardElement;
 exports.CheckoutButton = CheckoutButton;
 exports.PaymentElement = PaymentElement;
 exports.XPayProvider = XPayProvider;

package/dist/index.d.cts

@@ -1,8 +1,8 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode, FC } from 'react';
 import * as _xpayeg_sdk from '@xpayeg/sdk';
-import { CheckoutSession, CheckoutActions, XPayInstance, ElementsOptions, Elements, PaymentElementOptions, PaymentElementChangeEvent, CardElementOptions, CardElementChangeEvent, CheckoutOptions } from '@xpayeg/sdk';
-export { ActionResult, Appearance, CardElementChangeEvent, CheckoutActions, CheckoutSession, ConfirmPaymentOptions, ElementsOptions, PaymentElementChangeEvent, PaymentMethodInfo, XPayError } from '@xpayeg/sdk';
+import { CheckoutSession, CheckoutActions, XPayInstance, ElementsOptions, Elements, PaymentElementOptions, PaymentElementChangeEvent, CheckoutOptions } from '@xpayeg/sdk';
+export { ActionResult, Appearance, CheckoutActions, CheckoutSession, ConfirmPaymentOptions, ElementsOptions, PaymentElementChangeEvent, PaymentMethodInfo, XPayError } from '@xpayeg/sdk';
 
 /**
  * The checkout object returned by `useCheckout()` on success.
@@ -168,41 +168,6 @@ interface PaymentElementProps {
  */
 declare const PaymentElement: FC<PaymentElementProps>;
 
-interface CardElementProps {
-    /** Element configuration options */
-    options?: CardElementOptions;
-    /** Fired when the element is mounted and the iframe content is ready */
-    onReady?: () => void;
-    /** Fired on every card field change — use `event.complete` to enable/disable your pay button */
-    onChange?: (event: CardElementChangeEvent) => void;
-    /** Fired when the element's iframe starts loading */
-    onLoaderStart?: () => void;
-    /** Fired when the element fails to load */
-    onLoadError?: (event: {
-        type: string;
-        message: string;
-        code?: string;
-    }) => void;
-    /** CSS class name for the container `<div>` */
-    className?: string;
-    /** HTML id for the container `<div>` */
-    id?: string;
-}
-/**
- * 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)}
- * />
- * ```
- */
-declare const CardElement: FC<CardElementProps>;
-
 interface CheckoutButtonProps {
     /** Checkout session client secret */
     clientSecret: string;
@@ -235,5 +200,5 @@ interface CheckoutButtonProps {
  */
 declare const CheckoutButton: FC<CheckoutButtonProps>;
 
-export { CardElement, CheckoutButton, PaymentElement, XPayProvider, useCheckout, useConfirmPayment, useElements, useXPay };
-export type { CardElementProps, Checkout, CheckoutButtonProps, PaymentElementProps, UseCheckoutResult };
+export { CheckoutButton, PaymentElement, XPayProvider, useCheckout, useConfirmPayment, useElements, useXPay };
+export type { Checkout, CheckoutButtonProps, PaymentElementProps, UseCheckoutResult };

package/dist/index.d.mts

@@ -1,8 +1,8 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode, FC } from 'react';
 import * as _xpayeg_sdk from '@xpayeg/sdk';
-import { CheckoutSession, CheckoutActions, XPayInstance, ElementsOptions, Elements, PaymentElementOptions, PaymentElementChangeEvent, CardElementOptions, CardElementChangeEvent, CheckoutOptions } from '@xpayeg/sdk';
-export { ActionResult, Appearance, CardElementChangeEvent, CheckoutActions, CheckoutSession, ConfirmPaymentOptions, ElementsOptions, PaymentElementChangeEvent, PaymentMethodInfo, XPayError } from '@xpayeg/sdk';
+import { CheckoutSession, CheckoutActions, XPayInstance, ElementsOptions, Elements, PaymentElementOptions, PaymentElementChangeEvent, CheckoutOptions } from '@xpayeg/sdk';
+export { ActionResult, Appearance, CheckoutActions, CheckoutSession, ConfirmPaymentOptions, ElementsOptions, PaymentElementChangeEvent, PaymentMethodInfo, XPayError } from '@xpayeg/sdk';
 
 /**
  * The checkout object returned by `useCheckout()` on success.
@@ -168,41 +168,6 @@ interface PaymentElementProps {
  */
 declare const PaymentElement: FC<PaymentElementProps>;
 
-interface CardElementProps {
-    /** Element configuration options */
-    options?: CardElementOptions;
-    /** Fired when the element is mounted and the iframe content is ready */
-    onReady?: () => void;
-    /** Fired on every card field change — use `event.complete` to enable/disable your pay button */
-    onChange?: (event: CardElementChangeEvent) => void;
-    /** Fired when the element's iframe starts loading */
-    onLoaderStart?: () => void;
-    /** Fired when the element fails to load */
-    onLoadError?: (event: {
-        type: string;
-        message: string;
-        code?: string;
-    }) => void;
-    /** CSS class name for the container `<div>` */
-    className?: string;
-    /** HTML id for the container `<div>` */
-    id?: string;
-}
-/**
- * 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)}
- * />
- * ```
- */
-declare const CardElement: FC<CardElementProps>;
-
 interface CheckoutButtonProps {
     /** Checkout session client secret */
     clientSecret: string;
@@ -235,5 +200,5 @@ interface CheckoutButtonProps {
  */
 declare const CheckoutButton: FC<CheckoutButtonProps>;
 
-export { CardElement, CheckoutButton, PaymentElement, XPayProvider, useCheckout, useConfirmPayment, useElements, useXPay };
-export type { CardElementProps, Checkout, CheckoutButtonProps, PaymentElementProps, UseCheckoutResult };
+export { CheckoutButton, PaymentElement, XPayProvider, useCheckout, useConfirmPayment, useElements, useXPay };
+export type { Checkout, CheckoutButtonProps, PaymentElementProps, UseCheckoutResult };

package/dist/index.mjs

@@ -387,7 +387,7 @@ function isEqual(a, b) {
 const isServer = typeof window === "undefined";
 //#endregion
 //#region src/PaymentElement.tsx
-const IMMUTABLE_OPTS$1 = [];
+const IMMUTABLE_OPTS = [];
 const PaymentElementClient = ({ options, onReady, onChange, onLoaderStart, onLoadError, className, id }) => {
 	const elements = useElements();
 	const containerRef = useRef(null);
@@ -414,7 +414,7 @@ const PaymentElementClient = ({ options, onReady, onChange, onLoaderStart, onLoa
 	}, []);
 	useEffect(() => {
 		if (!element || !options) return;
-		const updates = extractAllowedOptionsUpdates(options, prevOptions, IMMUTABLE_OPTS$1);
+		const updates = extractAllowedOptionsUpdates(options, prevOptions, IMMUTABLE_OPTS);
 		if (updates && "update" in element) element.update(updates);
 	}, [
 		options,
@@ -456,72 +456,6 @@ const PaymentElementServer = ({ className, id }) => {
 */
 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.
@@ -565,4 +499,4 @@ const CheckoutButton = ({ clientSecret, children = "Pay", checkoutOptions, class
 	});
 };
 //#endregion
-export { CardElement, CheckoutButton, PaymentElement, XPayProvider, useCheckout, useConfirmPayment, useElements, useXPay };
+export { CheckoutButton, PaymentElement, XPayProvider, useCheckout, useConfirmPayment, useElements, useXPay };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xpayeg/react",
-  "version": "1.0.0",
-  "description": "XPay React components — PaymentElement, CardElement, CheckoutButton, and hooks",
+  "version": "2.0.0",
+  "description": "XPay React components — PaymentElement, CheckoutButton, and hooks",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
@@ -32,30 +32,25 @@
     "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"
+    "react-dom": "^18 || ^19",
+    "@xpayeg/sdk": "2.0.0"
   },
   "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:*",
+    "@types/react": "19.2.7",
+    "@types/react-dom": "19.2.3",
     "publint": "^0.3.21",
-    "react": "catalog:",
-    "react-dom": "catalog:",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
     "rollup": "^4.60.4",
     "rollup-plugin-dts": "^6.4.1",
     "tsdown": "^0.22.0",
-    "typescript": "catalog:"
+    "typescript": "5.9.3",
+    "@xpay/tsconfig": "0.0.0",
+    "@xpayeg/sdk": "2.0.0"
   },
   "repository": {
     "type": "git",
@@ -72,5 +67,10 @@
     "egypt",
     "checkout",
     "sdk"
-  ]
-}
+  ],
+  "scripts": {
+    "build": "tsdown && rollup -c rollup.dts.config.mjs",
+    "lint:pkg": "publint && attw --pack .",
+    "typecheck": "tsc --noEmit"
+  }
+}