@tolinku/web-sdk 0.2.0 → 0.4.0

package/dist/index.mjs

@@ -167,7 +167,11 @@ var HttpClient = class {
   }
   headers() {
     return {
-      "X-API-Key": this.apiKey
+      "X-API-Key": this.apiKey,
+      // Browsers default to "Accept: */*", which a server content-negotiating an
+      // error page reads as "HTML is fine". Saying so explicitly keeps an error
+      // parseable instead of arriving as a rendered page.
+      "Accept": "application/json"
     };
   }
 };
@@ -525,6 +529,7 @@ var Referrals = class {
 };
 
 // src/deferred.ts
+var CLAIMED_KEY = "tolinku_deferred_claimed";
 var Deferred = class {
   constructor(client) {
     this.client = client;
@@ -538,19 +543,85 @@ var Deferred = class {
       return null;
     }
   }
+  /**
+   * Recover the link that led here, once.
+   *
+   * There is no Play Install Referrer on the web, so this is signal matching
+   * with the bookkeeping that makes calling it safe. That bookkeeping is the
+   * point: a claim is consumed the first time it succeeds, so an app calling
+   * claimBySignals on every page load asks again after the answer is already
+   * spent, and every one of those asks is recorded as a miss. The match rate on
+   * the dashboard then falls towards zero while the integration is working
+   * correctly, which is a hard thing to diagnose from the outside.
+   *
+   * Call it once on first run. Calling it again is free after the first.
+   *
+   * Named to match the Android, React Native and Flutter SDKs, where the same
+   * call also tries the install referrer before falling back to here.
+   */
+  async claimDeferredLink(options) {
+    if (!options.appspaceId || !options.appspaceId.trim()) {
+      throw new Error("Tolinku: appspaceId is required and must not be blank for claimDeferredLink.");
+    }
+    if (!options.force && this.alreadyAttempted()) return null;
+    const { link, settled } = await this.attemptSignals({ appspaceId: options.appspaceId });
+    if (settled) this.rememberAttempt();
+    return link;
+  }
+  alreadyAttempted() {
+    try {
+      return window.localStorage.getItem(CLAIMED_KEY) !== null;
+    } catch {
+      return false;
+    }
+  }
+  rememberAttempt() {
+    try {
+      window.localStorage.setItem(CLAIMED_KEY, (/* @__PURE__ */ new Date()).toISOString());
+    } catch {
+    }
+  }
   /** Claim a deferred deep link by device signal matching */
   async claimBySignals(options) {
+    return (await this.attemptSignals(options)).link;
+  }
+  /**
+   * The signal claim, with whether the server actually answered.
+   *
+   * `settled` separates "nothing is waiting for this device", which no amount
+   * of asking will change, from "the request never got there". Both surface as
+   * null to callers of claimBySignals, but claimDeferredLink has to tell them
+   * apart: recording an attempt that never reached the server would spend an
+   * install's one chance at attribution on a dropped connection.
+   */
+  async attemptSignals(options) {
     try {
-      return await this.client.postPublic("/v1/api/deferred/claim-by-signals", {
+      const link = await this.client.postPublic("/v1/api/deferred/claim-by-signals", {
         appspace_id: options.appspaceId,
         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
       });
+      return { link, settled: true };
     } catch (err) {
+      const status = err?.statusCode ?? err?.status;
+      if (status === 404) {
+        return { link: null, settled: true };
+      }
+      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 { link: null, settled: false };
+      }
       console.warn("[Tolinku] Failed to claim deferred link by signals:", err);
-      return null;
+      return { link: null, settled: false };
     }
   }
 };
@@ -638,11 +709,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) {
@@ -660,94 +776,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 position = options.position || banner.position || "top";
-    const bgColor = sanitizeCssColor(banner.background_color) || "#ffffff";
-    const textColor = sanitizeCssColor(banner.text_color) || "#000000";
+    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 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;
@@ -760,7 +982,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;
@@ -774,29 +996,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