@tagadapay/plugin-sdk 4.0.4 → 4.0.7

package/README.md

@@ -2,9 +2,9 @@
 
 A comprehensive React SDK for building plugins on the TagadaPay platform. Create custom checkout experiences, landing pages, and interactive components with automatic configuration injection and advanced routing capabilities.
 
-> **🚀 V2 Now Available!** The new V2 architecture features TanStack Query integration, improved TypeScript support, and better performance. [See V2 Architecture](#-v2-architecture) for details.
+> **🚀 V2 is the supported surface.** TanStack Query integration, improved TypeScript support, and better performance. [See V2 Architecture](#-v2-architecture) for details.
 >
-> **Recommended**: Use `@tagadapay/plugin-sdk/v3` for new projects. V1 (`/react`) is still supported for existing projects.
+> **Recommended**: Use `@tagadapay/plugin-sdk/v2` for new projects. V1 (`/react`) is still supported for existing projects but no longer receives new features.
 
 ## 📚 Documentation
 
@@ -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
@@ -24,7 +25,6 @@ A comprehensive React SDK for building plugins on the TagadaPay platform. Create
 - **[useCheckout (V1)](./docs/README-useCheckout.md)** - Legacy checkout state management
 - **[setCheckoutInfo](./docs/README-setCheckoutInfo.md)** - Customer information and validation
 - **[useOffers (V1)](./docs/README-useOffers.md)** - Legacy dynamic pricing
-- **[usePromotionCodes](./docs/README-usePromotionCodes.md)** - Legacy promotion code management
 - **[Money utilities](./docs/README-money.md)** - Currency formatting and calculations
 - **[URL utilities](./docs/README-urlUtils.md)** - Navigation and routing helpers
 
@@ -146,7 +146,7 @@ import {
   useISOData,
   useCheckout,
   formatMoney,
-} from '@tagadapay/plugin-sdk/v3';
+} from '@tagadapay/plugin-sdk/v2';
 
 function MyPlugin() {
   const { config, storeId, accountId, basePath, loading } = usePluginConfig();
@@ -199,7 +199,7 @@ export default App;
 
 ### What's New in V2
 
-The TagadaPay Plugin SDK v3 introduces a clean architecture with significant improvements:
+The TagadaPay Plugin SDK V2 introduces a clean architecture with significant improvements:
 
 #### **🔄 TanStack Query Integration**
 
@@ -218,7 +218,7 @@ The TagadaPay Plugin SDK v3 introduces a clean architecture with significant imp
 
 ```tsx
 // V2 (Recommended)
-import { useCheckout, useOffers, TagadaProvider } from '@tagadapay/plugin-sdk/v3';
+import { useCheckout, useOffers, TagadaProvider } from '@tagadapay/plugin-sdk/v2';
 
 // Legacy (Still supported)
 import { useCheckout, useOffers, TagadaProvider } from '@tagadapay/plugin-sdk/react';
@@ -257,7 +257,7 @@ import {
   useProducts,
   usePluginConfig,
   formatMoney,
-} from '@tagadapay/plugin-sdk/v3';
+} from '@tagadapay/plugin-sdk/v2';
 
 function CheckoutPage() {
   const [checkoutToken, setCheckoutToken] = useState<string>();
@@ -355,7 +355,7 @@ function App() {
 
 ```tsx
 import React from 'react';
-import { TagadaProvider, useCheckout, useOffers, formatMoney } from '@tagadapay/plugin-sdk/v3';
+import { TagadaProvider, useCheckout, useOffers, formatMoney } from '@tagadapay/plugin-sdk/v2';
 
 // Component 1: Cart Summary
 function CartSummary({ checkoutToken }: { checkoutToken: string }) {
@@ -411,7 +411,7 @@ function CheckoutWithOffers() {
 
 ```tsx
 import React from 'react';
-import { useCheckout } from '@tagadapay/plugin-sdk/v3';
+import { useCheckout } from '@tagadapay/plugin-sdk/v2';
 
 function QuantitySelector({
   checkoutToken,
@@ -555,7 +555,7 @@ interface TagadaProviderProps {
 #### V2 Enhanced Provider Features
 
 ```tsx
-import { TagadaProvider } from '@tagadapay/plugin-sdk/v3';
+import { TagadaProvider } from '@tagadapay/plugin-sdk/v2';
 
 function App() {
   return (
@@ -577,7 +577,7 @@ function App() {
 }
 ```
 
-> **Version Compatibility:** V2 features require `@tagadapay/plugin-sdk/v3`. The `blockUntilSessionReady` option was added in v2.3.0. For older versions, the blocking behavior was the default and only option.
+> **Version Compatibility:** V2 features require `@tagadapay/plugin-sdk/v2`. The `blockUntilSessionReady` option was added in v2.3.0. For older versions, the blocking behavior was the default and only option.
 
 ### Development vs Production
 
@@ -677,6 +677,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.
@@ -729,7 +818,7 @@ const {
 **Example:**
 
 ```tsx
-import { useStoreConfig } from '@tagadapay/plugin-sdk/v3';
+import { useStoreConfig } from '@tagadapay/plugin-sdk/v2';
 
 function StoreInfo() {
   const { storeConfig, isLoading } = useStoreConfig();
@@ -808,7 +897,7 @@ import {
   useInvalidateQuery,
   usePreloadQuery,
   queryKeys,
-} from '@tagadapay/plugin-sdk/v3';
+} from '@tagadapay/plugin-sdk/v2';
 
 // Custom API queries
 const { data, isLoading } = useApiQuery({
@@ -838,7 +927,7 @@ preloadCheckout({
 Enhanced money formatting with better TypeScript support:
 
 ```typescript
-import { formatMoney, convertCurrency, getCurrencyInfo } from '@tagadapay/plugin-sdk/v3';
+import { formatMoney, convertCurrency, getCurrencyInfo } from '@tagadapay/plugin-sdk/v2';
 
 // Format money with automatic currency detection
 const formatted = formatMoney(2999, 'USD'); // "$29.99"
@@ -867,7 +956,7 @@ import {
   ProductsResource,
   PaymentsResource,
   PluginConfigUtils,
-} from '@tagadapay/plugin-sdk/v3';
+} from '@tagadapay/plugin-sdk/v2';
 
 // Use core functions directly (useful for server-side or non-React contexts)
 const checkoutResource = new CheckoutResource(apiClient);
@@ -883,7 +972,7 @@ const isValid = PluginConfigUtils.validateConfig(config);
 V2 includes built-in debugging tools:
 
 ```tsx
-import { TagadaProvider } from '@tagadapay/plugin-sdk/v3';
+import { TagadaProvider } from '@tagadapay/plugin-sdk/v2';
 
 function App() {
   return (
@@ -1030,7 +1119,7 @@ const handleTouchStart = (e) => {
 ### Multi-language Support
 
 ```typescript
-import { useTranslation } from '@tagadapay/plugin-sdk';
+import { useTranslation } from '@tagadapay/plugin-sdk/v2';
 
 function CheckoutForm() {
   const { t } = useTranslation();
@@ -1047,7 +1136,7 @@ function CheckoutForm() {
 ### Currency Support
 
 ```typescript
-import { useCurrency } from '@tagadapay/plugin-sdk';
+import { useCurrency } from '@tagadapay/plugin-sdk/v2';
 
 function PriceDisplay({ amount }) {
   const { formatPrice, currency } = useCurrency();
@@ -1056,39 +1145,19 @@ function PriceDisplay({ amount }) {
 }
 ```
 
-## 📊 Analytics & Monitoring
+## 📊 Analytics & Tracking
 
-### Event Tracking
+Pixel tracking (Facebook, TikTok, Snapchat, GTM) is configured per-step in
+the CRM step editor and auto-bootstrapped at runtime — no plugin code is
+required. For external (non-Tagadapay-hosted) pages, the lightweight
+external tracker is available:
 
 ```typescript
-import { trackEvent } from '@tagadapay/plugin-sdk';
-
-// Track user interactions
-trackEvent('checkout_started', {
-  product_id: 'prod_123',
-  value: 2999,
-  currency: 'USD',
-});
-
-// Track conversions
-trackEvent('purchase_completed', {
-  transaction_id: 'txn_456',
-  value: 2999,
-  currency: 'USD',
-});
+import { TagadaExternalTracker } from '@tagadapay/plugin-sdk/external-tracker';
 ```
 
-### Performance Monitoring
-
-```typescript
-import { performance } from '@tagadapay/plugin-sdk';
-
-// Measure load times
-performance.mark('checkout-start');
-// ... checkout logic
-performance.mark('checkout-end');
-performance.measure('checkout-duration', 'checkout-start', 'checkout-end');
-```
+See [External Page Tracker docs](../../mintlify/developer-tools/web-integration/external-page-tracker.mdx)
+for the full integration guide.
 
 ## 🤝 Contributing
 

package/dist/external-tracker.js

@@ -1,5 +1,5 @@
 /**
- * TagadaPay External Tracker v4.0.4
+ * TagadaPay External Tracker v4.0.7
  * 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.7
  * 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.7
  * 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.7
  * 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.7
  * 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.7
  * 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.7
  * CDN Bundle - Full standalone SDK for external/vanilla pages
  * Usage: window.tgd.createTagadaClient(), window.tgd.formatMoney(), etc.
  * @license MIT

package/package.json

@@ -1,115 +1,114 @@
-{
-  "name": "@tagadapay/plugin-sdk",
-  "version": "4.0.4",
-  "description": "Modern React SDK for building Tagada Pay plugins",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "sideEffects": false,
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.js"
-    },
-    "./react": {
-      "types": "./dist/react/index.d.ts",
-      "import": "./dist/react/index.js",
-      "require": "./dist/react/index.js"
-    },
-    "./v2": {
-      "types": "./dist/v2/index.d.ts",
-      "import": "./dist/v2/index.js",
-      "require": "./dist/v2/index.js"
-    },
-    "./v2/standalone": {
-      "types": "./dist/v2/standalone/index.d.ts",
-      "import": "./dist/v2/standalone/index.js",
-      "require": "./dist/v2/standalone/index.js"
-    },
-    "./external-tracker": {
-      "browser": "./dist/external-tracker.min.js",
-      "default": "./dist/external-tracker.min.js"
-    }
-  },
-  "scripts": {
-    "build": "tsc && npm run build:cdn",
-    "build:cdn": "node build-cdn.js",
-    "build:ts": "tsc",
-    "clean": "rm -rf dist",
-    "lint": "echo \"No linting configured\"",
-    "test": "jest --no-watchman",
-    "test:watch": "jest --watch --no-watchman",
-    "test:coverage": "jest --coverage --no-watchman",
-    "dev": "tsc --watch",
-    "prepublishOnly": "npm run clean && npm run build",
-    "publish:patch": "npm version patch && npm publish",
-    "publish:minor": "npm version minor && npm publish",
-    "publish:major": "npm version major && npm publish",
-    "publish:beta": "npm version prerelease --preid=beta && npm publish --tag beta",
-    "publish:alpha": "npm version prerelease --preid=alpha && npm publish --tag alpha",
-    "version:patch": "npm version patch",
-    "version:minor": "npm version minor",
-    "version:major": "npm version major",
-    "version:beta": "npm version prerelease --preid=beta",
-    "version:alpha": "npm version prerelease --preid=alpha",
-    "version:check": "node version-sync.js check",
-    "version:sync": "node version-sync.js sync",
-    "version:list": "node version-sync.js list",
-    "version:next": "node version-sync.js next",
-    "postversion": "echo \"✅ Version updated to $(node -p 'require(\"./package.json\").version')\" && (git push && git push --tags || echo \"⚠️ Git push failed - you may need to pull and push manually\")"
-  },
-  "keywords": [
-    "tagadapay",
-    "cms",
-    "plugin",
-    "sdk",
-    "react",
-    "typescript"
-  ],
-  "author": "Tagada Pay",
-  "license": "MIT",
-  "dependencies": {
-    "@basis-theory/apple-pay-js": "^2.0.2",
-    "@basis-theory/basis-theory-js": "^4.30.0",
-    "@basis-theory/basis-theory-react": "^1.32.5",
-    "@basis-theory/web-threeds": "^1.0.1",
-    "@google-pay/button-react": "^3.0.10",
-    "@stripe/react-stripe-js": "^5.6.1",
-    "@stripe/stripe-js": "^8.11.0",
-    "@tagadapay/core-js": "workspace:*",
-    "@tagadapay/plugin-sdk": "link:",
-    "@tanstack/react-query": "^5.90.2",
-    "@whop/checkout": "^0.0.40",
-    "axios": "^1.10.0",
-    "path-to-regexp": "^8.2.0",
-    "react-intl": "^7.1.11",
-    "swr": "^2.3.6"
-  },
-  "devDependencies": {
-    "@types/jest": "^29.5.0",
-    "@types/node": "^18.19.130",
-    "@types/react": "^19",
-    "@types/react-dom": "^19",
-    "esbuild": "^0.24.2",
-    "jest": "^29.5.0",
-    "ts-jest": "^29.1.0",
-    "typescript": "^5.0.0"
-  },
-  "peerDependencies": {
-    "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0 || ^19.0.0"
-  },
-  "files": [
-    "dist/**/*",
-    "README.md",
-    "build-cdn.js"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/tagadapay/plugin-sdk.git"
-  },
-  "bugs": {
-    "url": "https://github.com/tagadapay/plugin-sdk/issues"
-  },
-  "homepage": "https://github.com/tagadapay/plugin-sdk#readme"
-}
+{
+  "name": "@tagadapay/plugin-sdk",
+  "version": "4.0.7",
+  "description": "Modern React SDK for building Tagada Pay plugins",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js",
+      "require": "./dist/react/index.js"
+    },
+    "./v2": {
+      "types": "./dist/v2/index.d.ts",
+      "import": "./dist/v2/index.js",
+      "require": "./dist/v2/index.js"
+    },
+    "./v2/standalone": {
+      "types": "./dist/v2/standalone/index.d.ts",
+      "import": "./dist/v2/standalone/index.js",
+      "require": "./dist/v2/standalone/index.js"
+    },
+    "./external-tracker": {
+      "browser": "./dist/external-tracker.min.js",
+      "default": "./dist/external-tracker.min.js"
+    }
+  },
+  "keywords": [
+    "tagadapay",
+    "cms",
+    "plugin",
+    "sdk",
+    "react",
+    "typescript"
+  ],
+  "author": "Tagada Pay",
+  "license": "MIT",
+  "dependencies": {
+    "@basis-theory/apple-pay-js": "^2.0.2",
+    "@basis-theory/basis-theory-js": "^4.30.0",
+    "@basis-theory/basis-theory-react": "^1.32.5",
+    "@basis-theory/web-threeds": "^1.0.1",
+    "@google-pay/button-react": "^3.0.10",
+    "@stripe/react-stripe-js": "^5.6.1",
+    "@stripe/stripe-js": "^8.11.0",
+    "@tagadapay/plugin-sdk": "link:",
+    "@tanstack/react-query": "^5.90.2",
+    "@whop/checkout": "^0.0.40",
+    "axios": "^1.10.0",
+    "path-to-regexp": "^8.2.0",
+    "react-intl": "^7.1.11",
+    "swr": "^2.3.6",
+    "@tagadapay/core-js": "3.0.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^18.19.130",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "esbuild": "^0.24.2",
+    "jest": "^29.5.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "build-cdn.js"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tagadapay/plugin-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tagadapay/plugin-sdk/issues"
+  },
+  "homepage": "https://github.com/tagadapay/plugin-sdk#readme",
+  "scripts": {
+    "build": "tsc && npm run build:cdn",
+    "build:cdn": "node build-cdn.js",
+    "build:ts": "tsc",
+    "clean": "rm -rf dist",
+    "lint": "echo \"No linting configured\"",
+    "test": "jest --no-watchman",
+    "test:watch": "jest --watch --no-watchman",
+    "test:coverage": "jest --coverage --no-watchman",
+    "dev": "tsc --watch",
+    "publish:patch": "npm version patch && pnpm publish --no-git-checks",
+    "publish:minor": "npm version minor && pnpm publish --no-git-checks",
+    "publish:major": "npm version major && pnpm publish --no-git-checks",
+    "publish:beta": "npm version prerelease --preid=beta && pnpm publish --tag beta --no-git-checks",
+    "publish:alpha": "npm version prerelease --preid=alpha && pnpm publish --tag alpha --no-git-checks",
+    "version:patch": "npm version patch",
+    "version:minor": "npm version minor",
+    "version:major": "npm version major",
+    "version:beta": "npm version prerelease --preid=beta",
+    "version:alpha": "npm version prerelease --preid=alpha",
+    "version:check": "node version-sync.js check",
+    "version:sync": "node version-sync.js sync",
+    "version:list": "node version-sync.js list",
+    "version:next": "node version-sync.js next",
+    "postversion": "echo \"✅ Version updated to $(node -p 'require(\"./package.json\").version')\" && (git push && git push --tags || echo \"⚠️ Git push failed - you may need to pull and push manually\")"
+  }
+}