@g2crowd/buyer-intent-provider-sdk 0.1.0

package/README.md

@@ -0,0 +1,243 @@
+# Buyer Intent JS SDK
+
+Buyer Intent tracking SDK that emits a pageview when a `buyer-intent-tag` element appears. It supports tagging pageview properties during rendering and sends events via `sendBeacon` for best-effort delivery during navigation.
+
+## Install
+
+```bash
+npm install @g2crowd/buyer-intent-provider-sdk
+```
+
+If you plan to use the built-in Kafka connection (via `kafkaBrokers`), install the peer dependency:
+
+```bash
+npm install kafkajs
+```
+
+## Quick Start (Next.js)
+
+```tsx
+// pages/_app.tsx
+import type { AppProps } from 'next/app';
+import { BuyerIntent } from '@g2crowd/buyer-intent-provider-sdk';
+
+export default function App({ Component, pageProps }: AppProps) {
+  return (
+    <BuyerIntent.TagComponent
+      productIds={[123]}
+      categoryIds={[45]}
+      tag="products.show"
+      sourceLocation="ProductsController#show"
+      origin="g2.com"
+      activityEndpoint="/api/activity/events"
+      userType="standard"
+    >
+      <Component {...pageProps} />
+    </BuyerIntent.TagComponent>
+  );
+}
+```
+
+## Backend (Next.js Route)
+
+```ts
+// app/api/activity/events/route.ts
+import { createNextRouteHandler } from '@g2crowd/buyer-intent-provider-sdk/server';
+
+const POST = createNextRouteHandler({
+  kafkaBrokers: [process.env.KAFKA_BROKER || 'localhost:9092'],
+  partnerId: process.env.PARTNER_ID,
+});
+
+export { POST };
+```
+
+## Barebones Server
+
+This package ships a tiny server that hosts `POST /activity/events`.
+
+```bash
+PARTNER_ID=partner-a KAFKA_BROKERS=broker1:9092,broker2:9092 \
+buyer-intent-server
+```
+
+Environment variables:
+
+- `PORT` (default: 3000)
+- `PARTNER_ID`
+- `TOPIC_PREFIX` (optional)
+- `KAFKA_BROKERS` (comma-separated)
+- `KAFKA_TOPIC` (optional override)
+- `KAFKA_CLIENT_ID` (optional)
+- `USE_DEV_LOGGER=true` (logs instead of Kafka)
+
+## Kafka Setup (Partner Checklist)
+
+Provide these values to your partners so they can publish to their scoped topic:
+
+- Kafka broker list (host:port)
+- Topic name (scoped to their tenant)
+- Auth mechanism (SASL user/pass or mTLS)
+- TLS requirements (on/off, CA certs if needed)
+
+By default, the SDK derives the topic from `partnerId` using `intent_events_<partnerId>`.
+
+Example using a prebuilt producer:
+
+```ts
+// app/api/activity/events/route.ts
+import { Kafka } from 'kafkajs';
+import { createNextRouteHandler } from '@g2crowd/buyer-intent-provider-sdk/server';
+
+const kafka = new Kafka({
+  clientId: 'partner-app',
+  brokers: (process.env.KAFKA_BROKERS || '').split(','),
+});
+
+const producer = kafka.producer({
+  allowAutoTopicCreation: false,
+});
+
+const POST = createNextRouteHandler({
+  producer,
+  partnerId: process.env.PARTNER_ID,
+  topicPrefix: process.env.TOPIC_PREFIX,
+});
+
+export { POST };
+```
+
+## Dev Adapter (No Kafka)
+
+If you want to test locally without Kafka, use the dev logger producer.
+
+```ts
+// app/api/activity/events/route.ts
+import {
+  createNextRouteHandler,
+  createDevLoggerProducer,
+} from '@g2crowd/buyer-intent-provider-sdk/server';
+
+const POST = createNextRouteHandler({
+  producer: createDevLoggerProducer(),
+  partnerId: 'dev',
+});
+
+export { POST };
+```
+
+## Tag Page Properties
+
+Wrap content with `BuyerIntent.TagComponent` to emit tags and trigger a single pageview when it appears. No pageview is emitted without this element.
+
+```tsx
+import { buyerIntent, BuyerIntent } from '@g2crowd/buyer-intent-provider-sdk';
+
+<BuyerIntent.TagComponent
+  productIds={[123, 456]}
+  categoryIds={[78]}
+  tag="products.show"
+  sourceLocation="ProductsController#show"
+  context={{ page: 'product' }}
+>
+  <div />
+</BuyerIntent.TagComponent>;
+
+buyerIntent.setVisitProperties({
+  ip: '203.0.113.10',
+  referrer: 'https://example.com/',
+  landing_page: 'https://example.com/products/abc',
+  user_agent: 'Mozilla/5.0',
+  utm_source: 'newsletter',
+  utm_medium: 'email',
+  utm_campaign: 'spring_launch',
+  utm_term: 'buyer-intent',
+  utm_content: 'cta-button',
+});
+```
+
+## API
+
+### trackPageview()
+
+Manually trigger a pageview (sent via `sendBeacon`).
+
+### trackTaggedPageview(element)
+
+Triggers a pageview for a specific tag element and only once per element.
+
+### tagPage(options)
+
+Accumulates properties to be attached to the next pageview.
+
+### BuyerIntent.TagComponent
+
+React component that renders tags into the DOM and triggers a single pageview when it appears.
+
+### setBaseProperties(options)
+
+Sets base properties like `origin`, `distinctId`, and `userType`.
+
+### setActivityEndpoint(url)
+
+Updates the endpoint used for event delivery.
+
+### setVisitProperties(options)
+
+Adds or overrides visit properties to be attached to the next pageview.
+
+### trackNextRouter(router)
+
+Wires Next.js `Router.events` to trigger pageview events on route changes (emits only when tag elements exist).
+
+### createActivityHandler(options)
+
+Returns a framework-agnostic handler that validates, enriches, and publishes events to Kafka.
+
+### createNextRouteHandler(options)
+
+Next.js Route Handler wrapper around `createActivityHandler`.
+
+### createDevLoggerProducer(options)
+
+Dev-only producer that logs messages instead of sending to Kafka.
+
+### topicName(options)
+
+Builds a topic name from a `partnerId` and optional `prefix`.
+
+## Event Payload
+
+The SDK sends the following JSON body to `activityEndpoint`:
+
+```json
+{
+  "name": "$view",
+  "properties": {
+    "product_ids": [123],
+    "category_ids": [78],
+    "tag": "products.show",
+    "url": "https://example.com/products/abc",
+    "user_type": "standard",
+    "distinct_id": "visitor-uuid",
+    "origin": "g2.com",
+    "source_location": "ProductsController#show",
+    "context": {
+      "page": "product"
+    }
+  },
+  "visit": {
+    "properties": {
+      "landing_page": "https://example.com/products/abc",
+      "referrer": "https://example.com/",
+      "user_agent": "Mozilla/5.0",
+      "ip": "203.0.113.10",
+      "utm_source": "newsletter",
+      "utm_medium": "email",
+      "utm_campaign": "spring_launch",
+      "utm_term": "buyer-intent",
+      "utm_content": "cta-button"
+    }
+  }
+}
+```

package/browser/core.js

@@ -0,0 +1,135 @@
+function uniqueMerge(existing, incoming) {
+  const values = new Set([...(existing || []), ...(incoming || [])]);
+  return Array.from(values).filter(
+    (value) => value !== undefined && value !== null
+  );
+}
+
+function compactObject(value) {
+  return Object.fromEntries(
+    Object.entries(value).filter(([_key, entry]) => entry !== undefined)
+  );
+}
+
+export function createBuyerIntentCore() {
+  const pageState = {
+    productIds: [],
+    categoryIds: [],
+    tag: undefined,
+    sourceLocation: undefined,
+    context: {}
+  };
+
+  const baseState = {
+    origin: undefined,
+    distinctId: undefined,
+    userType: 'standard'
+  };
+
+  const visitState = {
+    properties: {}
+  };
+
+  function setBaseProperties(options = {}) {
+    if (options.origin) {
+      baseState.origin = options.origin;
+    }
+
+    if (options.distinctId) {
+      baseState.distinctId = options.distinctId;
+    }
+
+    if (options.userType) {
+      baseState.userType = options.userType;
+    }
+  }
+
+  function setVisitProperties(options = {}) {
+    if (options && typeof options === 'object') {
+      visitState.properties = { ...visitState.properties, ...options };
+    }
+  }
+
+  function tagPage(options = {}) {
+    pageState.productIds = uniqueMerge(
+      pageState.productIds,
+      options.productIds || []
+    );
+    pageState.categoryIds = uniqueMerge(
+      pageState.categoryIds,
+      options.categoryIds || []
+    );
+
+    if (options.tag) {
+      pageState.tag = options.tag;
+    }
+
+    if (options.sourceLocation) {
+      pageState.sourceLocation = options.sourceLocation;
+    }
+
+    if (options.context && typeof options.context === 'object') {
+      pageState.context = { ...pageState.context, ...options.context };
+    }
+  }
+
+  function resetPageState() {
+    pageState.productIds = [];
+    pageState.categoryIds = [];
+    pageState.tag = undefined;
+    pageState.sourceLocation = undefined;
+    pageState.context = {};
+  }
+
+  function buildPayload({
+    name,
+    url,
+    origin,
+    distinctId,
+    userType,
+    visit = {}
+  }) {
+    const resolvedContext = Object.keys(pageState.context).length
+      ? pageState.context
+      : undefined;
+    const properties = compactObject({
+      product_ids: pageState.productIds,
+      category_ids: pageState.categoryIds,
+      tag: pageState.tag,
+      url,
+      user_type: userType || baseState.userType,
+      distinct_id: distinctId || baseState.distinctId,
+      origin: origin || baseState.origin,
+      source_location: pageState.sourceLocation,
+      context: resolvedContext
+    });
+
+    const visitProperties = compactObject({
+      landing_page: visit.landingPage,
+      referrer: visit.referrer,
+      user_agent: visit.userAgent,
+      utm_source: visit.utmParams?.utm_source,
+      utm_medium: visit.utmParams?.utm_medium,
+      utm_campaign: visit.utmParams?.utm_campaign,
+      utm_term: visit.utmParams?.utm_term,
+      utm_content: visit.utmParams?.utm_content,
+      ...visitState.properties
+    });
+
+    return compactObject({
+      name,
+      properties,
+      visit: Object.keys(visitProperties).length
+        ? { properties: visitProperties }
+        : undefined
+    });
+  }
+
+  return {
+    setBaseProperties,
+    setVisitProperties,
+    tagPage,
+    resetPageState,
+    buildPayload
+  };
+}

package/browser/index.js

@@ -0,0 +1,6 @@
+import { TagComponent } from './tag_component.js';
+
+export { createBuyerIntentSDK, buyerIntent } from './sdk.js';
+export { TagComponent };
+
+export const BuyerIntent = { TagComponent };

package/browser/sdk.js

@@ -0,0 +1,411 @@
+import { createBuyerIntentCore } from './core.js';
+
+const DEFAULT_ACTIVITY_ENDPOINT = '/activity/events';
+const DEFAULT_PAGEVIEW_NAME = '$view';
+const DISTINCT_ID_STORAGE_KEY = 'buyer_intent_distinct_id';
+
+const firedTagElements = new WeakSet();
+
+function generateId() {
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+
+  return `bi-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+
+function readStoredDistinctId() {
+  if (typeof window === 'undefined') {
+    return null;
+  }
+
+  try {
+    return window.localStorage.getItem(DISTINCT_ID_STORAGE_KEY);
+  } catch (_error) {
+    return null;
+  }
+}
+
+function storeDistinctId(value) {
+  if (typeof window === 'undefined') {
+    return;
+  }
+
+  try {
+    window.localStorage.setItem(DISTINCT_ID_STORAGE_KEY, value);
+  } catch (_error) {
+    return;
+  }
+}
+
+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;
+}
+
+function parseJson(value) {
+  if (!value) {
+    return undefined;
+  }
+
+  try {
+    return JSON.parse(value);
+  } catch (_error) {
+    return undefined;
+  }
+}
+
+function parseArray(value) {
+  if (!value) {
+    return undefined;
+  }
+
+  const parsed = parseJson(value);
+  if (Array.isArray(parsed)) {
+    return parsed;
+  }
+
+  if (typeof value === 'string') {
+    return value
+      .split(',')
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+  }
+
+  return undefined;
+}
+
+export function createBuyerIntentSDK() {
+  const core = createBuyerIntentCore();
+  let activityEndpoint = DEFAULT_ACTIVITY_ENDPOINT;
+  let origin = null;
+  let pageviewName = DEFAULT_PAGEVIEW_NAME;
+  let distinctId = null;
+  let userType = 'standard';
+  let lastPageKey = null;
+  let initialLandingPage = null;
+  let initialReferrer = null;
+  let initialUtmParams = null;
+  let observerStarted = false;
+
+  function ensureDistinctId() {
+    if (distinctId) {
+      return distinctId;
+    }
+
+    const stored = readStoredDistinctId();
+    if (stored) {
+      distinctId = stored;
+      return stored;
+    }
+
+    const generated = generateId();
+    distinctId = generated;
+    storeDistinctId(generated);
+    return generated;
+  }
+
+  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 readDomTagElement(element) {
+    if (!element) {
+      return undefined;
+    }
+
+    if (element.tagName === 'SCRIPT') {
+      const parsed =
+        parseJson(element.textContent || '') ||
+        parseJson(element.getAttribute('data-buyer-intent'));
+      if (parsed && typeof parsed === 'object') {
+        return parsed;
+      }
+    }
+
+    const dataJson = parseJson(element.getAttribute('data-buyer-intent'));
+    if (dataJson && typeof dataJson === 'object') {
+      return dataJson;
+    }
+
+    const dataset = element.dataset || {};
+    return {
+      productIds: parseArray(dataset.productIds),
+      categoryIds: parseArray(dataset.categoryIds),
+      tag: dataset.tag,
+      sourceLocation: dataset.sourceLocation,
+      context: parseJson(dataset.context)
+    };
+  }
+
+  function readDomTags(elements) {
+    if (typeof document === 'undefined') {
+      return [];
+    }
+
+    const found = elements || new Set();
+    const legacy = document.getElementById('buyer-intent-tags');
+    if (legacy) {
+      found.add(legacy);
+    }
+
+    document.querySelectorAll('[data-buyer-intent]').forEach((element) => {
+      found.add(element);
+    });
+
+    return Array.from(found)
+      .map((element) => ({ element, tag: readDomTagElement(element) }))
+      .filter((entry) => entry.tag && typeof entry.tag === 'object');
+  }
+
+  function applyElementConfig(element) {
+    if (!element || !element.dataset) {
+      return;
+    }
+
+    const {
+      origin: originValue,
+      userType: userTypeValue,
+      distinctId: distinctIdValue,
+      activityEndpoint: endpointValue
+    } = element.dataset;
+
+    if (endpointValue) {
+      setActivityEndpoint(endpointValue);
+    }
+
+    if (originValue || userTypeValue || distinctIdValue) {
+      setBaseProperties({
+        origin: originValue,
+        userType: userTypeValue,
+        distinctId: distinctIdValue
+      });
+    }
+  }
+
+  function applyDomTags(element) {
+    const elements = element ? new Set([element]) : undefined;
+    const entries = readDomTags(elements);
+    entries.forEach(({ element: tagElement, tag }) => {
+      applyElementConfig(tagElement);
+      core.tagPage(tag);
+    });
+    return entries.length > 0;
+  }
+
+  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;
+    }
+    const payload = core.buildPayload({
+      name: pageviewName,
+      url: window.location.href,
+      origin: origin || window.location.hostname,
+      distinctId: ensureDistinctId(),
+      userType,
+      visit: buildVisitContext()
+    });
+
+    const sent = sendWithBeacon(activityEndpoint, payload);
+    core.resetPageState();
+    return sent;
+  }
+
+  function init(options = {}) {
+    activityEndpoint = options.activityEndpoint || activityEndpoint;
+    origin = options.origin || origin;
+    pageviewName = options.pageviewName || pageviewName;
+    distinctId = options.distinctId || distinctId;
+    userType = options.userType || userType;
+
+    if (typeof window !== 'undefined' && !initialLandingPage) {
+      initialLandingPage = window.location.href;
+      initialReferrer = document.referrer || undefined;
+      initialUtmParams = readUtmParams(initialLandingPage);
+    }
+
+    core.setBaseProperties({
+      origin: origin || undefined,
+      distinctId: distinctId || undefined,
+      userType
+    });
+  }
+
+  function setActivityEndpoint(value) {
+    activityEndpoint = value || activityEndpoint;
+  }
+
+  function setBaseProperties(options = {}) {
+    if (options.origin) {
+      origin = options.origin;
+    }
+
+    if (options.distinctId) {
+      distinctId = options.distinctId;
+      storeDistinctId(options.distinctId);
+    }
+
+    if (options.userType) {
+      userType = options.userType;
+    }
+
+    core.setBaseProperties({
+      origin: origin || undefined,
+      distinctId: distinctId || 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 trackTaggedPageview(element) {
+    if (!element || typeof element !== 'object') {
+      return false;
+    }
+
+    if (firedTagElements.has(element)) {
+      return false;
+    }
+
+    firedTagElements.add(element);
+    return trackPageview(element);
+  }
+
+  function observeTagElements() {
+    if (
+      observerStarted ||
+      typeof document === 'undefined' ||
+      typeof MutationObserver === 'undefined'
+    ) {
+      return;
+    }
+
+    observerStarted = true;
+
+    const handleElement = (element) => {
+      if (
+        element &&
+        element.matches &&
+        element.matches('buyer-intent-tag,[data-buyer-intent]')
+      ) {
+        trackTaggedPageview(element);
+      }
+
+      if (element && element.querySelectorAll) {
+        element
+          .querySelectorAll('buyer-intent-tag,[data-buyer-intent]')
+          .forEach((nested) => trackTaggedPageview(nested));
+      }
+    };
+
+    const observer = new MutationObserver((mutations) => {
+      mutations.forEach((mutation) => {
+        mutation.addedNodes.forEach((node) => {
+          if (node.nodeType === 1) {
+            handleElement(node);
+          }
+        });
+      });
+    });
+
+    observer.observe(document.documentElement || document.body, {
+      childList: true,
+      subtree: true
+    });
+
+    document
+      .querySelectorAll('buyer-intent-tag,[data-buyer-intent]')
+      .forEach((element) => trackTaggedPageview(element));
+  }
+
+  observeTagElements();
+
+  return {
+    init,
+    trackPageview,
+    trackTaggedPageview,
+    tagPage,
+    setBaseProperties,
+    setVisitProperties,
+    setActivityEndpoint,
+    trackNextRouter
+  };
+}
+
+export const buyerIntent = createBuyerIntentSDK();

package/browser/tag_component.js

@@ -0,0 +1,34 @@
+import React from 'react';
+
+export function TagComponent({
+  productIds,
+  categoryIds,
+  tag,
+  sourceLocation,
+  context,
+  origin,
+  activityEndpoint,
+  userType,
+  distinctId,
+  children
+}) {
+  const payload = {
+    productIds,
+    categoryIds,
+    tag,
+    sourceLocation,
+    context
+  };
+
+  return React.createElement(
+    'buyer-intent-tag',
+    {
+      'data-buyer-intent': JSON.stringify(payload),
+      'data-origin': origin,
+      'data-activity-endpoint': activityEndpoint,
+      'data-user-type': userType,
+      'data-distinct-id': distinctId
+    },
+    children
+  );
+}

package/index.d.ts

@@ -0,0 +1,145 @@
+import type * as React from 'react';
+
+export type BuyerIntentInitOptions = {
+  activityEndpoint?: string;
+  origin?: string;
+  pageviewName?: string;
+  autoPageview?: boolean;
+  distinctId?: string;
+  userType?: string;
+};
+
+export type BuyerIntentTagOptions = {
+  productIds?: number[];
+  categoryIds?: number[];
+  tag?: string;
+  sourceLocation?: string;
+  context?: Record<string, unknown>;
+};
+
+export type BuyerIntentBaseOptions = {
+  origin?: string;
+  distinctId?: string;
+  userType?: string;
+};
+
+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: () => boolean;
+  trackTaggedPageview: (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 const buyerIntent: BuyerIntentSDK;
+
+export type TagComponentProps = {
+  productIds?: number[];
+  categoryIds?: number[];
+  tag?: string;
+  sourceLocation?: string;
+  context?: Record<string, unknown>;
+  origin?: string;
+  activityEndpoint?: string;
+  userType?: string;
+  distinctId?: string;
+};
+
+export const TagComponent: React.FC<TagComponentProps>;
+
+export const BuyerIntent: {
+  TagComponent: React.FC<TagComponentProps>;
+};
+
+export type ActivityHandlerOptions = {
+  topic?: string;
+  partnerId?: string;
+  topicPrefix?: string;
+  kafkaBrokers?: string[];
+  kafkaClientId?: string;
+  producer?: {
+    send: (payload: {
+      topic: string;
+      messages: Array<{ value: string }>;
+    }) => Promise<unknown>;
+  };
+  nowFn?: () => string;
+  uuidFn?: () => string;
+  getIp?: (args: {
+    headers?: Record<string, string> | Headers;
+    request?: { ip?: string };
+  }) => string | undefined;
+};
+
+export type ActivityHandlerResponse = {
+  status: number;
+  body: { ok: boolean; error?: string };
+  setCookies: Array<{
+    name: string;
+    value: string;
+    options: { httpOnly: boolean; sameSite: string };
+  }>;
+};
+
+export function createActivityHandler(
+  options?: ActivityHandlerOptions
+): (args: {
+  body: {
+    name: string;
+    properties?: Record<string, unknown>;
+    visit?: { properties?: Record<string, unknown> };
+  };
+  headers?: Record<string, string> | Headers;
+  cookies?:
+    | Record<string, string>
+    | { get: (name: string) => { value?: string } | string | undefined };
+  request?: { ip?: string };
+}) => Promise<ActivityHandlerResponse>;
+
+export function createNextRouteHandler(
+  options?: ActivityHandlerOptions
+): (req: {
+  json: () => Promise<{
+    name: string;
+    properties?: Record<string, unknown>;
+    visit?: { properties?: Record<string, unknown> };
+  }>;
+  headers: Headers;
+  cookies: { get: (name: string) => { value?: string } | string | undefined };
+}) => Promise<unknown>;
+
+export function createDevLoggerProducer(options?: {
+  log?: (message: string, payload: { topic: string; value: string }) => void;
+}): {
+  send: (payload: {
+    topic: string;
+    messages: Array<{ value: string }>;
+  }) => Promise<unknown>;
+};
+
+export function topicName(options?: {
+  partnerId?: string;
+  prefix?: string;
+}): string | undefined;

package/index.js

@@ -0,0 +1,6 @@
+export {
+  buyerIntent,
+  createBuyerIntentSDK,
+  BuyerIntent,
+  TagComponent
+} from './browser/index.js';

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@g2crowd/buyer-intent-provider-sdk",
+  "version": "0.1.0",
+  "description": "Buyer intent tracking SDK with pageview defaults",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./server": "./server/index.js"
+  },
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "browser",
+    "server.js",
+    "server",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --experimental-vm-modules ./node_modules/.bin/jest --config ./jest.config.cjs"
+  },
+  "bin": {
+    "buyer-intent-server": "server.js"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/g2crowd/buyer-intent-provider-js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "kafkajs": "^2.2.4",
+    "react": ">=17"
+  },
+  "sideEffects": false,
+  "devDependencies": {
+    "@testing-library/dom": "^9.3.4",
+    "@testing-library/react": "^14.3.1",
+    "jest": "^30.2.0",
+    "jest-environment-jsdom": "^30.2.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  }
+}

package/server/handlers.js

@@ -0,0 +1,274 @@
+function compactObject(value) {
+  return Object.fromEntries(
+    Object.entries(value).filter(([_key, entry]) => entry !== undefined)
+  );
+}
+
+function generateId() {
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+
+  return `bi-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+
+function parseUtmParams(urlValue, originFallback) {
+  if (!urlValue) {
+    return {};
+  }
+
+  const url = new URL(urlValue, originFallback || 'https://example.com');
+  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 readHeader(headers, name) {
+  if (!headers) {
+    return undefined;
+  }
+
+  if (typeof headers.get === 'function') {
+    return headers.get(name);
+  }
+
+  const key = name.toLowerCase();
+  return headers[key];
+}
+
+function readCookie(cookies, name) {
+  if (!cookies) {
+    return undefined;
+  }
+
+  if (typeof cookies.get === 'function') {
+    const value = cookies.get(name);
+    if (value && typeof value === 'object') {
+      return value.value;
+    }
+    return value;
+  }
+
+  return cookies[name];
+}
+
+function defaultGetIp({ headers, request }) {
+  const forwarded = readHeader(headers, 'x-forwarded-for');
+  if (forwarded) {
+    return forwarded.split(',')[0].trim();
+  }
+
+  if (request && request.ip) {
+    return request.ip;
+  }
+
+  return undefined;
+}
+
+function ensureProducer({ producer, kafkaBrokers, kafkaClientId }) {
+  if (producer) {
+    return producer;
+  }
+
+  if (!kafkaBrokers || !kafkaBrokers.length) {
+    throw new Error('kafkaBrokers is required when no producer is provided');
+  }
+
+  return {
+    async connect() {
+      if (this._producer) {
+        return;
+      }
+      const module = await import('kafkajs');
+      const kafka = new module.Kafka({
+        clientId: kafkaClientId || 'buyer-intent-sdk',
+        brokers: kafkaBrokers
+      });
+      this._producer = kafka.producer();
+      await this._producer.connect();
+    },
+    async send(payload) {
+      await this.connect();
+      return this._producer.send(payload);
+    },
+    async disconnect() {
+      if (this._producer) {
+        await this._producer.disconnect();
+      }
+    }
+  };
+}
+
+function buildCompositeEvent({
+  body,
+  now,
+  eventId,
+  visitTokens,
+  visitProperties
+}) {
+  return {
+    event: {
+      id: eventId,
+      name: body.name,
+      time: now,
+      properties: body.properties || {}
+    },
+    visit: {
+      visit_token: visitTokens.visitToken,
+      visitor_token: visitTokens.visitorToken,
+      started_at: now,
+      created_at: now,
+      properties: visitProperties
+    }
+  };
+}
+
+export function topicName({ partnerId, prefix } = {}) {
+  if (!partnerId) {
+    return undefined;
+  }
+
+  const safePartnerId = String(partnerId)
+    .toLowerCase()
+    .replace(/[^a-z0-9-_]/g, '-');
+  const safePrefix = prefix
+    ? String(prefix).replace(/[^a-z0-9-_]/gi, '')
+    : 'intent_events_';
+  return `${safePrefix}${safePartnerId}`;
+}
+
+export function createActivityHandler(options = {}) {
+  const topic =
+    options.topic ||
+    topicName({
+      partnerId: options.partnerId,
+      prefix: options.topicPrefix
+    }) ||
+    'enduser_events';
+  const nowFn = options.nowFn || (() => new Date().toISOString());
+  const uuidFn = options.uuidFn || generateId;
+  const getIp = options.getIp || defaultGetIp;
+  const producer = ensureProducer({
+    producer: options.producer,
+    kafkaBrokers: options.kafkaBrokers,
+    kafkaClientId: options.kafkaClientId
+  });
+
+  return async function handle({ body, headers, cookies, request }) {
+    if (!body || !body.name) {
+      return {
+        status: 400,
+        body: { ok: false, error: 'invalid_event' },
+        setCookies: []
+      };
+    }
+
+    const visitToken = readCookie(cookies, 'visit_token') || uuidFn();
+    const visitorToken = readCookie(cookies, 'visitor_token') || uuidFn();
+    const now = nowFn();
+
+    const incomingVisitProps = (body.visit && body.visit.properties) || {};
+    const landingPage =
+      incomingVisitProps.landing_page ||
+      (body.properties && body.properties.url) ||
+      readHeader(headers, 'referer');
+    const referrer =
+      incomingVisitProps.referrer ||
+      readHeader(headers, 'referer') ||
+      undefined;
+    const userAgent =
+      incomingVisitProps.user_agent ||
+      readHeader(headers, 'user-agent') ||
+      undefined;
+    const utmParams =
+      parseUtmParams(landingPage, body.properties && body.properties.url) || {};
+
+    const visitProperties = compactObject({
+      landing_page: landingPage,
+      referrer,
+      user_agent: userAgent,
+      ip: incomingVisitProps.ip || getIp({ headers, request }),
+      utm_source: incomingVisitProps.utm_source || utmParams.utm_source,
+      utm_medium: incomingVisitProps.utm_medium || utmParams.utm_medium,
+      utm_campaign: incomingVisitProps.utm_campaign || utmParams.utm_campaign,
+      utm_term: incomingVisitProps.utm_term || utmParams.utm_term,
+      utm_content: incomingVisitProps.utm_content || utmParams.utm_content,
+      ...incomingVisitProps
+    });
+
+    const compositeEvent = buildCompositeEvent({
+      body,
+      now,
+      eventId: uuidFn(),
+      visitTokens: { visitToken, visitorToken },
+      visitProperties
+    });
+
+    await producer.send({
+      topic,
+      messages: [{ value: JSON.stringify(compositeEvent) }]
+    });
+
+    return {
+      status: 200,
+      body: { ok: true },
+      setCookies: [
+        {
+          name: 'visit_token',
+          value: visitToken,
+          options: { httpOnly: true, sameSite: 'lax' }
+        },
+        {
+          name: 'visitor_token',
+          value: visitorToken,
+          options: { httpOnly: true, sameSite: 'lax' }
+        }
+      ]
+    };
+  };
+}
+
+export function createNextRouteHandler(options = {}) {
+  const handler = createActivityHandler(options);
+
+  return async function POST(req) {
+    const body = await req.json();
+    const result = await handler({
+      body,
+      headers: req.headers,
+      cookies: req.cookies,
+      request: req
+    });
+
+    const { NextResponse } = await import('next/server');
+    const response = NextResponse.json(result.body, { status: result.status });
+
+    result.setCookies.forEach((cookie) => {
+      response.cookies.set(cookie.name, cookie.value, cookie.options);
+    });
+
+    return response;
+  };
+}
+
+export function createDevLoggerProducer(options = {}) {
+  const log = options.log || console.log;
+
+  return {
+    async send(payload) {
+      const message =
+        payload.messages && payload.messages[0] && payload.messages[0].value;
+      log('[buyer-intent-sdk] kafka message', {
+        topic: payload.topic,
+        value: message
+      });
+      return Promise.resolve();
+    }
+  };
+}

package/server/index.js

@@ -0,0 +1,6 @@
+export {
+  createActivityHandler,
+  createNextRouteHandler,
+  createDevLoggerProducer,
+  topicName
+} from './handlers.js';

package/server.js

@@ -0,0 +1,113 @@
+import http from 'http';
+import { fileURLToPath } from 'url';
+import {
+  createActivityHandler,
+  createDevLoggerProducer
+} from './server/handlers.js';
+
+function parseCookies(headerValue) {
+  if (!headerValue) {
+    return {};
+  }
+
+  return headerValue.split(';').reduce((acc, pair) => {
+    const [rawKey, ...rawValue] = pair.trim().split('=');
+    if (!rawKey) {
+      return acc;
+    }
+    acc[rawKey] = decodeURIComponent(rawValue.join('=') || '');
+    return acc;
+  }, {});
+}
+
+function readRequestBody(req) {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    req.on('data', (chunk) => {
+      data += chunk;
+    });
+    req.on('end', () => resolve(data));
+    req.on('error', reject);
+  });
+}
+
+function buildHandlerOptions() {
+  const brokers = process.env.KAFKA_BROKERS
+    ? process.env.KAFKA_BROKERS.split(',')
+        .map((value) => value.trim())
+        .filter(Boolean)
+    : undefined;
+  const useDevLogger = process.env.USE_DEV_LOGGER === 'true';
+
+  return {
+    kafkaBrokers: brokers,
+    kafkaClientId: process.env.KAFKA_CLIENT_ID,
+    partnerId: process.env.PARTNER_ID,
+    topicPrefix: process.env.TOPIC_PREFIX,
+    topic: process.env.KAFKA_TOPIC,
+    producer: useDevLogger ? createDevLoggerProducer() : undefined
+  };
+}
+
+async function handleRequest(req, res, handler) {
+  if (req.method !== 'POST' || req.url !== '/activity/events') {
+    res.statusCode = 404;
+    res.end();
+    return;
+  }
+
+  let body;
+  try {
+    const rawBody = await readRequestBody(req);
+    body = rawBody ? JSON.parse(rawBody) : {};
+  } catch (_error) {
+    res.statusCode = 400;
+    res.setHeader('Content-Type', 'application/json');
+    res.end(JSON.stringify({ ok: false, error: 'invalid_json' }));
+    return;
+  }
+
+  try {
+    const result = await handler({
+      body,
+      headers: req.headers,
+      cookies: parseCookies(req.headers.cookie),
+      request: req
+    });
+
+    const cookieHeaders = result.setCookies.map((cookie) => {
+      const base = `${cookie.name}=${encodeURIComponent(
+        cookie.value
+      )}; Path=/; SameSite=Lax`;
+      return cookie.options.httpOnly ? `${base}; HttpOnly` : base;
+    });
+
+    res.statusCode = result.status;
+    res.setHeader('Content-Type', 'application/json');
+    if (cookieHeaders.length) {
+      res.setHeader('Set-Cookie', cookieHeaders);
+    }
+    res.end(JSON.stringify(result.body));
+  } catch (_error) {
+    res.statusCode = 500;
+    res.setHeader('Content-Type', 'application/json');
+    res.end(JSON.stringify({ ok: false, error: 'server_error' }));
+  }
+}
+
+function startServer() {
+  const handler = createActivityHandler(buildHandlerOptions());
+  const port = Number(process.env.PORT || 3000);
+
+  const server = http.createServer((req, res) => {
+    handleRequest(req, res, handler);
+  });
+
+  server.listen(port);
+}
+
+const isMain = process.argv[1] === fileURLToPath(import.meta.url);
+
+if (isMain) {
+  startServer();
+}