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

package/README.md

@@ -1,193 +1,220 @@
 # Buyer Intent JS SDK
 
-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
+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
 ```
 
-## Entry Points
-
-| 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.
+Import the SDK, wrap your page in a session, and you're tracking:
 
 ```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"
+<buyer-intent-session
+  origin="yoursite.com"
+  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>
-```
-
-### React Components
+  <buyer-intent-view tag="products.show">
+    <buyer-intent-subject product-id="123"></buyer-intent-subject>
 
-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.
+    <h1>Acme CRM</h1>
+    <p>Product details here.</p>
 
-```tsx
-import { BuyerIntent } from '@g2crowd/buyer-intent-provider-sdk/react';
+    <buyer-intent-click event-name="/leads/create">
+      <button>Get a Demo</button>
+    </buyer-intent-click>
+  </buyer-intent-view>
 
-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-session>
 ```
 
-### Mixing Both
+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.
 
-Custom elements and React components use the same underlying event system. You can mix them freely on the same page:
+## Elements
 
-```tsx
-import { BuyerIntent } from '@g2crowd/buyer-intent-provider-sdk/react';
+### `<buyer-intent-session>`
 
-<BuyerIntent.PricingView
-  productId={123}
-  origin="g2.com"
-  activityEndpoint="/api/activity/events"
->
-  <h1>Pricing</h1>
+Wraps a page (or your entire app) and provides config to all elements inside it. Does not fire any events itself.
 
-  <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>;
-```
+| 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       |
 
-## Custom Elements
+| User Type        | Meaning                                           |
+| ---------------- | ------------------------------------------------- |
+| `guest`          | Logged-out visitor                                |
+| `standard`       | Logged-in user (default)                          |
+| `vendor-admin`   | Vendor role viewing their own content             |
+| `observer`       | Internal employee / superuser                     |
 
-Two elements cover all tracking scenarios. The `tag` or `event-name` attribute determines the interaction type.
+```html
+<buyer-intent-session origin="yoursite.com" activity-endpoint="/api/activity/events">
+  <!-- everything inside inherits origin and endpoint -->
+</buyer-intent-session>
+```
 
 ### `<buyer-intent-view>`
 
 Fires a `$view` event when the element connects to the DOM. One event per page navigation.
 
-| 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                                          |
+| 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)           |
 
-Supported `tag` values: `products.show`, `products.pricing`, `products.competitors`, `categories.show`, `comparisons.show`, `reviewers.take_survey`
+For pages with one product, you can put the ID directly on the view:
 
 ```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 tag="products.show" product-id="123">
+  <h1>Acme CRM</h1>
 </buyer-intent-view>
 ```
 
-Multiple product IDs (for comparisons):
+For pages with multiple products, use `<buyer-intent-subject>` children instead (see below).
+
+### `<buyer-intent-subject>`
+
+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.
+
+| 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)|
+
+A comparison page that references two products:
 
 ```html
-<buyer-intent-view tag="comparisons.show" product-ids="[101, 201]">
-  ...
+<buyer-intent-view tag="comparisons.show">
+  <buyer-intent-subject product-id="101"></buyer-intent-subject>
+  <buyer-intent-subject product-id="201"></buyer-intent-subject>
+
+  <h1>Acme CRM vs. Rival CRM</h1>
 </buyer-intent-view>
+```
+
+The resulting event has `product_ids: [101, 201]`. If the view also has an inline `product-id`, they merge together without duplicates.
 
-<buyer-intent-view tag="comparisons.show" product-ids="101,201">
-  ...
+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:
+
+```html
+<buyer-intent-view tag="categories.show">
+  <buyer-intent-subject category-id="45"></buyer-intent-subject>
+  <h1>CRM Software</h1>
+
+  <div class="product-grid">
+    <div class="product-card">
+      <buyer-intent-subject product-id="101"></buyer-intent-subject>
+      <h2>Acme CRM</h2>
+    </div>
+
+    <div class="product-card">
+      <buyer-intent-subject product-id="201"></buyer-intent-subject>
+      <h2>Rival CRM</h2>
+    </div>
+  </div>
 </buyer-intent-view>
 ```
 
-### `<buyer-intent-click>`
+This fires one event: `category_ids: [45]`, `product_ids: [101, 201]`, `tag: "categories.show"`.
 
-Fires an event each time the user clicks anything inside the element.
+### `<buyer-intent-click>`
 
-| Attribute    | Required | Description                         |
-| ------------ | -------- | ----------------------------------- |
-| `event-name` | Yes      | Click event type (see values below) |
-| `product-id` | -        | Product ID                          |
+Fires an event when the user clicks anything inside it.
 
-Supported `event-name` values: `/ad/clicked`, `/leads/create`
+| Attribute    | Description              |
+| ------------ | ------------------------ |
+| `event-name` | Click event type         |
 
 ```html
-<buyer-intent-click
-  event-name="/leads/create"
-  product-id="123"
-  data-origin="g2.com"
-  data-activity-endpoint="/api/activity/events"
->
+<buyer-intent-click event-name="/leads/create">
   <button>Get a Demo</button>
 </buyer-intent-click>
 ```
 
-### Common Attributes
+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.
 
-Both elements accept these optional `data-*` attributes:
+## Full Example
 
-| 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 |
+Putting it all together — a product page with a session, view, subjects, and two click actions:
 
-### TypeScript Support
+```html
+<script type="module">
+  import '@g2crowd/buyer-intent-provider-sdk';
+</script>
 
-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:
+<buyer-intent-session
+  origin="yoursite.com"
+  activity-endpoint="/api/activity/events"
+  user-type="standard"
+>
+
+  <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>
+
+    <h1>Acme CRM</h1>
+    <p>The best CRM for small teams.</p>
+
+    <buyer-intent-click event-name="/leads/create">
+      <button>Get a Demo</button>
+    </buyer-intent-click>
+
+    <buyer-intent-click event-name="/ad/clicked">
+      <a href="https://acme.example.com">Visit Acme</a>
+    </buyer-intent-click>
+  </buyer-intent-view>
+
+</buyer-intent-session>
+```
+
+## React Support
+
+Import from `/react` and use the same element hierarchy with camelCase props:
 
 ```tsx
-// ✅ Type-safe
-<buyer-intent-view tag="products.show" product-id="123">
+import { BuyerIntent } from '@g2crowd/buyer-intent-provider-sdk/react';
 
-// ❌ Type error: '"invalid.tag"' is not assignable to type 'ViewTag'
-<buyer-intent-view tag="invalid.tag" product-id="123">
+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>
+  );
+}
 ```
 
-## React Components
+`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
 
-Named React components wrap the custom elements with hardcoded `tag`/`event-name` values. They accept camelCase props instead of HTML attributes.
+For common page types, pre-built components hardcode the `tag` or `event-name` so you don't have to:
 
-### View Components
+### Views
 
 | Component         | Tag                     | Required Prop |
 | ----------------- | ----------------------- | ------------- |
@@ -198,62 +225,28 @@ Named React components wrap the custom elements with hardcoded `tag`/`event-name
 | `CompareView`     | `comparisons.show`      | `productIds`  |
 | `WriteReviewView` | `reviewers.take_survey` | `productId`   |
 
-### Click Components
+### Clicks
 
 | Component         | Event Name      | Required Prop |
 | ----------------- | --------------- | ------------- |
 | `AdClick`         | `/ad/clicked`   | `productId`   |
 | `LeadCreateClick` | `/leads/create` | `productId`   |
 
-### Generic Trackers
-
-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]}
-  origin="g2.com"
-  activityEndpoint="/api/activity/events"
->
-  <CustomPage />
-</BuyerIntent.ViewTracker>
+<BuyerIntent.Session origin="yoursite.com" activityEndpoint="/api/activity/events">
+  <BuyerIntent.ProfileView productId={123}>
+    <h1>Acme CRM</h1>
 
-<BuyerIntent.ClickTracker eventName="$custom_action" productIds={[123]}>
-  <button>Custom Action</button>
-</BuyerIntent.ClickTracker>
+    <BuyerIntent.LeadCreateClick productId={123}>
+      <button>Get a Demo</button>
+    </BuyerIntent.LeadCreateClick>
+  </BuyerIntent.ProfileView>
+</BuyerIntent.Session>
 ```
 
-### Common Props
-
-| 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({
-  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',
-});
-```
+These components still accept `origin`, `activityEndpoint`, `sourceLocation`, and `context` props for cases where you aren't using a session wrapper.
 
 ## Backend
 
@@ -314,50 +307,81 @@ const POST = createNextRouteHandler({
 export { POST };
 ```
 
-## Server API
-
-| 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)
+## Event Payload
 
-- 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)
+The client sends a beacon to the activity endpoint. The server handler wraps it into a composite event and writes it to Kafka.
 
-## Event Payload
+### Client → Server (sendBeacon body)
 
 ```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",
+    "origin": "yoursite.com",
     "source_location": "ProductsController#show",
-    "context": { "page": "product" }
+    "context": {}
   },
   "visit": {
     "properties": {
-      "landing_page": "https://example.com/products/abc",
-      "referrer": "https://example.com/",
-      "user_agent": "Mozilla/5.0",
-      "ip": "203.0.113.10",
+      "landing_page": "https://yoursite.com/products/acme-crm",
+      "referrer": "https://google.com/",
+      "user_agent": "Mozilla/5.0 ...",
       "utm_source": "newsletter",
       "utm_medium": "email",
-      "utm_campaign": "spring_launch",
-      "utm_term": "buyer-intent",
-      "utm_content": "cta-button"
+      "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,29 +1,24 @@
 {
   "name": "@g2crowd/buyer-intent-provider-sdk",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Buyer intent tracking SDK with pageview defaults",
   "type": "module",
-  "main": "index.js",
+  "main": "src/index.js",
   "exports": {
-    ".": "./index.js",
-    "./react": "./react/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",
-    "react",
-    "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": {
@@ -46,7 +41,7 @@
     }
   },
   "sideEffects": [
-    "./browser/elements/*.js"
+    "./src/browser/elements/*.js"
   ],
   "devDependencies": {
     "@testing-library/dom": "^9.3.4",

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

@@ -1,5 +1,10 @@
-export { ViewTracker, ClickTracker } from './tracker.js';
-import { ViewTracker, ClickTracker } from './tracker.js';
+export {
+  SessionProvider,
+  SubjectTracker,
+  ViewTracker,
+  ClickTracker,
+} from './tracker.js';
+import { SessionProvider, SubjectTracker, ViewTracker, ClickTracker } from './tracker.js';
 import React from 'react';
 
 function view(tag) {