feat: Short link resolver (#30)

* feat: resolve short links and integrate in hook

* fix: relax short-link path segment check

* feat: handle short link resolution failures gracefully

Author: piaccho

src/api/resolveShortLink.ts

@@ -0,0 +1,36 @@
+import type { RequiredConfig } from '../types';
+
+const API_URL = 'https://godetour.dev/api/link/resolve-short';
+
+export type ResolveShortLinkResponse = {
+  link: string;
+  route: string;
+  parameters: string;
+};
+
+export const resolveShortLink = async ({
+  API_KEY,
+  appID,
+  url,
+}: Omit<RequiredConfig, 'storage' | 'shouldUseClipboard'> & {
+  url: string;
+}): Promise<ResolveShortLinkResponse | null> => {
+  try {
+    const response = await fetch(API_URL, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${API_KEY}`,
+        'X-App-ID': appID,
+      },
+      body: JSON.stringify({ url }),
+    });
+
+    if (response.status === 404) return null;
+    if (!response.ok) return null;
+
+    return (await response.json()) as ResolveShortLinkResponse;
+  } catch {
+    return null;
+  }
+};

src/hooks/useDetour.ts

@@ -1,6 +1,7 @@
-import { useEffect, useState } from 'react';
+import { useCallback, useEffect, useState } from 'react';
 import { Linking } from 'react-native';
 import { getDeferredLink } from '../api/getDeferredLink';
+import { resolveShortLink } from '../api/resolveShortLink';
 import type { DetourContextType, LinkType, RequiredConfig } from '../types';
 import { checkIsFirstEntrance, markFirstEntrance } from '../utils/appEntrance';
 import {
@@ -25,63 +26,84 @@ export const useDetour = ({
   const [linkType, setLinkType] = useState<LinkType | null>(null);
 
   // Unified helper for parsing any link (API or Native)
-  const processLink = (rawLink: string, typeOverride?: LinkType) => {
-    if (isInfrastructureUrl(rawLink)) {
-      console.log('🔗[Detour] Ignored infrastructure URL:', rawLink);
-      return;
-    }
-
-    const isUrl = rawLink.includes('://') || rawLink.startsWith('//');
-
-    // Early return for standard relative/absolute path strings
-    if (!isUrl) {
-      const path = rawLink.startsWith('/') ? rawLink : `/${rawLink}`;
-      setLinkUrl(path);
-      setRoute(path);
-      setLinkType(typeOverride ?? 'scheme');
-      return;
-    }
-
-    try {
-      const urlObj = new URL(rawLink);
-      setLinkUrl(urlObj);
-
-      // Determine if it's a web URL (requiring app hash stripping)
-      // or a custom deep link scheme
-      const isWebUrl =
-        urlObj.protocol === 'http:' ||
-        urlObj.protocol === 'https:' ||
-        rawLink.startsWith('//');
-
-      const detectedType: LinkType = isWebUrl ? 'verified' : 'scheme';
-      setLinkType(typeOverride ?? detectedType);
-
-      if (isWebUrl) {
-        const pathNameWithoutAppHash = getRestOfPath(urlObj.pathname);
-        setRoute(pathNameWithoutAppHash + (urlObj.search ?? ''));
-      } else {
-        // custom schemes
-        const deepLinkRoute = getRouteFromDeepLink(urlObj);
-        setRoute(deepLinkRoute);
+  const processLink = useCallback(
+    async (rawLink: string, typeOverride?: LinkType) => {
+      if (isInfrastructureUrl(rawLink)) {
+        console.log('🔗[Detour] Ignored infrastructure URL:', rawLink);
+        return;
       }
-    } catch (e) {
-      console.warn(
-        '🔗[Detour] Failed to parse URL object, falling back to string',
-        e
-      );
-      setLinkUrl(rawLink);
-      setRoute(rawLink);
-      setLinkType(typeOverride ?? 'scheme');
-    }
-  };
+
+      const isUrl = rawLink.includes('://') || rawLink.startsWith('//');
+
+      // Early return for standard relative/absolute path strings
+      if (!isUrl) {
+        const path = rawLink.startsWith('/') ? rawLink : `/${rawLink}`;
+        setLinkUrl(path);
+        setRoute(path);
+        return;
+      }
+
+      try {
+        const urlObj = new URL(rawLink);
+        setLinkUrl(urlObj);
+
+        // Determine if it's a web URL (requiring app hash stripping)
+        // or a custom deep link scheme
+        const isWebUrl =
+          urlObj.protocol === 'http:' ||
+          urlObj.protocol === 'https:' ||
+          rawLink.startsWith('//');
+
+        const detectedType: LinkType = isWebUrl ? 'verified' : 'scheme';
+        setLinkType(typeOverride ?? detectedType);
+
+        if (isWebUrl) {
+          const pathSegments = urlObj.pathname.split('/').filter(Boolean);
+          const isSingleSegmentPath =
+            pathSegments.length === 1 &&
+            pathSegments[0] &&
+            pathSegments[0].length > 0;
+
+          // Attempt short link resolution for single-segment paths
+          if (isSingleSegmentPath) {
+            const resolved = await resolveShortLink({
+              API_KEY,
+              appID,
+              url: rawLink,
+            });
+            if (resolved?.link) {
+              await processLink(resolved.link);
+              return;
+            }
+            console.log('🔗[Detour] Not resolved, using original URL');
+          }
+          const pathNameWithoutAppHash = getRestOfPath(urlObj.pathname);
+          setRoute(pathNameWithoutAppHash + (urlObj.search ?? ''));
+        } else {
+          // custom schemes
+          const deepLinkRoute = getRouteFromDeepLink(urlObj);
+          setRoute(deepLinkRoute);
+        }
+      } catch (e) {
+        console.warn(
+          '🔗[Detour] Failed to parse URL object, falling back to string',
+          e
+        );
+        setLinkUrl(rawLink);
+        setRoute(rawLink);
+        setLinkType(typeOverride ?? 'scheme');
+      }
+    },
+    [API_KEY, appID]
+  );
 
   // 1. Listen for Universal Links (Running App)
   useEffect(() => {
     const subscription = Linking.addEventListener('url', ({ url }) => {
       processLink(url);
     });
     return () => subscription.remove();
-  }, []);
+  }, [processLink]);
 
   // 2. Handle Cold Start (Universal vs Deferred)
   useEffect(() => {
@@ -99,7 +121,7 @@ export const useDetour = ({
         const initialUrl = await Linking.getInitialURL();
         if (initialUrl && !isInfrastructureUrl(initialUrl)) {
           await markFirstEntrance(storage);
-          processLink(initialUrl);
+          await processLink(initialUrl);
           return;
         }
 
@@ -116,15 +138,15 @@ export const useDetour = ({
         });
 
         if (apiLink) {
-          processLink(apiLink, 'deferred');
+          await processLink(apiLink, 'deferred');
         }
       } catch (error) {
         console.error('🔗[Detour:ERROR]', error);
       } finally {
         setProcessed(true);
       }
     })();
-  }, [API_KEY, appID, shouldUseClipboard, storage]);
+  }, [API_KEY, appID, processLink, shouldUseClipboard, storage]);
 
   return {
     isLinkProcessed: processed,

src/index.ts

@@ -1,2 +1,3 @@
 export { DetourProvider, useDetourContext } from './DetourContext';
 export type { Config, DetourContextType, DetourStorage } from './types/index';
+export type { ResolveShortLinkResponse } from './api/resolveShortLink';