@proveanything/smartlinks 1.0.51 → 1.0.52

package/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.0.51  |  Generated: 2025-11-23T12:27:09.228Z
+Version: 1.0.52  |  Generated: 2025-11-24T19:18:29.127Z
 
 This is a concise summary of all available API functions and types.
 
@@ -37,6 +37,7 @@ Core HTTP functions for API configuration and communication:
   proxyMode?: boolean
   ngrokSkipBrowserWarning?: boolean
   extraHeaders?: Record<string, string>
+  iframeAutoResize?: boolean // default true when in iframe
 }) → `void`
 Call this once (e.g. at app startup) to configure baseURL/auth.
 

package/README.md

@@ -141,6 +141,58 @@ const collections = await collection.list(false)
 
 For a fuller UI example, see `examples/react-demo.tsx`.
 
+## Iframe Integration
+
+When embedding Smartlinks inside an iframe (set `proxyMode: true` in `initializeApi` if you need parent-proxy API calls), you can also send UI/control messages to the parent window. The SDK provides lightweight helpers in `iframe.ts`:
+
+```ts
+import { enableAutoIframeResize, disableAutoIframeResize, redirectParent, sendParentCustom, isIframe } from '@proveanything/smartlinks'
+
+// Automatically push height changes to parent so it can resize the iframe.
+enableAutoIframeResize({ intervalMs: 150 })
+
+// Later disable if not needed:
+disableAutoIframeResize()
+
+// Redirect parent window to a URL (e.g. after login):
+redirectParent('https://app.example.com/dashboard')
+
+// Send any custom event + payload:
+sendParentCustom('smartlinks:navigate', { url: '/profile' })
+
+if (isIframe()) {
+  console.log('Running inside an iframe')
+}
+```
+
+Parent page can listen for these messages:
+
+```ts
+window.addEventListener('message', (e) => {
+  const msg = e.data
+  if (!msg || !msg._smartlinksIframeMessage) return
+  switch (msg.type) {
+    case 'smartlinks:resize':
+      // adjust iframe height
+      const iframeEl = document.getElementById('smartlinks-frame') as HTMLIFrameElement
+      if (iframeEl) iframeEl.style.height = msg.payload.height + 'px'
+      break
+    case 'smartlinks:redirect':
+      window.location.href = msg.payload.url
+      break
+    case 'smartlinks:navigate':
+      // Custom example
+      console.log('Navigate request:', msg.payload.url)
+      break
+  }
+})
+```
+
+Notes:
+- Auto-resize uses `ResizeObserver` when available, falling back to `MutationObserver` + polling.
+- In non-browser or Node environments these helpers safely no-op.
+- Use `sendParentCustom` for any domain-specific integration events.
+
 ## Configuration reference
 
 ```ts
@@ -151,10 +203,12 @@ initializeApi({
   proxyMode?: boolean   // set true if running inside an iframe and using parent proxy
   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
 })
 
 // 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.
 ```
 
 When embedding the SDK in an iframe with `proxyMode: true`, you can also use:

package/dist/http.d.ts

@@ -1,12 +1,3 @@
-/**
- * Call this once (e.g. at app startup) to configure baseURL/auth.
- *
- * @param options - Configuration options
- * @property {string} options.baseURL - The root URL of the Smartlinks API (e.g. "https://smartlinks.app/api/v1")
- * @property {string} [options.apiKey] - (Optional) API key for X-API-Key header
- * @property {string} [options.bearerToken] - (Optional) Bearer token for AUTHORIZATION header
- * @property {boolean} [options.proxyMode] - (Optional) Tells the API that it is running in an iframe via parent proxy
- */
 export declare function initializeApi(options: {
     baseURL: string;
     apiKey?: string;
@@ -14,6 +5,7 @@ export declare function initializeApi(options: {
     proxyMode?: boolean;
     ngrokSkipBrowserWarning?: boolean;
     extraHeaders?: Record<string, string>;
+    iframeAutoResize?: boolean;
 }): void;
 /** Enable/disable automatic "ngrok-skip-browser-warning" header. */
 export declare function setNgrokSkipBrowserWarning(flag: boolean): void;

package/dist/http.js

@@ -17,6 +17,7 @@ let extraHeadersGlobal = {};
  * @property {string} [options.bearerToken] - (Optional) Bearer token for AUTHORIZATION header
  * @property {boolean} [options.proxyMode] - (Optional) Tells the API that it is running in an iframe via parent proxy
  */
+import { enableAutoIframeResize, isIframe } from './iframe';
 export function initializeApi(options) {
     // Normalize baseURL by removing trailing slashes.
     baseURL = options.baseURL.replace(/\/+$/g, "");
@@ -30,6 +31,10 @@ export function initializeApi(options) {
         ? !!options.ngrokSkipBrowserWarning
         : inferredNgrok;
     extraHeadersGlobal = options.extraHeaders ? Object.assign({}, options.extraHeaders) : {};
+    // Auto-enable iframe resize unless explicitly disabled
+    if (isIframe() && options.iframeAutoResize !== false) {
+        enableAutoIframeResize();
+    }
 }
 /** Enable/disable automatic "ngrok-skip-browser-warning" header. */
 export function setNgrokSkipBrowserWarning(flag) {

package/dist/iframe.d.ts

@@ -0,0 +1,25 @@
+interface IframeResizeOptions {
+    /** Minimum ms between height postMessages (default 100). */
+    intervalMs?: number;
+    /** Post even if height unchanged (default false). */
+    alwaysSend?: boolean;
+    /** Additional payload properties to include with each resize message. */
+    extra?: Record<string, any>;
+    /** Custom message type name (default 'smartlinks:resize'). */
+    messageType?: string;
+}
+/** Redirect parent window to a URL (if in iframe). */
+export declare function redirectParent(url: string): void;
+/** Request parent to adjust iframe height to current content height. */
+export declare function sendHeight(height?: number, extra?: Record<string, any>): void;
+/** Enable automatic height reporting to parent iframe. */
+export declare function enableAutoIframeResize(options?: IframeResizeOptions): void;
+/** Disable automatic height reporting. */
+export declare function disableAutoIframeResize(): void;
+/** Send a custom message to parent (browser-only). */
+export declare function sendParentCustom(type: string, payload: Record<string, any>): void;
+/** Returns true if running inside an iframe (browser). */
+export declare function isIframe(): boolean;
+/** Returns true if ResizeObserver is supported in current environment. */
+export declare function supportsResizeObserver(): boolean;
+export {};

package/dist/iframe.js

@@ -0,0 +1,123 @@
+// iframe.ts
+// Utilities to communicate with parent window when running inside an iframe.
+// These helpers are optional and safe in non-browser / Node environments.
+// They build on the existing proxyMode infrastructure but can also be used standalone.
+let autoResizeTimer;
+let lastHeight = 0;
+let resizeOptions;
+let resizeObserver;
+let mutationObserver;
+function isBrowser() {
+    return typeof window !== 'undefined' && typeof document !== 'undefined';
+}
+function inIframe() {
+    return isBrowser() && window.parent && window.parent !== window;
+}
+function postParentMessage(type, payload) {
+    if (!inIframe())
+        return;
+    try {
+        window.parent.postMessage({ _smartlinksIframeMessage: true, type, payload }, '*');
+    }
+    catch (_a) {
+        // swallow errors silently
+    }
+}
+/** Redirect parent window to a URL (if in iframe). */
+export function redirectParent(url) {
+    postParentMessage('smartlinks:redirect', { url });
+}
+/** Request parent to adjust iframe height to current content height. */
+export function sendHeight(height, extra) {
+    if (!inIframe())
+        return;
+    const h = height !== null && height !== void 0 ? height : document.documentElement.scrollHeight;
+    postParentMessage((resizeOptions === null || resizeOptions === void 0 ? void 0 : resizeOptions.messageType) || 'smartlinks:resize', Object.assign(Object.assign({ height: h }, resizeOptions === null || resizeOptions === void 0 ? void 0 : resizeOptions.extra), extra));
+}
+function measureHeight() {
+    if (!isBrowser())
+        return 0;
+    const doc = document.documentElement;
+    // Use max of several properties for robustness
+    return Math.max(doc.scrollHeight, doc.offsetHeight, doc.clientHeight, document.body ? document.body.scrollHeight : 0, document.body ? document.body.offsetHeight : 0);
+}
+function scheduleManualPolling() {
+    var _a;
+    if (!isBrowser())
+        return;
+    clearInterval(autoResizeTimer);
+    const interval = (_a = resizeOptions === null || resizeOptions === void 0 ? void 0 : resizeOptions.intervalMs) !== null && _a !== void 0 ? _a : 100;
+    autoResizeTimer = window.setInterval(() => {
+        const h = measureHeight();
+        if ((resizeOptions === null || resizeOptions === void 0 ? void 0 : resizeOptions.alwaysSend) || h !== lastHeight) {
+            lastHeight = h;
+            sendHeight(h);
+        }
+    }, interval);
+}
+function setupObservers() {
+    if (!isBrowser())
+        return;
+    // Prefer ResizeObserver for layout changes
+    if (typeof ResizeObserver !== 'undefined') {
+        resizeObserver = new ResizeObserver(() => {
+            const h = measureHeight();
+            if ((resizeOptions === null || resizeOptions === void 0 ? void 0 : resizeOptions.alwaysSend) || h !== lastHeight) {
+                lastHeight = h;
+                sendHeight(h);
+            }
+        });
+        resizeObserver.observe(document.body);
+    }
+    else {
+        // Fallback: MutationObserver for DOM changes
+        mutationObserver = new MutationObserver(() => {
+            const h = measureHeight();
+            if ((resizeOptions === null || resizeOptions === void 0 ? void 0 : resizeOptions.alwaysSend) || h !== lastHeight) {
+                lastHeight = h;
+                sendHeight(h);
+            }
+        });
+        mutationObserver.observe(document.body, { childList: true, subtree: true, attributes: true });
+        // Manual polling as additional safeguard
+        scheduleManualPolling();
+    }
+}
+/** Enable automatic height reporting to parent iframe. */
+export function enableAutoIframeResize(options) {
+    if (!inIframe())
+        return;
+    resizeOptions = options || {};
+    lastHeight = measureHeight();
+    sendHeight(lastHeight);
+    setupObservers();
+    if (!resizeObserver) {
+        // If no ResizeObserver, MutationObserver is active and we also poll
+        scheduleManualPolling();
+    }
+}
+/** Disable automatic height reporting. */
+export function disableAutoIframeResize() {
+    if (resizeObserver)
+        resizeObserver.disconnect();
+    if (mutationObserver)
+        mutationObserver.disconnect();
+    if (isBrowser())
+        clearInterval(autoResizeTimer);
+    resizeObserver = undefined;
+    mutationObserver = undefined;
+    autoResizeTimer = undefined;
+    resizeOptions = undefined;
+}
+/** Send a custom message to parent (browser-only). */
+export function sendParentCustom(type, payload) {
+    postParentMessage(type, payload);
+}
+/** Returns true if running inside an iframe (browser). */
+export function isIframe() {
+    return inIframe();
+}
+/** Returns true if ResizeObserver is supported in current environment. */
+export function supportsResizeObserver() {
+    return typeof ResizeObserver !== 'undefined';
+}

package/package.json

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