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

package/README.md

@@ -1,286 +1,333 @@
 # 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.
-
-## Install
+Buyer intent tracking for partner sites. Drop custom HTML elements into any page — no framework required. Events are sent via `sendBeacon` for reliable delivery during navigation.
 
 ```bash
 npm install @g2crowd/buyer-intent-provider-sdk
 ```
 
-If you plan to use the built-in Kafka connection (via `kafkaBrokers`), install the peer dependency:
+## Quick Start
 
-```bash
-npm install kafkajs
-```
+Import the SDK, wrap your page in a session, and you're tracking:
 
-## Quick Start (Next.js)
+```html
+<script type="module">
+  import '@g2crowd/buyer-intent-provider-sdk';
+</script>
 
-```tsx
-import { BuyerIntent } from '@g2crowd/buyer-intent-provider-sdk';
+<buyer-intent-session
+  origin="yoursite.com"
+  activity-endpoint="/api/activity/events"
+>
 
-// Product profile page — fires a $view with tag "products.show"
-export default function ProductPage() {
-  return (
-    <BuyerIntent.ProfileView
-      productId={123}
-      origin="g2.com"
-      activityEndpoint="/api/activity/events"
-    >
-      <h1>Acme CRM</h1>
-      <p>Product details here.</p>
-
-      <BuyerIntent.LeadCreateClick productId={123}>
-        <button>Get a Demo</button>
-      </BuyerIntent.LeadCreateClick>
-    </BuyerIntent.ProfileView>
-  );
-}
+  <buyer-intent-view tag="products.show">
+    <buyer-intent-subject product-id="123"></buyer-intent-subject>
+
+    <h1>Acme CRM</h1>
+    <p>Product details here.</p>
+
+    <buyer-intent-click event-name="/leads/create">
+      <button>Get a Demo</button>
+    </buyer-intent-click>
+  </buyer-intent-view>
+
+</buyer-intent-session>
 ```
 
-## Backend (Next.js Route)
+That's it. When the page loads, a `$view` event fires with `product_ids: [123]` and `tag: "products.show"`. When the user clicks "Get a Demo", a `/leads/create` event fires. Both events inherit the session's `origin` and `activity-endpoint` automatically.
 
-```ts
-// app/api/activity/events/route.ts
-import { createNextRouteHandler } from '@g2crowd/buyer-intent-provider-sdk/server';
+## Elements
 
-const POST = createNextRouteHandler({
-  kafkaBrokers: [process.env.KAFKA_BROKER || 'localhost:9092'],
-  partnerId: process.env.PARTNER_ID,
-});
+### `<buyer-intent-session>`
 
-export { POST };
+Wraps a page (or your entire app) and provides config to all elements inside it. Does not fire any events itself.
+
+| Attribute            | Description                                  |
+| -------------------- | -------------------------------------------- |
+| `origin`             | Partner hostname                             |
+| `activity-endpoint`  | URL to POST events to                        |
+| `user-type`          | Visitor role (default: `"standard"`)         |
+| `distinct-id`        | Override the auto-generated visitor ID       |
+
+| User Type        | Meaning                                           |
+| ---------------- | ------------------------------------------------- |
+| `guest`          | Logged-out visitor                                |
+| `standard`       | Logged-in user (default)                          |
+| `vendor-admin`   | Vendor role viewing their own content             |
+| `observer`       | Internal employee / superuser                     |
+
+```html
+<buyer-intent-session origin="yoursite.com" activity-endpoint="/api/activity/events">
+  <!-- everything inside inherits origin and endpoint -->
+</buyer-intent-session>
 ```
 
-## Barebones Server
+### `<buyer-intent-view>`
 
-This package ships a tiny server that hosts `POST /activity/events`.
+Fires a `$view` event when the element connects to the DOM. One event per page navigation.
 
-```bash
-PARTNER_ID=partner-a KAFKA_BROKERS=broker1:9092,broker2:9092 \
-buyer-intent-server
+| Attribute         | Description                                 |
+| ----------------- | ------------------------------------------- |
+| `tag`             | View type identifier (optional)             |
+| `source-location` | Controller/action string (optional)         |
+| `product-id`      | Single product ID (simple pages)            |
+| `category-id`     | Single category ID (simple pages)           |
+
+For pages with one product, you can put the ID directly on the view:
+
+```html
+<buyer-intent-view tag="products.show" product-id="123">
+  <h1>Acme CRM</h1>
+</buyer-intent-view>
 ```
 
-Environment variables:
+For pages with multiple products, use `<buyer-intent-subject>` children instead (see below).
 
-- `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)
+### `<buyer-intent-subject>`
 
-## Kafka Setup (Partner Checklist)
+Declares that a product or category is a **subject** of the current view. Nest any number of these inside a `<buyer-intent-view>` — their IDs accumulate into the view's event automatically. Does not render anything visible.
 
-Provide these values to your partners so they can publish to their scoped topic:
+| Attribute      | Description                                          |
+| -------------- | ---------------------------------------------------- |
+| `product-id`   | Single product ID                                    |
+| `product-ids`  | Multiple product IDs (JSON array or comma-separated) |
+| `category-id`  | Single category ID                                   |
+| `category-ids` | Multiple category IDs (JSON array or comma-separated)|
 
-- 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)
+A comparison page that references two products:
 
-By default, the SDK derives the topic from `partnerId` using `intent_events_<partnerId>`.
+```html
+<buyer-intent-view tag="comparisons.show">
+  <buyer-intent-subject product-id="101"></buyer-intent-subject>
+  <buyer-intent-subject product-id="201"></buyer-intent-subject>
 
-Example using a prebuilt producer:
+  <h1>Acme CRM vs. Rival CRM</h1>
+</buyer-intent-view>
+```
 
-```ts
-// app/api/activity/events/route.ts
-import { Kafka } from 'kafkajs';
-import { createNextRouteHandler } from '@g2crowd/buyer-intent-provider-sdk/server';
+The resulting event has `product_ids: [101, 201]`. If the view also has an inline `product-id`, they merge together without duplicates.
 
-const kafka = new Kafka({
-  clientId: 'partner-app',
-  brokers: (process.env.KAFKA_BROKERS || '').split(','),
-});
+Subjects can live anywhere inside the view — they don't need to be direct children. This makes them easy to place next to the content they describe:
 
-const producer = kafka.producer({
-  allowAutoTopicCreation: false,
-});
+```html
+<buyer-intent-view tag="categories.show">
+  <buyer-intent-subject category-id="45"></buyer-intent-subject>
+  <h1>CRM Software</h1>
 
-const POST = createNextRouteHandler({
-  producer,
-  partnerId: process.env.PARTNER_ID,
-  topicPrefix: process.env.TOPIC_PREFIX,
-});
+  <div class="product-grid">
+    <div class="product-card">
+      <buyer-intent-subject product-id="101"></buyer-intent-subject>
+      <h2>Acme CRM</h2>
+    </div>
 
-export { POST };
+    <div class="product-card">
+      <buyer-intent-subject product-id="201"></buyer-intent-subject>
+      <h2>Rival CRM</h2>
+    </div>
+  </div>
+</buyer-intent-view>
 ```
 
-## Dev Adapter (No Kafka)
+This fires one event: `category_ids: [45]`, `product_ids: [101, 201]`, `tag: "categories.show"`.
 
-If you want to test locally without Kafka, use the dev logger producer.
+### `<buyer-intent-click>`
 
-```ts
-// app/api/activity/events/route.ts
-import {
-  createNextRouteHandler,
-  createDevLoggerProducer,
-} from '@g2crowd/buyer-intent-provider-sdk/server';
+Fires an event when the user clicks anything inside it.
 
-const POST = createNextRouteHandler({
-  producer: createDevLoggerProducer(),
-  partnerId: 'dev',
-});
+| Attribute    | Description              |
+| ------------ | ------------------------ |
+| `event-name` | Click event type         |
 
-export { POST };
+```html
+<buyer-intent-click event-name="/leads/create">
+  <button>Get a Demo</button>
+</buyer-intent-click>
 ```
 
-## Interaction Components
+A click element inside a view automatically inherits the view's tag, product IDs, and category IDs. A click inside a session inherits the session's config. You don't need to repeat anything.
 
-Purpose-built components for each tracked interaction type. Each sets the correct event name and tag automatically — you just provide the required ID.
+## Full Example
 
-### Page Views
+Putting it all together — a product page with a session, view, subjects, and two click actions:
 
-These fire a `$view` event when the component appears in the DOM. One event per page navigation.
+```html
+<script type="module">
+  import '@g2crowd/buyer-intent-provider-sdk';
+</script>
 
-| 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` |
+<buyer-intent-session
+  origin="yoursite.com"
+  activity-endpoint="/api/activity/events"
+  user-type="standard"
+>
 
-```tsx
-import { BuyerIntent } from '@g2crowd/buyer-intent-provider-sdk';
+  <buyer-intent-view
+    tag="products.show"
+    source-location="ProductsController#show"
+  >
+    <buyer-intent-subject product-id="123"></buyer-intent-subject>
+    <buyer-intent-subject category-id="45"></buyer-intent-subject>
 
-<BuyerIntent.ProfileView productId={123} origin="g2.com" activityEndpoint="/api/activity/events">
-  <ProductPage />
-</BuyerIntent.ProfileView>
+    <h1>Acme CRM</h1>
+    <p>The best CRM for small teams.</p>
 
-<BuyerIntent.CategoryView categoryId={45} origin="g2.com" activityEndpoint="/api/activity/events">
-  <CategoryPage />
-</BuyerIntent.CategoryView>
+    <buyer-intent-click event-name="/leads/create">
+      <button>Get a Demo</button>
+    </buyer-intent-click>
 
-<BuyerIntent.CompareView productIds={[123, 456]} origin="g2.com" activityEndpoint="/api/activity/events">
-  <ComparisonPage />
-</BuyerIntent.CompareView>
-```
+    <buyer-intent-click event-name="/ad/clicked">
+      <a href="https://acme.example.com">Visit Acme</a>
+    </buyer-intent-click>
+  </buyer-intent-view>
 
-### Click Events
+</buyer-intent-session>
+```
 
-These fire an event each time the user clicks anything inside the component.
+## React Support
 
-| Component         | Required Prop | Event Name      |
-| ----------------- | ------------- | --------------- |
-| `AdClick`         | `productId`   | `/ad/clicked`   |
-| `LeadCreateClick` | `productId`   | `/leads/create` |
+Import from `/react` and use the same element hierarchy with camelCase props:
 
 ```tsx
-<BuyerIntent.LeadCreateClick productId={123}>
-  <button>Get a Demo</button>
-</BuyerIntent.LeadCreateClick>
+import { BuyerIntent } from '@g2crowd/buyer-intent-provider-sdk/react';
 
-<BuyerIntent.AdClick productId={123}>
-  <button>Sponsored Link</button>
-</BuyerIntent.AdClick>
+export default function ProductPage() {
+  return (
+    <BuyerIntent.Session origin="yoursite.com" activityEndpoint="/api/activity/events">
+      <BuyerIntent.View tag="products.show" sourceLocation="ProductsController#show">
+        <BuyerIntent.Subject productId={123} />
+        <BuyerIntent.Subject categoryId={45} />
+
+        <h1>Acme CRM</h1>
+
+        <BuyerIntent.Click eventName="/leads/create">
+          <button>Get a Demo</button>
+        </BuyerIntent.Click>
+      </BuyerIntent.View>
+    </BuyerIntent.Session>
+  );
+}
 ```
 
-### Common Props
+`BuyerIntent.Session`, `BuyerIntent.View`, `BuyerIntent.Subject`, and `BuyerIntent.Click` map 1:1 to the HTML elements described above. The session is a good fit for a layout component or `_app` wrapper so it's set once for every page.
+
+## Syntactic Sugar
 
-All interaction components accept these optional props:
+For common page types, pre-built components hardcode the `tag` or `event-name` so you don't have to:
 
-| 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          |
+### Views
 
-### Low-Level Primitives
+| 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`   |
 
-For interaction types not covered above, use `ViewTracker` and `ClickTracker` directly with a custom `tag` or `eventName`:
+### Clicks
+
+| Component         | Event Name      | Required Prop |
+| ----------------- | --------------- | ------------- |
+| `AdClick`         | `/ad/clicked`   | `productId`   |
+| `LeadCreateClick` | `/leads/create` | `productId`   |
 
 ```tsx
-<BuyerIntent.ViewTracker
-  tag="custom.page_type"
-  productIds={[123]}
-  origin="g2.com"
-  activityEndpoint="/api/activity/events"
->
-  <CustomPage />
-</BuyerIntent.ViewTracker>
+import { BuyerIntent } from '@g2crowd/buyer-intent-provider-sdk/react';
 
-<BuyerIntent.ClickTracker
-  eventName="$custom_action"
-  productIds={[123]}
->
-  <button>Custom Action</button>
-</BuyerIntent.ClickTracker>
+<BuyerIntent.Session origin="yoursite.com" activityEndpoint="/api/activity/events">
+  <BuyerIntent.ProfileView productId={123}>
+    <h1>Acme CRM</h1>
+
+    <BuyerIntent.LeadCreateClick productId={123}>
+      <button>Get a Demo</button>
+    </BuyerIntent.LeadCreateClick>
+  </BuyerIntent.ProfileView>
+</BuyerIntent.Session>
 ```
 
-### Visit Properties
+These components still accept `origin`, `activityEndpoint`, `sourceLocation`, and `context` props for cases where you aren't using a session wrapper.
 
-```tsx
-import { buyerIntent } from '@g2crowd/buyer-intent-provider-sdk';
-
-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',
+## Backend
+
+### Next.js Route Handler
+
+```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 };
+```
+
+### Standalone Server
+
+```bash
+PARTNER_ID=partner-a KAFKA_BROKERS=broker1:9092,broker2:9092 \
+buyer-intent-server
 ```
 
-## Server API
+Environment variables: `PORT` (default 3000), `PARTNER_ID`, `KAFKA_BROKERS` (comma-separated), `TOPIC_PREFIX`, `KAFKA_TOPIC`, `KAFKA_CLIENT_ID`, `USE_DEV_LOGGER=true`.
 
-### createActivityHandler(options)
+### Custom Kafka Producer
 
-Returns a framework-agnostic handler that validates, enriches, and publishes events to Kafka.
+```ts
+import { Kafka } from 'kafkajs';
+import { createNextRouteHandler } from '@g2crowd/buyer-intent-provider-sdk/server';
 
-### createNextRouteHandler(options)
+const kafka = new Kafka({
+  clientId: 'partner-app',
+  brokers: (process.env.KAFKA_BROKERS || '').split(','),
+});
 
-Next.js Route Handler wrapper around `createActivityHandler`.
+const POST = createNextRouteHandler({
+  producer: kafka.producer({ allowAutoTopicCreation: false }),
+  partnerId: process.env.PARTNER_ID,
+});
 
-### createDevLoggerProducer(options)
+export { POST };
+```
 
-Dev-only producer that logs messages instead of sending to Kafka.
+### Dev Adapter (No Kafka)
 
-### topicName(options)
+```ts
+import {
+  createNextRouteHandler,
+  createDevLoggerProducer,
+} from '@g2crowd/buyer-intent-provider-sdk/server';
 
-Builds a topic name from a `partnerId` and optional `prefix`.
+const POST = createNextRouteHandler({
+  producer: createDevLoggerProducer(),
+  partnerId: 'dev',
+});
 
-## Event Payload
+export { POST };
+```
 
-The SDK sends the following JSON body to `activityEndpoint`:
+## Event Payload
 
 ```json
 {
   "name": "$view",
   "properties": {
     "product_ids": [123],
-    "category_ids": [78],
+    "category_ids": [45],
     "tag": "products.show",
-    "url": "https://example.com/products/abc",
+    "url": "https://yoursite.com/products/acme-crm",
     "user_type": "standard",
     "distinct_id": "visitor-uuid",
-    "origin": "g2.com",
-    "source_location": "ProductsController#show",
-    "context": {
-      "page": "product"
-    }
+    "origin": "yoursite.com",
+    "source_location": "ProductsController#show"
   },
   "visit": {
     "properties": {
-      "landing_page": "https://example.com/products/abc",
-      "referrer": "https://example.com/",
+      "landing_page": "https://yoursite.com/products/acme-crm",
+      "referrer": "https://google.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"
+      "utm_source": "newsletter"
     }
   }
 }

package/package.json

@@ -1,27 +1,24 @@
 {
   "name": "@g2crowd/buyer-intent-provider-sdk",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Buyer intent tracking SDK with pageview defaults",
   "type": "module",
-  "main": "index.js",
+  "main": "src/index.js",
   "exports": {
-    ".": "./index.js",
-    "./server": "./server/index.js"
+    ".": "./src/index.js",
+    "./react": "./src/react/index.js",
+    "./server": "./src/server/index.js"
   },
-  "types": "index.d.ts",
+  "types": "src/index.d.ts",
   "files": [
-    "index.js",
-    "index.d.ts",
-    "browser",
-    "server.js",
-    "server",
+    "src",
     "README.md"
   ],
   "scripts": {
     "test": "node --experimental-vm-modules ./node_modules/.bin/jest --config ./jest.config.cjs"
   },
   "bin": {
-    "buyer-intent-server": "server.js"
+    "buyer-intent-server": "src/server.js"
   },
   "license": "MIT",
   "repository": {
@@ -35,7 +32,17 @@
     "kafkajs": "^2.2.4",
     "react": ">=17"
   },
-  "sideEffects": false,
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "kafkajs": {
+      "optional": true
+    }
+  },
+  "sideEffects": [
+    "./src/browser/elements/*.js"
+  ],
   "devDependencies": {
     "@testing-library/dom": "^9.3.4",
     "@testing-library/react": "^14.3.1",

package/src/browser/components/index.js

@@ -0,0 +1,29 @@
+export {
+  SessionProvider,
+  SubjectTracker,
+  ViewTracker,
+  ClickTracker,
+} from './tracker.js';
+import { SessionProvider, SubjectTracker, 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');