@tolinku/web-sdk 0.2.0 → 0.4.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 {
@@ -357,8 +393,41 @@ declare class Deferred {
     constructor(client: HttpClient);
     /** Claim a deferred deep link by referrer token (from Play Store referrer or clipboard) */
     claimByToken(token: string): Promise<DeferredLink | 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.
+     */
+    claimDeferredLink(options: {
+        appspaceId: string;
+        /** Claim again even if an attempt was already recorded. For tests. */
+        force?: boolean;
+    }): Promise<DeferredLink | null>;
+    private alreadyAttempted;
+    private rememberAttempt;
     /** Claim a deferred deep link by device signal matching */
     claimBySignals(options: ClaimBySignalsOptions): Promise<DeferredLink | null>;
+    /**
+     * 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.
+     */
+    private attemptSignals;
 }
 
 declare class Tolinku {

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 {
@@ -357,8 +393,41 @@ declare class Deferred {
     constructor(client: HttpClient);
     /** Claim a deferred deep link by referrer token (from Play Store referrer or clipboard) */
     claimByToken(token: string): Promise<DeferredLink | 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.
+     */
+    claimDeferredLink(options: {
+        appspaceId: string;
+        /** Claim again even if an attempt was already recorded. For tests. */
+        force?: boolean;
+    }): Promise<DeferredLink | null>;
+    private alreadyAttempted;
+    private rememberAttempt;
     /** Claim a deferred deep link by device signal matching */
     claimBySignals(options: ClaimBySignalsOptions): Promise<DeferredLink | null>;
+    /**
+     * 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.
+     */
+    private attemptSignals;
 }
 
 declare class Tolinku {