@affiliateo/web 1.0.0 → 1.1.5

package/package.json

@@ -1,14 +1,22 @@
-{
-  "name": "@affiliateo/web",
-  "version": "1.0.0",
-  "description": "Affiliateo web SDK — pass affiliate attribution metadata to your Stripe checkout",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
-  "scripts": {
-    "build": "tsc",
-    "typecheck": "tsc --noEmit"
-  },
-  "keywords": ["affiliateo", "affiliate", "attribution", "stripe", "web"],
-  "license": "MIT",
-  "files": ["src"]
-}
+{
+  "name": "@affiliateo/web",
+  "version": "1.1.5",
+  "description": "Affiliateo web SDK — affiliate attribution and session tracking for web apps",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "keywords": ["affiliateo", "affiliate", "attribution", "stripe", "web", "session", "tracking"],
+  "license": "MIT",
+  "files": ["src"]
+}

package/src/index.ts

@@ -1,72 +1,29 @@
-/**
- * @affiliateo/web — Pass affiliate attribution metadata to your Stripe checkout.
- *
- * Usage:
- * ```ts
- * import { getMetadata } from '@affiliateo/web';
- *
- * const session = await stripe.checkout.sessions.create({
- *   line_items: [...],
- *   mode: 'payment',
- *   metadata: getMetadata(req),
- * });
- * ```
- */
-
-/**
- * Extract affiliateo cookies from an incoming request.
- * Works with Next.js (App Router & Pages Router), Express, and any framework
- * that exposes cookies on the request object.
- *
- * Returns metadata object to pass to Stripe checkout session.
- */
-export function getMetadata(
-  req: {
-    cookies?: Record<string, string> | { get?: (name: string) => { value: string } | undefined }
-    headers?: { cookie?: string } | Headers
-  }
-): { affiliateo_visitor_id?: string; affiliateo_ref?: string } {
-  const metadata: { affiliateo_visitor_id?: string; affiliateo_ref?: string } = {}
-
-  // Try Next.js App Router cookies (ReadonlyRequestCookies with .get())
-  if (req.cookies && typeof req.cookies === 'object' && 'get' in req.cookies && typeof req.cookies.get === 'function') {
-    const visitorId = req.cookies.get('affiliateo_visitor_id')
-    const ref = req.cookies.get('affiliateo_ref')
-    if (visitorId?.value) metadata.affiliateo_visitor_id = visitorId.value
-    if (ref?.value) metadata.affiliateo_ref = ref.value
-    return metadata
-  }
-
-  // Try plain object cookies (Express, Pages Router, etc.)
-  if (req.cookies && typeof req.cookies === 'object') {
-    const cookies = req.cookies as Record<string, string>
-    if (cookies.affiliateo_visitor_id) metadata.affiliateo_visitor_id = cookies.affiliateo_visitor_id
-    if (cookies.affiliateo_ref) metadata.affiliateo_ref = cookies.affiliateo_ref
-    return metadata
-  }
-
-  // Fallback: parse cookie header manually
-  const cookieHeader = req.headers instanceof Headers
-    ? req.headers.get('cookie')
-    : (req.headers as { cookie?: string })?.cookie
-
-  if (cookieHeader) {
-    const cookies = parseCookies(cookieHeader)
-    if (cookies.affiliateo_visitor_id) metadata.affiliateo_visitor_id = cookies.affiliateo_visitor_id
-    if (cookies.affiliateo_ref) metadata.affiliateo_ref = cookies.affiliateo_ref
-  }
-
-  return metadata
-}
-
-/**
- * Parse a cookie header string into key-value pairs.
- */
-function parseCookies(cookieHeader: string): Record<string, string> {
-  const cookies: Record<string, string> = {}
-  for (const pair of cookieHeader.split(';')) {
-    const [key, ...rest] = pair.trim().split('=')
-    if (key) cookies[key.trim()] = rest.join('=').trim()
-  }
-  return cookies
-}
+/**
+ * @affiliateo/web — Affiliate attribution and session tracking for web apps.
+ *
+ * React usage:
+ * ```tsx
+ * import { AffiliateoProvider } from '@affiliateo/web';
+ *
+ * export default function App() {
+ *   return (
+ *     <AffiliateoProvider siteId="YOUR_SITE_ID">
+ *       <YourApp />
+ *     </AffiliateoProvider>
+ *   );
+ * }
+ * ```
+ *
+ * Server-side (pass ref to Stripe checkout):
+ * ```ts
+ * import { getMetadata } from '@affiliateo/web';
+ *
+ * const session = await stripe.checkout.sessions.create({
+ *   metadata: getMetadata(req),
+ * });
+ * ```
+ */
+
+export { AffiliateoProvider, useAffiliateRef } from './provider'
+export { getMetadata } from './metadata'
+export type { AffiliateoConfig, AffiliateoContextValue } from './types'

package/src/metadata.ts

@@ -0,0 +1,57 @@
+/**
+ * Extract affiliateo cookies from an incoming request.
+ * Works with Next.js (App Router & Pages Router), Express, and any framework
+ * that exposes cookies on the request object.
+ *
+ * Returns metadata object to pass to Stripe checkout session.
+ */
+export function getMetadata(
+  req: {
+    cookies?: Record<string, string> | { get?: (name: string) => { value: string } | undefined }
+    headers?: { cookie?: string } | Headers
+  }
+): { affiliateo_visitor_id?: string; affiliateo_ref?: string } {
+  const metadata: { affiliateo_visitor_id?: string; affiliateo_ref?: string } = {}
+
+  // Try Next.js App Router cookies (ReadonlyRequestCookies with .get())
+  if (req.cookies && typeof req.cookies === 'object' && 'get' in req.cookies && typeof req.cookies.get === 'function') {
+    const visitorId = req.cookies.get('affiliateo_visitor_id')
+    const ref = req.cookies.get('affiliateo_ref')
+    if (visitorId?.value) metadata.affiliateo_visitor_id = visitorId.value
+    if (ref?.value) metadata.affiliateo_ref = ref.value
+    return metadata
+  }
+
+  // Try plain object cookies (Express, Pages Router, etc.)
+  if (req.cookies && typeof req.cookies === 'object') {
+    const cookies = req.cookies as Record<string, string>
+    if (cookies.affiliateo_visitor_id) metadata.affiliateo_visitor_id = cookies.affiliateo_visitor_id
+    if (cookies.affiliateo_ref) metadata.affiliateo_ref = cookies.affiliateo_ref
+    return metadata
+  }
+
+  // Fallback: parse cookie header manually
+  const cookieHeader = req.headers instanceof Headers
+    ? req.headers.get('cookie')
+    : (req.headers as { cookie?: string })?.cookie
+
+  if (cookieHeader) {
+    const cookies = parseCookies(cookieHeader)
+    if (cookies.affiliateo_visitor_id) metadata.affiliateo_visitor_id = cookies.affiliateo_visitor_id
+    if (cookies.affiliateo_ref) metadata.affiliateo_ref = cookies.affiliateo_ref
+  }
+
+  return metadata
+}
+
+/**
+ * Parse a cookie header string into key-value pairs.
+ */
+function parseCookies(cookieHeader: string): Record<string, string> {
+  const cookies: Record<string, string> = {}
+  for (const pair of cookieHeader.split(';')) {
+    const [key, ...rest] = pair.trim().split('=')
+    if (key) cookies[key.trim()] = rest.join('=').trim()
+  }
+  return cookies
+}

package/src/provider.tsx

@@ -0,0 +1,147 @@
+'use client'
+
+import React, { createContext, useContext, useEffect, useRef, useState } from 'react'
+import type { AffiliateoConfig, AffiliateoContextValue } from './types'
+
+const DEFAULT_API_URL = 'https://affiliateo.com'
+
+// Cookie helpers
+function getCookie(name: string): string | null {
+  if (typeof document === 'undefined') return null
+  const m = document.cookie.match(new RegExp('(^| )' + name + '=([^;]+)'))
+  return m ? m[2] : null
+}
+
+function setCookie(name: string, value: string, days: number) {
+  if (typeof document === 'undefined') return
+  const dt = new Date()
+  dt.setTime(dt.getTime() + days * 864e5)
+  document.cookie = `${name}=${value};expires=${dt.toUTCString()};path=/;SameSite=Lax`
+}
+
+// Generate UUID
+function uuid(): string {
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) return crypto.randomUUID()
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0
+    const v = c === 'x' ? r : (r & 0x3) | 0x8
+    return v.toString(16)
+  })
+}
+
+const AffiliateoContext = createContext<AffiliateoContextValue>({
+  refCode: null,
+  visitorId: null,
+})
+
+/**
+ * Returns the affiliate ref code and visitor ID.
+ */
+export function useAffiliateRef(): AffiliateoContextValue {
+  return useContext(AffiliateoContext)
+}
+
+export function AffiliateoProvider({
+  siteId,
+  apiUrl,
+  children,
+}: AffiliateoConfig & { children: React.ReactNode }) {
+  const [state, setState] = useState<AffiliateoContextValue>({
+    refCode: null,
+    visitorId: null,
+  })
+
+  const apiBase = (apiUrl || DEFAULT_API_URL).replace(/\/$/, '')
+  const siteIdRef = useRef(siteId)
+  const visitorIdRef = useRef<string | null>(null)
+  const refRef = useRef<string | null>(null)
+  const sentRef = useRef(false)
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return
+
+    // Get or create visitor ID
+    let vid = getCookie('affiliateo_visitor_id')
+    if (!vid) {
+      vid = uuid()
+    }
+    setCookie('affiliateo_visitor_id', vid, 365)
+    visitorIdRef.current = vid
+
+    // Read ref from URL params
+    const params = new URLSearchParams(window.location.search)
+    const ref = params.get('ref') || params.get('via') || params.get('source') || getCookie('affiliateo_ref') || null
+    if (ref) {
+      setCookie('affiliateo_ref', ref, 365)
+    }
+    refRef.current = ref
+
+    setState({ refCode: ref, visitorId: vid })
+
+    // Send event helper
+    function send(type: string) {
+      const payload = {
+        type,
+        site_id: siteIdRef.current,
+        visitor_id: visitorIdRef.current,
+        url: window.location.href,
+        path: window.location.pathname,
+        hostname: window.location.hostname,
+        referrer: document.referrer || '',
+        ref: refRef.current || '',
+        utm_source: params.get('utm_source') || '',
+        utm_medium: params.get('utm_medium') || '',
+        utm_campaign: params.get('utm_campaign') || '',
+        screen_width: window.innerWidth,
+      }
+      const data = JSON.stringify(payload)
+      if (navigator.sendBeacon) {
+        navigator.sendBeacon(`${apiBase}/api/v1/event`, new Blob([data], { type: 'application/json' }))
+      } else {
+        fetch(`${apiBase}/api/v1/event`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: data,
+          keepalive: true,
+        }).catch(() => {})
+      }
+    }
+
+    // Send initial session_start
+    if (!sentRef.current) {
+      sentRef.current = true
+      send('session_start')
+    }
+
+    // Visibility change — session_start/session_end
+    let left = false
+    function onLeave() {
+      if (left) return
+      left = true
+      send('session_end')
+    }
+
+    function onVisibilityChange() {
+      if (document.visibilityState === 'hidden') {
+        onLeave()
+      } else if (document.visibilityState === 'visible') {
+        left = false
+        send('session_start')
+      }
+    }
+
+    document.addEventListener('visibilitychange', onVisibilityChange)
+    window.addEventListener('beforeunload', onLeave)
+
+    return () => {
+      document.removeEventListener('visibilitychange', onVisibilityChange)
+      window.removeEventListener('beforeunload', onLeave)
+    }
+  }, [siteId, apiBase])
+
+  return (
+    <AffiliateoContext.Provider value={state}>
+      {children}
+    </AffiliateoContext.Provider>
+  )
+}

package/src/types.ts

@@ -0,0 +1,12 @@
+export interface AffiliateoConfig {
+  siteId: string
+  /** Base URL for the API. Defaults to https://affiliateo.com */
+  apiUrl?: string
+}
+
+export interface AffiliateoContextValue {
+  /** The affiliate ref code from the URL (if present) */
+  refCode: string | null
+  /** The visitor ID stored in the cookie */
+  visitorId: string | null
+}