@proveanything/smartlinks 1.1.24 → 1.1.26

package/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.1.24  |  Generated: 2026-01-11T11:29:10.460Z
+Version: 1.1.26  |  Generated: 2026-01-17T11:03:13.776Z
 
 This is a concise summary of all available API functions and types.
 
@@ -57,6 +57,9 @@ The Smartlinks SDK is organized into the following namespaces:
 
 Core HTTP functions for API configuration and communication:
 
+**isProxyEnabled**() → `boolean`
+Return whether proxy mode is currently enabled.
+
 **initializeApi**(options: {
   baseURL: string
   apiKey?: string
@@ -78,6 +81,11 @@ Replace or augment globally applied custom headers.
 **setBearerToken**(token: string | undefined) → `void`
 Allows setting the bearerToken at runtime (e.g. after login/logout).
 
+**proxyUploadFormData**(path: string,
+  formData: FormData,
+  onProgress?: (percent: number) → `void`
+Upload a FormData payload via proxy with progress events using chunked postMessage. Parent is expected to implement the counterpart protocol.
+
 **request**(path: string) → `Promise<T>`
 Internal helper that performs a GET request to \`\${baseURL}\${path}\`, injecting headers for apiKey or bearerToken if present. Returns the parsed JSON as T, or throws an Error.
 
@@ -1518,7 +1526,7 @@ interface Proof {
   tokenId: string
   userId: string
   claimable?: boolean
-  transient?: boolean
+  virtual?: boolean
   values: Record<string, any>
 }
 ```
@@ -1528,7 +1536,7 @@ interface Proof {
 interface ProofCreateRequest {
   values: Record<string, any>
   claimable?: boolean
-  transient?: boolean
+  virtual?: boolean
 }
 ```
 
@@ -1809,7 +1817,8 @@ type AccountInfoResponse = {
   };
   sub: string;
   uid: string;
-  user_id: string;
+  userId: string;
+  contactId: string
   whitelabel: {
     [key: string]: any;
   }

package/README.md

@@ -180,6 +180,90 @@ await asset.remove({
 }
 ```
 
+#### Proxy mode and uploads
+
+When `initializeApi({ proxyMode: true })` is active (e.g., SDK runs inside an iframe and the parent performs API calls), the SDK serializes `FormData` for upload into a proxy-safe shape and posts a message to the parent window. The parent proxy handler should detect this payload and reconstruct a native `FormData` before performing the actual HTTP request.
+
+- SDK proxy message body shape for uploads:
+  - `{ _isFormData: true, entries: Array<[name: string, value: string | File]> }`
+  - Each entry’s value is either a string or a `File` object (structured-cloneable).
+- Direct XHR uploads are only used when NOT in proxy mode. In proxy mode, the SDK uses the proxy channel and `postMessage`.
+
+Progress support in proxy mode:
+
+- If you pass `onProgress`, the SDK uses an enhanced upload protocol with chunked messages and progress events.
+- Unified envelope protocol (single message shape):
+  - Iframe → Parent
+    - `{ _smartlinksProxyUpload: true, phase: 'start', id, path, method: 'POST', headers, fields, fileInfo }`
+    - `{ _smartlinksProxyUpload: true, phase: 'chunk', id, seq, chunk: ArrayBuffer }`
+    - `{ _smartlinksProxyUpload: true, phase: 'end', id }`
+  - Parent → Iframe
+    - `{ _smartlinksProxyUpload: true, phase: 'ack', id, seq }` (reply via `event.source.postMessage`)
+    - `{ _smartlinksProxyUpload: true, phase: 'progress', id, percent }` (reply via `event.source.postMessage`)
+    - `{ _smartlinksProxyUpload: true, phase: 'done', id, ok, data? | error? }` (reply via `event.source.postMessage`)
+
+Example parent handler (buffered, simple):
+
+```html
+<script>
+  const uploads = new Map();
+  window.addEventListener('message', async (e) => {
+    const m = e.data;
+    if (!m || m._smartlinksProxyUpload !== true) return;
+    const target = e.source; // reply to the sender iframe
+    const origin = e.origin; // consider validating and passing a strict origin
+    switch (m.phase) {
+      case 'start': {
+        uploads.set(m.id, { chunks: [], fields: m.fields, fileInfo: m.fileInfo, path: m.path, headers: m.headers });
+        break;
+      }
+      case 'chunk': {
+        const u = uploads.get(m.id);
+        if (!u) break;
+        u.chunks.push(new Uint8Array(m.chunk));
+        target && target.postMessage({ _smartlinksProxyUpload: true, phase: 'ack', id: m.id, seq: m.seq }, origin);
+        break;
+      }
+      case 'end': {
+        const u = uploads.get(m.id);
+        if (!u) break;
+        const blob = new Blob(u.chunks, { type: u.fileInfo.type || 'application/octet-stream' });
+        const fd = new FormData();
+        for (const [k, v] of u.fields) fd.append(k, v);
+        fd.append(u.fileInfo.key || 'file', blob, u.fileInfo.name || 'upload.bin');
+
+        const xhr = new XMLHttpRequest();
+        xhr.open('POST', (window.SMARTLINKS_API_BASEURL || '') + u.path);
+        for (const [k, v] of Object.entries(u.headers || {})) xhr.setRequestHeader(k, v);
+        xhr.upload.onprogress = (ev) => {
+          if (ev.lengthComputable) {
+            const pct = Math.round((ev.loaded / ev.total) * 100);
+            target && target.postMessage({ _smartlinksProxyUpload: true, phase: 'progress', id: m.id, percent: pct }, origin);
+          }
+        };
+        xhr.onload = () => {
+          const ok = xhr.status >= 200 && xhr.status < 300;
+          try {
+            const data = JSON.parse(xhr.responseText);
+            target && target.postMessage({ _smartlinksProxyUpload: true, phase: 'done', id: m.id, ok, data, error: ok ? undefined : data?.message }, origin);
+          } catch (err) {
+            target && target.postMessage({ _smartlinksProxyUpload: true, phase: 'done', id: m.id, ok: false, error: 'Invalid server response' }, origin);
+          }
+        };
+        xhr.onerror = () => target && target.postMessage({ _smartlinksProxyUpload: true, phase: 'done', id: m.id, ok: false, error: 'Network error' }, origin);
+        xhr.send(fd);
+        uploads.delete(m.id);
+        break;
+      }
+    }
+  });
+</script>
+```
+
+If you maintain the parent proxy, ensure its handler for `_smartlinksProxyRequest`:
+- Detects `body._isFormData === true` and rebuilds `const fd = new FormData(); for (const [k,v] of body.entries) fd.append(k, v);`
+- Issues the HTTP request with that `FormData` and returns the parsed JSON response back to the iframe.
+
 ### AI helpers
 
 ```ts

package/dist/api/asset.js

@@ -1,4 +1,4 @@
-import { request, post, del, getApiHeaders } from "../http";
+import { request, post, del, getApiHeaders, isProxyEnabled, proxyUploadFormData } from "../http";
 export var asset;
 (function (asset) {
     /**
@@ -41,8 +41,8 @@ export var asset;
             formData.append("name", options.name);
         if (options.metadata)
             formData.append("metadata", JSON.stringify(options.metadata));
-        // If progress callback provided, use XHR for progress events (browser-only)
-        if (options.onProgress && typeof window !== "undefined") {
+        // If progress callback provided and NOT in proxy mode, use XHR for progress events (browser-only)
+        if (options.onProgress && typeof window !== "undefined" && !isProxyEnabled()) {
             const url = (typeof window !== "undefined" && window.SMARTLINKS_API_BASEURL)
                 ? window.SMARTLINKS_API_BASEURL + path
                 : path;
@@ -85,7 +85,17 @@ export var asset;
                 xhr.send(formData);
             });
         }
-        // Otherwise use fetch helper
+        // If in proxy mode and progress requested, use enhanced proxy upload to support progress
+        if (options.onProgress && isProxyEnabled()) {
+            try {
+                return await proxyUploadFormData(path, formData, options.onProgress);
+            }
+            catch (e) {
+                const msg = (e === null || e === void 0 ? void 0 : e.message) || 'Upload failed';
+                throw new AssetUploadError(msg, 'UNKNOWN');
+            }
+        }
+        // Otherwise use fetch helper (in proxy mode this becomes a postMessage with serialized FormData)
         try {
             return await post(path, formData);
         }

package/dist/api/auth.d.ts

@@ -41,7 +41,8 @@ export type AccountInfoResponse = {
     };
     sub: string;
     uid: string;
-    user_id: string;
+    userId: string;
+    contactId: string;
     whitelabel: {
         [key: string]: any;
     };

package/dist/http.d.ts

@@ -5,6 +5,8 @@ type Logger = {
     error?: (...args: any[]) => void;
     log?: (...args: any[]) => void;
 } | ((...args: any[]) => void);
+/** Return whether proxy mode is currently enabled. */
+export declare function isProxyEnabled(): boolean;
 export declare function initializeApi(options: {
     baseURL: string;
     apiKey?: string;
@@ -23,6 +25,11 @@ export declare function setExtraHeaders(headers: Record<string, string>): void;
  * Allows setting the bearerToken at runtime (e.g. after login/logout).
  */
 export declare function setBearerToken(token: string | undefined): void;
+/**
+ * Upload a FormData payload via proxy with progress events using chunked postMessage.
+ * Parent is expected to implement the counterpart protocol.
+ */
+export declare function proxyUploadFormData<T>(path: string, formData: FormData, onProgress?: (percent: number) => void): Promise<T>;
 /**
  * Internal helper that performs a GET request to \`\${baseURL}\${path}\`,
  * injecting headers for apiKey or bearerToken if present.

package/dist/http.js

@@ -19,6 +19,10 @@ function logDebug(...args) {
     if (logger.log)
         return logger.log(...args);
 }
+/** Return whether proxy mode is currently enabled. */
+export function isProxyEnabled() {
+    return proxyMode;
+}
 function maskSensitive(value) {
     if (!value)
         return value;
@@ -138,15 +142,26 @@ function ensureProxyListener() {
     window._smartlinksProxyListener = true;
 }
 // Proxy request implementation
+function serializeFormDataForProxy(fd) {
+    const entries = [];
+    // FormData#forEach iterates values which can be string | Blob (File extends Blob)
+    fd.forEach((value, key) => {
+        entries.push([key, value]);
+    });
+    return { _isFormData: true, entries };
+}
 async function proxyRequest(method, path, body, headers, options) {
     ensureProxyListener();
+    const payloadBody = (typeof FormData !== 'undefined' && body instanceof FormData)
+        ? serializeFormDataForProxy(body)
+        : body;
     const id = generateProxyId();
     const msg = {
         _smartlinksProxyRequest: true,
         id,
         method,
         path,
-        body,
+        body: payloadBody,
         headers,
         options,
     };
@@ -157,6 +172,140 @@ async function proxyRequest(method, path, body, headers, options) {
         // Optionally: add a timeout here to reject if no response
     });
 }
+/**
+ * Upload a FormData payload via proxy with progress events using chunked postMessage.
+ * Parent is expected to implement the counterpart protocol.
+ */
+export async function proxyUploadFormData(path, formData, onProgress) {
+    var _a;
+    if (!proxyMode) {
+        throw new Error('proxyUploadFormData called when proxyMode is disabled');
+    }
+    ensureProxyListener();
+    // Extract file and plain fields
+    let fileKey = null;
+    let file = null;
+    const fields = [];
+    formData.forEach((value, key) => {
+        const isFile = typeof value !== 'string';
+        if (!file && isFile) {
+            fileKey = key;
+            file = value; // File | Blob in browser
+        }
+        else {
+            fields.push([key, String(value)]);
+        }
+    });
+    if (!file || !fileKey) {
+        throw new Error('proxyUploadFormData requires a File/Blob in FormData');
+    }
+    const id = generateProxyId();
+    const headers = getApiHeaders();
+    let resolveDone;
+    let rejectDone;
+    const done = new Promise((resolve, reject) => { resolveDone = resolve; rejectDone = reject; });
+    function handleMessage(event) {
+        const msg = event.data;
+        if (!msg || msg.id !== id)
+            return;
+        // Unified envelope support
+        if (msg._smartlinksProxyUpload === true) {
+            if (msg.phase === 'progress' && typeof msg.percent === 'number') {
+                try {
+                    onProgress && onProgress(Math.max(0, Math.min(100, Math.round(msg.percent))));
+                }
+                catch (_a) { }
+                return;
+            }
+            if (msg.phase === 'done') {
+                window.removeEventListener('message', handleMessage);
+                if (msg.ok) {
+                    resolveDone(msg.data);
+                }
+                else {
+                    rejectDone(new Error(msg.error || 'Upload failed'));
+                }
+                return;
+            }
+            return;
+        }
+        // Backward-compat flags (older docs)
+        if (msg._smartlinksProxyUploadProgress === true && typeof msg.percent === 'number') {
+            try {
+                onProgress && onProgress(Math.max(0, Math.min(100, Math.round(msg.percent))));
+            }
+            catch (_b) { }
+            return;
+        }
+        if (msg._smartlinksProxyUploadDone === true) {
+            window.removeEventListener('message', handleMessage);
+            if (msg.ok) {
+                resolveDone(msg.data);
+            }
+            else {
+                rejectDone(new Error(msg.error || 'Upload failed'));
+            }
+            return;
+        }
+    }
+    window.addEventListener('message', handleMessage);
+    // Start
+    const startMsg = {
+        _smartlinksProxyUpload: true,
+        phase: 'start',
+        id,
+        path,
+        method: 'POST',
+        headers,
+        fields,
+        fileInfo: { name: file.name || fileKey, size: file.size || undefined, type: file.type || undefined, key: fileKey },
+    };
+    window.parent.postMessage(startMsg, '*');
+    // Send chunks with simple ack pacing
+    const CHUNK_SIZE = 256 * 1024; // 256KB
+    const totalSize = (_a = file.size) !== null && _a !== void 0 ? _a : 0;
+    let offset = 0;
+    let seq = 0;
+    while (totalSize && offset < totalSize) {
+        const end = Math.min(offset + CHUNK_SIZE, totalSize);
+        const blob = file.slice(offset, end);
+        // eslint-disable-next-line no-await-in-loop
+        const buf = await blob.arrayBuffer();
+        const chunkMsg = {
+            _smartlinksProxyUpload: true,
+            phase: 'chunk',
+            id,
+            seq,
+            chunk: buf,
+        };
+        window.parent.postMessage(chunkMsg, '*', [buf]);
+        // Wait for ack for this seq
+        // eslint-disable-next-line no-await-in-loop
+        await new Promise((res) => {
+            function onAck(ev) {
+                const m = ev.data;
+                // Unified envelope ack
+                if (m && m._smartlinksProxyUpload === true && m.id === id && m.phase === 'ack' && m.seq === seq) {
+                    window.removeEventListener('message', onAck);
+                    res();
+                    return;
+                }
+                // Backward-compat ack
+                if (m && m._smartlinksProxyUploadAck === true && m.id === id && m.seq === seq) {
+                    window.removeEventListener('message', onAck);
+                    res();
+                }
+            }
+            window.addEventListener('message', onAck);
+        });
+        offset = end;
+        seq += 1;
+    }
+    // End
+    const endMsg = { _smartlinksProxyUpload: true, phase: 'end', id };
+    window.parent.postMessage(endMsg, '*');
+    return done;
+}
 /**
  * Internal helper that performs a GET request to \`\${baseURL}\${path}\`,
  * injecting headers for apiKey or bearerToken if present.

package/dist/types/proof.d.ts

@@ -16,8 +16,8 @@ export interface Proof {
     userId: string;
     /** Is this proof available to be claimed */
     claimable?: boolean;
-    /** Is this proof transient */
-    transient?: boolean;
+    /** Is this proof virtual */
+    virtual?: boolean;
     /** Arbitrary key-value pairs for proof values */
     values: Record<string, any>;
 }
@@ -25,7 +25,7 @@ export type ProofResponse = Proof;
 export interface ProofCreateRequest {
     values: Record<string, any>;
     claimable?: boolean;
-    transient?: boolean;
+    virtual?: boolean;
 }
 export type ProofUpdateRequest = Partial<ProofCreateRequest>;
 export type ProofClaimRequest = Record<string, any>;

package/package.json

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