@proveanything/smartlinks 1.8.0 → 1.8.2

package/dist/iframeResponder.js

@@ -35,6 +35,7 @@ export class IframeResponder {
     constructor(options) {
         this.iframe = null;
         this.uploads = new Map();
+        this.activeStreams = new Map();
         this.isInitialLoad = true;
         this.messageHandler = null;
         this.resizeHandler = null;
@@ -97,6 +98,8 @@ export class IframeResponder {
             this.resizeHandler = null;
         }
         this.uploads.clear();
+        this.activeStreams.forEach(controller => controller.abort());
+        this.activeStreams.clear();
         this.iframe = null;
     }
     // ===========================================================================
@@ -263,6 +266,16 @@ export class IframeResponder {
             await this.handleUpload(data, event);
             return;
         }
+        // Stream proxy aborts
+        if (data._smartlinksProxyStreamAbort) {
+            this.handleProxyStreamAbort(data);
+            return;
+        }
+        // Stream proxy requests
+        if (data._smartlinksProxyStreamRequest) {
+            await this.handleProxyStreamRequest(data, event);
+            return;
+        }
         // API proxy requests
         if (data._smartlinksProxyRequest || data._smartlinksCustomProxyRequest) {
             await this.handleProxyRequest(data, event);
@@ -426,6 +439,145 @@ export class IframeResponder {
         }
         this.sendResponse(event, response);
     }
+    handleProxyStreamAbort(data) {
+        const controller = this.activeStreams.get(data.id);
+        if (!controller) {
+            return;
+        }
+        controller.abort();
+        this.activeStreams.delete(data.id);
+    }
+    async handleProxyStreamRequest(data, event) {
+        var _a, _b, _c;
+        const controller = new AbortController();
+        this.activeStreams.set(data.id, controller);
+        try {
+            const path = data.path.startsWith('/') ? data.path.slice(1) : data.path;
+            const baseUrl = getBaseURL();
+            if (!baseUrl) {
+                throw new Error('SDK not initialized - call initializeApi() first');
+            }
+            const fetchOptions = {
+                method: data.method,
+                headers: data.headers,
+                signal: controller.signal,
+            };
+            if (data.body && data.method !== 'GET') {
+                fetchOptions.body = JSON.stringify(data.body);
+                fetchOptions.headers = Object.assign(Object.assign({}, fetchOptions.headers), { 'Content-Type': 'application/json' });
+            }
+            const response = await fetch(`${baseUrl}/${path}`, fetchOptions);
+            if (!response.ok) {
+                let responseBody = null;
+                try {
+                    responseBody = await response.json();
+                }
+                catch (_d) {
+                    responseBody = null;
+                }
+                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 ${response.status}`;
+                this.sendResponse(event, {
+                    _smartlinksProxyStream: true,
+                    id: data.id,
+                    phase: 'error',
+                    status: response.status,
+                    error: message,
+                });
+                return;
+            }
+            if (!response.body) {
+                throw new Error('Streaming response body is unavailable in this environment');
+            }
+            this.sendResponse(event, {
+                _smartlinksProxyStream: true,
+                id: data.id,
+                phase: 'open',
+            });
+            await this.forwardProxyStream(data.id, response.body, event);
+            this.sendResponse(event, {
+                _smartlinksProxyStream: true,
+                id: data.id,
+                phase: 'end',
+            });
+        }
+        catch (err) {
+            if ((err === null || err === void 0 ? void 0 : err.name) === 'AbortError') {
+                return;
+            }
+            console.error('[IframeResponder] Proxy stream error:', err);
+            this.sendResponse(event, {
+                _smartlinksProxyStream: true,
+                id: data.id,
+                phase: 'error',
+                error: (err === null || err === void 0 ? void 0 : err.message) || 'Unknown streaming error',
+            });
+            (_c = (_b = this.options).onError) === null || _c === void 0 ? void 0 : _c.call(_b, err);
+        }
+        finally {
+            this.activeStreams.delete(data.id);
+        }
+    }
+    async forwardProxyStream(id, stream, event) {
+        const reader = stream.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        let dataLines = [];
+        while (true) {
+            const { done, value } = 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;
+                    }
+                    try {
+                        const parsed = JSON.parse(payload);
+                        this.sendResponse(event, {
+                            _smartlinksProxyStream: true,
+                            id,
+                            phase: 'event',
+                            data: parsed,
+                        });
+                    }
+                    catch (_a) {
+                        // Ignore malformed event chunks
+                    }
+                    continue;
+                }
+                if (line.startsWith('data:')) {
+                    dataLines.push(line.slice(5).trimStart());
+                }
+            }
+        }
+        if (dataLines.length) {
+            const payload = dataLines.join('\n');
+            if (payload !== '[DONE]') {
+                try {
+                    const parsed = JSON.parse(payload);
+                    this.sendResponse(event, {
+                        _smartlinksProxyStream: true,
+                        id,
+                        phase: 'event',
+                        data: parsed,
+                    });
+                }
+                catch (_b) {
+                    // Ignore malformed trailing event chunk
+                }
+            }
+        }
+    }
     getCachedResponse(path) {
         // App data endpoints should NOT be cached - they need fresh data from API
         // These are the new separated app config endpoints

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:
@@ -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/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/dist/types/iframeResponder.d.ts

@@ -68,6 +68,26 @@ export interface ProxyResponse {
     data?: any;
     error?: string;
 }
+export interface ProxyStreamRequest {
+    _smartlinksProxyStreamRequest: true;
+    id: string;
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    body?: any;
+    headers?: Record<string, string>;
+}
+export interface ProxyStreamAbortMessage {
+    _smartlinksProxyStreamAbort: true;
+    id: string;
+}
+export interface ProxyStreamMessage {
+    _smartlinksProxyStream: true;
+    id: string;
+    phase: 'open' | 'event' | 'end' | 'error';
+    data?: any;
+    error?: string;
+    status?: number;
+}
 export interface UploadStartMessage {
     _smartlinksProxyUpload: true;
     phase: 'start';

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.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/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',
   },