@xpayeg/sdk 1.0.0 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @xpayeg/sdk
 
+## 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.
+
+## 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");
+  ```
+
 ## 1.0.0
 ### Major Changes
 

package/README.md

@@ -189,17 +189,6 @@ paymentElement.on('change', (event) => {
 });
 ```
 
-### Card Element (card form only -- you handle method selection)
-
-```javascript
-const cardElement = elements.create('card');
-cardElement.mount('#card-form');
-
-cardElement.on('change', (event) => {
-  console.log(event.complete, event.value.brand);
-});
-```
-
 ## Step 4: Confirm the Payment
 
 `confirm()` returns a tagged union -- check `type` to determine the outcome.
@@ -242,18 +231,10 @@ await checkout.confirm({
 | `redirect` | Behavior |
 |---|---|
 | Not set (default) | `"if_required"` — returns result to your code |
-| `"always"` | Redirects to `returnUrl` (client override) → server's `afterCompletion.redirect.url` |
+| `"always"` | Redirects to the session's `afterCompletion.redirect.url` |
 | `"if_required"` | Returns result to your code — no redirect |
 
-You can override the server's redirect URL from the client:
-
-```javascript
-await checkout.confirm({
-  customerDetails: { email, name },
-  redirect: 'always',
-  returnUrl: 'https://mysite.com/custom-success', // Overrides server URL
-});
-```
+Your server sets that URL when it creates the session. XPay navigates there unchanged, appending nothing.
 
 ### Pre-validation with `submit()`
 
@@ -477,7 +458,7 @@ elements.changeAppearance({ colorMode: 'light' });
 
 ## API Reference
 
-### `loadXPay(publishableKey?)`
+### `loadXPay(publishableKey)`
 
 Loads the XPay SDK from CDN. Returns a Promise. Call at module level, not inside components.
 

package/dist/index.d.cts

@@ -749,7 +749,11 @@ interface ChargeCardDetailsDto {
     expYear: number;
     funding: string;
     last4: string;
-    network: string;
+    /**
+     * Payment rails the transaction rode (e.g. mastercard for a Meeza card). Null until the charge is processed by the gateway.
+     * @nullable
+     */
+    network: string | null;
     /** Card fingerprint for identifying the same card across customers */
     fingerprint: string;
     threeDSecure: ThreeDSecureDto;
@@ -1347,6 +1351,16 @@ interface ChargeResponseDto {
     config: ChargeConfigDto;
     geocoding?: ChargeGeocodingDto;
     session?: ChargeSessionDto;
+    /**
+     * Origin of the page where this checkout ran — the merchant's site for embedded integrations (SDK Elements / drop-in), or our hosted checkout domain for hosted checkout and payment links. Null for merchant-initiated charges (recurring / MOTO).
+     * @nullable
+     */
+    merchantOrigin?: string | null;
+    /**
+     * Registrable domain (eTLD+1) derived from merchantOrigin.
+     * @nullable
+     */
+    merchantDomain?: string | null;
     processorCapabilities?: ProcessorCapabilitiesDto;
     /**
      * ID of the currently-active risk hold on this charge, if any
@@ -3158,6 +3172,8 @@ interface CheckoutSessionResponseDto {
     clientSecret?: string;
     /** Expiration timestamp (ISO 8601) */
     expiresAt?: string;
+    /** Whether this session can no longer be paid because it has expired (either swept/expired by status, or past `expiresAt`). Clients MUST render from this flag and MUST NOT re-derive expiry by comparing `expiresAt` against the local clock — a customer device running fast reads a live session as dead. */
+    isExpired: boolean;
     /** Customer ID (when existing customer linked) */
     customerId?: string;
     /** Customer object (when customerId is provided). Contains existing customer data for prefill. */
@@ -3406,7 +3422,7 @@ interface XPayError {
 interface XPayInstance {
     /**
      * Create an Elements instance for custom checkout UI.
-     * Use with `PaymentElement` or `CardElement` to render payment forms.
+     * Use with `PaymentElement` to render the payment form.
      *
      * @param options - Must include `clientSecret` from a checkout session
      * @returns An Elements instance for creating and managing payment elements
@@ -3456,7 +3472,7 @@ interface ElementsOptions {
     locale?: "en" | "ar";
 }
 /**
- * Manages the lifecycle of payment elements (PaymentElement, CardElement).
+ * Manages the lifecycle of the PaymentElement.
  *
  * A single Elements instance manages one embed iframe shared by all elements.
  * Provides session management methods (promo codes, quantities, etc.) and
@@ -3465,12 +3481,8 @@ interface ElementsOptions {
 interface Elements {
     /** Create a PaymentElement (full payment method selector + card form) */
     create(type: "payment", options?: PaymentElementOptions): PaymentElement;
-    /** Create a CardElement (card form only — merchant handles method selection) */
-    create(type: "card", options?: CardElementOptions): CardElement;
     /** Get an existing element by type, or null if not created */
     getElement(type: "payment"): PaymentElement | null;
-    /** Get an existing element by type, or null if not created */
-    getElement(type: "card"): CardElement | null;
     /** Fetch available payment methods for this session */
     fetchPaymentMethods(): Promise<PaymentMethodInfo[]>;
     /**
@@ -3536,11 +3548,6 @@ interface PaymentElementOptions {
     /** Custom ordering of payment methods by type */
     paymentMethodOrder?: string[];
 }
-/** Options for creating a CardElement */
-interface CardElementOptions {
-    /** Whether to show the cardholder name input */
-    showCardholderName?: boolean;
-}
 /**
  * Change event from a PaymentElement.
  * Fires on payment method selection, card field changes, and session updates.
@@ -3570,22 +3577,6 @@ interface PaymentElementChangeEvent {
     /** Full session data including updated amounts, fees, and discounts */
     session: CheckoutSession;
 }
-/**
- * Change event from a CardElement.
- * Fires when card fields change (input, validation, completion).
- */
-interface CardElementChangeEvent {
-    elementType: "card";
-    /** Whether all card fields are empty */
-    empty: boolean;
-    /** Whether all card fields are filled and valid */
-    complete: boolean;
-    /** Detected card details (available as user types) */
-    value: {
-        /** Card brand (e.g., "visa", "mastercard") — null until detected */
-        brand: string | null;
-    };
-}
 /** Base interface shared by all element types */
 interface BaseElement {
     /** Mount the element into a DOM container (CSS selector or HTMLElement) */
@@ -3614,17 +3605,17 @@ interface PaymentElement extends BaseElement {
     /** Update element options at runtime */
     update(options: Partial<PaymentElementOptions>): void;
 }
-/** CardElement — card-only form (merchant handles payment method selection) */
-interface CardElement extends BaseElement {
-    /** Update element options at runtime */
-    update(options: Partial<CardElementOptions>): void;
-}
 /**
  * Options for `confirmPayment()` or `checkout.confirm()`.
  *
  * The `redirect` option controls what happens after a successful payment:
  * - `"if_required"` (default) — returns the result to your code
- * - `"always"` — always redirects to `returnUrl` after payment
+ * - `"always"` — always redirects to the session's own destination after payment
+ *
+ * The destination is never set here. It is the `afterCompletion.redirect.url` you gave
+ * when creating the checkout session, because the same address is handed to the
+ * customer's bank during verification — before the browser leaves your page. A value
+ * supplied from the page could only ever disagree with what the bank was already told.
  *
  * @example
  * ```ts
@@ -3633,11 +3624,8 @@ interface CardElement extends BaseElement {
  *   customerDetails: { email: "user@example.com" },
  * });
  *
- * // Always redirect after payment
- * await checkout.confirm({
- *   redirect: "always",
- *   returnUrl: "https://merchant.com/success",
- * });
+ * // Always redirect to the session's own destination after payment
+ * await checkout.confirm({ redirect: "always" });
  * ```
  */
 interface ConfirmPaymentOptions {
@@ -3657,11 +3645,9 @@ interface ConfirmPaymentOptions {
     /**
      * Redirect behavior after payment.
      * - `"if_required"` (default) — returns the result to your code; only redirects if the payment method requires it
-     * - `"always"` — always redirects to `returnUrl` after payment. The page navigates away and the function never returns on success.
+     * - `"always"` — always redirects to the session's `afterCompletion.redirect.url` after payment. The page navigates away and the function never returns on success.
      */
     redirect?: "if_required" | "always";
-    /** URL to redirect to after payment. Overrides the session's `afterCompletion.redirect.url`. Only needed if you want a different URL than the one set server-side. */
-    returnUrl?: string;
 }
 /**
  * Options for creating a drop-in checkout instance.
@@ -3871,4 +3857,4 @@ declare global {
 declare function loadXPay(publishableKey: string): Promise<XPayInstance | null>;
 
 export { loadXPay };
-export type { ActionResult, Address, Appearance, BaseElement, CardElement, CardElementChangeEvent, CardElementOptions, CheckoutActions, CheckoutCompleteResult, DiscountResponseDto as CheckoutDiscount, CheckoutError, FeesResponseDto as CheckoutFees, CheckoutInstance, LineItemDto as CheckoutLineItem, CheckoutOptions, CheckoutSession, TotalDetailsResponseDto as CheckoutTotalDetails, ConfirmPaymentOptions, CustomerDetails, Elements, ElementsLoadErrorEvent, ElementsOptions, ElementsReadyEvent, InitCheckoutOptions, InitCheckoutResult, PaymentElement, PaymentElementChangeEvent, PaymentElementOptions, PaymentMethodInfo, SessionStatus, XPayError, XPayInstance };
+export type { ActionResult, Address, Appearance, BaseElement, CheckoutActions, CheckoutCompleteResult, DiscountResponseDto as CheckoutDiscount, CheckoutError, FeesResponseDto as CheckoutFees, CheckoutInstance, LineItemDto as CheckoutLineItem, CheckoutOptions, CheckoutSession, TotalDetailsResponseDto as CheckoutTotalDetails, ConfirmPaymentOptions, CustomerDetails, Elements, ElementsLoadErrorEvent, ElementsOptions, ElementsReadyEvent, InitCheckoutOptions, InitCheckoutResult, PaymentElement, PaymentElementChangeEvent, PaymentElementOptions, PaymentMethodInfo, SessionStatus, XPayError, XPayInstance };

package/dist/index.d.mts

@@ -749,7 +749,11 @@ interface ChargeCardDetailsDto {
     expYear: number;
     funding: string;
     last4: string;
-    network: string;
+    /**
+     * Payment rails the transaction rode (e.g. mastercard for a Meeza card). Null until the charge is processed by the gateway.
+     * @nullable
+     */
+    network: string | null;
     /** Card fingerprint for identifying the same card across customers */
     fingerprint: string;
     threeDSecure: ThreeDSecureDto;
@@ -1347,6 +1351,16 @@ interface ChargeResponseDto {
     config: ChargeConfigDto;
     geocoding?: ChargeGeocodingDto;
     session?: ChargeSessionDto;
+    /**
+     * Origin of the page where this checkout ran — the merchant's site for embedded integrations (SDK Elements / drop-in), or our hosted checkout domain for hosted checkout and payment links. Null for merchant-initiated charges (recurring / MOTO).
+     * @nullable
+     */
+    merchantOrigin?: string | null;
+    /**
+     * Registrable domain (eTLD+1) derived from merchantOrigin.
+     * @nullable
+     */
+    merchantDomain?: string | null;
     processorCapabilities?: ProcessorCapabilitiesDto;
     /**
      * ID of the currently-active risk hold on this charge, if any
@@ -3158,6 +3172,8 @@ interface CheckoutSessionResponseDto {
     clientSecret?: string;
     /** Expiration timestamp (ISO 8601) */
     expiresAt?: string;
+    /** Whether this session can no longer be paid because it has expired (either swept/expired by status, or past `expiresAt`). Clients MUST render from this flag and MUST NOT re-derive expiry by comparing `expiresAt` against the local clock — a customer device running fast reads a live session as dead. */
+    isExpired: boolean;
     /** Customer ID (when existing customer linked) */
     customerId?: string;
     /** Customer object (when customerId is provided). Contains existing customer data for prefill. */
@@ -3406,7 +3422,7 @@ interface XPayError {
 interface XPayInstance {
     /**
      * Create an Elements instance for custom checkout UI.
-     * Use with `PaymentElement` or `CardElement` to render payment forms.
+     * Use with `PaymentElement` to render the payment form.
      *
      * @param options - Must include `clientSecret` from a checkout session
      * @returns An Elements instance for creating and managing payment elements
@@ -3456,7 +3472,7 @@ interface ElementsOptions {
     locale?: "en" | "ar";
 }
 /**
- * Manages the lifecycle of payment elements (PaymentElement, CardElement).
+ * Manages the lifecycle of the PaymentElement.
  *
  * A single Elements instance manages one embed iframe shared by all elements.
  * Provides session management methods (promo codes, quantities, etc.) and
@@ -3465,12 +3481,8 @@ interface ElementsOptions {
 interface Elements {
     /** Create a PaymentElement (full payment method selector + card form) */
     create(type: "payment", options?: PaymentElementOptions): PaymentElement;
-    /** Create a CardElement (card form only — merchant handles method selection) */
-    create(type: "card", options?: CardElementOptions): CardElement;
     /** Get an existing element by type, or null if not created */
     getElement(type: "payment"): PaymentElement | null;
-    /** Get an existing element by type, or null if not created */
-    getElement(type: "card"): CardElement | null;
     /** Fetch available payment methods for this session */
     fetchPaymentMethods(): Promise<PaymentMethodInfo[]>;
     /**
@@ -3536,11 +3548,6 @@ interface PaymentElementOptions {
     /** Custom ordering of payment methods by type */
     paymentMethodOrder?: string[];
 }
-/** Options for creating a CardElement */
-interface CardElementOptions {
-    /** Whether to show the cardholder name input */
-    showCardholderName?: boolean;
-}
 /**
  * Change event from a PaymentElement.
  * Fires on payment method selection, card field changes, and session updates.
@@ -3570,22 +3577,6 @@ interface PaymentElementChangeEvent {
     /** Full session data including updated amounts, fees, and discounts */
     session: CheckoutSession;
 }
-/**
- * Change event from a CardElement.
- * Fires when card fields change (input, validation, completion).
- */
-interface CardElementChangeEvent {
-    elementType: "card";
-    /** Whether all card fields are empty */
-    empty: boolean;
-    /** Whether all card fields are filled and valid */
-    complete: boolean;
-    /** Detected card details (available as user types) */
-    value: {
-        /** Card brand (e.g., "visa", "mastercard") — null until detected */
-        brand: string | null;
-    };
-}
 /** Base interface shared by all element types */
 interface BaseElement {
     /** Mount the element into a DOM container (CSS selector or HTMLElement) */
@@ -3614,17 +3605,17 @@ interface PaymentElement extends BaseElement {
     /** Update element options at runtime */
     update(options: Partial<PaymentElementOptions>): void;
 }
-/** CardElement — card-only form (merchant handles payment method selection) */
-interface CardElement extends BaseElement {
-    /** Update element options at runtime */
-    update(options: Partial<CardElementOptions>): void;
-}
 /**
  * Options for `confirmPayment()` or `checkout.confirm()`.
  *
  * The `redirect` option controls what happens after a successful payment:
  * - `"if_required"` (default) — returns the result to your code
- * - `"always"` — always redirects to `returnUrl` after payment
+ * - `"always"` — always redirects to the session's own destination after payment
+ *
+ * The destination is never set here. It is the `afterCompletion.redirect.url` you gave
+ * when creating the checkout session, because the same address is handed to the
+ * customer's bank during verification — before the browser leaves your page. A value
+ * supplied from the page could only ever disagree with what the bank was already told.
  *
  * @example
  * ```ts
@@ -3633,11 +3624,8 @@ interface CardElement extends BaseElement {
  *   customerDetails: { email: "user@example.com" },
  * });
  *
- * // Always redirect after payment
- * await checkout.confirm({
- *   redirect: "always",
- *   returnUrl: "https://merchant.com/success",
- * });
+ * // Always redirect to the session's own destination after payment
+ * await checkout.confirm({ redirect: "always" });
  * ```
  */
 interface ConfirmPaymentOptions {
@@ -3657,11 +3645,9 @@ interface ConfirmPaymentOptions {
     /**
      * Redirect behavior after payment.
      * - `"if_required"` (default) — returns the result to your code; only redirects if the payment method requires it
-     * - `"always"` — always redirects to `returnUrl` after payment. The page navigates away and the function never returns on success.
+     * - `"always"` — always redirects to the session's `afterCompletion.redirect.url` after payment. The page navigates away and the function never returns on success.
      */
     redirect?: "if_required" | "always";
-    /** URL to redirect to after payment. Overrides the session's `afterCompletion.redirect.url`. Only needed if you want a different URL than the one set server-side. */
-    returnUrl?: string;
 }
 /**
  * Options for creating a drop-in checkout instance.
@@ -3871,4 +3857,4 @@ declare global {
 declare function loadXPay(publishableKey: string): Promise<XPayInstance | null>;
 
 export { loadXPay };
-export type { ActionResult, Address, Appearance, BaseElement, CardElement, CardElementChangeEvent, CardElementOptions, CheckoutActions, CheckoutCompleteResult, DiscountResponseDto as CheckoutDiscount, CheckoutError, FeesResponseDto as CheckoutFees, CheckoutInstance, LineItemDto as CheckoutLineItem, CheckoutOptions, CheckoutSession, TotalDetailsResponseDto as CheckoutTotalDetails, ConfirmPaymentOptions, CustomerDetails, Elements, ElementsLoadErrorEvent, ElementsOptions, ElementsReadyEvent, InitCheckoutOptions, InitCheckoutResult, PaymentElement, PaymentElementChangeEvent, PaymentElementOptions, PaymentMethodInfo, SessionStatus, XPayError, XPayInstance };
+export type { ActionResult, Address, Appearance, BaseElement, CheckoutActions, CheckoutCompleteResult, DiscountResponseDto as CheckoutDiscount, CheckoutError, FeesResponseDto as CheckoutFees, CheckoutInstance, LineItemDto as CheckoutLineItem, CheckoutOptions, CheckoutSession, TotalDetailsResponseDto as CheckoutTotalDetails, ConfirmPaymentOptions, CustomerDetails, Elements, ElementsLoadErrorEvent, ElementsOptions, ElementsReadyEvent, InitCheckoutOptions, InitCheckoutResult, PaymentElement, PaymentElementChangeEvent, PaymentElementOptions, PaymentMethodInfo, SessionStatus, XPayError, XPayInstance };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpayeg/sdk",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "XPay JavaScript SDK — loader and TypeScript types for embedding XPay payments",
   "license": "MIT",
   "type": "module",
@@ -32,21 +32,16 @@
     "CHANGELOG.md",
     "LICENSE"
   ],
-  "scripts": {
-    "build": "tsdown && rollup -c rollup.dts.config.mjs",
-    "lint:pkg": "publint && attw --pack .",
-    "typecheck": "tsc --noEmit"
-  },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
     "@rollup/plugin-node-resolve": "^16.0.3",
-    "@xpay/checkout-api": "workspace:*",
-    "@xpay/tsconfig": "workspace:*",
     "publint": "^0.3.21",
     "rollup": "^4.60.4",
     "rollup-plugin-dts": "^6.4.1",
     "tsdown": "^0.22.0",
-    "typescript": "catalog:"
+    "typescript": "5.9.3",
+    "@xpay/checkout-api": "0.0.0",
+    "@xpay/tsconfig": "0.0.0"
   },
   "repository": {
     "type": "git",
@@ -62,5 +57,10 @@
     "egypt",
     "checkout",
     "sdk"
-  ]
-}
+  ],
+  "scripts": {
+    "build": "tsdown && rollup -c rollup.dts.config.mjs",
+    "lint:pkg": "publint && attw --pack .",
+    "typecheck": "tsc --noEmit"
+  }
+}