@proveanything/smartlinks 1.8.0 → 1.8.2

package/dist/api/ai.js

@@ -1,19 +1,6 @@
-var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
-var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
-    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
-    var g = generator.apply(thisArg, _arguments || []), i, q = [];
-    return i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i;
-    function verb(n) { if (g[n]) i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; }
-    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
-    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
-    function fulfill(value) { resume("next", value); }
-    function reject(value) { resume("throw", value); }
-    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
-};
 // src/api/ai.ts
 // AI endpoints: public and admin helpers
-import { post, request, del, getBaseURL, getApiHeaders } from "../http";
-import { SmartlinksApiError } from "../types/error";
+import { post, request, del, requestStream } from "../http";
 function encodeQueryParams(params) {
     if (!params)
         return '';
@@ -25,89 +12,6 @@ function encodeQueryParams(params) {
     const search = query.toString();
     return search ? `?${search}` : '';
 }
-async function createSseStream(path, body) {
-    var _a, _b, _c;
-    const baseURL = getBaseURL();
-    if (!baseURL) {
-        throw new Error('HTTP client is not initialized. Call initializeApi(...) first.');
-    }
-    const url = `${baseURL}${path}`;
-    const headers = Object.assign({ Accept: 'text/event-stream', 'Content-Type': 'application/json' }, getApiHeaders());
-    const response = await fetch(url, {
-        method: 'POST',
-        headers,
-        body: JSON.stringify(body),
-    });
-    if (!response.ok) {
-        let responseBody;
-        try {
-            responseBody = await response.json();
-        }
-        catch (_d) {
-            responseBody = null;
-        }
-        const code = response.status;
-        const message = (responseBody === null || responseBody === void 0 ? void 0 : responseBody.message) || ((_a = responseBody === null || responseBody === void 0 ? void 0 : responseBody.error) === null || _a === void 0 ? void 0 : _a.message) || `Request failed with status ${code}`;
-        throw new SmartlinksApiError(`Error ${code}: ${message}`, code, {
-            code,
-            errorCode: ((_b = responseBody === null || responseBody === void 0 ? void 0 : responseBody.error) === null || _b === void 0 ? void 0 : _b.code) || (responseBody === null || responseBody === void 0 ? void 0 : responseBody.errorCode),
-            message,
-            details: ((_c = responseBody === null || responseBody === void 0 ? void 0 : responseBody.error) === null || _c === void 0 ? void 0 : _c.details) || (responseBody === null || responseBody === void 0 ? void 0 : responseBody.details),
-        }, url);
-    }
-    if (!response.body) {
-        throw new Error('Streaming response body is unavailable in this environment');
-    }
-    return parseSseStream(response.body);
-}
-function parseSseStream(stream) {
-    return __asyncGenerator(this, arguments, function* parseSseStream_1() {
-        const reader = stream.getReader();
-        const decoder = new TextDecoder();
-        let buffer = '';
-        let dataLines = [];
-        while (true) {
-            const { done, value } = yield __await(reader.read());
-            if (done)
-                break;
-            buffer += decoder.decode(value, { stream: true });
-            const lines = buffer.split(/\r?\n/);
-            buffer = lines.pop() || '';
-            for (const rawLine of lines) {
-                const line = rawLine.trimEnd();
-                if (!line) {
-                    if (!dataLines.length)
-                        continue;
-                    const payload = dataLines.join('\n');
-                    dataLines = [];
-                    if (payload === '[DONE]')
-                        return yield __await(void 0);
-                    try {
-                        yield yield __await(JSON.parse(payload));
-                    }
-                    catch (_a) {
-                        continue;
-                    }
-                    continue;
-                }
-                if (line.startsWith('data:')) {
-                    dataLines.push(line.slice(5).trimStart());
-                }
-            }
-        }
-        if (dataLines.length) {
-            const payload = dataLines.join('\n');
-            if (payload !== '[DONE]') {
-                try {
-                    yield yield __await(JSON.parse(payload));
-                }
-                catch (_b) {
-                    return yield __await(void 0);
-                }
-            }
-        }
-    });
-}
 var aiInternal;
 (function (aiInternal) {
     // ============================================================================
@@ -126,7 +30,7 @@ var aiInternal;
             async function create(collectionId, request) {
                 const path = `/admin/collection/${encodeURIComponent(collectionId)}/ai/v1/responses`;
                 if (request.stream) {
-                    return createSseStream(path, request);
+                    return requestStream(path, { method: 'POST', body: request });
                 }
                 return post(path, request);
             }
@@ -143,7 +47,7 @@ var aiInternal;
             async function create(collectionId, request) {
                 const path = `/admin/collection/${encodeURIComponent(collectionId)}/ai/v1/chat/completions`;
                 if (request.stream) {
-                    return createSseStream(path, request);
+                    return requestStream(path, { method: 'POST', body: request });
                 }
                 return post(path, request);
             }

package/dist/api/analytics.d.ts

@@ -1,5 +1,5 @@
-import type { AnalyticsTrackOptions, AnalyticsTrackResult, AnalyticsBrowserConfig, AnalyticsGeolocationCaptureOptions, AnalyticsLinkClickInput, AnalyticsLinkBindingOptions, AnalyticsPageViewBindingOptions, AnalyticsClassicReportRequest, AnalyticsVisitorIdOptions, CollectionAnalyticsEvent, TagAnalyticsEvent, AnalyticsSummaryRequest, AnalyticsSummaryResponse, AnalyticsTimeseriesRequest, AnalyticsTimeseriesResponse, AnalyticsBreakdownRequest, AnalyticsBreakdownResponse, AnalyticsEventsRequest, AnalyticsEventsResponse, LegacyAnalyticsRequest, AnalyticsDashboardResponse, AnalyticsProductsResponse, AnalyticsQrCodesResponse, AnalyticsTagsResponse, AnalyticsWeeklyRequest, AnalyticsCountryRequest } from "../types/analytics";
-export type { AnalyticsTrackOptions, AnalyticsTrackResult, AnalyticsBrowserConfig, AnalyticsGeolocationCaptureOptions, AnalyticsLinkClickInput, AnalyticsLinkBindingOptions, AnalyticsPageViewBindingOptions, AnalyticsClassicReportRequest, AnalyticsVisitorIdOptions, CollectionAnalyticsEvent, TagAnalyticsEvent, AnalyticsSummaryRequest, AnalyticsSummaryResponse, AnalyticsTimeseriesRequest, AnalyticsTimeseriesResponse, AnalyticsBreakdownRequest, AnalyticsBreakdownResponse, AnalyticsEventsRequest, AnalyticsEventsResponse, LegacyAnalyticsRequest, AnalyticsDashboardResponse, AnalyticsProductsResponse, AnalyticsQrCodesResponse, AnalyticsTagsResponse, AnalyticsWeeklyRequest, AnalyticsCountryRequest, };
+import type { AnalyticsTrackOptions, AnalyticsTrackResult, AnalyticsBrowserConfig, AnalyticsGeolocationCaptureOptions, AnalyticsLinkClickInput, AnalyticsLinkBindingOptions, AnalyticsPageViewBindingOptions, AnalyticsClassicReportRequest, AnalyticsVisitorIdOptions, AnalyticsSessionId, CollectionAnalyticsEvent, TagAnalyticsEvent, AnalyticsSummaryRequest, AnalyticsSummaryResponse, AnalyticsTimeseriesRequest, AnalyticsTimeseriesResponse, AnalyticsBreakdownRequest, AnalyticsBreakdownResponse, AnalyticsEventsRequest, AnalyticsEventsResponse, LegacyAnalyticsRequest, AnalyticsDashboardResponse, AnalyticsProductsResponse, AnalyticsQrCodesResponse, AnalyticsTagsResponse, AnalyticsWeeklyRequest, AnalyticsCountryRequest } from "../types/analytics";
+export type { AnalyticsTrackOptions, AnalyticsTrackResult, AnalyticsBrowserConfig, AnalyticsGeolocationCaptureOptions, AnalyticsLinkClickInput, AnalyticsLinkBindingOptions, AnalyticsPageViewBindingOptions, AnalyticsClassicReportRequest, AnalyticsVisitorIdOptions, AnalyticsSessionId, CollectionAnalyticsEvent, TagAnalyticsEvent, AnalyticsSummaryRequest, AnalyticsSummaryResponse, AnalyticsTimeseriesRequest, AnalyticsTimeseriesResponse, AnalyticsBreakdownRequest, AnalyticsBreakdownResponse, AnalyticsEventsRequest, AnalyticsEventsResponse, LegacyAnalyticsRequest, AnalyticsDashboardResponse, AnalyticsProductsResponse, AnalyticsQrCodesResponse, AnalyticsTagsResponse, AnalyticsWeeklyRequest, AnalyticsCountryRequest, };
 export declare namespace analytics {
     namespace collection {
         /**
@@ -17,7 +17,7 @@ export declare namespace analytics {
     }
     namespace browser {
         function configure(config: AnalyticsBrowserConfig): void;
-        function getSessionId(): string | undefined;
+        function getSessionId(): AnalyticsSessionId | undefined;
         function getVisitorId(): string | undefined;
         function setVisitorId(visitorId: string, options?: AnalyticsVisitorIdOptions): string;
         function clearVisitorId(options?: Pick<AnalyticsVisitorIdOptions, 'storage' | 'storageKey'>): void;

package/dist/api/analytics.js

@@ -39,8 +39,15 @@ const defaultCampaignParamMap = {
     qrCodeId: 'qrCodeId',
     scanMethod: ['scanMethod', 'scan_method'],
 };
+const promotedAnalyticsKeys = new Set([
+    'visitorId',
+    'referrerHost',
+    'pageId',
+    'entryType',
+    'scanMethod',
+]);
 function createSessionId() {
-    return `${Date.now()}_${Math.floor(Math.random() * 1000000)}`;
+    return Date.now() * 1000 + Math.floor(Math.random() * 1000);
 }
 function createVisitorId() {
     return `visitor_${Date.now()}_${Math.floor(Math.random() * 1000000)}`;
@@ -56,6 +63,33 @@ function getStorage(mode) {
     }
     return undefined;
 }
+function parseStoredSessionId(value) {
+    if (/^\d+$/.test(value)) {
+        const parsed = Number(value);
+        if (Number.isSafeInteger(parsed))
+            return parsed;
+    }
+    return undefined;
+}
+function assertValidSessionId(sessionId) {
+    if (sessionId === undefined || sessionId === null)
+        return undefined;
+    if (typeof sessionId !== 'number' || !Number.isSafeInteger(sessionId)) {
+        throw new Error('analytics sessionId must be a safe integer number.');
+    }
+    return sessionId;
+}
+function prunePromotedMetadataKeys(metadata) {
+    if (!metadata)
+        return undefined;
+    const entries = Object.entries(metadata).filter(([key]) => !promotedAnalyticsKeys.has(key));
+    if (entries.length === 0)
+        return undefined;
+    return Object.fromEntries(entries);
+}
+function normalizeAnalyticsEvent(event) {
+    return Object.assign(Object.assign({}, event), { sessionId: assertValidSessionId(event.sessionId), metadata: prunePromotedMetadataKeys(event.metadata) });
+}
 function getOrCreateSessionId() {
     var _a, _b, _c, _d;
     if (analyticsBrowserState.sessionId)
@@ -64,14 +98,17 @@ function getOrCreateSessionId() {
     const storage = getStorage('session');
     const existing = key ? storage === null || storage === void 0 ? void 0 : storage.getItem(key) : undefined;
     if (existing) {
-        analyticsBrowserState.sessionId = existing;
-        return existing;
+        const parsed = parseStoredSessionId(existing);
+        if (parsed !== undefined) {
+            analyticsBrowserState.sessionId = parsed;
+            return parsed;
+        }
     }
-    const generated = (_d = (_c = (_b = analyticsBrowserState.config).sessionIdFactory) === null || _c === void 0 ? void 0 : _c.call(_b)) !== null && _d !== void 0 ? _d : createSessionId();
+    const generated = assertValidSessionId((_d = (_c = (_b = analyticsBrowserState.config).sessionIdFactory) === null || _c === void 0 ? void 0 : _c.call(_b)) !== null && _d !== void 0 ? _d : createSessionId());
     analyticsBrowserState.sessionId = generated;
     if (key) {
         try {
-            storage === null || storage === void 0 ? void 0 : storage.setItem(key, generated);
+            storage === null || storage === void 0 ? void 0 : storage.setItem(key, String(generated));
         }
         catch (_e) {
         }
@@ -201,21 +238,21 @@ function getResolvedLocation() {
     return undefined;
 }
 function mergeCollectionEventDefaults(event) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
     const configuredDefaults = (_a = analyticsBrowserState.config.defaultCollectionEvent) !== null && _a !== void 0 ? _a : {};
     const dynamicDefaults = (_d = (_c = (_b = analyticsBrowserState.config).getCollectionDefaults) === null || _c === void 0 ? void 0 : _c.call(_b)) !== null && _d !== void 0 ? _d : {};
     const campaignFields = analyticsBrowserState.config.autoCaptureCampaignParams === false ? {} : getCampaignFields();
     const path = (_e = event.path) !== null && _e !== void 0 ? _e : getCurrentPath();
     const visitorId = (_f = event.visitorId) !== null && _f !== void 0 ? _f : getOrCreateVisitorId();
     const href = (_h = (_g = event.href) !== null && _g !== void 0 ? _g : dynamicDefaults.href) !== null && _h !== void 0 ? _h : configuredDefaults.href;
-    return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, configuredDefaults), dynamicDefaults), campaignFields), getCurrentReferrerFields()), { visitorId, sessionId: getOrCreateSessionId(), deviceType: detectDeviceType(), path, pagePath: (_k = (_j = event.pagePath) !== null && _j !== void 0 ? _j : campaignFields.pagePath) !== null && _k !== void 0 ? _k : path, destinationDomain: (_l = event.destinationDomain) !== null && _l !== void 0 ? _l : getDestinationDomain(href), location: getResolvedLocation(), eventType: 'page_view' }), event), { metadata: Object.assign(Object.assign(Object.assign(Object.assign({}, ((_m = configuredDefaults.metadata) !== null && _m !== void 0 ? _m : {})), ((_o = dynamicDefaults.metadata) !== null && _o !== void 0 ? _o : {})), (visitorId ? { visitorId } : {})), ((_p = event.metadata) !== null && _p !== void 0 ? _p : {})) });
+    return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, configuredDefaults), dynamicDefaults), campaignFields), getCurrentReferrerFields()), { visitorId, sessionId: assertValidSessionId((_j = event.sessionId) !== null && _j !== void 0 ? _j : getOrCreateSessionId()), deviceType: detectDeviceType(), path, pagePath: (_l = (_k = event.pagePath) !== null && _k !== void 0 ? _k : campaignFields.pagePath) !== null && _l !== void 0 ? _l : path, destinationDomain: (_m = event.destinationDomain) !== null && _m !== void 0 ? _m : getDestinationDomain(href), location: getResolvedLocation(), eventType: 'page_view' }), event), { metadata: prunePromotedMetadataKeys(Object.assign(Object.assign(Object.assign({}, ((_o = configuredDefaults.metadata) !== null && _o !== void 0 ? _o : {})), ((_p = dynamicDefaults.metadata) !== null && _p !== void 0 ? _p : {})), ((_q = event.metadata) !== null && _q !== void 0 ? _q : {}))) });
 }
 function mergeTagEventDefaults(event) {
-    var _a, _b, _c, _d, _e, _f, _g, _h;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
     const configuredDefaults = (_a = analyticsBrowserState.config.defaultTagEvent) !== null && _a !== void 0 ? _a : {};
     const dynamicDefaults = (_d = (_c = (_b = analyticsBrowserState.config).getTagDefaults) === null || _c === void 0 ? void 0 : _c.call(_b)) !== null && _d !== void 0 ? _d : {};
     const visitorId = (_e = event.visitorId) !== null && _e !== void 0 ? _e : getOrCreateVisitorId();
-    return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, configuredDefaults), dynamicDefaults), { visitorId, sessionId: getOrCreateSessionId(), deviceType: detectDeviceType(), location: getResolvedLocation(), eventType: 'scan_tag' }), event), { metadata: Object.assign(Object.assign(Object.assign(Object.assign({}, ((_f = configuredDefaults.metadata) !== null && _f !== void 0 ? _f : {})), ((_g = dynamicDefaults.metadata) !== null && _g !== void 0 ? _g : {})), (visitorId ? { visitorId } : {})), ((_h = event.metadata) !== null && _h !== void 0 ? _h : {})) });
+    return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, configuredDefaults), dynamicDefaults), { visitorId, sessionId: assertValidSessionId((_f = event.sessionId) !== null && _f !== void 0 ? _f : getOrCreateSessionId()), deviceType: detectDeviceType(), location: getResolvedLocation(), eventType: 'scan_tag' }), event), { metadata: prunePromotedMetadataKeys(Object.assign(Object.assign(Object.assign({}, ((_g = configuredDefaults.metadata) !== null && _g !== void 0 ? _g : {})), ((_h = dynamicDefaults.metadata) !== null && _h !== void 0 ? _h : {})), ((_j = event.metadata) !== null && _j !== void 0 ? _j : {}))) });
 }
 function isExternalHref(href) {
     if (typeof window === 'undefined')
@@ -267,7 +304,7 @@ export var analytics;
          * Uses `navigator.sendBeacon()` when available, falling back to `fetch(..., { keepalive: true })`.
          */
         function track(event, options) {
-            return queueAnalytics('/public/analytics/collection', event, options);
+            return queueAnalytics('/public/analytics/collection', normalizeAnalyticsEvent(event), options);
         }
         collection.track = track;
     })(collection = analytics.collection || (analytics.collection = {}));
@@ -278,7 +315,7 @@ export var analytics;
          * Uses `navigator.sendBeacon()` when available, falling back to `fetch(..., { keepalive: true })`.
          */
         function track(event, options) {
-            return queueAnalytics('/public/analytics/tag', event, options);
+            return queueAnalytics('/public/analytics/tag', normalizeAnalyticsEvent(event), options);
         }
         tag.track = track;
     })(tag = analytics.tag || (analytics.tag = {}));

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.8.0  |  Generated: 2026-03-12T19:37:47.506Z
+Version: 1.8.2  |  Generated: 2026-03-14T10:21:47.666Z
 
 This is a concise summary of all available API functions and types.
 
@@ -166,6 +166,14 @@ Internal helper that performs a PATCH request to `${baseURL}${path}`, injecting
   options: RequestInit) → `Promise<T>`
 Internal helper that performs a request to `${baseURL}${path}` with custom options, injecting headers for apiKey or bearerToken if present. Returns the parsed JSON as T, or throws an Error.
 
+**requestStream**(path: string,
+  options?: {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+    body?: any
+    headers?: Record<string, string>
+  }) → `Promise<AsyncIterable<T>>`
+Internal helper that performs a streaming request using the shared auth and proxy transport. The response is expected to be `text/event-stream` with JSON payloads in `data:` frames.
+
 **del**(path: string,
   extraHeaders?: Record<string, string>) → `Promise<T>`
 Internal helper that performs a DELETE request to `${baseURL}${path}`, injecting headers for apiKey or bearerToken if present. Returns the parsed JSON as T, or throws an Error.
@@ -938,9 +946,9 @@ interface AnalyticsLocation {
 }
 ```
 
-**AnalyticsStandardMetadataFields** (interface)
+**AnalyticsStandardEventFields** (interface)
 ```typescript
-interface AnalyticsStandardMetadataFields {
+interface AnalyticsStandardEventFields {
   visitorId?: string
   referrer?: string
   referrerHost?: string
@@ -977,13 +985,13 @@ interface AnalyticsTrackOptions {
 ```typescript
 interface AnalyticsBrowserConfig {
   sessionStorageKey?: string
-  sessionIdFactory?: () => string
+  sessionIdFactory?: () => AnalyticsSessionId
   visitorId?: string
   visitorStorage?: AnalyticsStorageMode
   visitorStorageKey?: string
   visitorIdFactory?: () => string
   autoCaptureCampaignParams?: boolean
-  campaignParamMap?: Partial<Record<keyof AnalyticsStandardMetadataFields, string | string[]>>
+  campaignParamMap?: Partial<Record<keyof AnalyticsStandardEventFields, string | string[]>>
   defaultCollectionEvent?: Partial<CollectionAnalyticsEvent>
   defaultTagEvent?: Partial<TagAnalyticsEvent>
   getCollectionDefaults?: () => Partial<CollectionAnalyticsEvent> | undefined
@@ -1048,8 +1056,8 @@ interface AnalyticsFilterRequest {
   batchIds?: string[]
   variantId?: string
   variantIds?: string[]
-  sessionId?: string
-  sessionIds?: string[]
+  sessionId?: AnalyticsSessionId
+  sessionIds?: AnalyticsSessionId[]
   country?: string
   countries?: string[]
   metadata?: Record<string, any>
@@ -1256,6 +1264,8 @@ interface AnalyticsTagsResponse {
 
 **AnalyticsStorageMode** = `'local' | 'session' | false`
 
+**AnalyticsSessionId** = `number`
+
 **EventAnalyticsDimension** = ``
 
 **TagAnalyticsDimension** = ``
@@ -4203,6 +4213,38 @@ interface ProxyResponse {
 }
 ```
 
+**ProxyStreamRequest** (interface)
+```typescript
+interface ProxyStreamRequest {
+  _smartlinksProxyStreamRequest: true;
+  id: string;
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  path: string;
+  body?: any;
+  headers?: Record<string, string>;
+}
+```
+
+**ProxyStreamAbortMessage** (interface)
+```typescript
+interface ProxyStreamAbortMessage {
+  _smartlinksProxyStreamAbort: true;
+  id: string;
+}
+```
+
+**ProxyStreamMessage** (interface)
+```typescript
+interface ProxyStreamMessage {
+  _smartlinksProxyStream: true;
+  id: string;
+  phase: 'open' | 'event' | 'end' | 'error';
+  data?: any;
+  error?: string;
+  status?: number;
+}
+```
+
 **UploadStartMessage** (interface)
 ```typescript
 interface UploadStartMessage {
@@ -5789,7 +5831,7 @@ Fire-and-forget tag analytics event. Uses `navigator.sendBeacon()` when availabl
 **configure**(config: AnalyticsBrowserConfig) → `void`
 Fire-and-forget tag analytics event. Uses `navigator.sendBeacon()` when available, falling back to `fetch(..., { keepalive: true })`.
 
-**getSessionId**() → `string | undefined`
+**getSessionId**() → `AnalyticsSessionId | undefined`
 Fire-and-forget tag analytics event. Uses `navigator.sendBeacon()` when available, falling back to `fetch(..., { keepalive: true })`.
 
 **getVisitorId**() → `string | undefined`

package/dist/docs/analytics-metadata-conventions.md

@@ -1,26 +1,31 @@
 # Analytics Metadata Conventions
 
-Use these as the recommended standard keys for analytics event metadata.
+Use these as the recommended standard analytics keys.
 
-You can put them in `metadata` directly today. The public analytics ingestion endpoints also accept these as top-level convenience fields and mirror them into `metadata` on the backend.
+Some of these are now promoted top-level analytics fields. Others remain good metadata keys for custom dimensions.
 
 ---
 
 ## Recommended Keys
 
-### Traffic and attribution
+### Promoted top-level fields
 
-- `referrer`
+- `visitorId`
 - `referrerHost`
+- `entryType`
+- `pageId`
+- `scanMethod`
+
+These should be sent as top-level analytics fields, not inside `metadata`.
+
+### Metadata-friendly keys
+
+- `referrer`
 - `utmSource`
 - `utmMedium`
 - `utmCampaign`
 - `utmContent`
 - `utmTerm`
-- `entryType` — for example `direct`, `qr`, `nfc`, `social`, `email`, `paid`, or `organic`
-
-### Link-tree and page analytics
-
 - `group`
 - `tag`
 - `campaign`
@@ -31,13 +36,8 @@ You can put them in `metadata` directly today. The public analytics ingestion en
 - `linkTitle`
 - `destinationDomain`
 - `pagePath`
-- `pageId`
 - `qrCodeId`
 
-### Physical scan analytics
-
-- `scanMethod` — for example `nfc` or `qr`
-
 ---
 
 ## Why These Matter
@@ -56,6 +56,7 @@ These keys give teams a shared vocabulary for:
 
 - Treat these as reserved standard keys.
 - Prefer these names before inventing custom alternatives.
+- Send promoted fields at top level.
 - Keep values flat and scalar where possible so they are easier to filter and break down later.
 - Promote a field to a first-class backend column only when it becomes a hot platform-wide dimension.
 
@@ -65,14 +66,17 @@ These keys give teams a shared vocabulary for:
 
 ```typescript
 analytics.collection.track({
-  sessionId: 'sess_123',
+  sessionId: 1234567890,
   eventType: 'click_link',
   collectionId: 'demo-collection',
+  visitorId: 'visitor_123',
   linkId: 'hero-cta',
   href: 'https://example.com/buy',
+  referrerHost: 'instagram.com',
   placement: 'hero',
   campaign: 'summer-launch',
   utmSource: 'email',
+  pageId: 'QR123',
   metadata: {
     pagePath: '/c/demo-collection',
   },

package/dist/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',