@tagadapay/plugin-sdk 4.0.4 → 4.0.6

package/README.md

@@ -14,6 +14,7 @@ A comprehensive React SDK for building plugins on the TagadaPay platform. Create
 - **[V2 Examples](#-v2-examples)** - Complete examples using the new V2 hooks
 - **[useCheckout (V2)](#usecheckout)** - TanStack Query-based checkout management
 - **[useOffers (V2)](#useoffers)** - Dynamic pricing with automatic caching
+- **[usePreviewOffer (V2)](#usepreviewoffer)** - Post-checkout upsell page (auto-applies MIT/CIT)
 - **[useProducts (V2)](#useproducts)** - Product data management
 - **[useStoreConfig (V2)](#usestoreconfig)** - Store configuration with automatic caching
 - **[usePayment (V2)](#usepayment)** - Payment processing with 3DS support
@@ -677,6 +678,95 @@ const {
 } = useOffers({ storeId, enabled });
 ```
 
+> ⚠️ **`useOffer` (singular) is deprecated.** Use `usePreviewOffer` for upsell
+> pages — it skips the upfront checkout-session round-trip, recomputes
+> pricing client-side, and auto-applies the CRM-configured MIT/CIT payment
+> initiator. `useOffer` will be removed in a future major version.
+
+#### usePreviewOffer()
+
+Lightweight hook for post-checkout upsell pages. Fetches an offer with a
+precomputed pricing summary, lets the customer pick variants and quantities,
+and recomputes totals client-side without round-tripping the backend on every
+change. Pay once the customer accepts.
+
+```typescript
+const {
+  // Query state
+  offer,             // Offer | null
+  isLoading,         // boolean
+  isFetching,        // boolean
+  isPaying,          // boolean
+  error,             // Error | null
+
+  // Pricing
+  summary,           // { items, totalAmount, totalAdjustedAmount, currency, options }
+  selections,        // Record<lineItemId, { variantId, quantity, priceId? }>
+
+  // Selection methods (by lineItemId)
+  selectVariant,     // (lineItemId, variantId) => void
+  updateQuantity,    // (lineItemId, quantity) => void
+  // Selection methods (by productId — convenience for single-line steps)
+  selectVariantByProduct,
+  updateQuantityByProduct,
+  getAvailableVariants, // (productId) => Array<{ variantId, variantName, unitAmount, currency, imageUrl }>
+
+  // Actions
+  pay,               // (mainOrderId?, options?: { initiatedBy }) => Promise<{ checkoutUrl }>
+  toCheckout,        // (mainOrderId?) => Promise<{ checkoutToken, customerId, status }>
+} = usePreviewOffer({
+  offerId,                // required
+  currency,               // optional override; defaults to ?currency= URL param or funnel context
+  initialSelections,      // optional preselected variants/quantities
+});
+```
+
+**Example — accept-or-skip upsell page:**
+
+```tsx
+import { usePreviewOffer } from '@tagadapay/plugin-sdk/v2';
+
+function UpsellOffer({ offerId, mainOrderId }: { offerId: string; mainOrderId: string }) {
+  const { offer, summary, pay, isPaying } = usePreviewOffer({ offerId });
+
+  const handleAccept = async () => {
+    const { checkoutUrl } = await pay(mainOrderId);
+    if (checkoutUrl) window.location.href = checkoutUrl;
+  };
+
+  return (
+    <div>
+      <h2>{offer?.name}</h2>
+      <p>Total: {summary?.totalAdjustedAmount} {summary?.currency}</p>
+      <button onClick={handleAccept} disabled={isPaying}>
+        {isPaying ? 'Processing…' : 'Add to my order'}
+      </button>
+    </div>
+  );
+}
+```
+
+**MIT vs CIT auto-pickup**
+
+`pay()` reads `stepConfig.paymentInitiator` from the runtime
+`window.__TGD_STEP_CONFIG__` injection and applies it automatically:
+
+- `paymentInitiator: 'merchant'` (default) → **MIT**, sent to Stripe as
+  `off_session: true`. No 3DS challenge, higher conversion.
+- `paymentInitiator: 'customer'` → **CIT**, sent as
+  `setup_future_usage: 'off_session'`. May trigger 3DS — useful when MIT
+  charges are being declined by the issuer.
+
+Merchants flip the toggle from the CRM step config; no plugin code change is
+required. To override per call, pass `{ initiatedBy }`:
+
+```tsx
+await pay(mainOrderId, { initiatedBy: 'customer' });
+```
+
+`OffersResource.payOffer()` and `OffersResource.payWithCheckoutSession()` share
+the same auto-pickup under the hood.
+
 #### usePromotions()
 
 Hook for managing promotion codes in checkout sessions with TanStack Query.

package/dist/external-tracker.js

@@ -1,5 +1,5 @@
 /**
- * TagadaPay External Tracker v4.0.4
+ * TagadaPay External Tracker v4.0.6
  * CDN Bundle - Standalone tracking for external pages (Debug Build)
  * @license MIT
  */

package/dist/external-tracker.min.js

@@ -1,5 +1,5 @@
 /**
- * TagadaPay External Tracker v4.0.4
+ * TagadaPay External Tracker v4.0.6
  * CDN Bundle - Standalone tracking for external pages
  * @license MIT
  */

package/dist/tagada-react-sdk-minimal.min.js

@@ -1,5 +1,5 @@
 /**
- * TagadaPay React SDK MINIMAL v4.0.4
+ * TagadaPay React SDK MINIMAL v4.0.6
  * CDN Bundle - Slim checkout SDK (TagadaProvider + essential hooks only)
  * Requires: React 18+ loaded before this script
  * For full SDK with all hooks, use tagada-react-sdk.min.js instead

package/dist/tagada-react-sdk.js

@@ -1,5 +1,5 @@
 /**
- * TagadaPay React SDK v4.0.4
+ * TagadaPay React SDK v4.0.6
  * CDN Bundle - React hooks and TagadaProvider (Debug Build)
  * @license MIT
  */

package/dist/tagada-react-sdk.min.js

@@ -1,5 +1,5 @@
 /**
- * TagadaPay React SDK v4.0.4
+ * TagadaPay React SDK v4.0.6
  * CDN Bundle - React hooks and TagadaProvider for checkout integration
  * Requires: React 18+ loaded before this script
  * Usage: window.tgd.TagadaProvider, window.tgd.useCheckout, etc.

package/dist/tagada-sdk.js

@@ -1,5 +1,5 @@
 /**
- * TagadaPay SDK v4.0.4
+ * TagadaPay SDK v4.0.6
  * CDN Bundle - Full standalone SDK (Debug Build)
  * Usage: window.tgd.createTagadaClient(), window.tgd.formatMoney(), etc.
  * @license MIT

package/dist/tagada-sdk.min.js

@@ -1,5 +1,5 @@
 /**
- * TagadaPay SDK v4.0.4
+ * TagadaPay SDK v4.0.6
  * CDN Bundle - Full standalone SDK for external/vanilla pages
  * Usage: window.tgd.createTagadaClient(), window.tgd.formatMoney(), etc.
  * @license MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tagadapay/plugin-sdk",
-  "version": "4.0.4",
+  "version": "4.0.6",
   "description": "Modern React SDK for building Tagada Pay plugins",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",