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

package/README.md

@@ -1,6 +1,6 @@
 # Buyer Intent JS SDK
 
-Buyer Intent tracking SDK for partner sites. Provides purpose-built React components for each tracked interaction type, plus low-level `ViewTracker` and `ClickTracker` primitives. Events are sent via `sendBeacon` for best-effort delivery during navigation.
+Buyer intent tracking SDK for partner sites. Works in any frontend — drop in custom HTML elements, or use the React convenience layer. Events are sent via `sendBeacon` for best-effort delivery during navigation. React is never loaded unless you import from the `/react` subpath.
 
 ## Install
 
@@ -8,18 +8,52 @@ Buyer Intent tracking SDK for partner sites. Provides purpose-built React compon
 npm install @g2crowd/buyer-intent-provider-sdk
 ```
 
-If you plan to use the built-in Kafka connection (via `kafkaBrokers`), install the peer dependency:
+## Entry Points
 
-```bash
-npm install kafkajs
+| Import Path                                 | Contains             | React Required |
+| ------------------------------------------- | -------------------- | -------------- |
+| `@g2crowd/buyer-intent-provider-sdk`        | SDK, custom elements | No             |
+| `@g2crowd/buyer-intent-provider-sdk/react`  | React components     | Yes            |
+| `@g2crowd/buyer-intent-provider-sdk/server` | Server handlers      | No             |
+
+## Quick Start
+
+### HTML Custom Elements (any framework)
+
+The SDK registers two custom elements — `<buyer-intent-view>` and `<buyer-intent-click>` — that work in any HTML page. No React, no build step required.
+
+```html
+<script type="module">
+  import '@g2crowd/buyer-intent-provider-sdk';
+</script>
+
+<buyer-intent-view
+  tag="products.show"
+  product-id="123"
+  data-origin="g2.com"
+  data-activity-endpoint="/api/activity/events"
+>
+  <h1>Acme CRM</h1>
+  <p>Product details here.</p>
+
+  <buyer-intent-click
+    event-name="/leads/create"
+    product-id="123"
+    data-origin="g2.com"
+    data-activity-endpoint="/api/activity/events"
+  >
+    <button>Get a Demo</button>
+  </buyer-intent-click>
+</buyer-intent-view>
 ```
 
-## Quick Start (Next.js)
+### React Components
+
+For React apps, import from `/react` to get named components with typed props. Each component hardcodes its `tag` or `event-name`, so typos are caught at compile time.
 
 ```tsx
-import { BuyerIntent } from '@g2crowd/buyer-intent-provider-sdk';
+import { BuyerIntent } from '@g2crowd/buyer-intent-provider-sdk/react';
 
-// Product profile page — fires a $view with tag "products.show"
 export default function ProductPage() {
   return (
     <BuyerIntent.ProfileView
@@ -38,165 +72,146 @@ export default function ProductPage() {
 }
 ```
 
-## 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 };
-```
+### Mixing Both
 
-## Barebones Server
+Custom elements and React components use the same underlying event system. You can mix them freely on the same page:
 
-This package ships a tiny server that hosts `POST /activity/events`.
+```tsx
+import { BuyerIntent } from '@g2crowd/buyer-intent-provider-sdk/react';
 
-```bash
-PARTNER_ID=partner-a KAFKA_BROKERS=broker1:9092,broker2:9092 \
-buyer-intent-server
+<BuyerIntent.PricingView
+  productId={123}
+  origin="g2.com"
+  activityEndpoint="/api/activity/events"
+>
+  <h1>Pricing</h1>
+
+  <buyer-intent-click
+    event-name="/leads/create"
+    product-id="123"
+    data-origin="g2.com"
+    data-activity-endpoint="/api/activity/events"
+  >
+    <button>Start Free Trial</button>
+  </buyer-intent-click>
+</BuyerIntent.PricingView>;
 ```
 
-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)
+## Custom Elements
 
-## Kafka Setup (Partner Checklist)
+Two elements cover all tracking scenarios. The `tag` or `event-name` attribute determines the interaction type.
 
-Provide these values to your partners so they can publish to their scoped topic:
+### `<buyer-intent-view>`
 
-- 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)
+Fires a `$view` event when the element connects to the DOM. One event per page navigation.
 
-By default, the SDK derives the topic from `partnerId` using `intent_events_<partnerId>`.
+| Attribute     | Required | Description                                          |
+| ------------- | -------- | ---------------------------------------------------- |
+| `tag`         | Yes      | View type (see supported tags below)                 |
+| `product-id`  | -        | Single product ID                                    |
+| `product-ids` | -        | Multiple product IDs (JSON array or comma-separated) |
+| `category-id` | -        | Category ID                                          |
 
-Example using a prebuilt producer:
+Supported `tag` values: `products.show`, `products.pricing`, `products.competitors`, `categories.show`, `comparisons.show`, `reviewers.take_survey`
 
-```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(','),
-});
+```html
+<buyer-intent-view
+  tag="categories.show"
+  category-id="45"
+  data-origin="g2.com"
+  data-activity-endpoint="/api/activity/events"
+>
+  <h1>CRM Software</h1>
+</buyer-intent-view>
+```
 
-const producer = kafka.producer({
-  allowAutoTopicCreation: false,
-});
+Multiple product IDs (for comparisons):
 
-const POST = createNextRouteHandler({
-  producer,
-  partnerId: process.env.PARTNER_ID,
-  topicPrefix: process.env.TOPIC_PREFIX,
-});
+```html
+<buyer-intent-view tag="comparisons.show" product-ids="[101, 201]">
+  ...
+</buyer-intent-view>
 
-export { POST };
+<buyer-intent-view tag="comparisons.show" product-ids="101,201">
+  ...
+</buyer-intent-view>
 ```
 
-## Dev Adapter (No Kafka)
+### `<buyer-intent-click>`
 
-If you want to test locally without Kafka, use the dev logger producer.
+Fires an event each time the user clicks anything inside the element.
 
-```ts
-// app/api/activity/events/route.ts
-import {
-  createNextRouteHandler,
-  createDevLoggerProducer,
-} from '@g2crowd/buyer-intent-provider-sdk/server';
+| Attribute    | Required | Description                         |
+| ------------ | -------- | ----------------------------------- |
+| `event-name` | Yes      | Click event type (see values below) |
+| `product-id` | -        | Product ID                          |
 
-const POST = createNextRouteHandler({
-  producer: createDevLoggerProducer(),
-  partnerId: 'dev',
-});
+Supported `event-name` values: `/ad/clicked`, `/leads/create`
 
-export { POST };
+```html
+<buyer-intent-click
+  event-name="/leads/create"
+  product-id="123"
+  data-origin="g2.com"
+  data-activity-endpoint="/api/activity/events"
+>
+  <button>Get a Demo</button>
+</buyer-intent-click>
 ```
 
-## Interaction Components
+### Common Attributes
 
-Purpose-built components for each tracked interaction type. Each sets the correct event name and tag automatically — you just provide the required ID.
+Both elements accept these optional `data-*` attributes:
 
-### Page Views
+| Attribute                | Description                                            |
+| ------------------------ | ------------------------------------------------------ |
+| `data-origin`            | Partner hostname                                       |
+| `data-activity-endpoint` | URL to POST events to                                  |
+| `data-user-type`         | User type string (default: `"standard"`)               |
+| `data-distinct-id`       | Override the auto-generated visitor ID                 |
+| `data-buyer-intent`      | JSON object with `sourceLocation` and `context` fields |
 
-These fire a `$view` event when the component appears in the DOM. One event per page navigation.
+### TypeScript Support
 
-| Component         | Required Prop     | Tag                     |
-| ----------------- | ----------------- | ----------------------- |
-| `ProfileView`     | `productId`       | `products.show`         |
-| `PricingView`     | `productId`       | `products.pricing`      |
-| `CompetitorsView` | `productId`       | `products.competitors`  |
-| `CategoryView`    | `categoryId`      | `categories.show`       |
-| `CompareView`     | `productIds` (2+) | `comparisons.show`      |
-| `WriteReviewView` | `productId`       | `reviewers.take_survey` |
+The package augments `JSX.IntrinsicElements` with typed attributes. The `tag` and `event-name` attributes are union types, so invalid values are caught at compile time:
 
 ```tsx
-import { BuyerIntent } from '@g2crowd/buyer-intent-provider-sdk';
-
-<BuyerIntent.ProfileView productId={123} origin="g2.com" activityEndpoint="/api/activity/events">
-  <ProductPage />
-</BuyerIntent.ProfileView>
+// ✅ Type-safe
+<buyer-intent-view tag="products.show" product-id="123">
 
-<BuyerIntent.CategoryView categoryId={45} origin="g2.com" activityEndpoint="/api/activity/events">
-  <CategoryPage />
-</BuyerIntent.CategoryView>
-
-<BuyerIntent.CompareView productIds={[123, 456]} origin="g2.com" activityEndpoint="/api/activity/events">
-  <ComparisonPage />
-</BuyerIntent.CompareView>
+// ❌ Type error: '"invalid.tag"' is not assignable to type 'ViewTag'
+<buyer-intent-view tag="invalid.tag" product-id="123">
 ```
 
-### Click Events
-
-These fire an event each time the user clicks anything inside the component.
+## React Components
 
-| Component         | Required Prop | Event Name      |
-| ----------------- | ------------- | --------------- |
-| `AdClick`         | `productId`   | `/ad/clicked`   |
-| `LeadCreateClick` | `productId`   | `/leads/create` |
-
-```tsx
-<BuyerIntent.LeadCreateClick productId={123}>
-  <button>Get a Demo</button>
-</BuyerIntent.LeadCreateClick>
+Named React components wrap the custom elements with hardcoded `tag`/`event-name` values. They accept camelCase props instead of HTML attributes.
 
-<BuyerIntent.AdClick productId={123}>
-  <button>Sponsored Link</button>
-</BuyerIntent.AdClick>
-```
+### View Components
 
-### Common Props
+| Component         | Tag                     | Required Prop |
+| ----------------- | ----------------------- | ------------- |
+| `ProfileView`     | `products.show`         | `productId`   |
+| `PricingView`     | `products.pricing`      | `productId`   |
+| `CompetitorsView` | `products.competitors`  | `productId`   |
+| `CategoryView`    | `categories.show`       | `categoryId`  |
+| `CompareView`     | `comparisons.show`      | `productIds`  |
+| `WriteReviewView` | `reviewers.take_survey` | `productId`   |
 
-All interaction components accept these optional props:
+### Click Components
 
-| Prop               | Description                              |
-| ------------------ | ---------------------------------------- |
-| `origin`           | Partner hostname                         |
-| `activityEndpoint` | URL to POST events to                    |
-| `userType`         | User type string (default: `"standard"`) |
-| `distinctId`       | Override the auto-generated visitor ID   |
-| `sourceLocation`   | Controller/action identifier             |
-| `context`          | Arbitrary metadata object                |
-| `eventName`        | Override the default event name          |
+| Component         | Event Name      | Required Prop |
+| ----------------- | --------------- | ------------- |
+| `AdClick`         | `/ad/clicked`   | `productId`   |
+| `LeadCreateClick` | `/leads/create` | `productId`   |
 
-### Low-Level Primitives
+### Generic Trackers
 
-For interaction types not covered above, use `ViewTracker` and `ClickTracker` directly with a custom `tag` or `eventName`:
+For custom interaction types, use `ViewTracker` or `ClickTracker` directly:
 
 ```tsx
+import { BuyerIntent } from '@g2crowd/buyer-intent-provider-sdk/react';
+
 <BuyerIntent.ViewTracker
   tag="custom.page_type"
   productIds={[123]}
@@ -206,17 +221,25 @@ For interaction types not covered above, use `ViewTracker` and `ClickTracker` di
   <CustomPage />
 </BuyerIntent.ViewTracker>
 
-<BuyerIntent.ClickTracker
-  eventName="$custom_action"
-  productIds={[123]}
->
+<BuyerIntent.ClickTracker eventName="$custom_action" productIds={[123]}>
   <button>Custom Action</button>
 </BuyerIntent.ClickTracker>
 ```
 
-### Visit Properties
+### Common Props
 
-```tsx
+| Prop               | Description                              |
+| ------------------ | ---------------------------------------- |
+| `origin`           | Partner hostname                         |
+| `activityEndpoint` | URL to POST events to                    |
+| `userType`         | User type string (default: `"standard"`) |
+| `distinctId`       | Override the auto-generated visitor ID   |
+| `sourceLocation`   | Controller/action identifier             |
+| `context`          | Arbitrary metadata object                |
+
+## Visit Properties
+
+```js
 import { buyerIntent } from '@g2crowd/buyer-intent-provider-sdk';
 
 buyerIntent.setVisitProperties({
@@ -232,27 +255,82 @@ buyerIntent.setVisitProperties({
 });
 ```
 
-## Server API
+## Backend
 
-### createActivityHandler(options)
+### Next.js Route Handler
 
-Returns a framework-agnostic handler that validates, enriches, and publishes events to Kafka.
+```ts
+import { createNextRouteHandler } from '@g2crowd/buyer-intent-provider-sdk/server';
 
-### createNextRouteHandler(options)
+const POST = createNextRouteHandler({
+  kafkaBrokers: [process.env.KAFKA_BROKER || 'localhost:9092'],
+  partnerId: process.env.PARTNER_ID,
+});
+
+export { POST };
+```
 
-Next.js Route Handler wrapper around `createActivityHandler`.
+### Standalone Server
 
-### createDevLoggerProducer(options)
+```bash
+PARTNER_ID=partner-a KAFKA_BROKERS=broker1:9092,broker2:9092 \
+buyer-intent-server
+```
 
-Dev-only producer that logs messages instead of sending to Kafka.
+Environment variables: `PORT` (default 3000), `PARTNER_ID`, `KAFKA_BROKERS` (comma-separated), `TOPIC_PREFIX`, `KAFKA_TOPIC`, `KAFKA_CLIENT_ID`, `USE_DEV_LOGGER=true`.
 
-### topicName(options)
+### Custom Kafka Producer
 
-Builds a topic name from a `partnerId` and optional `prefix`.
+```ts
+import { Kafka } from 'kafkajs';
+import { createNextRouteHandler } from '@g2crowd/buyer-intent-provider-sdk/server';
 
-## Event Payload
+const kafka = new Kafka({
+  clientId: 'partner-app',
+  brokers: (process.env.KAFKA_BROKERS || '').split(','),
+});
+
+const POST = createNextRouteHandler({
+  producer: kafka.producer({ allowAutoTopicCreation: false }),
+  partnerId: process.env.PARTNER_ID,
+});
+
+export { POST };
+```
+
+### Dev Adapter (No Kafka)
+
+```ts
+import {
+  createNextRouteHandler,
+  createDevLoggerProducer,
+} from '@g2crowd/buyer-intent-provider-sdk/server';
+
+const POST = createNextRouteHandler({
+  producer: createDevLoggerProducer(),
+  partnerId: 'dev',
+});
+
+export { POST };
+```
+
+## Server API
 
-The SDK sends the following JSON body to `activityEndpoint`:
+| Function                           | Purpose                                                                            |
+| ---------------------------------- | ---------------------------------------------------------------------------------- |
+| `createActivityHandler(options)`   | 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 `partnerId` and optional `prefix`                         |
+
+## Kafka Setup (Partner Checklist)
+
+- Kafka broker list (host:port)
+- Topic name (scoped to their tenant, default: `intent_events_<partnerId>`)
+- Auth mechanism (SASL user/pass or mTLS)
+- TLS requirements (on/off, CA certs if needed)
+
+## Event Payload
 
 ```json
 {
@@ -266,9 +344,7 @@ The SDK sends the following JSON body to `activityEndpoint`:
     "distinct_id": "visitor-uuid",
     "origin": "g2.com",
     "source_location": "ProductsController#show",
-    "context": {
-      "page": "product"
-    }
+    "context": { "page": "product" }
   },
   "visit": {
     "properties": {

package/browser/components/index.js

@@ -0,0 +1,24 @@
+export { ViewTracker, ClickTracker } from './tracker.js';
+import { ViewTracker, ClickTracker } from './tracker.js';
+import React from 'react';
+
+function view(tag) {
+  return function ViewComponent({ children, ...rest }) {
+    return React.createElement(ViewTracker, { ...rest, tag }, children);
+  };
+}
+
+function click(eventName) {
+  return function ClickComponent({ children, ...rest }) {
+    return React.createElement(ClickTracker, { ...rest, eventName }, children);
+  };
+}
+
+export const ProfileView = view('products.show');
+export const PricingView = view('products.pricing');
+export const CompetitorsView = view('products.competitors');
+export const CategoryView = view('categories.show');
+export const CompareView = view('comparisons.show');
+export const WriteReviewView = view('reviewers.take_survey');
+export const AdClick = click('/ad/clicked');
+export const LeadCreateClick = click('/leads/create');

package/browser/components/tracker.js

@@ -0,0 +1,40 @@
+import React from 'react';
+
+function buildAttrs({
+  productId,
+  productIds,
+  categoryId,
+  tag,
+  eventName,
+  sourceLocation,
+  context,
+  origin,
+  activityEndpoint,
+  userType,
+  distinctId,
+}) {
+  const payload = { sourceLocation, context };
+  const attrs = {
+    'data-buyer-intent': JSON.stringify(payload),
+    'data-origin': origin,
+    'data-activity-endpoint': activityEndpoint,
+    'data-user-type': userType,
+    'data-distinct-id': distinctId,
+  };
+
+  if (tag) attrs.tag = tag;
+  if (eventName) attrs['event-name'] = eventName;
+  if (productId != null) attrs['product-id'] = String(productId);
+  if (productIds) attrs['product-ids'] = JSON.stringify(productIds);
+  if (categoryId != null) attrs['category-id'] = String(categoryId);
+
+  return attrs;
+}
+
+export function ViewTracker({ children, ...rest }) {
+  return React.createElement('buyer-intent-view', buildAttrs(rest), children);
+}
+
+export function ClickTracker({ children, ...rest }) {
+  return React.createElement('buyer-intent-click', buildAttrs(rest), children);
+}

package/browser/dom.js

@@ -0,0 +1,98 @@
+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;
+}
+
+function readTagElement(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),
+  };
+}
+
+export function readTags(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: readTagElement(element) }))
+    .filter((entry) => entry.tag && typeof entry.tag === 'object');
+}
+
+export function readElementConfig(element) {
+  if (!element || !element.dataset) {
+    return {};
+  }
+
+  const { origin, userType, distinctId, activityEndpoint } = element.dataset;
+
+  return { origin, userType, distinctId, activityEndpoint };
+}
+
+export function resolveEventName(element, fallback) {
+  if (element && element.dataset && element.dataset.eventName) {
+    return element.dataset.eventName;
+  }
+
+  return fallback;
+}