@g2crowd/buyer-intent-provider-sdk 0.2.0 → 0.4.0

package/src/browser/sdk.js

@@ -0,0 +1,336 @@
+import { createBuyerIntentCore } from './core.js';
+import { sendWithBeacon } from './transport.js';
+import { createIdentityManager } from './identity.js';
+import {
+  readTags,
+  readElementConfig,
+  resolveEventName,
+  readSessionConfig,
+  collectSubjectIds,
+  readViewContext,
+} from './dom.js';
+
+const DEFAULT_ACTIVITY_ENDPOINT = '/activity/events';
+const DEFAULT_VIEW_NAME = '$view';
+const DEFAULT_CLICK_NAME = '$click';
+
+const firedViewElements = new WeakSet();
+
+export function createBuyerIntentSDK() {
+  const core = createBuyerIntentCore();
+  const identity = createIdentityManager();
+  let activityEndpoint = DEFAULT_ACTIVITY_ENDPOINT;
+  let origin = null;
+  let viewName = DEFAULT_VIEW_NAME;
+  let userType = 'standard';
+  let lastPageKey = null;
+  let initialLandingPage = null;
+  let initialReferrer = null;
+  let initialUtmParams = null;
+
+  function readUtmParams(urlValue) {
+    if (!urlValue) {
+      return {};
+    }
+
+    const url = new URL(urlValue, window.location.origin);
+    const params = url.searchParams;
+
+    return {
+      utm_source: params.get('utm_source') || undefined,
+      utm_medium: params.get('utm_medium') || undefined,
+      utm_campaign: params.get('utm_campaign') || undefined,
+      utm_term: params.get('utm_term') || undefined,
+      utm_content: params.get('utm_content') || undefined,
+    };
+  }
+
+  function buildVisitContext() {
+    if (typeof window === 'undefined') {
+      return {};
+    }
+
+    const landingPage = initialLandingPage || window.location.href;
+    return {
+      landingPage,
+      referrer: initialReferrer || document.referrer || undefined,
+      userAgent:
+        typeof navigator !== 'undefined' ? navigator.userAgent : undefined,
+      utmParams: initialUtmParams || readUtmParams(landingPage),
+    };
+  }
+
+  function applyElementConfig(element) {
+    const config = readElementConfig(element);
+
+    if (config.activityEndpoint) {
+      setActivityEndpoint(config.activityEndpoint);
+    }
+
+    if (config.origin || config.userType || config.distinctId) {
+      setBaseProperties({
+        origin: config.origin,
+        userType: config.userType,
+        distinctId: config.distinctId,
+      });
+    }
+  }
+
+  function applyDomTags(element) {
+    const elements = element ? new Set([element]) : undefined;
+    const entries = readTags(elements);
+    entries.forEach(({ element: tagElement, tag }) => {
+      applyElementConfig(tagElement);
+      core.tagPage(tag);
+    });
+    return entries.length > 0;
+  }
+
+  function sendPayload(element, defaultEventName) {
+    if (typeof window === 'undefined') {
+      return false;
+    }
+
+    const eventName = resolveEventName(element, defaultEventName);
+    const payload = core.buildPayload({
+      name: eventName,
+      url: window.location.href,
+      origin: origin || window.location.hostname,
+      distinctId: identity.ensure(),
+      userType,
+      visit: buildVisitContext(),
+    });
+
+    const sent = sendWithBeacon(activityEndpoint, payload);
+    core.resetPageState();
+    return sent;
+  }
+
+  function trackPageviewInternal(element) {
+    if (typeof window === 'undefined') {
+      return false;
+    }
+
+    const pageKey = `${window.location.pathname}${window.location.search}`;
+    if (pageKey === lastPageKey) {
+      return false;
+    }
+
+    lastPageKey = pageKey;
+    return sendPayload(element, viewName);
+  }
+
+  function trackPageview(element) {
+    if (typeof window === 'undefined') {
+      return false;
+    }
+
+    const pageKey = `${window.location.pathname}${window.location.search}`;
+    if (pageKey === lastPageKey) {
+      return false;
+    }
+
+    lastPageKey = pageKey;
+    const hasTags = applyDomTags(element);
+    if (!hasTags) {
+      return false;
+    }
+
+    return sendPayload(element, viewName);
+  }
+
+  function trackClick(element) {
+    if (typeof window === 'undefined' || !element) {
+      return false;
+    }
+
+    return sendPayload(element, DEFAULT_CLICK_NAME);
+  }
+
+  function init(options = {}) {
+    activityEndpoint = options.activityEndpoint || activityEndpoint;
+    origin = options.origin || origin;
+    viewName = options.viewName || options.pageviewName || viewName;
+    userType = options.userType || userType;
+
+    if (options.distinctId) {
+      identity.set(options.distinctId);
+    }
+
+    if (typeof window !== 'undefined' && !initialLandingPage) {
+      initialLandingPage = window.location.href;
+      initialReferrer = document.referrer || undefined;
+      initialUtmParams = readUtmParams(initialLandingPage);
+    }
+
+    core.setBaseProperties({
+      origin: origin || undefined,
+      distinctId: identity.get() || undefined,
+      userType,
+    });
+  }
+
+  function setActivityEndpoint(value) {
+    activityEndpoint = value || activityEndpoint;
+  }
+
+  function setBaseProperties(options = {}) {
+    if (options.origin) {
+      origin = options.origin;
+    }
+
+    if (options.distinctId) {
+      identity.set(options.distinctId);
+    }
+
+    if (options.userType) {
+      userType = options.userType;
+    }
+
+    core.setBaseProperties({
+      origin: origin || undefined,
+      distinctId: identity.get() || undefined,
+      userType,
+    });
+  }
+
+  function tagPage(options = {}) {
+    core.tagPage(options);
+  }
+
+  function setVisitProperties(options = {}) {
+    core.setVisitProperties(options);
+  }
+
+  function trackNextRouter(nextRouter) {
+    if (!nextRouter || !nextRouter.events) {
+      return () => {};
+    }
+
+    const handler = () => trackPageview();
+    nextRouter.events.on('routeChangeComplete', handler);
+    return () => nextRouter.events.off('routeChangeComplete', handler);
+  }
+
+  function resolveConfig(element) {
+    const session = readSessionConfig(element);
+    const own = readElementConfig(element);
+    return {
+      origin: session.origin || own.origin,
+      activityEndpoint: session.activityEndpoint || own.activityEndpoint,
+      userType: session.userType || own.userType,
+      distinctId: session.distinctId || own.distinctId,
+    };
+  }
+
+  function applyConfig(config) {
+    if (config.activityEndpoint) {
+      setActivityEndpoint(config.activityEndpoint);
+    }
+    if (config.origin || config.userType || config.distinctId) {
+      setBaseProperties({
+        origin: config.origin,
+        userType: config.userType,
+        distinctId: config.distinctId,
+      });
+    }
+  }
+
+  function handleView(element) {
+    if (!element || firedViewElements.has(element)) {
+      return false;
+    }
+
+    firedViewElements.add(element);
+
+    // 1. Resolve config: session ancestor > element's own data-* attrs
+    const config = resolveConfig(element);
+    applyConfig(config);
+
+    // 2. Read page tags from element's data-buyer-intent (existing flow)
+    const entries = readTags(new Set([element]));
+    entries.forEach(({ element: tagElement, tag }) => {
+      if (tagElement !== element) {
+        applyElementConfig(tagElement);
+      }
+      core.tagPage(tag);
+    });
+
+    // 3. Collect IDs from descendant <buyer-intent-subject> elements
+    const subjectIds = collectSubjectIds(element);
+    if (subjectIds.productIds.length || subjectIds.categoryIds.length) {
+      core.tagPage(subjectIds);
+    }
+
+    // 4. Fire pageview
+    return trackPageviewInternal(element, config);
+  }
+
+  function handleClick(element) {
+    if (!element) {
+      return false;
+    }
+
+    // 1. Resolve config: session ancestor > element's own data-* attrs
+    const config = resolveConfig(element);
+    applyConfig(config);
+
+    // 2. Inherit tag/IDs from ancestor <buyer-intent-view>
+    const viewCtx = readViewContext(element);
+    if (viewCtx && typeof viewCtx === 'object') {
+      core.tagPage(viewCtx);
+    }
+
+    // 3. Also read click element's own data-buyer-intent
+    const entries = readTags(new Set([element]));
+    entries.forEach(({ tag }) => core.tagPage(tag));
+
+    return trackClick(element);
+  }
+
+  function listenForElements() {
+    if (typeof document === 'undefined') {
+      return;
+    }
+
+    if (document.__buyerIntentListenersBound) {
+      return;
+    }
+
+    document.__buyerIntentListenersBound = true;
+
+    document.addEventListener('buyerintent:view', (e) => {
+      handleView(e.target);
+    });
+
+    document.addEventListener('buyerintent:click', (e) => {
+      handleClick(e.target);
+    });
+  }
+
+  listenForElements();
+
+  return {
+    init,
+    trackPageview,
+    trackClick,
+    tagPage,
+    setBaseProperties,
+    setVisitProperties,
+    setActivityEndpoint,
+    trackNextRouter,
+    listenForElements,
+  };
+}
+
+let _instance;
+
+export function ensureSDK() {
+  if (!_instance) {
+    _instance = createBuyerIntentSDK();
+  }
+  _instance.listenForElements();
+  return _instance;
+}
+
+export const buyerIntent = ensureSDK();

package/src/browser/transport.js

@@ -0,0 +1,25 @@
+export function sendWithBeacon(url, payload) {
+  if (
+    typeof navigator !== 'undefined' &&
+    typeof navigator.sendBeacon === 'function'
+  ) {
+    const blob = new Blob([JSON.stringify(payload)], {
+      type: 'application/json',
+    });
+    const sent = navigator.sendBeacon(url, blob);
+    if (sent) {
+      return true;
+    }
+  }
+
+  if (typeof fetch !== 'undefined') {
+    fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+      keepalive: true,
+    });
+  }
+
+  return false;
+}

package/src/index.d.ts

@@ -0,0 +1,126 @@
+export class BuyerIntentSessionElement extends HTMLElement {}
+export class BuyerIntentSubjectElement extends HTMLElement {}
+export class BuyerIntentViewElement extends HTMLElement {}
+export class BuyerIntentClickElement extends HTMLElement {}
+
+export type ViewTag =
+  | 'products.show'
+  | 'products.pricing'
+  | 'products.competitors'
+  | 'categories.show'
+  | 'comparisons.show'
+  | 'reviewers.take_survey';
+
+export type ClickEventName = '/ad/clicked' | '/leads/create';
+
+/**
+ * - `guest` — logged-out visitor
+ * - `standard` — logged-in user (default)
+ * - `vendor-admin` — vendor role viewing their own content
+ * - `observer` — internal employee / superuser
+ */
+export type UserType = 'guest' | 'standard' | 'vendor-admin' | 'observer';
+
+interface BuyerIntentBaseAttrs {
+  'data-origin'?: string;
+  'data-activity-endpoint'?: string;
+  'data-user-type'?: UserType;
+  'data-distinct-id'?: string;
+  'data-buyer-intent'?: string;
+  'product-id'?: string;
+  'product-ids'?: string;
+  'category-id'?: string;
+}
+
+export interface BuyerIntentSessionAttrs {
+  origin?: string;
+  'activity-endpoint'?: string;
+  'user-type'?: UserType;
+  'distinct-id'?: string;
+}
+
+export interface BuyerIntentSubjectAttrs {
+  'product-id'?: string;
+  'product-ids'?: string;
+  'category-id'?: string;
+  'category-ids'?: string;
+}
+
+export interface BuyerIntentViewAttrs extends BuyerIntentBaseAttrs {
+  tag?: ViewTag | string;
+  'source-location'?: string;
+}
+
+export interface BuyerIntentClickAttrs extends BuyerIntentBaseAttrs {
+  'event-name'?: ClickEventName | string;
+}
+
+declare global {
+  namespace JSX {
+    interface IntrinsicElements {
+      'buyer-intent-session': BuyerIntentSessionAttrs &
+        React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;
+      'buyer-intent-subject': BuyerIntentSubjectAttrs &
+        React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;
+      'buyer-intent-view': BuyerIntentViewAttrs &
+        React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;
+      'buyer-intent-click': BuyerIntentClickAttrs &
+        React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;
+    }
+  }
+}
+
+export type BuyerIntentInitOptions = {
+  activityEndpoint?: string;
+  origin?: string;
+  viewName?: string;
+  distinctId?: string;
+  userType?: UserType;
+};
+
+export type BuyerIntentTagOptions = {
+  productIds?: number[];
+  categoryIds?: number[];
+  tag?: string;
+  sourceLocation?: string;
+  context?: Record<string, unknown>;
+};
+
+export type BuyerIntentBaseOptions = {
+  origin?: string;
+  distinctId?: string;
+  userType?: UserType;
+};
+
+export type BuyerIntentVisitProperties = {
+  ip?: string;
+  referrer?: string;
+  landing_page?: string;
+  user_agent?: string;
+  utm_source?: string;
+  utm_medium?: string;
+  utm_campaign?: string;
+  utm_term?: string;
+  utm_content?: string;
+  [key: string]: unknown;
+};
+
+export type BuyerIntentSDK = {
+  init: (options?: BuyerIntentInitOptions) => void;
+  trackPageview: (element?: Element) => boolean;
+  trackClick: (element: Element) => boolean;
+  tagPage: (options?: BuyerIntentTagOptions) => void;
+  setBaseProperties: (options?: BuyerIntentBaseOptions) => void;
+  setVisitProperties: (options?: BuyerIntentVisitProperties) => void;
+  setActivityEndpoint: (endpoint: string) => void;
+  trackNextRouter: (nextRouter: {
+    events?: {
+      on: (event: string, handler: () => void) => void;
+      off: (event: string, handler: () => void) => void;
+    };
+  }) => () => void;
+};
+
+export function createBuyerIntentSDK(): BuyerIntentSDK;
+export function ensureSDK(): BuyerIntentSDK;
+export const buyerIntent: BuyerIntentSDK;

package/src/index.js

@@ -0,0 +1,8 @@
+export {
+  buyerIntent,
+  createBuyerIntentSDK,
+  BuyerIntentSessionElement,
+  BuyerIntentSubjectElement,
+  BuyerIntentViewElement,
+  BuyerIntentClickElement,
+} from './browser/index.js';

package/src/react/index.d.ts

@@ -0,0 +1,77 @@
+import type * as React from 'react';
+import type { UserType } from '../index';
+
+type CommonProps = {
+  sourceLocation?: string;
+  context?: Record<string, unknown>;
+  origin?: string;
+  activityEndpoint?: string;
+  userType?: UserType;
+  distinctId?: string;
+  children?: React.ReactNode;
+};
+
+export type SessionProviderProps = {
+  origin?: string;
+  activityEndpoint?: string;
+  userType?: UserType;
+  distinctId?: string;
+  children?: React.ReactNode;
+};
+
+export type SubjectTrackerProps = {
+  productId?: number;
+  categoryId?: number;
+  productIds?: number[];
+  categoryIds?: number[];
+};
+
+export type ViewTrackerProps = CommonProps & {
+  tag?: string;
+  productId?: number;
+  productIds?: number[];
+  categoryId?: number;
+};
+
+export type ClickTrackerProps = CommonProps & {
+  eventName?: string;
+  productId?: number;
+  productIds?: number[];
+  categoryId?: number;
+};
+
+type ProductIdViewProps = CommonProps & { productId: number };
+type CategoryViewProps = CommonProps & { categoryId: number };
+type ProductIdsViewProps = CommonProps & { productIds: number[] };
+type ProductIdClickProps = CommonProps & { productId: number };
+
+export const SessionProvider: React.FC<SessionProviderProps>;
+export const SubjectTracker: React.FC<SubjectTrackerProps>;
+export const ViewTracker: React.FC<ViewTrackerProps>;
+export const ClickTracker: React.FC<ClickTrackerProps>;
+
+export const ProfileView: React.FC<ProductIdViewProps>;
+export const PricingView: React.FC<ProductIdViewProps>;
+export const CompetitorsView: React.FC<ProductIdViewProps>;
+export const CategoryView: React.FC<CategoryViewProps>;
+export const CompareView: React.FC<ProductIdsViewProps>;
+export const WriteReviewView: React.FC<ProductIdViewProps>;
+export const AdClick: React.FC<ProductIdClickProps>;
+export const LeadCreateClick: React.FC<ProductIdClickProps>;
+
+export const BuyerIntent: {
+  Session: React.FC<SessionProviderProps>;
+  Subject: React.FC<SubjectTrackerProps>;
+  View: React.FC<ViewTrackerProps>;
+  Click: React.FC<ClickTrackerProps>;
+  ViewTracker: React.FC<ViewTrackerProps>;
+  ClickTracker: React.FC<ClickTrackerProps>;
+  ProfileView: React.FC<ProductIdViewProps>;
+  PricingView: React.FC<ProductIdViewProps>;
+  CompetitorsView: React.FC<ProductIdViewProps>;
+  CategoryView: React.FC<CategoryViewProps>;
+  CompareView: React.FC<ProductIdsViewProps>;
+  WriteReviewView: React.FC<ProductIdViewProps>;
+  AdClick: React.FC<ProductIdClickProps>;
+  LeadCreateClick: React.FC<ProductIdClickProps>;
+};

package/{browser → src/react}/index.js

@@ -1,36 +1,46 @@
-import { ViewTracker, ClickTracker } from './tag_component.js';
+import '../browser/elements/index.js';
 import {
-  CompareView,
-  CompetitorsView,
+  SessionProvider,
+  SubjectTracker,
+  ViewTracker,
+  ClickTracker,
   ProfileView,
   PricingView,
+  CompetitorsView,
   CategoryView,
+  CompareView,
   WriteReviewView,
   AdClick,
   LeadCreateClick,
-} from './trackers.js';
+} from '../browser/components/index.js';
 
-export { createBuyerIntentSDK, buyerIntent } from './sdk.js';
-export { ViewTracker, ClickTracker };
 export {
-  CompareView,
-  CompetitorsView,
+  SessionProvider,
+  SubjectTracker,
+  ViewTracker,
+  ClickTracker,
   ProfileView,
   PricingView,
+  CompetitorsView,
   CategoryView,
+  CompareView,
   WriteReviewView,
   AdClick,
   LeadCreateClick,
 };
 
 export const BuyerIntent = {
+  Session: SessionProvider,
+  Subject: SubjectTracker,
+  View: ViewTracker,
+  Click: ClickTracker,
   ViewTracker,
   ClickTracker,
-  CompareView,
-  CompetitorsView,
   ProfileView,
   PricingView,
+  CompetitorsView,
   CategoryView,
+  CompareView,
   WriteReviewView,
   AdClick,
   LeadCreateClick,