feat/check-limits (#53)

* verify click limit before universal link return

* Universal links analytics handler for sdk (#56)

* feat:universal links analytics handler for sdk

* feat:add check flag

* fix:listener condition check

* fix:remove import

* refactor: removed unused function

---------

Co-authored-by: Kamil Sikora <kamil.sikora@swmansion.com>

* Extend universal links with analytics (#58)

* feature:extend with analytics

* refactor:cleanup

---------

Co-authored-by: Bartek Krasoń <45288762+BrtqKr@users.noreply.github.com>

Author: SikoraKam

packages/react-native-detour/src/expo-router/nativeIntent.ts

@@ -1,6 +1,5 @@
-import { OPENED_VIA_UNIVERSAL_LINK } from "../analytics/const/definedEvents";
-import { analyticsEmitter } from "../analytics/utils/analyticsEmitter";
 import { resolveShortLink } from "../links/api/resolveShortLink";
+import { sendUniversalLinkClick } from "../links/api/sendUniversalLinkClick";
 import type { Config } from "../links/types";
 import { getRouteFromDeepLink } from "../links/utils/urlHelpers";
 
@@ -288,12 +287,24 @@ export const createDetourNativeIntentHandler = (
       return path;
     }
 
-    analyticsEmitter.emit({
-      eventName: OPENED_VIA_UNIVERSAL_LINK,
-      data: { url: path },
+    if (!options.config) {
+      return fallbackPath;
+    }
+
+    const clickResult = await sendUniversalLinkClick({
+      apiKey: options.config.apiKey,
+      appID: options.config.appID,
+      url: url.toString(),
     });
 
-    if (!options.config) {
+    if (!clickResult.allowed) {
+      console.error("🔗[Detour:CLICK_LIMIT_ERROR] Native-intent routing blocked:", {
+        path,
+        error: clickResult.error,
+        code: clickResult.code,
+        clicksInPeriod: clickResult.clicksInPeriod,
+        effectiveLimit: clickResult.effectiveLimit,
+      });
       return fallbackPath;
     }
 

packages/react-native-detour/src/links/api/sendUniversalLinkClick.ts

@@ -0,0 +1,116 @@
+import { Platform } from "react-native";
+
+import Constants from "expo-constants";
+import * as Device from "expo-device";
+
+import { SDK_HEADER_VALUE } from "../../version";
+import type { RequiredConfig } from "../types";
+
+const API_URL = "https://godetour.dev/api/link/universal-link-click";
+
+type UniversalLinkClickResponseBody = {
+  allowed?: boolean;
+  error?: string;
+  code?: string;
+  clicksInPeriod?: number;
+  effectiveLimit?: number;
+  remainingClicks?: number;
+  clickId?: string | null;
+};
+
+export type UniversalLinkClickResult =
+  | { allowed: true; clickId: string | null }
+  | {
+      allowed: false;
+      error: string;
+      code?: string;
+      clicksInPeriod?: number;
+      effectiveLimit?: number;
+    };
+
+type ClickPlatform = "ios" | "android" | "unknown";
+
+const resolvePlatform = (): ClickPlatform =>
+  Platform.OS === "ios" || Platform.OS === "android" ? Platform.OS : "unknown";
+
+const extractParams = (url: string): Record<string, string> | undefined => {
+  try {
+    const { searchParams } = new URL(url);
+    const params: Record<string, string> = {};
+    searchParams.forEach((value, key) => {
+      params[key] = value;
+    });
+    return Object.keys(params).length > 0 ? params : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+const buildMetadata = (): Record<string, string> => {
+  const raw: Record<string, string | null | undefined> = {
+    os_version: Device.osVersion,
+    app_version: Constants.nativeAppVersion,
+    device_model: Device.modelName,
+  };
+  return Object.fromEntries(
+    Object.entries(raw).filter((entry): entry is [string, string] => typeof entry[1] === "string"),
+  );
+};
+
+export const sendUniversalLinkClick = async ({
+  apiKey: API_KEY,
+  appID,
+  url,
+}: Pick<RequiredConfig, "apiKey" | "appID"> & {
+  url: string;
+}): Promise<UniversalLinkClickResult> => {
+  try {
+    const params = extractParams(url);
+    const metadata = buildMetadata();
+
+    const response = await fetch(API_URL, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${API_KEY}`,
+        "X-App-ID": appID,
+        "X-SDK": SDK_HEADER_VALUE,
+      },
+      body: JSON.stringify({
+        url,
+        timestamp: Date.now(),
+        platform: resolvePlatform(),
+        ...(params !== undefined && { params }),
+        ...(Object.keys(metadata).length > 0 && { metadata }),
+      }),
+    });
+
+    let body: UniversalLinkClickResponseBody | null = null;
+    try {
+      body = (await response.json()) as UniversalLinkClickResponseBody;
+    } catch {
+      body = null;
+    }
+
+    const isExplicitDeny = body?.allowed === false || response.status === 402;
+    if (isExplicitDeny) {
+      return {
+        allowed: false,
+        error: body?.error ?? "Click limit exceeded",
+        code: body?.code,
+        clicksInPeriod: body?.clicksInPeriod,
+        effectiveLimit: body?.effectiveLimit,
+      };
+    }
+
+    if (!response.ok) {
+      // Fail-open for temporary backend/network issues so apps keep working.
+      return { allowed: true, clickId: null };
+    }
+
+    return { allowed: true, clickId: body?.clickId ?? null };
+  } catch {
+    // Fail-open on transport errors; limit enforcement only happens on explicit deny.
+    return { allowed: true, clickId: null };
+  }
+};

packages/react-native-detour/src/links/hooks/useDetour.ts

@@ -2,10 +2,9 @@ import { useCallback, useEffect, useState } from "react";
 
 import { Linking } from "react-native";
 
-import { OPENED_VIA_UNIVERSAL_LINK } from "../../analytics/const/definedEvents";
-import { analyticsEmitter } from "../../analytics/utils/analyticsEmitter";
 import { getDeferredLink } from "../api/getDeferredLink";
 import { resolveShortLink } from "../api/resolveShortLink";
+import { sendUniversalLinkClick } from "../api/sendUniversalLinkClick";
 import type { DetourContextType, DetourLink, LinkType, RequiredConfig } from "../types";
 import { checkIsFirstEntrance, markFirstEntrance } from "../utils/appEntrance";
 import {
@@ -40,7 +39,15 @@ export const useDetour = ({
   }, []);
 
   const resolveLink = useCallback(
-    async (rawLink: string, typeOverride?: LinkType): Promise<DetourLink> => {
+    async ({
+      rawLink,
+      typeOverride,
+      skipClickLimitCheck,
+    }: {
+      rawLink: string;
+      typeOverride?: LinkType;
+      skipClickLimitCheck?: boolean;
+    }): Promise<DetourLink> => {
       if (isInfrastructureUrl(rawLink)) {
         console.log("🔗[Detour] Ignored infrastructure URL:", rawLink);
         return null;
@@ -76,6 +83,20 @@ export const useDetour = ({
         const detectedType: LinkType = isWeb ? "verified" : "scheme";
         const type = typeOverride ?? detectedType;
 
+        if (!skipClickLimitCheck && isWeb && type !== "deferred") {
+          const clickResult = await sendUniversalLinkClick({ apiKey, appID, url: rawLink });
+          if (!clickResult.allowed) {
+            console.error("🔗[Detour:CLICK_LIMIT_ERROR] Universal/App link blocked:", {
+              url: rawLink,
+              error: clickResult.error,
+              code: clickResult.code,
+              clicksInPeriod: clickResult.clicksInPeriod,
+              effectiveLimit: clickResult.effectiveLimit,
+            });
+            return null;
+          }
+        }
+
         if (isWeb) {
           const pathSegments = urlObj.pathname.split("/").filter(Boolean);
           const isSingleSegmentPath =
@@ -89,7 +110,7 @@ export const useDetour = ({
               url: rawLink,
             });
             if (resolved?.link) {
-              return resolveLink(resolved.link);
+              return resolveLink({ rawLink: resolved.link, skipClickLimitCheck: true });
             }
             console.log("🔗[Detour] Not resolved, using original URL");
           }
@@ -143,14 +164,8 @@ export const useDetour = ({
     }
 
     const subscription = Linking.addEventListener("url", async ({ url }) => {
-      const resolved = await resolveLink(url);
+      const resolved = await resolveLink({ rawLink: url });
       if (resolved) {
-        if (resolved.type !== "scheme") {
-          analyticsEmitter.emit({
-            eventName: OPENED_VIA_UNIVERSAL_LINK,
-            data: { url },
-          });
-        }
         setLink(resolved);
       }
     });
@@ -174,14 +189,8 @@ export const useDetour = ({
           const initialUrl = await Linking.getInitialURL();
           if (initialUrl && !isInfrastructureUrl(initialUrl)) {
             await markFirstEntrance(storage);
-            const resolved = await resolveLink(initialUrl);
+            const resolved = await resolveLink({ rawLink: initialUrl });
             if (resolved) {
-              if (resolved.type !== "scheme") {
-                analyticsEmitter.emit({
-                  eventName: OPENED_VIA_UNIVERSAL_LINK,
-                  data: { url: initialUrl },
-                });
-              }
               setLink(resolved);
             }
             return;
@@ -201,7 +210,7 @@ export const useDetour = ({
         });
 
         if (apiLink) {
-          const resolved = await resolveLink(apiLink, "deferred");
+          const resolved = await resolveLink({ rawLink: apiLink, typeOverride: "deferred" });
           if (resolved) setLink(resolved);
         }
       } catch (error) {