@tolinku/web-sdk 0.2.0 → 0.3.0

package/README.md

@@ -121,12 +121,17 @@ if (link) {
   console.log(link.deep_link_path); // e.g. "/merchant/xyz"
 }
 
-// Claim by device signal matching
+// Claim by device signal matching. Timezone, language, screen size and pixel ratio
+// are detected for you.
 const link = await tolinku.deferred.claimBySignals({
-  appspaceId: 'your_appspace_id',
+  appspaceId: '64f0a1b2c3d4e5f60718',
 });
 ```
 
+`appspaceId` is your Appspace ID, not your subdomain or slug. Copy it from the dashboard
+under **Integrate** or **Settings**. It looks like `64f0a1b2c3d4e5f60718`.
+
+
 ### In-App Messages
 
 Display visually rich, server-configured messages as modal overlays. Create and manage messages from the Tolinku dashboard without shipping app updates.

package/dist/index.d.mts

@@ -98,6 +98,8 @@ interface ClaimBySignalsOptions {
     language?: string;
     screenWidth?: number;
     screenHeight?: number;
+    /** Defaults to `window.devicePixelRatio`. Override only if you report a custom screen size. */
+    devicePixelRatio?: number;
 }
 /** Banner config returned by the API */
 interface BannerConfig {
@@ -118,13 +120,47 @@ interface BannerItem {
     text_color: string;
     cta_text: string | null;
     position: string | null;
+    style: string | null;
+    shadow: string | null;
+    radius: number | null;
+    margin: number | null;
     dismiss_days: number | null;
     priority: number;
 }
-/** Options for showing a banner */
+/** Options for showing a banner. All fields are optional.
+ *  Resolution chain per value: option → server config → theme → built-in default. */
 interface ShowBannerOptions {
     position?: 'top' | 'bottom';
+    style?: 'pinned' | 'floating' | 'stacked';
+    animation?: 'slide' | 'fade' | 'pop' | 'none';
+    theme?: 'light' | 'dark';
     label?: string;
+    delay?: number;
+    /** Stacked-mode only: CSS selector for the element to inject before (top) or after (bottom).
+     *  Falls back to auto-detect when omitted. */
+    anchor?: string;
+    bg?: string;
+    border?: string;
+    radius?: number;
+    margin?: number;
+    shadow?: 'none' | 'sm' | 'md' | 'lg';
+    titleColor?: string;
+    titleSize?: number;
+    titleWeight?: 400 | 500 | 600 | 700;
+    bodyColor?: string;
+    bodySize?: number;
+    bodyWeight?: 400 | 500 | 600 | 700;
+    ctaBg?: string;
+    ctaColor?: string;
+    ctaSize?: number;
+    ctaWeight?: 400 | 500 | 600 | 700;
+    ctaRadius?: number;
+    iconSize?: number;
+    iconRadius?: number;
+    hideIcon?: boolean;
+    hideClose?: boolean;
+    hideBody?: boolean;
+    customClass?: string;
 }
 /** In-app message from the API */
 interface Message {

package/dist/index.d.ts

@@ -98,6 +98,8 @@ interface ClaimBySignalsOptions {
     language?: string;
     screenWidth?: number;
     screenHeight?: number;
+    /** Defaults to `window.devicePixelRatio`. Override only if you report a custom screen size. */
+    devicePixelRatio?: number;
 }
 /** Banner config returned by the API */
 interface BannerConfig {
@@ -118,13 +120,47 @@ interface BannerItem {
     text_color: string;
     cta_text: string | null;
     position: string | null;
+    style: string | null;
+    shadow: string | null;
+    radius: number | null;
+    margin: number | null;
     dismiss_days: number | null;
     priority: number;
 }
-/** Options for showing a banner */
+/** Options for showing a banner. All fields are optional.
+ *  Resolution chain per value: option → server config → theme → built-in default. */
 interface ShowBannerOptions {
     position?: 'top' | 'bottom';
+    style?: 'pinned' | 'floating' | 'stacked';
+    animation?: 'slide' | 'fade' | 'pop' | 'none';
+    theme?: 'light' | 'dark';
     label?: string;
+    delay?: number;
+    /** Stacked-mode only: CSS selector for the element to inject before (top) or after (bottom).
+     *  Falls back to auto-detect when omitted. */
+    anchor?: string;
+    bg?: string;
+    border?: string;
+    radius?: number;
+    margin?: number;
+    shadow?: 'none' | 'sm' | 'md' | 'lg';
+    titleColor?: string;
+    titleSize?: number;
+    titleWeight?: 400 | 500 | 600 | 700;
+    bodyColor?: string;
+    bodySize?: number;
+    bodyWeight?: 400 | 500 | 600 | 700;
+    ctaBg?: string;
+    ctaColor?: string;
+    ctaSize?: number;
+    ctaWeight?: 400 | 500 | 600 | 700;
+    ctaRadius?: number;
+    iconSize?: number;
+    iconRadius?: number;
+    hideIcon?: boolean;
+    hideClose?: boolean;
+    hideBody?: boolean;
+    customClass?: string;
 }
 /** In-app message from the API */
 interface Message {

package/dist/index.js

@@ -548,9 +548,24 @@ var Deferred = class {
         timezone: options.timezone || Intl.DateTimeFormat().resolvedOptions().timeZone,
         language: options.language || navigator.language,
         screen_width: options.screenWidth || window.screen.width,
-        screen_height: options.screenHeight || window.screen.height
+        screen_height: options.screenHeight || window.screen.height,
+        // Separates devices reporting identical logical dimensions.
+        device_pixel_ratio: options.devicePixelRatio || window.devicePixelRatio || 1
       });
     } catch (err) {
+      const status = err?.statusCode ?? err?.status;
+      if (status === 404) {
+        return null;
+      }
+      if (status === 403) {
+        console.warn(
+          "[Tolinku] Failed to claim deferred link by signals: HTTP 403.",
+          "Check that appspaceId is your Appspace ID (copy it from the dashboard",
+          "under Settings), not your subdomain or slug.",
+          err
+        );
+        return null;
+      }
       console.warn("[Tolinku] Failed to claim deferred link by signals:", err);
       return null;
     }
@@ -640,11 +655,56 @@ function sanitizeCssColor(value) {
 }
 
 // src/banners.ts
+var themes = {
+  light: {
+    bg: "#ffffff",
+    border: "",
+    shadow: "sm",
+    title: { color: "#000000", size: 14, weight: 600 },
+    body: { color: "#000000", size: 12, weight: 400 },
+    cta: { size: 13, weight: 600, radius: 100 },
+    icon: { size: 40, radius: 10 }
+  },
+  dark: {
+    bg: "#1B1B1B",
+    border: "",
+    shadow: "sm",
+    title: { color: "#ffffff", size: 14, weight: 600 },
+    body: { color: "#ffffff", size: 12, weight: 400 },
+    cta: { size: 13, weight: 600, radius: 100 },
+    icon: { size: 40, radius: 10 }
+  }
+};
+var SHADOW_VALUES = {
+  none: "none",
+  sm: "0 2px 8px rgba(0,0,0,0.15)",
+  md: "0 6px 20px rgba(0,0,0,0.18)",
+  lg: "0 12px 36px rgba(0,0,0,0.22)"
+};
+function clampInt(val, min, max) {
+  if (val === void 0 || val === null || isNaN(val)) return null;
+  return Math.max(min, Math.min(max, Math.floor(val)));
+}
+function sanitizeClass(val) {
+  if (!val || typeof val !== "string") return "";
+  return val.replace(/[^a-zA-Z0-9_\-\s]/g, "").slice(0, 100).trim();
+}
+function isSafeUrl(url) {
+  try {
+    const parsed = new URL(url, window.location.href);
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
 var Banners = class {
   constructor(client) {
     this.client = client;
     this.container = null;
     this.styleEl = null;
+    this.currentAnimation = "slide";
+    this.currentStyle = "pinned";
+    this.currentPosition = "top";
   }
   /** Fetch banner config and show the highest-priority banner */
   async show(options = {}, userId) {
@@ -662,94 +722,200 @@ var Banners = class {
       }
     }
     if (!banner) return;
-    this.render(config, banner, options);
+    const delay = clampInt(options.delay, 0, 6e4);
+    if (delay && delay > 0) {
+      setTimeout(() => this.render(config, banner, options), delay);
+    } else {
+      this.render(config, banner, options);
+    }
   }
-  /** Remove the banner from the DOM */
+  /** Remove the banner from the DOM, respecting the active animation */
   dismiss() {
-    if (this.container) {
-      this.container.classList.remove("tolk-visible");
-      const pos = this.container.dataset.position || "top";
-      document.body.style.removeProperty(pos === "top" ? "padding-top" : "padding-bottom");
-      setTimeout(() => {
-        this.container?.remove();
-        this.styleEl?.remove();
+    if (!this.container) return;
+    const container = this.container;
+    const styleEl = this.styleEl;
+    container.classList.remove("tolk-visible");
+    if (this.currentStyle === "pinned") {
+      document.body.style.removeProperty(this.currentPosition === "top" ? "padding-top" : "padding-bottom");
+    }
+    const cleanup = () => {
+      container.remove();
+      styleEl?.remove();
+      if (this.container === container) {
         this.container = null;
         this.styleEl = null;
-      }, 400);
+      }
+    };
+    if (this.currentAnimation === "none") {
+      cleanup();
+    } else {
+      setTimeout(cleanup, 400);
     }
   }
   render(config, banner, options) {
     if (this.container) {
       this.container.remove();
       this.styleEl?.remove();
+      if (this.currentStyle === "pinned") {
+        document.body.style.removeProperty(this.currentPosition === "top" ? "padding-top" : "padding-bottom");
+      }
+    }
+    const themeName = options.theme && themes[options.theme] ? options.theme : "light";
+    const theme = themes[themeName];
+    let position = "top";
+    if (options.position === "top" || options.position === "bottom") position = options.position;
+    else if (banner.position === "top" || banner.position === "bottom") position = banner.position;
+    let resolvedStyle = "pinned";
+    if (options.style === "pinned" || options.style === "floating" || options.style === "stacked") {
+      resolvedStyle = options.style;
+    } else if (banner.style === "pinned" || banner.style === "floating" || banner.style === "stacked") {
+      resolvedStyle = banner.style;
     }
-    const position = options.position || banner.position || "top";
-    const bgColor = sanitizeCssColor(banner.background_color) || "#ffffff";
-    const textColor = sanitizeCssColor(banner.text_color) || "#000000";
+    const floating = resolvedStyle === "floating";
+    const stacked = resolvedStyle === "stacked";
+    let animation = options.animation || "slide";
+    if (animation === "pop" && !floating && !stacked) animation = "slide";
+    this.currentPosition = position;
+    this.currentStyle = resolvedStyle;
+    this.currentAnimation = animation;
+    const serverBg = sanitizeCssColor(banner.background_color);
+    const serverText = sanitizeCssColor(banner.text_color);
+    const optBg = sanitizeCssColor(options.bg);
+    const optBorder = sanitizeCssColor(options.border);
+    const optTitleColor = sanitizeCssColor(options.titleColor);
+    const optBodyColor = sanitizeCssColor(options.bodyColor);
+    const optCtaBg = sanitizeCssColor(options.ctaBg);
+    const optCtaColor = sanitizeCssColor(options.ctaColor);
+    const bg = optBg || serverBg || theme.bg;
+    const border = optBorder || theme.border;
+    const titleColor = optTitleColor || serverText || theme.title.color;
+    const bodyColor = optBodyColor || serverText || theme.body.color;
+    const ctaBg = optCtaBg || theme.cta.bg || titleColor;
+    const ctaColor = optCtaColor || theme.cta.color || bg;
+    const titleSize = clampInt(options.titleSize, 10, 24) ?? theme.title.size;
+    const titleWeight = options.titleWeight ?? theme.title.weight;
+    const bodySize = clampInt(options.bodySize, 10, 20) ?? theme.body.size;
+    const bodyWeight = options.bodyWeight ?? theme.body.weight;
+    const ctaSize = clampInt(options.ctaSize, 10, 18) ?? theme.cta.size;
+    const ctaWeight = options.ctaWeight ?? theme.cta.weight;
+    const ctaRadius = clampInt(options.ctaRadius, 0, 100) ?? theme.cta.radius;
+    const iconSize = clampInt(options.iconSize, 24, 64) ?? theme.icon.size;
+    const iconRadius = clampInt(options.iconRadius, 0, 32) ?? theme.icon.radius;
+    const optRadius = clampInt(options.radius, 0, 24);
+    const serverRadius = typeof banner.radius === "number" && banner.radius >= 0 && banner.radius <= 24 ? banner.radius : null;
+    const optMargin = clampInt(options.margin, 0, 24);
+    const serverMargin = typeof banner.margin === "number" && banner.margin >= 0 && banner.margin <= 24 ? banner.margin : null;
+    const bannerRadius = floating ? optRadius ?? serverRadius ?? 12 : 0;
+    const bannerMargin = floating ? optMargin ?? serverMargin ?? 12 : 0;
+    const shadowKey = options.shadow && SHADOW_VALUES[options.shadow] ? options.shadow : banner.shadow && SHADOW_VALUES[banner.shadow] ? banner.shadow : theme.shadow;
+    const shadow = SHADOW_VALUES[shadowKey];
+    const hideIcon = !!options.hideIcon;
+    const hideClose = !!options.hideClose;
+    const hideBody = !!options.hideBody;
+    const customClass = sanitizeClass(options.customClass);
     const ctaText = banner.cta_text || "Open";
-    const baseUrl = this.client.baseUrl;
-    const installUrl = banner.action_url || baseUrl + (config.install_url || "/install");
+    const installUrl = banner.action_url || this.client.baseUrl + (config.install_url || "/install");
     const safeTop = position === "top" ? "padding-top: env(safe-area-inset-top, 0px);" : "";
     const safeBottom = position === "bottom" ? "padding-bottom: env(safe-area-inset-bottom, 0px);" : "";
+    let containerPosition;
+    let containerInsets;
+    if (stacked) {
+      containerPosition = "position: sticky;";
+      containerInsets = `${position}: 0;`;
+    } else if (floating) {
+      containerPosition = "position: fixed;";
+      containerInsets = `left: ${bannerMargin}px; right: ${bannerMargin}px; ${position}: ${bannerMargin}px;`;
+    } else {
+      containerPosition = "position: fixed;";
+      containerInsets = `left: 0; right: 0; ${position}: 0;`;
+    }
+    const hideOffset = bannerMargin + 60;
+    const slideHide = position === "top" ? `translateY(calc(-100% - ${hideOffset}px))` : `translateY(calc(100% + ${hideOffset}px))`;
+    let hiddenCss = "";
+    let visibleCss = "";
+    let transitionCss = "";
+    if (animation === "slide") {
+      hiddenCss = `transform: ${slideHide};`;
+      visibleCss = "transform: translateY(0);";
+      transitionCss = "transition: transform 0.35s ease;";
+    } else if (animation === "fade") {
+      hiddenCss = "opacity: 0;";
+      visibleCss = "opacity: 1;";
+      transitionCss = "transition: opacity 0.3s ease;";
+    } else if (animation === "pop") {
+      hiddenCss = "opacity: 0; transform: scale(0.92);";
+      visibleCss = "opacity: 1; transform: scale(1);";
+      transitionCss = "transition: transform 0.3s cubic-bezier(0.34, 1.56, 0.64, 1), opacity 0.25s ease;";
+    }
     const container = document.createElement("div");
     container.id = "tolinku-banner";
     container.setAttribute("role", "banner");
     container.setAttribute("aria-live", "polite");
     container.dataset.position = position;
+    if (customClass) container.className = customClass;
+    const borderCss = border ? `border: 1px solid ${border};` : "";
+    const radiusCss = bannerRadius > 0 ? `border-radius: ${bannerRadius}px;` : "";
     const style = document.createElement("style");
     style.textContent = `
       #tolinku-banner {
-        position: fixed;
-        ${position}: 0;
-        left: 0; right: 0;
+        ${containerPosition}
+        ${containerInsets}
         z-index: 999999;
         font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
-        transform: translateY(${position === "top" ? "-100%" : "100%"});
-        transition: transform 0.35s ease;
+        ${hiddenCss}
+        ${transitionCss}
         ${safeTop}${safeBottom}
       }
-      #tolinku-banner.tolk-visible { transform: translateY(0); }
+      #tolinku-banner.tolk-visible { ${visibleCss} }
       #tolinku-banner .tolk-inner {
         display: flex; align-items: center; gap: 10px;
         padding: 10px 14px;
-        background: ${bgColor}; color: ${textColor};
-        box-shadow: 0 2px 8px rgba(0,0,0,0.15);
+        background: ${bg};
+        ${borderCss}
+        ${radiusCss}
+        box-shadow: ${shadow};
       }
       #tolinku-banner .tolk-close {
         background: none; border: none; font-size: 20px; line-height: 1;
-        cursor: pointer; color: ${textColor}; opacity: 0.6; padding: 0 4px; flex-shrink: 0;
+        cursor: pointer; color: ${titleColor}; opacity: 0.6; padding: 0 4px; flex-shrink: 0;
       }
       #tolinku-banner .tolk-close:hover { opacity: 1; }
       #tolinku-banner .tolk-icon {
-        width: 40px; height: 40px; border-radius: 10px; flex-shrink: 0; object-fit: cover;
+        width: ${iconSize}px; height: ${iconSize}px; border-radius: ${iconRadius}px;
+        flex-shrink: 0; object-fit: cover;
       }
       #tolinku-banner .tolk-text { flex: 1; min-width: 0; }
       #tolinku-banner .tolk-title {
-        font-size: 14px; font-weight: 600; margin: 0;
+        font-size: ${titleSize}px; font-weight: ${titleWeight}; line-height: 1.3;
+        color: ${titleColor}; margin: 0;
         white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
       }
       #tolinku-banner .tolk-body {
-        font-size: 12px; margin: 0; opacity: 0.75;
+        font-size: ${bodySize}px; font-weight: ${bodyWeight}; line-height: 1.3;
+        color: ${bodyColor}; margin: 0; opacity: 0.75;
         white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
       }
       #tolinku-banner .tolk-cta {
-        display: inline-block; padding: 6px 16px; border-radius: 100px;
-        font-size: 13px; font-weight: 600; text-decoration: none;
-        background: ${textColor}; color: ${bgColor}; flex-shrink: 0; text-align: center;
+        display: inline-block; padding: 0.5em 1.2em; border-radius: ${ctaRadius}px;
+        font-size: ${ctaSize}px; font-weight: ${ctaWeight}; line-height: 1.2;
+        text-decoration: none; background: ${ctaBg}; color: ${ctaColor};
+        flex-shrink: 0; text-align: center;
       }
     `;
     const inner = document.createElement("div");
     inner.className = "tolk-inner";
-    const closeBtn = document.createElement("button");
-    closeBtn.className = "tolk-close";
-    closeBtn.setAttribute("aria-label", "Dismiss banner");
-    closeBtn.textContent = "\xD7";
-    closeBtn.addEventListener("click", () => {
-      saveBannerDismissal(banner.id);
-      this.dismiss();
-    });
-    inner.appendChild(closeBtn);
-    if (config.app_icon && isSafeUrl(config.app_icon)) {
+    if (!hideClose) {
+      const closeBtn = document.createElement("button");
+      closeBtn.className = "tolk-close";
+      closeBtn.setAttribute("aria-label", "Dismiss banner");
+      closeBtn.textContent = "\xD7";
+      closeBtn.addEventListener("click", () => {
+        saveBannerDismissal(banner.id);
+        this.dismiss();
+      });
+      inner.appendChild(closeBtn);
+    }
+    if (!hideIcon && config.app_icon && isSafeUrl(config.app_icon)) {
       const icon = document.createElement("img");
       icon.className = "tolk-icon";
       icon.src = config.app_icon;
@@ -762,7 +928,7 @@ var Banners = class {
     titleEl.className = "tolk-title";
     titleEl.textContent = banner.title || config.app_name || "Get the App";
     textWrap.appendChild(titleEl);
-    if (banner.body) {
+    if (!hideBody && banner.body) {
       const bodyEl = document.createElement("p");
       bodyEl.className = "tolk-body";
       bodyEl.textContent = banner.body;
@@ -776,29 +942,57 @@ var Banners = class {
     inner.appendChild(cta);
     container.appendChild(inner);
     document.head.appendChild(style);
-    document.body.appendChild(container);
+    if (stacked) {
+      const anchor = findStackedAnchor(position, options.anchor);
+      if (anchor && anchor.parentNode) {
+        if (position === "top") {
+          anchor.parentNode.insertBefore(container, anchor);
+        } else if (anchor.nextSibling) {
+          anchor.parentNode.insertBefore(container, anchor.nextSibling);
+        } else {
+          anchor.parentNode.appendChild(container);
+        }
+      } else if (document.body) {
+        if (position === "top") {
+          document.body.insertBefore(container, document.body.firstChild);
+        } else {
+          document.body.appendChild(container);
+        }
+      }
+    } else {
+      document.body.appendChild(container);
+    }
     this.container = container;
     this.styleEl = style;
     requestAnimationFrame(() => {
       requestAnimationFrame(() => {
         container.classList.add("tolk-visible");
-        const bannerHeight = container.offsetHeight + "px";
-        if (position === "top") {
-          document.body.style.paddingTop = bannerHeight;
-        } else {
-          document.body.style.paddingBottom = bannerHeight;
+        if (!floating && !stacked) {
+          const bannerHeight = container.offsetHeight + "px";
+          if (position === "top") {
+            document.body.style.paddingTop = bannerHeight;
+          } else {
+            document.body.style.paddingBottom = bannerHeight;
+          }
         }
       });
     });
   }
 };
-function isSafeUrl(url) {
-  try {
-    const parsed = new URL(url, window.location.href);
-    return parsed.protocol === "http:" || parsed.protocol === "https:";
-  } catch {
-    return false;
+function findStackedAnchor(position, explicit) {
+  if (explicit) {
+    try {
+      const el = document.querySelector(explicit);
+      if (el) return el;
+    } catch {
+    }
+  }
+  const selectors = position === "top" ? ["header", '[role="banner"]', "nav", ".header", "#header", ".navbar"] : ["footer", '[role="contentinfo"]', ".footer", "#footer"];
+  for (const s of selectors) {
+    const el = document.body?.querySelector(s);
+    if (el) return el;
   }
+  return null;
 }
 
 // src/messages.ts