@proveanything/smartlinks 1.8.0 → 1.8.1

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.1  |  Generated: 2026-03-14T09:21:59.178Z
 
 This is a concise summary of all available API functions and types.
 
@@ -938,9 +938,9 @@ interface AnalyticsLocation {
 }
 ```
 
-**AnalyticsStandardMetadataFields** (interface)
+**AnalyticsStandardEventFields** (interface)
 ```typescript
-interface AnalyticsStandardMetadataFields {
+interface AnalyticsStandardEventFields {
   visitorId?: string
   referrer?: string
   referrerHost?: string
@@ -977,13 +977,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 +1048,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 +1256,8 @@ interface AnalyticsTagsResponse {
 
 **AnalyticsStorageMode** = `'local' | 'session' | false`
 
+**AnalyticsSessionId** = `number`
+
 **EventAnalyticsDimension** = ``
 
 **TagAnalyticsDimension** = ``
@@ -5789,7 +5791,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',

package/dist/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:

package/dist/types/analytics.d.ts

@@ -11,6 +11,7 @@ export type AnalyticsMetric = 'count' | 'uniqueSessions' | 'uniqueVisitors';
 export type AnalyticsSortOrder = 'asc' | 'desc';
 export type AnalyticsDeviceType = 'mobile' | 'tablet' | 'desktop' | 'unknown';
 export type AnalyticsStorageMode = 'local' | 'session' | false;
+export type AnalyticsSessionId = number;
 export interface AnalyticsLocation {
     country?: string;
     latitude?: number;
@@ -18,7 +19,7 @@ export interface AnalyticsLocation {
     area?: number;
     [key: string]: any;
 }
-export interface AnalyticsStandardMetadataFields {
+export interface AnalyticsStandardEventFields {
     visitorId?: string;
     referrer?: string;
     referrerHost?: string;
@@ -42,8 +43,8 @@ export interface AnalyticsStandardMetadataFields {
     qrCodeId?: string;
     scanMethod?: string;
 }
-export interface CollectionAnalyticsEvent extends AnalyticsStandardMetadataFields {
-    sessionId?: string;
+export interface CollectionAnalyticsEvent extends AnalyticsStandardEventFields {
+    sessionId?: AnalyticsSessionId;
     eventType: AnalyticsEventType;
     collectionId: string;
     productId?: string;
@@ -60,8 +61,8 @@ export interface CollectionAnalyticsEvent extends AnalyticsStandardMetadataField
     location?: AnalyticsLocation;
     metadata?: Record<string, any>;
 }
-export interface TagAnalyticsEvent extends AnalyticsStandardMetadataFields {
-    sessionId?: string;
+export interface TagAnalyticsEvent extends AnalyticsStandardEventFields {
+    sessionId?: AnalyticsSessionId;
     eventType: AnalyticsEventType;
     collectionId: string;
     productId?: string;
@@ -81,13 +82,13 @@ export interface AnalyticsTrackOptions {
 }
 export 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;
@@ -148,8 +149,8 @@ export interface AnalyticsFilterRequest {
     batchIds?: string[];
     variantId?: string;
     variantIds?: string[];
-    sessionId?: string;
-    sessionIds?: string[];
+    sessionId?: AnalyticsSessionId;
+    sessionIds?: AnalyticsSessionId[];
     country?: string;
     countries?: string[];
     metadata?: Record<string, any>;

package/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.1  |  Generated: 2026-03-14T09:21:59.178Z
 
 This is a concise summary of all available API functions and types.
 
@@ -938,9 +938,9 @@ interface AnalyticsLocation {
 }
 ```
 
-**AnalyticsStandardMetadataFields** (interface)
+**AnalyticsStandardEventFields** (interface)
 ```typescript
-interface AnalyticsStandardMetadataFields {
+interface AnalyticsStandardEventFields {
   visitorId?: string
   referrer?: string
   referrerHost?: string
@@ -977,13 +977,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 +1048,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 +1256,8 @@ interface AnalyticsTagsResponse {
 
 **AnalyticsStorageMode** = `'local' | 'session' | false`
 
+**AnalyticsSessionId** = `number`
+
 **EventAnalyticsDimension** = ``
 
 **TagAnalyticsDimension** = ``
@@ -5789,7 +5791,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/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/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/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:

package/package.json

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