@proveanything/smartlinks 1.0.54 → 1.0.56

package/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.0.54  |  Generated: 2025-11-27T11:26:08.078Z
+Version: 1.0.56  |  Generated: 2025-12-10T12:13:56.087Z
 
 This is a concise summary of all available API functions and types.
 
@@ -39,6 +39,7 @@ Core HTTP functions for API configuration and communication:
   ngrokSkipBrowserWarning?: boolean
   extraHeaders?: Record<string, string>
   iframeAutoResize?: boolean // default true when in iframe
+  logger?: Logger // optional console-like or function to enable verbose logging
 }) → `void`
 Call this once (e.g. at app startup) to configure baseURL/auth.
 
@@ -319,30 +320,30 @@ interface AuthKitConfig {
 **ClaimCodeRef** (interface)
 ```typescript
 interface ClaimCodeRef {
-  codeId: string
-  claimId: string
+  codeId: string // Identifier of the code (e.g., tag or QR code)
+  claimId: string // Identifier of the claim within the claim set
 }
 ```
 
 **UpdateClaimDataRequest** (interface)
 ```typescript
 interface UpdateClaimDataRequest {
-  data: Record<string, any>
-  codes: ClaimCodeRef[]
+  data: Record<string, any> // Arbitrary key/value pairs for the claim data update
+  codes: ClaimCodeRef[] // Array of code+claim references affected by this update
 }
 ```
 
 **AssignClaimsRequest** (interface)
 ```typescript
 interface AssignClaimsRequest {
-  id: string
-  collectionId: string
-  productId: string
-  batchId?: string
-  start?: number
-  end?: number
-  codeId?: string
-  data?: Record<string, any>
+  id: string // The claim set ID (required)
+  collectionId: string // The collection ID (required)
+  productId: string // The product ID (required)
+  batchId?: string // Optional batch identifier
+  start?: number // Optional start index for bulk assignment
+  end?: number // Optional end index for bulk assignment
+  codeId?: string // Optional single code identifier for single assignment
+  data?: Record<string, any> // Optional key/value pairs to set on the claim
 }
 ```
 
@@ -487,6 +488,65 @@ interface ErrorResponse {
 }
 ```
 
+### nfc
+
+**NfcTagInfo** (interface)
+```typescript
+interface NfcTagInfo {
+  id: string
+  tagId: string
+  claimSetId: string
+  collectionId?: string
+  productId?: string
+  batchId?: string
+  variantId?: string
+  proofId?: string
+  index?: number
+  data?: Record<string, any>
+}
+```
+
+**NfcValidateRequest** (interface)
+```typescript
+interface NfcValidateRequest {
+  claimSetId: string
+  codeId: string
+  mirror?: string
+  userId?: string
+}
+```
+
+**NfcValidateResponse** (interface)
+```typescript
+interface NfcValidateResponse {
+  claimSetId: string
+  codeId: string
+  tagId: string
+  index?: number
+  isAdmin: boolean
+  path?: string
+  collectionId?:  string
+  collection?:  Record<string, any>
+  count: number,
+  previousCount: number
+  data?: Record<string, any>
+  productId?:  string
+  product?:  Record<string, any>
+  batchId?:  string
+  variantId?:  string
+  proofId?:  string
+}
+```
+
+**NfcClaimTagRequest** (interface)
+```typescript
+interface NfcClaimTagRequest {
+  claimSetId: string
+  codeId: string
+  data: Record<string, any>
+}
+```
+
 ### product
 
 **ProductResponse** (interface)
@@ -530,6 +590,8 @@ interface ProofResponse {
   productId: string
   tokenId: string
   userId: string
+  claimable: boolean
+  transient: boolean
   values: Record<string, any>
 }
 ```

package/README.md

@@ -28,6 +28,7 @@ import { initializeApi } from '@proveanything/smartlinks'
 
 initializeApi({
   baseURL: 'https://smartlinks.app/api/v1',            // or 'https://smartlinks.app/api/v1/'
+  // logger: console,                                   // optional: verbose logging of requests/responses and proxy messages
   // apiKey: process.env.SMARTLINKS_API_KEY,            // Node/server only (optional)
   // ngrokSkipBrowserWarning: true,                    // adds 'ngrok-skip-browser-warning: true'
   // extraHeaders: { 'X-Debug': '1' }                  // merged into every request
@@ -204,11 +205,13 @@ initializeApi({
   ngrokSkipBrowserWarning?: boolean // forces header 'ngrok-skip-browser-warning: true'
   extraHeaders?: Record<string,string> // custom headers merged in each request
   iframeAutoResize?: boolean // default true when embedded in an iframe
+  logger?: Function | { debug?: Function; info?: Function; warn?: Function; error?: Function; log?: Function } // optional verbose logging
 })
 
 // Auto-detection: If baseURL contains '.ngrok.io' or '.ngrok-free.dev' the header is added automatically
 // unless you explicitly set ngrokSkipBrowserWarning: false.
 // Auto iframe resize: When in an iframe, resize messages are sent by default unless iframeAutoResize: false.
+// Verbose logging: Pass a logger (e.g. console) to log outbound requests/responses and proxy postMessages.
 ```
 
 When embedding the SDK in an iframe with `proxyMode: true`, you can also use:

package/dist/api/nfc.d.ts

@@ -1,7 +1,18 @@
+import type { NfcValidateRequest, NfcValidateResponse, NfcTagInfo, NfcClaimTagRequest } from "../types/nfc";
 export declare const nfc: {
     /**
      * Claim an NFC tag (public).
      * POST /api/va/public/nfc/claimTag
      */
-    claimTag<T = any>(data: any): Promise<T>;
+    claimTag(data: NfcClaimTagRequest): Promise<NfcTagInfo>;
+    /**
+     * Validate an NFC tag payload (public).
+     * POST /public/nfc/validate
+     */
+    validate(data: NfcValidateRequest): Promise<NfcValidateResponse>;
+    /**
+     * Lookup a tag by its ID (public).
+     * GET /public/nfc/findByTag/:tagId
+     */
+    lookupTag(tagId: string): Promise<NfcTagInfo[]>;
 };

package/dist/api/nfc.js

@@ -1,5 +1,5 @@
 // src/api/nfc.ts
-import { post } from "../http";
+import { post, request } from "../http";
 export const nfc = {
     /**
      * Claim an NFC tag (public).
@@ -8,4 +8,18 @@ export const nfc = {
     async claimTag(data) {
         return post("/public/nfc/claimTag", data);
     },
+    /**
+     * Validate an NFC tag payload (public).
+     * POST /public/nfc/validate
+     */
+    async validate(data) {
+        return post("/public/nfc/validate", data);
+    },
+    /**
+     * Lookup a tag by its ID (public).
+     * GET /public/nfc/findByTag/:tagId
+     */
+    async lookupTag(tagId) {
+        return request(`/public/nfc/findByTag/${encodeURIComponent(tagId)}`);
+    },
 };

package/dist/http.d.ts

@@ -1,3 +1,10 @@
+type Logger = {
+    debug?: (...args: any[]) => void;
+    info?: (...args: any[]) => void;
+    warn?: (...args: any[]) => void;
+    error?: (...args: any[]) => void;
+    log?: (...args: any[]) => void;
+} | ((...args: any[]) => void);
 export declare function initializeApi(options: {
     baseURL: string;
     apiKey?: string;
@@ -6,6 +13,7 @@ export declare function initializeApi(options: {
     ngrokSkipBrowserWarning?: boolean;
     extraHeaders?: Record<string, string>;
     iframeAutoResize?: boolean;
+    logger?: Logger;
 }): void;
 /** Enable/disable automatic "ngrok-skip-browser-warning" header. */
 export declare function setNgrokSkipBrowserWarning(flag: boolean): void;
@@ -60,3 +68,4 @@ export declare function getApiHeaders(): Record<string, string>;
  * @returns The data from the proxy response
  */
 export declare function sendCustomProxyMessage<T = any>(request: string, params: any): Promise<T>;
+export {};

package/dist/http.js

@@ -8,6 +8,57 @@ let bearerToken = undefined;
 let proxyMode = false;
 let ngrokSkipBrowserWarning = false;
 let extraHeadersGlobal = {};
+let logger;
+function logDebug(...args) {
+    if (!logger)
+        return;
+    if (typeof logger === 'function')
+        return logger(...args);
+    if (logger.debug)
+        return logger.debug(...args);
+    if (logger.log)
+        return logger.log(...args);
+}
+function maskSensitive(value) {
+    if (!value)
+        return value;
+    if (value.length <= 8)
+        return '*'.repeat(Math.max(4, value.length));
+    return value.slice(0, 2) + '***' + value.slice(-4);
+}
+function redactHeaders(headers) {
+    const h = Object.assign({}, headers);
+    for (const key of Object.keys(h)) {
+        const k = key.toLowerCase();
+        if (k === 'authorization' || k === 'x-api-key' || k === 'auth' || k === 'proxy-authorization') {
+            h[key] = maskSensitive(h[key]);
+        }
+    }
+    return h;
+}
+function safeBodyPreview(body) {
+    if (body == null)
+        return undefined;
+    if (typeof FormData !== 'undefined' && body instanceof FormData)
+        return '[FormData]';
+    if (typeof body === 'string')
+        return body.slice(0, 1000);
+    if (typeof body === 'object') {
+        const copy = Array.isArray(body) ? [...body] : Object.assign({}, body);
+        const redactKeys = ['password', 'token', 'authorization', 'apiKey', 'bearerToken'];
+        for (const k of Object.keys(copy)) {
+            if (redactKeys.includes(k))
+                copy[k] = '[redacted]';
+        }
+        try {
+            return JSON.parse(JSON.stringify(copy));
+        }
+        catch (_a) {
+            return '[Object]';
+        }
+    }
+    return body;
+}
 /**
  * Call this once (e.g. at app startup) to configure baseURL/auth.
  *
@@ -35,6 +86,15 @@ export function initializeApi(options) {
     if (isIframe() && options.iframeAutoResize !== false) {
         enableAutoIframeResize();
     }
+    logger = options.logger;
+    logDebug('[smartlinks] initializeApi', {
+        baseURL,
+        proxyMode,
+        inferredNgrok,
+        ngrokSkipBrowserWarning,
+        extraHeaders: Object.keys(extraHeadersGlobal),
+        iframeAutoResizeEnabled: isIframe() && options.iframeAutoResize !== false,
+    });
 }
 /** Enable/disable automatic "ngrok-skip-browser-warning" header. */
 export function setNgrokSkipBrowserWarning(flag) {
@@ -63,6 +123,7 @@ function ensureProxyListener() {
         const msg = event.data;
         if (!msg || !msg._smartlinksProxyResponse || !msg.id)
             return;
+        logDebug('[smartlinks] proxy:response', { id: msg.id, ok: !msg.error, keys: Object.keys(msg) });
         const pending = proxyPending[msg.id];
         if (pending) {
             if (msg.error) {
@@ -89,6 +150,7 @@ async function proxyRequest(method, path, body, headers, options) {
         headers,
         options,
     };
+    logDebug('[smartlinks] proxy:postMessage', { id, method, path, headers: headers ? redactHeaders(headers) : undefined, hasBody: !!body });
     return new Promise((resolve, reject) => {
         proxyPending[id] = { resolve, reject };
         window.parent.postMessage(msg, "*");
@@ -102,6 +164,7 @@ async function proxyRequest(method, path, body, headers, options) {
  */
 export async function request(path) {
     if (proxyMode) {
+        logDebug('[smartlinks] GET via proxy', { path });
         return proxyRequest("GET", path);
     }
     if (!baseURL) {
@@ -117,10 +180,12 @@ export async function request(path) {
         headers["ngrok-skip-browser-warning"] = "true";
     for (const [k, v] of Object.entries(extraHeadersGlobal))
         headers[k] = v;
+    logDebug('[smartlinks] GET fetch', { url, headers: redactHeaders(headers) });
     const response = await fetch(url, {
         method: "GET",
         headers,
     });
+    logDebug('[smartlinks] GET response', { url, status: response.status, ok: response.ok });
     if (!response.ok) {
         // Try to parse ErrorResponse; if that fails, throw generic
         try {
@@ -141,6 +206,7 @@ export async function request(path) {
  */
 export async function post(path, body, extraHeaders) {
     if (proxyMode) {
+        logDebug('[smartlinks] POST via proxy', { path, body: safeBodyPreview(body) });
         return proxyRequest("POST", path, body, extraHeaders);
     }
     if (!baseURL) {
@@ -161,11 +227,13 @@ export async function post(path, body, extraHeaders) {
     if (!(body instanceof FormData)) {
         headers["Content-Type"] = "application/json";
     }
+    logDebug('[smartlinks] POST fetch', { url, headers: redactHeaders(headers), body: safeBodyPreview(body) });
     const response = await fetch(url, {
         method: "POST",
         headers,
         body: body instanceof FormData ? body : JSON.stringify(body),
     });
+    logDebug('[smartlinks] POST response', { url, status: response.status, ok: response.ok });
     if (!response.ok) {
         try {
             const errBody = (await response.json());
@@ -185,6 +253,7 @@ export async function post(path, body, extraHeaders) {
  */
 export async function put(path, body, extraHeaders) {
     if (proxyMode) {
+        logDebug('[smartlinks] PUT via proxy', { path, body: safeBodyPreview(body) });
         return proxyRequest("PUT", path, body, extraHeaders);
     }
     if (!baseURL) {
@@ -205,11 +274,13 @@ export async function put(path, body, extraHeaders) {
     if (!(body instanceof FormData)) {
         headers["Content-Type"] = "application/json";
     }
+    logDebug('[smartlinks] PUT fetch', { url, headers: redactHeaders(headers), body: safeBodyPreview(body) });
     const response = await fetch(url, {
         method: "PUT",
         headers,
         body: body instanceof FormData ? body : JSON.stringify(body),
     });
+    logDebug('[smartlinks] PUT response', { url, status: response.status, ok: response.ok });
     if (!response.ok) {
         try {
             const errBody = (await response.json());
@@ -228,6 +299,7 @@ export async function put(path, body, extraHeaders) {
  */
 export async function requestWithOptions(path, options) {
     if (proxyMode) {
+        logDebug('[smartlinks] requestWithOptions via proxy', { path, method: options.method || 'GET' });
         return proxyRequest(options.method || "GET", path, options.body, options.headers, options);
     }
     if (!baseURL) {
@@ -256,7 +328,9 @@ export async function requestWithOptions(path, options) {
     for (const [k, v] of Object.entries(extraHeadersGlobal))
         if (!(k in headers))
             headers[k] = v;
+    logDebug('[smartlinks] requestWithOptions fetch', { url, method: options.method || 'GET', headers: redactHeaders(headers), body: safeBodyPreview(options.body) });
     const response = await fetch(url, Object.assign(Object.assign({}, options), { headers }));
+    logDebug('[smartlinks] requestWithOptions response', { url, status: response.status, ok: response.ok });
     if (!response.ok) {
         try {
             const errBody = (await response.json());
@@ -275,6 +349,7 @@ export async function requestWithOptions(path, options) {
  */
 export async function del(path, extraHeaders) {
     if (proxyMode) {
+        logDebug('[smartlinks] DELETE via proxy', { path });
         return proxyRequest("DELETE", path, undefined, extraHeaders);
     }
     if (!baseURL) {
@@ -291,10 +366,12 @@ export async function del(path, extraHeaders) {
     for (const [k, v] of Object.entries(extraHeadersGlobal))
         if (!(k in headers))
             headers[k] = v;
+    logDebug('[smartlinks] DELETE fetch', { url, headers: redactHeaders(headers) });
     const response = await fetch(url, {
         method: "DELETE",
         headers,
     });
+    logDebug('[smartlinks] DELETE response', { url, status: response.status, ok: response.ok });
     if (!response.ok) {
         try {
             const errBody = (await response.json());
@@ -345,6 +422,7 @@ export async function sendCustomProxyMessage(request, params) {
         request,
         params,
     };
+    logDebug('[smartlinks] proxy:custom postMessage', { id, request, params: safeBodyPreview(params) });
     return new Promise((resolve, reject) => {
         proxyPending[id] = { resolve, reject };
         window.parent.postMessage(msg, "*");

package/dist/types/claimSet.d.ts

@@ -2,9 +2,7 @@
  * Reference to a specific claim attached to a code/tag.
  */
 export interface ClaimCodeRef {
-    /** Identifier of the code (e.g., tag or QR code) */
     codeId: string;
-    /** Identifier of the claim within the claim set */
     claimId: string;
 }
 /**
@@ -12,29 +10,19 @@ export interface ClaimCodeRef {
  * Contains arbitrary key/value pairs and a list of code+claim references to update.
  */
 export interface UpdateClaimDataRequest {
-    /** Arbitrary key/value pairs for the claim data update */
     data: Record<string, any>;
-    /** Array of code+claim references affected by this update */
     codes: ClaimCodeRef[];
 }
 /**
  * Request body for assigning claims to codes or ranges within a collection.
  */
 export interface AssignClaimsRequest {
-    /** The claim set ID (required) */
     id: string;
-    /** The collection ID (required) */
     collectionId: string;
-    /** The product ID (required) */
     productId: string;
-    /** Optional batch identifier */
     batchId?: string;
-    /** Optional start index for bulk assignment */
     start?: number;
-    /** Optional end index for bulk assignment */
     end?: number;
-    /** Optional single code identifier for single assignment */
     codeId?: string;
-    /** Optional key/value pairs to set on the claim */
     data?: Record<string, any>;
 }

package/dist/types/index.d.ts

@@ -9,3 +9,4 @@ export * from "./variant";
 export * from "./claimSet";
 export * from "./auth";
 export * from "./comms";
+export * from "./nfc";

package/dist/types/index.js

@@ -11,3 +11,4 @@ export * from "./variant";
 export * from "./claimSet";
 export * from "./auth";
 export * from "./comms";
+export * from "./nfc";

package/dist/types/nfc.d.ts

@@ -0,0 +1,41 @@
+export interface NfcTagInfo {
+    id: string;
+    tagId: string;
+    claimSetId: string;
+    collectionId?: string;
+    productId?: string;
+    batchId?: string;
+    variantId?: string;
+    proofId?: string;
+    index?: number;
+    data?: Record<string, any>;
+}
+export interface NfcValidateRequest {
+    claimSetId: string;
+    codeId: string;
+    mirror?: string;
+    userId?: string;
+}
+export interface NfcValidateResponse {
+    claimSetId: string;
+    codeId: string;
+    tagId: string;
+    index?: number;
+    isAdmin: boolean;
+    path?: string;
+    collectionId?: string;
+    collection?: Record<string, any>;
+    count: number;
+    previousCount: number;
+    data?: Record<string, any>;
+    productId?: string;
+    product?: Record<string, any>;
+    batchId?: string;
+    variantId?: string;
+    proofId?: string;
+}
+export interface NfcClaimTagRequest {
+    claimSetId: string;
+    codeId: string;
+    data: Record<string, any>;
+}

package/dist/types/nfc.js

@@ -0,0 +1,2 @@
+// src/types/nfc.ts
+export {};

package/dist/types/proof.d.ts

@@ -14,6 +14,10 @@ export interface ProofResponse {
     tokenId: string;
     /** Unique identifier for the user */
     userId: string;
+    /** Is this proof available to be claimed */
+    claimable: boolean;
+    /** Is this proof transient */
+    transient: boolean;
     /** Arbitrary key-value pairs for proof values */
     values: Record<string, any>;
 }

package/package.json

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