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

package/README.md

@@ -270,21 +270,64 @@ PARTNER_ID=partner-a KAFKA_BROKERS=broker1:9092,broker2:9092 \
 buyer-intent-server
 ```
 
-Environment variables: `PORT` (default 3000), `PARTNER_ID`, `KAFKA_BROKERS` (comma-separated), `TOPIC_PREFIX`, `KAFKA_TOPIC`, `KAFKA_CLIENT_ID`, `USE_DEV_LOGGER=true`.
+Environment variables: `PORT` (default 3000), `PARTNER_ID`, `KAFKA_BROKERS` (comma-separated), `KAFKA_BRIDGE_URL` (Strimzi HTTP bridge), `KAFKA_BRIDGE_USERNAME`, `KAFKA_BRIDGE_PASSWORD`, `TOPIC_PREFIX`, `KAFKA_TOPIC`, `KAFKA_CLIENT_ID`, `USE_DEV_LOGGER=true`.
 
 ### Custom Kafka Producer
 
 ```ts
-import { Kafka } from 'kafkajs';
+import {
+  createNextRouteHandler,
+  createKafkaProducer,
+} from '@g2crowd/buyer-intent-provider-sdk/server';
+
+const POST = createNextRouteHandler({
+  producer: createKafkaProducer({
+    brokers: (process.env.KAFKA_BROKERS || '').split(','),
+    clientId: 'partner-app',
+  }),
+  partnerId: process.env.PARTNER_ID,
+});
+
+export { POST };
+```
+
+You can also pass a raw `kafkajs` producer or any object with a `send({ topic, messages })` method.
+
+### HTTP Bridge (Strimzi)
+
+Use `KAFKA_BRIDGE_URL` to produce via an HTTP bridge instead of connecting to Kafka directly. No `kafkajs` dependency required.
+
+```bash
+PARTNER_ID=partner-a KAFKA_BRIDGE_URL=http://my-bridge:8080 \
+buyer-intent-server
+```
+
+Or pass it programmatically:
+
+```ts
 import { createNextRouteHandler } from '@g2crowd/buyer-intent-provider-sdk/server';
 
-const kafka = new Kafka({
-  clientId: 'partner-app',
-  brokers: (process.env.KAFKA_BROKERS || '').split(','),
+const POST = createNextRouteHandler({
+  kafkaBridgeUrl: process.env.KAFKA_BRIDGE_URL,
+  partnerId: process.env.PARTNER_ID,
 });
 
+export { POST };
+```
+
+For custom headers (e.g. auth tokens):
+
+```ts
+import {
+  createNextRouteHandler,
+  createHttpProducer,
+} from '@g2crowd/buyer-intent-provider-sdk/server';
+
 const POST = createNextRouteHandler({
-  producer: kafka.producer({ allowAutoTopicCreation: false }),
+  producer: createHttpProducer({
+    bridgeUrl: process.env.KAFKA_BRIDGE_URL,
+    headers: { Authorization: `Bearer ${process.env.BRIDGE_TOKEN}` },
+  }),
   partnerId: process.env.PARTNER_ID,
 });
 
@@ -309,6 +352,10 @@ export { POST };
 
 ## Event Payload
 
+The client sends a beacon to the activity endpoint. The server handler wraps it into a composite event and writes it to Kafka.
+
+### Client → Server (sendBeacon body)
+
 ```json
 {
   "name": "$view",
@@ -320,15 +367,64 @@ export { POST };
     "user_type": "standard",
     "distinct_id": "visitor-uuid",
     "origin": "yoursite.com",
-    "source_location": "ProductsController#show"
+    "source_location": "ProductsController#show",
+    "context": {}
   },
   "visit": {
     "properties": {
       "landing_page": "https://yoursite.com/products/acme-crm",
       "referrer": "https://google.com/",
-      "user_agent": "Mozilla/5.0",
-      "utm_source": "newsletter"
+      "user_agent": "Mozilla/5.0 ...",
+      "utm_source": "newsletter",
+      "utm_medium": "email",
+      "utm_campaign": "spring-2026",
+      "utm_term": "crm+software",
+      "utm_content": "hero-cta"
     }
   }
 }
 ```
+
+### Server → Kafka (composite event)
+
+The server enriches the client payload with server-side tokens, timestamps, and IP before writing to Kafka. This is the shape written to the `intent_events_{partnerId}` topic:
+
+```json
+{
+  "event": {
+    "id": "e0c1f2a3-...",
+    "name": "$view",
+    "time": "2026-02-17T14:20:00.000Z",
+    "properties": {
+      "product_ids": [123],
+      "category_ids": [45],
+      "tag": "products.show",
+      "url": "https://yoursite.com/products/acme-crm",
+      "user_type": "standard",
+      "distinct_id": "visitor-uuid",
+      "origin": "yoursite.com",
+      "source_location": "ProductsController#show",
+      "context": {}
+    }
+  },
+  "visit": {
+    "visit_token": "a1b2c3d4-...",
+    "visitor_token": "f5e6d7c8-...",
+    "started_at": "2026-02-17T14:20:00.000Z",
+    "created_at": "2026-02-17T14:20:00.000Z",
+    "properties": {
+      "landing_page": "https://yoursite.com/products/acme-crm",
+      "referrer": "https://google.com/",
+      "user_agent": "Mozilla/5.0 ...",
+      "ip": "203.0.113.42",
+      "utm_source": "newsletter",
+      "utm_medium": "email",
+      "utm_campaign": "spring-2026",
+      "utm_term": "crm+software",
+      "utm_content": "hero-cta"
+    }
+  }
+}
+```
+
+The server sets `visit_token` and `visitor_token` as `httpOnly` cookies so repeat visits from the same browser share stable tokens.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@g2crowd/buyer-intent-provider-sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Buyer intent tracking SDK with pageview defaults",
   "type": "module",
   "main": "src/index.js",
@@ -26,17 +26,18 @@
     "url": "https://github.com/g2crowd/buyer-intent-provider-js"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "restricted",
+    "registry": "https://npm.pkg.github.com"
   },
   "peerDependencies": {
     "kafkajs": "^2.2.4",
     "react": ">=17"
   },
   "peerDependenciesMeta": {
-    "react": {
+    "kafkajs": {
       "optional": true
     },
-    "kafkajs": {
+    "react": {
       "optional": true
     }
   },

package/src/browser/components/tracker.js

@@ -4,6 +4,7 @@ function buildViewAttrs({
   productId,
   productIds,
   categoryId,
+  categoryIds,
   tag,
   sourceLocation,
   context,
@@ -26,6 +27,7 @@ function buildViewAttrs({
   if (productId != null) attrs['product-id'] = String(productId);
   if (productIds) attrs['product-ids'] = JSON.stringify(productIds);
   if (categoryId != null) attrs['category-id'] = String(categoryId);
+  if (categoryIds) attrs['category-ids'] = JSON.stringify(categoryIds);
 
   return attrs;
 }
@@ -35,6 +37,7 @@ function buildClickAttrs({
   productId,
   productIds,
   categoryId,
+  categoryIds,
   sourceLocation,
   context,
   origin,
@@ -55,6 +58,7 @@ function buildClickAttrs({
   if (productId != null) attrs['product-id'] = String(productId);
   if (productIds) attrs['product-ids'] = JSON.stringify(productIds);
   if (categoryId != null) attrs['category-id'] = String(categoryId);
+  if (categoryIds) attrs['category-ids'] = JSON.stringify(categoryIds);
 
   return attrs;
 }

package/src/browser/dom.js

@@ -101,9 +101,9 @@ function parseIds(raw) {
   if (!raw) return [];
   try {
     const parsed = JSON.parse(raw);
-    if (Array.isArray(parsed)) return parsed.map(Number);
+    if (Array.isArray(parsed)) return parsed;
   } catch (_e) {}
-  return raw.split(',').map((s) => Number(s.trim())).filter((n) => !Number.isNaN(n));
+  return raw.split(',').map((s) => s.trim()).filter(Boolean);
 }
 
 export function readSessionConfig(element) {
@@ -139,7 +139,7 @@ export function collectSubjectIds(viewElement) {
     if (pids) {
       productIds.push(...parseIds(pids));
     } else if (pid) {
-      productIds.push(Number(pid));
+      productIds.push(pid);
     }
 
     const cids = subject.getAttribute('category-ids');
@@ -147,7 +147,7 @@ export function collectSubjectIds(viewElement) {
     if (cids) {
       categoryIds.push(...parseIds(cids));
     } else if (cid) {
-      categoryIds.push(Number(cid));
+      categoryIds.push(cid);
     }
   }
 

package/src/browser/elements/base.js

@@ -9,7 +9,7 @@ function parseIds(raw) {
     const parsed = JSON.parse(raw);
     if (Array.isArray(parsed)) return parsed;
   } catch (_e) {}
-  return raw.split(',').map((s) => Number(s.trim()));
+  return raw.split(',').map((s) => s.trim()).filter(Boolean);
 }
 
 function readIntentData(element) {
@@ -21,11 +21,11 @@ function readIntentData(element) {
   if (productIds) {
     data.productIds = parseIds(productIds);
   } else if (productId) {
-    data.productIds = [Number(productId)];
+    data.productIds = [productId];
   }
 
   if (categoryId) {
-    data.categoryIds = [Number(categoryId)];
+    data.categoryIds = [categoryId];
   }
 
   const tag = element.getAttribute('tag');

package/src/browser/index.js

@@ -5,4 +5,4 @@ export {
   BuyerIntentClickElement,
 } from './elements/index.js';
 
-export { createBuyerIntentSDK, buyerIntent } from './sdk.js';
+export { createBuyerIntentSDK, ensureSDK, buyerIntent } from './sdk.js';

package/src/browser/sdk.js

@@ -150,7 +150,7 @@ export function createBuyerIntentSDK() {
   function init(options = {}) {
     activityEndpoint = options.activityEndpoint || activityEndpoint;
     origin = options.origin || origin;
-    viewName = options.viewName || options.pageviewName || viewName;
+    viewName = options.viewName || viewName;
     userType = options.userType || userType;
 
     if (options.distinctId) {

package/src/index.d.ts

@@ -78,9 +78,10 @@ export type BuyerIntentInitOptions = {
   userType?: UserType;
 };
 
+export type SubjectId = number | string;
 export type BuyerIntentTagOptions = {
-  productIds?: number[];
-  categoryIds?: number[];
+  productIds?: SubjectId[];
+  categoryIds?: SubjectId[];
   tag?: string;
   sourceLocation?: string;
   context?: Record<string, unknown>;
@@ -113,6 +114,7 @@ export type BuyerIntentSDK = {
   setBaseProperties: (options?: BuyerIntentBaseOptions) => void;
   setVisitProperties: (options?: BuyerIntentVisitProperties) => void;
   setActivityEndpoint: (endpoint: string) => void;
+  listenForElements: () => void;
   trackNextRouter: (nextRouter: {
     events?: {
       on: (event: string, handler: () => void) => void;

package/src/index.js

@@ -1,6 +1,7 @@
 export {
   buyerIntent,
   createBuyerIntentSDK,
+  ensureSDK,
   BuyerIntentSessionElement,
   BuyerIntentSubjectElement,
   BuyerIntentViewElement,

package/src/react/index.d.ts

@@ -1,5 +1,5 @@
 import type * as React from 'react';
-import type { UserType } from '../index';
+import type { UserType, SubjectId } from '../index';
 
 type CommonProps = {
   sourceLocation?: string;
@@ -20,30 +20,32 @@ export type SessionProviderProps = {
 };
 
 export type SubjectTrackerProps = {
-  productId?: number;
-  categoryId?: number;
-  productIds?: number[];
-  categoryIds?: number[];
+  productId?: SubjectId;
+  categoryId?: SubjectId;
+  productIds?: SubjectId[];
+  categoryIds?: SubjectId[];
 };
 
 export type ViewTrackerProps = CommonProps & {
   tag?: string;
-  productId?: number;
-  productIds?: number[];
-  categoryId?: number;
+  productId?: SubjectId;
+  productIds?: SubjectId[];
+  categoryId?: SubjectId;
+  categoryIds?: SubjectId[];
 };
 
 export type ClickTrackerProps = CommonProps & {
   eventName?: string;
-  productId?: number;
-  productIds?: number[];
-  categoryId?: number;
+  productId?: SubjectId;
+  productIds?: SubjectId[];
+  categoryId?: SubjectId;
+  categoryIds?: SubjectId[];
 };
 
-type ProductIdViewProps = CommonProps & { productId: number };
-type CategoryViewProps = CommonProps & { categoryId: number };
-type ProductIdsViewProps = CommonProps & { productIds: number[] };
-type ProductIdClickProps = CommonProps & { productId: number };
+type ProductIdViewProps = CommonProps & { productId: SubjectId };
+type CategoryViewProps = CommonProps & { categoryId: SubjectId };
+type ProductIdsViewProps = CommonProps & { productIds: SubjectId[] };
+type ProductIdClickProps = CommonProps & { productId: SubjectId };
 
 export const SessionProvider: React.FC<SessionProviderProps>;
 export const SubjectTracker: React.FC<SubjectTrackerProps>;

package/src/server/handlers.js

@@ -71,38 +71,38 @@ function defaultGetIp({ headers, request }) {
   return undefined;
 }
 
-function ensureProducer({ producer, kafkaBrokers, kafkaClientId }) {
+function resolveProducer({
+  producer,
+  kafkaBrokers,
+  kafkaClientId,
+  kafkaBridgeUrl,
+  kafkaBridgeUsername,
+  kafkaBridgePassword,
+  kafkaBridgeHeaders
+}) {
   if (producer) {
     return producer;
   }
 
-  if (!kafkaBrokers || !kafkaBrokers.length) {
-    throw new Error('kafkaBrokers is required when no producer is provided');
+  if (kafkaBridgeUrl) {
+    return createHttpProducer({
+      bridgeUrl: kafkaBridgeUrl,
+      bridgeUsername: kafkaBridgeUsername,
+      bridgePassword: kafkaBridgePassword,
+      headers: kafkaBridgeHeaders
+    });
   }
 
-  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();
-      }
-    }
-  };
+  if (kafkaBrokers && kafkaBrokers.length) {
+    return createKafkaProducer({
+      brokers: kafkaBrokers,
+      clientId: kafkaClientId
+    });
+  }
+
+  throw new Error(
+    'producer, kafkaBridgeUrl, or kafkaBrokers is required'
+  );
 }
 
 function buildCompositeEvent({
@@ -154,10 +154,14 @@ export function createActivityHandler(options = {}) {
   const nowFn = options.nowFn || (() => new Date().toISOString());
   const uuidFn = options.uuidFn || generateId;
   const getIp = options.getIp || defaultGetIp;
-  const producer = ensureProducer({
+  const producer = resolveProducer({
     producer: options.producer,
     kafkaBrokers: options.kafkaBrokers,
-    kafkaClientId: options.kafkaClientId
+    kafkaClientId: options.kafkaClientId,
+    kafkaBridgeUrl: options.kafkaBridgeUrl,
+    kafkaBridgeUsername: options.kafkaBridgeUsername,
+    kafkaBridgePassword: options.kafkaBridgePassword,
+    kafkaBridgeHeaders: options.kafkaBridgeHeaders
   });
 
   return async function handle({ body, headers, cookies, request }) {
@@ -257,6 +261,76 @@ export function createNextRouteHandler(options = {}) {
   };
 }
 
+export function createKafkaProducer(options = {}) {
+  const brokers = options.brokers;
+  if (!brokers || !brokers.length) {
+    throw new Error('brokers is required for createKafkaProducer');
+  }
+
+  const clientId = options.clientId || 'buyer-intent-sdk';
+  let _producer;
+
+  return {
+    async connect() {
+      if (_producer) {
+        return;
+      }
+      const module = await import('kafkajs');
+      const kafka = new module.Kafka({ clientId, brokers });
+      _producer = kafka.producer();
+      await _producer.connect();
+    },
+    async send(payload) {
+      await this.connect();
+      return _producer.send(payload);
+    },
+    async disconnect() {
+      if (_producer) {
+        await _producer.disconnect();
+      }
+    }
+  };
+}
+
+export function createHttpProducer(options = {}) {
+  const bridgeUrl = options.bridgeUrl;
+  if (!bridgeUrl) {
+    throw new Error('bridgeUrl is required for createHttpProducer');
+  }
+
+  const headers = {
+    'Content-Type': 'application/vnd.kafka.json.v2+json',
+    ...(options.bridgeUsername && {
+      'Authorization': `Basic ${Buffer.from(`${options.bridgeUsername}:${options.bridgePassword || ''}`).toString('base64')}`
+    }),
+    ...options.headers
+  };
+
+  return {
+    async send(payload) {
+      const url = `${bridgeUrl.replace(/\/+$/, '')}/topics/${encodeURIComponent(payload.topic)}`;
+      const records = payload.messages.map((msg) => ({
+        value: typeof msg.value === 'string' ? JSON.parse(msg.value) : msg.value
+      }));
+
+      const response = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ records })
+      });
+
+      if (!response.ok) {
+        const body = await response.text();
+        throw new Error(
+          `Kafka bridge error ${response.status}: ${body}`
+        );
+      }
+
+      return response.json();
+    }
+  };
+}
+
 export function createDevLoggerProducer(options = {}) {
   const log = options.log || console.log;
 

package/src/server/index.js

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

package/src/server.js

@@ -42,6 +42,9 @@ function buildHandlerOptions() {
   return {
     kafkaBrokers: brokers,
     kafkaClientId: process.env.KAFKA_CLIENT_ID,
+    kafkaBridgeUrl: process.env.KAFKA_BRIDGE_URL,
+    kafkaBridgeUsername: process.env.KAFKA_BRIDGE_USERNAME,
+    kafkaBridgePassword: process.env.KAFKA_BRIDGE_PASSWORD,
     partnerId: process.env.PARTNER_ID,
     topicPrefix: process.env.TOPIC_PREFIX,
     topic: process.env.KAFKA_TOPIC,