@affiliateo/web 4.4.1 → 4.6.0

package/README.md

@@ -1,238 +1,238 @@
-# @affiliateo/web
-
-Affiliateo web SDK. track affiliate visits and pass attribution metadata to your Stripe checkout.
-
-## Install
-
-```bash
-npm install @affiliateo/web
-```
-
-## Setup
-
-1. Connect your Stripe account on the Affiliateo dashboard
-2. Wrap your app in `<AffiliateoProvider>` with your campaign ID
-3. At checkout time, call `getAttribution()` and pass the result to Stripe metadata
-
-### Step 1. wrap your app
-
-```tsx
-// app/layout.tsx (Next.js App Router) or _app.tsx (Pages Router)
-import { AffiliateoProvider } from '@affiliateo/web';
-
-export default function RootLayout({ children }) {
-  return (
-    <AffiliateoProvider campaignId="YOUR_CAMPAIGN_ID">
-      {children}
-    </AffiliateoProvider>
-  );
-}
-```
-
-The provider:
-- Reads `?ref=` from the URL when a visitor arrives
-- Stores attribution in `localStorage` so it survives navigation
-- Sends pageview events to Affiliateo for click tracking
-
-### Step 2. in your checkout button (client-side)
-
-```tsx
-'use client'
-import { getAttribution } from '@affiliateo/web';
-
-async function handleCheckout() {
-  const attribution = getAttribution();
-
-  const res = await fetch('/api/checkout', {
-    method: 'POST',
-    body: JSON.stringify({ attribution }),
-  });
-
-  const { url } = await res.json();
-  window.location.href = url;
-}
-```
-
-`getAttribution()` reads `affiliateo_ref`, `affiliateo_visitor_id`, and `affiliateo_campaign_id` from `localStorage` and returns them as an object, ready to pass to Stripe.
-
-### Step 3. in your checkout API route (server-side)
-
-```ts
-// app/api/checkout/route.ts
-export async function POST(req) {
-  const { attribution } = await req.json();
-
-  const session = await stripe.checkout.sessions.create({
-    line_items: [{ price: 'price_xxx', quantity: 1 }],
-    mode: 'payment',
-    success_url: 'https://yoursite.com/success',
-    cancel_url: 'https://yoursite.com/cancel',
-    metadata: attribution,
-  });
-
-  return Response.json({ url: session.url });
-}
-```
-
-That's it. Affiliateo's webhook will automatically read the metadata and credit the right affiliate when the payment succeeds.
-
-## How it works
-
-1. Visitor clicks affiliate link → `yoursite.com?ref=pinkproton`
-2. `<AffiliateoProvider>` reads `?ref=pinkproton` from the URL and saves it in `localStorage`
-3. As the visitor browses, attribution stays in their browser
-4. At checkout, `getAttribution()` reads localStorage and returns the attribution object
-5. Your server passes it as Stripe metadata when creating the checkout session
-6. When Stripe fires the `checkout.session.completed` webhook, Affiliateo reads the metadata and credits the affiliate
-
-## Why `localStorage` and not cookies?
-
-- **Not blocked by Safari ITP or most privacy tools**
-- **No CSRF concerns**
-
-## GDPR / ePrivacy. merchant responsibility
-
-The SDK writes persistent identifiers (`affiliateo_visitor_id`, `affiliateo_ref`, `affiliateo_campaign_id`) to the visitor's `localStorage` and sends pageview events that include the visitor's IP, user agent, and approximate geolocation to Affiliateo's servers. Under EU ePrivacy (Article 5(3)) and GDPR, persistent identifiers stored on a visitor's device require prior consent the same way cookies do.
-
-If you serve visitors in the EU/EEA, UK, or any jurisdiction with equivalent rules, **you are responsible for obtaining consent before this script loads**, the same way you would for Google Analytics, Meta Pixel, or any other analytics tool. Typical approaches:
-
-- Gate the `<AffiliateoProvider>` (or the `<script src="…/t.js">` tag) behind your cookie banner's "accept" callback so it only loads after consent.
-- Document Affiliateo in your privacy policy as a processor (see our [Data Processing Agreement](https://affiliateo.com/dpa)) and list the categories of data collected.
-
-Affiliateo acts as your data processor for visitor analytics. You are the controller and decide the lawful basis for processing your visitors' data.
-
-## Alternative: vanilla HTML (no React)
-
-If you're not using React, use the tracking script directly instead of the provider:
-
-```html
-<script defer
-  data-campaign="YOUR_CAMPAIGN_ID"
-  src="https://affiliateo.com/t.js"
-></script>
-```
-
-Then in your checkout flow (vanilla JS):
-
-```js
-const attribution = {
-  affiliateo_ref: localStorage.getItem('affiliateo_ref'),
-  affiliateo_visitor_id: localStorage.getItem('affiliateo_visitor_id'),
-  affiliateo_campaign_id: localStorage.getItem('affiliateo_campaign_id'),
-};
-
-// Send to your server with the rest of your checkout payload
-fetch('/api/checkout', {
-  method: 'POST',
-  body: JSON.stringify({ attribution }),
-});
-```
-
-## Track conversion goals
-
-Pageviews auto-track. For specific moments that matter to your funnel
-(`signup_completed`, `trial_started`, `initiate_checkout`, etc.), use
-`track()` or HTML data attributes.
-
-### From React
-
-```tsx
-'use client'
-import { useEffect } from 'react'
-import { useAffiliateRef } from '@affiliateo/web'
-
-export default function SignupSuccess() {
-  const { track } = useAffiliateRef()
-  useEffect(() => {
-    track('signup_completed', { plan: 'free' })
-  }, [])
-  return <div>Welcome!</div>
-}
-```
-
-### HTML data attributes (zero JS, works everywhere)
-
-```html
-<button data-affiliateo-goal="initiate_checkout"
-        data-affiliateo-goal-price="49"
-        data-affiliateo-goal-plan="pro">
-  Subscribe
-</button>
-```
-
-The SDK auto-fires the goal on click. Optional `data-affiliateo-goal-*`
-attributes become metadata (kebab-case → snake_case, up to 10 params).
-
-### Scroll-depth tracking
-
-```html
-<section data-affiliateo-scroll="pricing_viewed">
-  ...your pricing content...
-</section>
-```
-
-Fires the first time any pixel of the section overlaps the viewport.
-Maximum permissiveness — if the user scrolled enough to see even a sliver,
-it counts. Earlier versions required 50% visibility, which was unreachable
-for tall sections (a pricing page with comparison tables silently dropped
-out of every funnel). Great for landing pages where you want to know
-which sections convert.
-
-### Goal naming rules
-
-Lowercase letters, digits, underscores, hyphens, colons. Max 64 chars.
-Metadata bounded to 4KB JSON.
-
-## Identify signed-in users (cross-device stitching)
-
-Without `identify()`, the same person browsing on phone and buying on
-laptop counts as two visitors. Call it once after sign-in:
-
-```tsx
-'use client'
-import { useEffect } from 'react'
-import { useAffiliateRef } from '@affiliateo/web'
-import { useUser } from './your-auth'
-
-export default function AuthBoundary({ children }) {
-  const { identify } = useAffiliateRef()
-  const user = useUser()
-  useEffect(() => {
-    if (user) identify(user.id)
-  }, [user])
-  return <>{children}</>
-}
-```
-
-Idempotent. safe to fire on every page load while a user is signed in.
-**user_id only.** The SDK does not accept, collect, or transmit email
-or any other PII.
-
-## API
-
-### `<AffiliateoProvider campaignId="..." apiUrl?="...">`
-
-React provider. Wrap your app once. Reads `?ref=` from URL, persists to localStorage, sends pageview events, sets up data-attribute + scroll listeners.
-
-Props:
-- `campaignId` (required): your Affiliateo campaign ID
-- `apiUrl` (optional): defaults to `https://affiliateo.com`
-
-### `useAffiliateRef()`
-
-React hook that returns `{ refCode, visitorId, track, identify }`.
-
-- `track(eventName, metadata?)`. fire a custom goal
-- `identify(userId)`. link this visitor to a merchant user_id (no PII)
-
-### `getAttribution()`
-
-Client-side function. Returns an object with `affiliateo_ref`, `affiliateo_visitor_id`, and `affiliateo_campaign_id` from localStorage. Pass directly as Stripe `metadata`.
-
-## Framework support
-
-Works with any JavaScript framework or vanilla JS:
-- **Next.js** (App Router & Pages Router)
-- **Remix** / **React Router**
-- **Vite + React**
-- **Vanilla JS/HTML** (use the `<script>` tag instead)
+# @affiliateo/web
+
+Affiliateo web SDK. track affiliate visits and pass attribution metadata to your Stripe checkout.
+
+## Install
+
+```bash
+npm install @affiliateo/web
+```
+
+## Setup
+
+1. Connect your Stripe account on the Affiliateo dashboard
+2. Wrap your app in `<AffiliateoProvider>` with your app ID
+3. At checkout time, call `getAttribution()` and pass the result to Stripe metadata
+
+### Step 1. wrap your app
+
+```tsx
+// app/layout.tsx (Next.js App Router) or _app.tsx (Pages Router)
+import { AffiliateoProvider } from '@affiliateo/web';
+
+export default function RootLayout({ children }) {
+  return (
+    <AffiliateoProvider appId="YOUR_APP_ID">
+      {children}
+    </AffiliateoProvider>
+  );
+}
+```
+
+The provider:
+- Reads `?ref=` from the URL when a visitor arrives
+- Stores attribution in `localStorage` so it survives navigation
+- Sends pageview events to Affiliateo for click tracking
+
+### Step 2. in your checkout button (client-side)
+
+```tsx
+'use client'
+import { getAttribution } from '@affiliateo/web';
+
+async function handleCheckout() {
+  const attribution = getAttribution();
+
+  const res = await fetch('/api/checkout', {
+    method: 'POST',
+    body: JSON.stringify({ attribution }),
+  });
+
+  const { url } = await res.json();
+  window.location.href = url;
+}
+```
+
+`getAttribution()` reads the stored attribution from `localStorage` and returns `affiliateo_ref`, `affiliateo_visitor_id`, and `affiliateo_app_id` as an object, ready to pass to Stripe.
+
+### Step 3. in your checkout API route (server-side)
+
+```ts
+// app/api/checkout/route.ts
+export async function POST(req) {
+  const { attribution } = await req.json();
+
+  const session = await stripe.checkout.sessions.create({
+    line_items: [{ price: 'price_xxx', quantity: 1 }],
+    mode: 'payment',
+    success_url: 'https://yoursite.com/success',
+    cancel_url: 'https://yoursite.com/cancel',
+    metadata: attribution,
+  });
+
+  return Response.json({ url: session.url });
+}
+```
+
+That's it. Affiliateo's webhook will automatically read the metadata and credit the right affiliate when the payment succeeds.
+
+## How it works
+
+1. Visitor clicks affiliate link → `yoursite.com?ref=pinkproton`
+2. `<AffiliateoProvider>` reads `?ref=pinkproton` from the URL and saves it in `localStorage`
+3. As the visitor browses, attribution stays in their browser
+4. At checkout, `getAttribution()` reads localStorage and returns the attribution object
+5. Your server passes it as Stripe metadata when creating the checkout session
+6. When Stripe fires the `checkout.session.completed` webhook, Affiliateo reads the metadata and credits the affiliate
+
+## Why `localStorage` and not cookies?
+
+- **Not blocked by Safari ITP or most privacy tools**
+- **No CSRF concerns**
+
+## GDPR / ePrivacy. merchant responsibility
+
+The SDK writes persistent identifiers (`affiliateo_visitor_id`, `affiliateo_ref`, `affiliateo_campaign_id`) to the visitor's `localStorage` and sends pageview events that include the visitor's IP, user agent, and approximate geolocation to Affiliateo's servers. Under EU ePrivacy (Article 5(3)) and GDPR, persistent identifiers stored on a visitor's device require prior consent the same way cookies do.
+
+If you serve visitors in the EU/EEA, UK, or any jurisdiction with equivalent rules, **you are responsible for obtaining consent before this script loads**, the same way you would for Google Analytics, Meta Pixel, or any other analytics tool. Typical approaches:
+
+- Gate the `<AffiliateoProvider>` (or the `<script src="…/t.js">` tag) behind your cookie banner's "accept" callback so it only loads after consent.
+- Document Affiliateo in your privacy policy as a processor (see our [Data Processing Agreement](https://affiliateo.com/dpa)) and list the categories of data collected.
+
+Affiliateo acts as your data processor for visitor analytics. You are the controller and decide the lawful basis for processing your visitors' data.
+
+## Alternative: vanilla HTML (no React)
+
+If you're not using React, use the tracking script directly instead of the provider:
+
+```html
+<script defer
+  data-app="YOUR_APP_ID"
+  src="https://affiliateo.com/t.js"
+></script>
+```
+
+Then in your checkout flow (vanilla JS):
+
+```js
+const attribution = {
+  affiliateo_ref: localStorage.getItem('affiliateo_ref'),
+  affiliateo_visitor_id: localStorage.getItem('affiliateo_visitor_id'),
+  affiliateo_app_id: localStorage.getItem('affiliateo_campaign_id'), // stored under its legacy key
+};
+
+// Send to your server with the rest of your checkout payload
+fetch('/api/checkout', {
+  method: 'POST',
+  body: JSON.stringify({ attribution }),
+});
+```
+
+## Track conversion goals
+
+Pageviews auto-track. For specific moments that matter to your funnel
+(`signup_completed`, `trial_started`, `initiate_checkout`, etc.), use
+`track()` or HTML data attributes.
+
+### From React
+
+```tsx
+'use client'
+import { useEffect } from 'react'
+import { useAffiliateRef } from '@affiliateo/web'
+
+export default function SignupSuccess() {
+  const { track } = useAffiliateRef()
+  useEffect(() => {
+    track('signup_completed', { plan: 'free' })
+  }, [])
+  return <div>Welcome!</div>
+}
+```
+
+### HTML data attributes (zero JS, works everywhere)
+
+```html
+<button data-affiliateo-goal="initiate_checkout"
+        data-affiliateo-goal-price="49"
+        data-affiliateo-goal-plan="pro">
+  Subscribe
+</button>
+```
+
+The SDK auto-fires the goal on click. Optional `data-affiliateo-goal-*`
+attributes become metadata (kebab-case → snake_case, up to 10 params).
+
+### Scroll-depth tracking
+
+```html
+<section data-affiliateo-scroll="pricing_viewed">
+  ...your pricing content...
+</section>
+```
+
+Fires the first time any pixel of the section overlaps the viewport.
+Maximum permissiveness — if the user scrolled enough to see even a sliver,
+it counts. Earlier versions required 50% visibility, which was unreachable
+for tall sections (a pricing page with comparison tables silently dropped
+out of every funnel). Great for landing pages where you want to know
+which sections convert.
+
+### Goal naming rules
+
+Lowercase letters, digits, underscores, hyphens, colons. Max 64 chars.
+Metadata bounded to 4KB JSON.
+
+## Identify signed-in users (cross-device stitching)
+
+Without `identify()`, the same person browsing on phone and buying on
+laptop counts as two visitors. Call it once after sign-in:
+
+```tsx
+'use client'
+import { useEffect } from 'react'
+import { useAffiliateRef } from '@affiliateo/web'
+import { useUser } from './your-auth'
+
+export default function AuthBoundary({ children }) {
+  const { identify } = useAffiliateRef()
+  const user = useUser()
+  useEffect(() => {
+    if (user) identify(user.id)
+  }, [user])
+  return <>{children}</>
+}
+```
+
+Idempotent. safe to fire on every page load while a user is signed in.
+**user_id only.** The SDK does not accept, collect, or transmit email
+or any other PII.
+
+## API
+
+### `<AffiliateoProvider appId="..." apiUrl?="...">`
+
+React provider. Wrap your app once. Reads `?ref=` from URL, persists to localStorage, sends pageview events, sets up data-attribute + scroll listeners.
+
+Props:
+- `appId` (required): your Affiliateo app ID (`campaignId` still works as a deprecated alias)
+- `apiUrl` (optional): defaults to `https://affiliateo.com`
+
+### `useAffiliateRef()`
+
+React hook that returns `{ refCode, visitorId, track, identify }`.
+
+- `track(eventName, metadata?)`. fire a custom goal
+- `identify(userId)`. link this visitor to a merchant user_id (no PII)
+
+### `getAttribution()`
+
+Client-side function. Returns an object with `affiliateo_ref`, `affiliateo_visitor_id`, and `affiliateo_app_id` from localStorage. Pass directly as Stripe `metadata`.
+
+## Framework support
+
+Works with any JavaScript framework or vanilla JS:
+- **Next.js** (App Router & Pages Router)
+- **Remix** / **React Router**
+- **Vite + React**
+- **Vanilla JS/HTML** (use the `<script>` tag instead)

package/dist/provider.d.ts

@@ -18,6 +18,6 @@ export declare function useAffiliateRef(): AffiliateoContextValue;
  * ```
  */
 export declare function getAttribution(): Record<string, string>;
-export declare function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allowLocalhost, allowIframe, allowFileProtocol, debug, flushInterval, maxQueueSize, autoCapturePageviews, children, }: AffiliateoConfig & {
+export declare function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames, allowLocalhost, allowIframe, allowFileProtocol, debug, flushInterval, maxQueueSize, autoCapturePageviews, children, }: AffiliateoConfig & {
     children: React.ReactNode;
 }): import("react/jsx-runtime").JSX.Element;

package/dist/provider.js

@@ -4,10 +4,14 @@ import { createContext, useCallback, useContext, useEffect, useRef, useState } f
 import { EventQueue } from './queue';
 import { isLikelyBot } from './bot-detect';
 import { isDevHost } from './dev-host';
+import { mintTurnstileToken, consumeTurnstileToken } from './turnstile';
 const DEFAULT_API_URL = 'https://affiliateo.com';
 const LS_VISITOR_ID = 'affiliateo_visitor_id';
 const LS_REF = 'affiliateo_ref';
-const LS_CAMPAIGN_ID = 'affiliateo_campaign_id';
+// Storage key keeps its historical name: t.js and the WooCommerce tracker
+// write the same key, and renaming it would orphan existing visitors'
+// attribution mid-session.
+const LS_APP_ID = 'affiliateo_campaign_id';
 // Persistent opt-out flag (affiliateo_opt_out) —
 // when set to "true" the SDK silently noops every outbound call. Survives
 // page reloads. removed by optIn(). Checked at init time so a previously
@@ -149,13 +153,15 @@ export function getAttribution() {
     const data = {};
     const vid = lsGet(LS_VISITOR_ID);
     const ref = lsGet(LS_REF);
-    const cid = lsGet(LS_CAMPAIGN_ID);
+    const cid = lsGet(LS_APP_ID);
     if (vid)
         data.affiliateo_visitor_id = vid;
     if (ref)
         data.affiliateo_ref = ref;
+    // Key renamed from affiliateo_campaign_id in 4.5.0 — the Affiliateo
+    // webhook accepts both, so checkouts created by older SDKs keep working.
     if (cid)
-        data.affiliateo_campaign_id = cid;
+        data.affiliateo_app_id = cid;
     return data;
 }
 // Double-mount detection. The host app should mount AffiliateoProvider
@@ -165,7 +171,7 @@ export function getAttribution() {
 // mount (host has the call sites) but we can shout in dev so the
 // mistake is visible.
 let providerMountCount = 0;
-export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allowLocalhost, allowIframe, allowFileProtocol, debug, flushInterval, maxQueueSize, autoCapturePageviews, children, }) {
+export function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames, allowLocalhost, allowIframe, allowFileProtocol, debug, flushInterval, maxQueueSize, autoCapturePageviews, children, }) {
     // Normalize autoCapturePageviews. Three shapes:
     //   - undefined / true / object → auto-capture ON (with object overrides)
     //   - false → auto-capture OFF entirely (host must call trackPageview)
@@ -211,12 +217,15 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
             console.log('[Affiliateo] ' + msg);
     }, [debug]);
     const apiBase = (apiUrl || DEFAULT_API_URL).replace(/\/$/, '');
-    // campaignIdRef stays current so callbacks defined inside useEffect
+    // appId is the documented prop; campaignId is the pre-4.5.0 name kept as
+    // a working alias so upgrading the package never breaks an integration.
+    const resolvedAppId = appId ?? campaignId ?? '';
+    // appIdRef stays current so callbacks defined inside useEffect
     // always read the latest value, even after a prop change. Closures
     // captured by host-side `useRef` no longer drift to a stale id.
-    const campaignIdRef = useRef(campaignId);
-    campaignIdRef.current = campaignId;
-    // Mint visitorId once and put it in a ref so it survives campaignId
+    const appIdRef = useRef(resolvedAppId);
+    appIdRef.current = resolvedAppId;
+    // Mint visitorId once and put it in a ref so it survives appId
     // prop changes without forcing a re-fetch / re-mint cycle. Same UUID
     // for the lifetime of the localStorage entry across the whole tab.
     const visitorIdRef = useRef(null);
@@ -230,7 +239,7 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
     // handlers, which fire after mount.
     const queueRef = useRef(null);
     // track + identify are defined OUTSIDE the route-effect so they
-    // close over refs (campaignIdRef, visitorIdRef) rather than the
+    // close over refs (appIdRef, visitorIdRef) rather than the
     // captured-once values from inside the effect. A consumer caching
     // `track` keeps firing under the LATEST (campaignId, visitorId).
     const track = useCallback(async (eventName, metadata) => {
@@ -246,7 +255,7 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
             const name = eventName.trim().toLowerCase();
             if (!name || name.length > 64 || !/^[a-z0-9_:-]+$/.test(name))
                 return;
-            const cid = campaignIdRef.current;
+            const cid = appIdRef.current;
             const vid = visitorIdRef.current;
             if (!cid || !vid)
                 return;
@@ -285,7 +294,7 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
             // firebase uid, supabase uuid.
             if (!uid || uid.length > 128)
                 return;
-            const cid = campaignIdRef.current;
+            const cid = appIdRef.current;
             const vid = visitorIdRef.current;
             if (!cid || !vid)
                 return;
@@ -315,7 +324,7 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
                 return;
             if (isOptedOut())
                 return;
-            const cid = campaignIdRef.current;
+            const cid = appIdRef.current;
             const vid = visitorIdRef.current;
             if (!cid || !vid)
                 return;
@@ -347,6 +356,12 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
                 gclid: params.get('gclid') || '',
                 screen_width: window.innerWidth,
             };
+            // Attach the (single-use) Turnstile token if one is still unconsumed.
+            // Matters for consent flows where the host disabled auto-capture and
+            // this manual call is the session-opening event.
+            const tsToken = consumeTurnstileToken();
+            if (tsToken)
+                payload.cf_turnstile_token = tsToken;
             queueRef.current?.enqueue(`${apiBase}/api/v1/web/event`, payload);
             log('pageview (manual)', { path: pagePath });
         }
@@ -425,6 +440,13 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
     useEffect(() => {
         if (typeof window === 'undefined')
             return;
+        // Neither appId nor the legacy campaignId alias was passed — nothing to
+        // attribute events to, so stay dormant instead of firing junk.
+        if (!appIdRef.current) {
+            // eslint-disable-next-line no-console
+            console.error('[Affiliateo] Missing appId — pass your app ID to <AffiliateoProvider appId="...">.');
+            return;
+        }
         // Mount-count warning. Fires only when more than one Provider has
         // ever mounted in the page lifetime. Dev-only; production swallows
         // the warning to avoid noise in real merchant consoles.
@@ -613,7 +635,7 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
             vid = uuid();
         }
         lsSet(LS_VISITOR_ID, vid);
-        lsSet(LS_CAMPAIGN_ID, campaignIdRef.current);
+        lsSet(LS_APP_ID, appIdRef.current);
         visitorIdRef.current = vid;
         // Read ref. Cross-domain inbound wins, then fresh affiliate link
         // params (?ref / ?via / ?source), then stored value.
@@ -628,7 +650,7 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
             visitorId: vid,
             track, identify, trackPageview, reset, optOut, optIn, flush,
         });
-        log('init', { campaign: campaignIdRef.current, visitor: vid, ref: ref || null });
+        log('init', { app: appIdRef.current, visitor: vid, ref: ref || null });
         // lastSendTime drives the visibility-refire heuristic below (refire a
         // pageview when a tab returns after the session window). Duplicate
         // suppression itself is the persisted same-URL throttle inside
@@ -659,9 +681,14 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
             ssSet(SS_PV_THROTTLE, JSON.stringify({ url: href, time: now }));
             lastSendTime = now;
             ended = false;
+            // Attach the (single-use) Turnstile token to the session-opening
+            // pageview. consumeTurnstileToken() returns null after the first
+            // consume, so SPA navigations go out bare — the server trusts them
+            // because the visitor row was created behind the verified token.
+            const tsToken = consumeTurnstileToken();
             queue.enqueue(endpoint, {
                 type: 'pageview',
-                campaign_id: campaignIdRef.current,
+                campaign_id: appIdRef.current,
                 visitor_id: vid,
                 session_id: getSessionId(),
                 url: href,
@@ -677,6 +704,7 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
                 ttclid: params.get('ttclid') || '',
                 gclid: params.get('gclid') || '',
                 screen_width: window.innerWidth,
+                ...(tsToken ? { cf_turnstile_token: tsToken } : {}),
             });
             log('pageview', { path: window.location.pathname });
         }
@@ -702,7 +730,7 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
             queue.flushOnUnload();
             const data = JSON.stringify({
                 type: 'session_end',
-                campaign_id: campaignIdRef.current,
+                campaign_id: appIdRef.current,
                 visitor_id: vid,
                 ref: ref || lsGet(LS_REF) || '',
             });
@@ -746,13 +774,30 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
                 }
             }
         }
-        // Send pageview on mount. captureInitialPageview === false skips this
-        // for cookie-consent flows where the host wants to defer until the
-        // user accepts (then call trackPageview() manually).
-        if (!sentRef.current && autoCfg.captureInitialPageview && autoCfg.enabled) {
-            sentRef.current = true;
-            sendPageview();
-        }
+        // Kick off the Turnstile mint regardless of auto-capture config so a
+        // consent flow's later manual trackPageview() finds a token waiting.
+        // Never rejects; resolves with or without a token (see turnstile.ts).
+        let cancelled = false;
+        void mintTurnstileToken().then(() => {
+            // Send pageview on mount, deferred until the Turnstile mint settles so
+            // the session-opening event carries the token (SPA navigations reuse
+            // the resolved state and don't wait). captureInitialPageview === false
+            // skips this for cookie-consent flows where the host wants to defer
+            // until the user accepts (then call trackPageview() manually).
+            //
+            // sentRef is set HERE (not before the mint) so a StrictMode
+            // double-mount can't mark the pageview as sent and then tear down the
+            // queue before the deferred send ever ran — the surviving mount's
+            // callback sees sentRef still false and fires.
+            if (cancelled)
+                return;
+            if (sentRef.current)
+                return;
+            if (autoCfg.captureInitialPageview && autoCfg.enabled) {
+                sentRef.current = true;
+                sendPageview();
+            }
+        });
         // Detect user leaving
         document.addEventListener('visibilitychange', onVisibilityChange);
         window.addEventListener('pagehide', sendEnd);
@@ -884,6 +929,7 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
             document.addEventListener('keydown', onKeydownForLinkDecoration, true);
         }
         return () => {
+            cancelled = true;
             document.removeEventListener('visibilitychange', onVisibilityChange);
             window.removeEventListener('pagehide', sendEnd);
             window.removeEventListener('popstate', onUrlChange);

package/dist/turnstile.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Cloudflare Turnstile token minting. Mirrors the hosted t.js tracker:
+ * mint ONE invisible token at SDK init and attach it to the first pageview.
+ * The server verifies the token before creating the visitor row (and before
+ * counting a pay-per-click web_traffic click — the billable path REQUIRES a
+ * genuine pass when TURNSTILE_SECRET is configured). Subsequent events from
+ * the same visitor_id are trusted because the row was created behind a
+ * verified token, so the cost is one mint + one verify per session.
+ *
+ * Tokens are single-use at Cloudflare's siteverify, so consumeToken()
+ * hands the token out exactly once — re-sending a used token would get the
+ * event rejected server-side, not warn-allowed.
+ *
+ * Failure modes: if the Turnstile script is blocked (ad blockers, strict
+ * CSP), errors, or times out, minting resolves with no token and events go
+ * out bare. The server's warn-allow mode (TURNSTILE_REQUIRE unset) lets
+ * those through; commission-on-sale (web_affiliate) tracking never depends
+ * on the token at all.
+ */
+interface TurnstileApi {
+    render: (el: HTMLElement, opts: Record<string, unknown>) => unknown;
+}
+declare global {
+    interface Window {
+        turnstile?: TurnstileApi;
+        __affiliateoTSLoaded?: () => void;
+    }
+}
+/**
+ * Load the Turnstile script (once) and run the invisible challenge. Resolves
+ * when a token is available OR the mint failed/timed out — never rejects, so
+ * callers can unconditionally `.then(sendPageview)`.
+ */
+export declare function mintTurnstileToken(): Promise<void>;
+/**
+ * Hand out the minted token exactly once (single-use at siteverify).
+ * Returns null when no token was minted or it was already consumed.
+ */
+export declare function consumeTurnstileToken(): string | null;
+export {};

package/dist/turnstile.js

@@ -0,0 +1,105 @@
+/**
+ * Cloudflare Turnstile token minting. Mirrors the hosted t.js tracker:
+ * mint ONE invisible token at SDK init and attach it to the first pageview.
+ * The server verifies the token before creating the visitor row (and before
+ * counting a pay-per-click web_traffic click — the billable path REQUIRES a
+ * genuine pass when TURNSTILE_SECRET is configured). Subsequent events from
+ * the same visitor_id are trusted because the row was created behind a
+ * verified token, so the cost is one mint + one verify per session.
+ *
+ * Tokens are single-use at Cloudflare's siteverify, so consumeToken()
+ * hands the token out exactly once — re-sending a used token would get the
+ * event rejected server-side, not warn-allowed.
+ *
+ * Failure modes: if the Turnstile script is blocked (ad blockers, strict
+ * CSP), errors, or times out, minting resolves with no token and events go
+ * out bare. The server's warn-allow mode (TURNSTILE_REQUIRE unset) lets
+ * those through; commission-on-sale (web_affiliate) tracking never depends
+ * on the token at all.
+ */
+// Public sitekey (safe to expose) — the same one public/t.js ships. The
+// matching secret lives in TURNSTILE_SECRET on the server.
+const TURNSTILE_SITEKEY = '0x4AAAAAADR5UW2x6axFd13p';
+const TURNSTILE_SCRIPT_SRC = 'https://challenges.cloudflare.com/turnstile/v0/api.js?onload=__affiliateoTSLoaded&render=explicit';
+// Hard deadline for the whole mint (script load + challenge). t.js relies on
+// Turnstile's own timeout-callback, but a script tag that never loads never
+// fires ANY callback — this timer makes sure the first pageview can't be
+// held hostage by a blocked challenges.cloudflare.com.
+const MINT_TIMEOUT_MS = 3000;
+let token = null;
+let minting = null;
+/**
+ * Load the Turnstile script (once) and run the invisible challenge. Resolves
+ * when a token is available OR the mint failed/timed out — never rejects, so
+ * callers can unconditionally `.then(sendPageview)`.
+ */
+export function mintTurnstileToken() {
+    if (typeof window === 'undefined' || typeof document === 'undefined') {
+        return Promise.resolve();
+    }
+    if (minting)
+        return minting;
+    minting = new Promise((resolve) => {
+        let settled = false;
+        const settle = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(deadline);
+            resolve();
+        };
+        const deadline = setTimeout(settle, MINT_TIMEOUT_MS);
+        const render = () => {
+            if (!window.turnstile) {
+                settle();
+                return;
+            }
+            try {
+                const holder = document.createElement('div');
+                holder.style.display = 'none';
+                document.body.appendChild(holder);
+                window.turnstile.render(holder, {
+                    sitekey: TURNSTILE_SITEKEY,
+                    // Invisible widget — never shows UI. Real browsers pass the
+                    // challenge in 50-200ms with zero user interaction.
+                    size: 'invisible',
+                    callback: (tok) => {
+                        token = tok;
+                        settle();
+                    },
+                    'error-callback': settle,
+                    'timeout-callback': settle,
+                });
+            }
+            catch {
+                settle();
+            }
+        };
+        if (window.turnstile) {
+            render();
+            return;
+        }
+        try {
+            const script = document.createElement('script');
+            script.src = TURNSTILE_SCRIPT_SRC;
+            script.async = true;
+            script.defer = true;
+            script.onerror = settle;
+            window.__affiliateoTSLoaded = render;
+            document.head.appendChild(script);
+        }
+        catch {
+            settle();
+        }
+    });
+    return minting;
+}
+/**
+ * Hand out the minted token exactly once (single-use at siteverify).
+ * Returns null when no token was minted or it was already consumed.
+ */
+export function consumeTurnstileToken() {
+    const t = token;
+    token = null;
+    return t;
+}

package/dist/types.d.ts

@@ -1,5 +1,11 @@
 export interface AffiliateoConfig {
-    campaignId: string;
+    /** Your Affiliateo app ID — shown in the dashboard when you create a
+     *  Web App Affiliate app. One of `appId` / `campaignId` is required;
+     *  `appId` wins when both are set. */
+    appId?: string;
+    /** @deprecated Affiliateo campaigns are now called apps — use `appId`.
+     *  Kept working so existing integrations don't break. */
+    campaignId?: string;
     /** Base URL for the API. Defaults to https://affiliateo.com */
     apiUrl?: string;
     /** Other domains that are part of the same merchant property and should
@@ -22,7 +28,7 @@ export interface AffiliateoConfig {
      *
      *  Example:
      *    <AffiliateoProvider
-     *      campaignId="..."
+     *      appId="..."
      *      allowedHostnames={['app.merchant.com', 'docs.merchant.com']}
      *    > */
     allowedHostnames?: string[];
@@ -36,7 +42,7 @@ export interface AffiliateoConfig {
      *  land server-side).
      *
      *  Example:
-     *    <AffiliateoProvider campaignId="..." allowLocalhost> */
+     *    <AffiliateoProvider appId="..." allowLocalhost> */
     allowLocalhost?: boolean;
     /** Allow tracking when the page is rendered inside an iframe. Defaults
      *  to false so scrapers, preview tools, and other sites embedding yours
@@ -55,7 +61,7 @@ export interface AffiliateoConfig {
      *  showing up?". Leave off in production.
      *
      *  Example:
-     *    <AffiliateoProvider campaignId="..." debug> */
+     *    <AffiliateoProvider appId="..." debug> */
     debug?: boolean;
     /** Allow tracking from pages served via the `file://` protocol (someone
      *  double-clicking a built HTML file instead of running a server).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@affiliateo/web",
-  "version": "4.4.1",
+  "version": "4.6.0",
   "description": "Affiliateo web SDK — affiliate attribution and tracking for web apps",
   "main": "dist/index.js",
   "module": "dist/index.js",