@proveanything/smartlinks 1.8.0 → 1.8.2

package/docs/analytics.md

@@ -44,7 +44,7 @@ There are two analytics domains:
 | Collection events | `/public/analytics/collection` | Page views, clicks, app navigation, landing pages |
 | Tag events | `/public/analytics/tag` | NFC / QR scans, claim/code activity, suspicious scan monitoring |
 
-The backend stores custom analytics dimensions in `metadata`. For the most common attribution and placement keys, the public ingestion endpoints also accept standard top-level convenience fields and mirror them into `metadata` automatically.
+The backend stores custom analytics dimensions in `metadata`, but promoted analytics fields now belong at top level and are queried from real columns.
 
 See [docs/analytics-metadata-conventions.md](analytics-metadata-conventions.md) for the recommended key set.
 
@@ -60,7 +60,7 @@ import { initializeApi, analytics } from '@proveanything/smartlinks'
 initializeApi({ baseURL: 'https://smartlinks.app/api/v1' })
 
 analytics.collection.track({
-  sessionId: 'sess_123',
+  sessionId: 1234567890,
   eventType: 'page_view',
   collectionId: 'demo-collection',
   productId: 'product_1',
@@ -74,7 +74,7 @@ analytics.collection.track({
 
 ```typescript
 analytics.collection.track({
-  sessionId: 'sess_123',
+  sessionId: 1234567890,
   eventType: 'click_link',
   collectionId: 'demo-collection',
   productId: 'product_1',
@@ -91,7 +91,7 @@ analytics.collection.track({
 
 ```typescript
 analytics.tag.track({
-  sessionId: 'sess_123',
+  sessionId: 1234567890,
   eventType: 'scan_tag',
   collectionId: 'demo-collection',
   productId: 'product_1',
@@ -298,15 +298,13 @@ Tracks generic collection analytics events such as:
 - internal navigation
 - outbound link activity
 
-Supported top-level fields include the core event fields plus standard convenience metadata fields such as `referrer`, `utmSource`, `group`, `placement`, `linkTitle`, `pagePath`, and `qrCodeId`.
-
-`visitorId` is also supported as a standard top-level field and is mirrored into `metadata` by the backend for backward compatibility.
+Supported top-level fields include the core event fields plus promoted analytics columns such as `visitorId`, `referrerHost`, `pageId`, and `entryType`, along with custom metadata dimensions like `group`, `placement`, `pagePath`, and `qrCodeId`.
 
 Example:
 
 ```typescript
 analytics.collection.track({
-  sessionId: 'sess_123',
+  sessionId: 1234567890,
   eventType: 'page_view',
   collectionId: 'demo-collection',
   productId: 'product_1',
@@ -322,6 +320,7 @@ analytics.collection.track({
   utmCampaign: 'summer-launch',
   group: 'summer-launch',
   placement: 'hero',
+  pageId: 'QR123',
   metadata: { pagePath: '/c/demo-collection?pageId=QR123' },
 })
 ```
@@ -335,15 +334,13 @@ Tracks physical scan analytics such as:
 - claim/code activity
 - admin vs customer scan behavior
 
-Supported top-level fields include the core scan fields plus the same standard convenience metadata fields, especially `entryType`, `scanMethod`, `group`, `tag`, and campaign or attribution keys when relevant.
-
-Like collection events, tag events also accept `visitorId` as a standard top-level field.
+Supported top-level fields include the core scan fields plus promoted analytics columns such as `visitorId`, `entryType`, and `scanMethod`, along with custom metadata dimensions like `group`, `tag`, and campaign extras.
 
 Example:
 
 ```typescript
 analytics.tag.track({
-  sessionId: 'sess_123',
+  sessionId: 1234567890,
   eventType: 'scan_tag',
   collectionId: 'demo-collection',
   productId: 'product_1',
@@ -374,6 +371,8 @@ Notes:
 
 Top-level scalar metadata values are the most query-friendly today. You can filter them with `metadata` and break them down with `dimension: 'metadata'` plus `metadataKey`.
 
+Promoted fields such as `visitorId`, `referrerHost`, `pageId`, `entryType`, and `scanMethod` should be sent and queried as top-level fields, not inside `metadata`.
+
 ```typescript
 const grouped = await analytics.admin.breakdown('demo-collection', {
   source: 'tag',
@@ -528,7 +527,7 @@ const traffic = await analytics.admin.timeseries('demo-collection', {
 })
 ```
 
-`uniqueVisitors` now works in generic analytics queries. The backend uses `visitorId` when present and falls back to `sessionId` for older events that do not include it yet.
+`uniqueVisitors` now works in generic analytics queries. The backend uses the top-level `visitorId` column when present and falls back to numeric `sessionId` for older events that do not include it yet.
 
 ### Breakdown
 
@@ -579,7 +578,7 @@ Most admin analytics queries support combinations of:
 - `proofId` or `proofIds[]`
 - `batchId` or `batchIds[]`
 - `variantId` or `variantIds[]`
-- `sessionId` or `sessionIds[]`
+- `sessionId` or `sessionIds[]` as numbers
 - `country` or `countries[]`
 - `metadata` for top-level JSON equality matching
 
@@ -626,11 +625,9 @@ Analytics metadata filtering currently works best with top-level scalar keys suc
 - `campaign`
 - `group`
 - `tag`
-- `referrerHost`
 - `utmSource`
 - `utmCampaign`
 - `pagePath`
-- `scanMethod`
 
 See [docs/analytics-metadata-conventions.md](analytics-metadata-conventions.md) for the recommended shared vocabulary.
 
@@ -645,7 +642,7 @@ Use `/summary`, `/timeseries`, `/breakdown`, and `/events` when you are building
 ```typescript
 function trackAndNavigate(href: string) {
   analytics.collection.track({
-    sessionId: 'sess_123',
+    sessionId: 1234567890,
     eventType: 'click_link',
     collectionId: 'demo-collection',
     linkId: 'buy-now',

package/docs/iframe-streaming-parent-changes.md

@@ -0,0 +1,308 @@
+# Iframe Streaming Parent Changes
+
+This note describes the parent-side changes needed to support AI streaming when an embedded SmartLinks app is running in iframe proxy mode.
+
+If you are using the SDK `IframeResponder` directly, this is already implemented in the SDK changes. You only need this document if your parent application has its own iframe proxy handler and does not rely on `IframeResponder`.
+
+## Goal
+
+Keep the existing architecture:
+
+- local mode: child calls API directly
+- iframe proxy mode: child never owns auth state and streams through the parent
+
+This keeps user/session authority in the parent while making AI streaming behave like the rest of the SDK transport.
+
+## What changed
+
+Previously, proxy mode only supported one-shot request/response messages:
+
+- `_smartlinksProxyRequest`
+- `_smartlinksProxyResponse`
+
+Streaming now adds a second protocol for long-lived responses:
+
+- `_smartlinksProxyStreamRequest`
+- `_smartlinksProxyStream`
+- `_smartlinksProxyStreamAbort`
+
+## New parent message handling
+
+### 1. Listen for stream requests
+
+The iframe child may now send this message:
+
+```ts
+{
+  _smartlinksProxyStreamRequest: true,
+  id: string,
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+  path: string,
+  body?: any,
+  headers?: Record<string, string>
+}
+```
+
+Parent behavior:
+
+- treat this like a proxied API request
+- build the real API URL from your configured base URL plus `path`
+- send the request using the parent's current auth/session context
+- expect an SSE / streaming response body
+- keep the request open until the stream ends or is aborted
+
+### 2. Forward stream lifecycle messages back to the child
+
+The parent should send messages back to the iframe using this envelope:
+
+```ts
+{
+  _smartlinksProxyStream: true,
+  id: string,
+  phase: 'open' | 'event' | 'end' | 'error',
+  data?: any,
+  error?: string,
+  status?: number
+}
+```
+
+Phases:
+
+- `open`
+  - optional but recommended
+  - indicates the upstream streaming request was accepted and a body exists
+- `event`
+  - contains one parsed JSON event from an SSE `data:` frame
+  - send one message per logical event payload
+- `end`
+  - sent once when the stream finishes normally
+- `error`
+  - sent if the upstream request fails before or during streaming
+
+### 3. Support abort from the child
+
+The child may stop reading early and send:
+
+```ts
+{
+  _smartlinksProxyStreamAbort: true,
+  id: string
+}
+```
+
+Parent behavior:
+
+- look up the active stream by `id`
+- abort the underlying fetch / reader
+- clean up any local state for that stream
+- do not keep streaming after abort
+
+## SSE forwarding rules
+
+The upstream AI endpoints return SSE-like frames. The parent should:
+
+- read the response body as a stream
+- buffer text until line boundaries
+- collect `data:` lines for a single event
+- join multi-line `data:` payloads with `\n`
+- ignore blank events
+- stop on `data: [DONE]`
+- JSON-parse each event payload
+- forward parsed payloads to the iframe as `_smartlinksProxyStream` with `phase: 'event'`
+
+Minimal parsing behavior:
+
+1. accumulate bytes into text
+2. split on `\r?\n`
+3. collect each `data:` line
+4. on blank line, finalize the event
+5. if payload is `[DONE]`, finish
+6. otherwise `JSON.parse(payload)` and forward
+
+## Auth and session expectations
+
+The parent remains the source of truth for auth.
+
+That means the parent stream handler should:
+
+- use the same auth headers/token source as normal proxied requests
+- not require the iframe to know the bearer token or API key
+- naturally pick up the current logged-in user when the stream starts
+- cancel active streams if your app invalidates session state on logout or account switch
+
+In practice, the stream request should use the same header-building logic as your normal parent proxy transport.
+
+## Error handling expectations
+
+If the upstream fetch returns a non-2xx status:
+
+- try to read the JSON error body
+- derive a useful message
+- send one `_smartlinksProxyStream` message with `phase: 'error'`
+- include `status` when available
+- do not send `end` afterward
+
+If the stream body is missing unexpectedly:
+
+- send `phase: 'error'`
+
+If JSON parsing fails for a single event chunk:
+
+- safest behavior is to ignore that malformed chunk and continue
+
+## State the parent should keep
+
+Track active streams in a map keyed by `id`:
+
+```ts
+Map<string, AbortController>
+```
+
+Recommended cleanup points:
+
+- on normal stream end
+- on error
+- on child abort
+- on iframe detach/unmount
+- on parent auth reset/logout if you want all in-flight streams cancelled immediately
+
+## Parent implementation outline
+
+```ts
+const activeStreams = new Map<string, AbortController>()
+
+window.addEventListener('message', async (event) => {
+  const msg = event.data
+
+  if (msg?._smartlinksProxyStreamAbort && msg.id) {
+    activeStreams.get(msg.id)?.abort()
+    activeStreams.delete(msg.id)
+    return
+  }
+
+  if (msg?._smartlinksProxyStreamRequest && msg.id) {
+    const controller = new AbortController()
+    activeStreams.set(msg.id, controller)
+
+    try {
+      const response = await fetch(buildUrl(msg.path), {
+        method: msg.method,
+        headers: msg.headers,
+        body: msg.body ? JSON.stringify(msg.body) : undefined,
+        signal: controller.signal,
+      })
+
+      if (!response.ok || !response.body) {
+        postError(...)
+        return
+      }
+
+      postOpen(...)
+      await forwardSse(response.body, parsed => postEvent(...parsed))
+      postEnd(...)
+    } catch (err) {
+      if (err?.name !== 'AbortError') postError(...)
+    } finally {
+      activeStreams.delete(msg.id)
+    }
+  }
+})
+```
+
+## Exact protocol summary
+
+### Child → parent
+
+Standard stream request:
+
+```ts
+{
+  _smartlinksProxyStreamRequest: true,
+  id,
+  method,
+  path,
+  body,
+  headers
+}
+```
+
+Abort request:
+
+```ts
+{
+  _smartlinksProxyStreamAbort: true,
+  id
+}
+```
+
+### Parent → child
+
+Open:
+
+```ts
+{
+  _smartlinksProxyStream: true,
+  id,
+  phase: 'open'
+}
+```
+
+Event:
+
+```ts
+{
+  _smartlinksProxyStream: true,
+  id,
+  phase: 'event',
+  data: parsedJsonEvent
+}
+```
+
+End:
+
+```ts
+{
+  _smartlinksProxyStream: true,
+  id,
+  phase: 'end'
+}
+```
+
+Error:
+
+```ts
+{
+  _smartlinksProxyStream: true,
+  id,
+  phase: 'error',
+  error: 'message',
+  status?: number
+}
+```
+
+## What does not change
+
+These parts of the parent iframe integration stay the same:
+
+- normal `_smartlinksProxyRequest` request/response flow
+- upload proxy flow
+- auth login/logout postMessage handling
+- route/deep-link handling
+- resize handling
+
+This is an additive protocol, not a replacement.
+
+## Current SDK reference
+
+The SDK implementation lives in:
+
+- [src/http.ts](src/http.ts)
+- [src/iframeResponder.ts](src/iframeResponder.ts)
+- [src/types/iframeResponder.ts](src/types/iframeResponder.ts)
+- [src/api/ai.ts](src/api/ai.ts)
+
+## Practical recommendation
+
+If your parent already uses `IframeResponder`, prefer upgrading to the SDK version with these changes instead of re-implementing the protocol manually.
+
+If your parent has a custom iframe bridge, implement exactly the three new message types above and reuse your existing auth/header logic from normal proxied requests.

package/openapi.yaml

@@ -10782,7 +10782,7 @@ components:
           type: number
         area:
           type: number
-    AnalyticsStandardMetadataFields:
+    AnalyticsStandardEventFields:
       type: object
       properties:
         visitorId:
@@ -10834,7 +10834,7 @@ components:
       type: object
       properties:
         sessionId:
-          type: string
+          $ref: "#/components/schemas/AnalyticsSessionId"
         eventType:
           $ref: "#/components/schemas/AnalyticsEventType"
         collectionId:
@@ -10873,7 +10873,7 @@ components:
       type: object
       properties:
         sessionId:
-          type: string
+          $ref: "#/components/schemas/AnalyticsSessionId"
         eventType:
           $ref: "#/components/schemas/AnalyticsEventType"
         collectionId:
@@ -11048,11 +11048,11 @@ components:
           items:
             type: string
         sessionId:
-          type: string
+          $ref: "#/components/schemas/AnalyticsSessionId"
         sessionIds:
           type: array
           items:
-            type: string
+            $ref: "#/components/schemas/AnalyticsSessionId"
         country:
           type: string
         countries:
@@ -15478,6 +15478,69 @@ components:
       required:
         - _smartlinksProxyResponse
         - id
+    ProxyStreamRequest:
+      type: object
+      properties:
+        _smartlinksProxyStreamRequest:
+          type: object
+          additionalProperties: true
+        id:
+          type: string
+        method:
+          type: string
+          enum:
+            - GET
+            - POST
+            - PUT
+            - PATCH
+            - DELETE
+        path:
+          type: string
+        body: {}
+        headers:
+          type: object
+          additionalProperties:
+            type: string
+      required:
+        - _smartlinksProxyStreamRequest
+        - id
+        - method
+        - path
+    ProxyStreamAbortMessage:
+      type: object
+      properties:
+        _smartlinksProxyStreamAbort:
+          type: object
+          additionalProperties: true
+        id:
+          type: string
+      required:
+        - _smartlinksProxyStreamAbort
+        - id
+    ProxyStreamMessage:
+      type: object
+      properties:
+        _smartlinksProxyStream:
+          type: object
+          additionalProperties: true
+        id:
+          type: string
+        phase:
+          type: string
+          enum:
+            - open
+            - event
+            - end
+            - error
+        data: {}
+        error:
+          type: string
+        status:
+          type: number
+      required:
+        - _smartlinksProxyStream
+        - id
+        - phase
     UploadStartMessage:
       type: object
       properties:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "1.8.0",
+  "version": "1.8.2",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",