@qredex/react 1.0.3 → 1.0.5

package/README.md

@@ -1,4 +1,21 @@
-span
+<!--
+    ▄▄▄▄
+  ▄█▀▀███▄▄              █▄
+  ██    ██ ▄             ██
+  ██    ██ ████▄▄█▀█▄ ▄████ ▄█▀█▄▀██ ██▀
+  ██  ▄ ██ ██   ██▄█▀ ██ ██ ██▄█▀  ███
+   ▀█████▄▄█▀  ▄▀█▄▄▄▄█▀███▄▀█▄▄▄▄██ ██▄
+        ▀█
+
+  Copyright (C) 2026 — 2026, Qredex, LTD. All Rights Reserved.
+
+  DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+
+  This file is part of the Qredex Agent SDK and is licensed under the MIT License. See LICENSE.
+  Redistribution and use are permitted under that license.
+
+  If you need additional information or have any questions, please email: copyright@qredex.com
+-->
 
 # @qredex/react
 
@@ -17,13 +34,17 @@ npm install @qredex/react
 
 ## Attribution Flow
 
-![React wrapper attribution flow](https://raw.githubusercontent.com/Qredex/qredex-agent/main/docs/diagrams/wrapper-attribution-sequence.svg?v=20260313-2)
+![React wrapper attribution flow](https://raw.githubusercontent.com/Qredex/qredex-agent/main/docs/diagrams/wrapper-attribution-sequence.svg?v=20260313-3)
 
 Call `useQredexAgent()`, then forward merchant cart state with `agent.handleCartChange(...)`, read the PIT with `agent.getPurchaseIntentToken()`, and clear attribution with `agent.handleCartEmpty()`. Only call `agent.handlePaymentSuccess()` if your platform has no cart-empty step after checkout.
 
 ## Recommended Integration
 
 Use `useQredexAgent()` inside the cart surface you already own. The wrapper stays headless.
+The merchant still owns cart APIs, totals, checkout, and order submission.
+Qredex only needs the cart transition so the core runtime can lock IIT to PIT.
+After lock, the merchant reads that PIT and carries it with the normal order
+payload to the merchant backend or direct Qredex ingestion path.
 
 ```tsx
 import { useEffect, useRef } from 'react';
@@ -38,25 +59,32 @@ export function QredexCartBridge({ itemCount }: QredexCartBridgeProps) {
   const previousCountRef = useRef(itemCount);
 
   useEffect(() => {
+    // [Qredex] Report the cart transition after your merchant cart changes.
     agent.handleCartChange({
       itemCount,
       previousCount: previousCountRef.current,
     });
 
+    // [Merchant] Keep your local snapshot ready for the next transition.
     previousCountRef.current = itemCount;
   }, [agent, itemCount]);
 
   async function clearCart() {
+    // [Merchant] Clear the real cart in your own backend/storefront first.
     await fetch('/api/cart/clear', {
       method: 'POST',
     });
 
+    // [Qredex] Clear attribution because the merchant cart is now empty.
     agent.handleCartEmpty();
   }
 
   async function submitOrder() {
+    // [Qredex] Read PIT from wrapper state, with the core runtime as fallback.
     const pit = state.pit ?? agent.getPurchaseIntentToken();
 
+    // [Merchant] Send the PIT as part of your normal order payload so the
+    // backend can carry order + PIT into attribution ingestion.
     await fetch('/api/orders', {
       method: 'POST',
       headers: {
@@ -68,6 +96,7 @@ export function QredexCartBridge({ itemCount }: QredexCartBridgeProps) {
       }),
     });
 
+    // [Merchant + Qredex] Reuse the same clear path after checkout succeeds.
     await clearCart();
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qredex/react",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "React wrapper for Qredex Agent",
   "type": "module",
   "sideEffects": false,
@@ -22,7 +22,7 @@
     "build": "tsc -p tsconfig.json"
   },
   "dependencies": {
-    "@qredex/agent": "^1.0.3"
+    "@qredex/agent": "^1.0.5"
   },
   "devDependencies": {
     "@qredex/agent": "file:../.."