Add version skew detection and refresh prompt

Why:
When deploying new code to production, users with stale cached client
code may experience API compatibility issues, unexpected behavior, or
see bugs that have been fixed. This implements automatic detection of
client/server version mismatches and prompts users to refresh.

The implementation follows the pattern from
https://makerkit.dev/blog/tutorials/force-update-nextjs and is
adapted to our codebase structure using existing patterns:
- API route: apps/next/pages/api/version.ts returns Git SHA
- Hook: packages/app/utils/useVersionUpdater.ts polls for changes
- Component: packages/app/components/VersionUpdater.tsx (web Dialog)
- Native no-op: packages/app/components/VersionUpdater.native.tsx
- Uses Tamagui Dialog pattern from SendpotRiskDialog.tsx
- Uses React Query pattern from useOFACGeoBlock.ts
- Uses .native.tsx tree-shaking pattern from CustomToast.tsx

Web-only: Version skew detection is only needed for web deployments
since native apps are updated through app stores. The .native.tsx
file exports a no-op that returns null, keeping native bundle size
minimal.

Vercel automatically provides VERCEL_GIT_COMMIT_SHA in deployments,
so no additional configuration is needed for production. The version
check runs every 120 seconds by default (configurable via
NEXT_PUBLIC_VERSION_UPDATER_REFETCH_INTERVAL_SECONDS).

Test plan:
- Start dev server: yarn web
- Navigate to http://localhost:3000
- Verify no errors in console
- Check /api/version returns a git hash
- Component renders but dialog is hidden (no version change)
- To test dialog: modify module-level version variable in
  useVersionUpdater.ts to simulate a version change
- Native: verify VersionUpdater.native.tsx is used (returns null)

Author: youngkidwarrior

apps/next/pages/api/version.ts

@@ -0,0 +1,50 @@
+import type { NextApiRequest, NextApiResponse } from 'next'
+
+/**
+ * Version endpoint for detecting client/server version skew.
+ * Returns the current Git commit SHA from the deployment.
+ *
+ * This endpoint is used by the VersionUpdater component to check if
+ * the client needs to refresh to get the latest code.
+ *
+ * Vercel automatically provides VERCEL_GIT_COMMIT_SHA in deployments.
+ * For other environments, provide GIT_HASH or similar.
+ */
+
+const KNOWN_GIT_ENV_VARS = ['VERCEL_GIT_COMMIT_SHA', 'CF_PAGES_COMMIT_SHA', 'GIT_HASH']
+
+async function getGitHash(): Promise<string> {
+  // Check known environment variables first
+  for (const envVar of KNOWN_GIT_ENV_VARS) {
+    if (process.env[envVar]) {
+      return process.env[envVar] as string
+    }
+  }
+
+  // Fallback to git command in development
+  if (process.env.NODE_ENV === 'development') {
+    try {
+      const { execSync } = await import('node:child_process')
+      return execSync('git log --pretty=format:"%h" -n1').toString().trim()
+    } catch (error) {
+      console.warn('[WARN] Could not get git hash from command:', error)
+      return 'dev'
+    }
+  }
+
+  console.warn(
+    '[WARN] Could not find git hash. Provide VERCEL_GIT_COMMIT_SHA or GIT_HASH environment variable.'
+  )
+  return 'unknown'
+}
+
+export default async function handler(_req: NextApiRequest, res: NextApiResponse<string>) {
+  const currentGitHash = await getGitHash()
+
+  // Set cache headers to prevent caching
+  res.setHeader('Cache-Control', 'no-cache, no-store, must-revalidate')
+  res.setHeader('Pragma', 'no-cache')
+  res.setHeader('Expires', '0')
+
+  res.status(200).send(currentGitHash)
+}

packages/app/components/VersionUpdater.native.tsx

@@ -0,0 +1,8 @@
+/**
+ * Native no-op version of VersionUpdater.
+ * Version skew detection is only needed for web deployments.
+ * Native apps are updated through app stores, not hot reloads.
+ */
+export function VersionUpdater() {
+  return null
+}

packages/app/components/VersionUpdater.tsx

@@ -0,0 +1,82 @@
+import { Button, Dialog, H2, Paragraph, YStack } from '@my/ui'
+import { RefreshCw } from '@tamagui/lucide-icons'
+import { useVersionUpdater } from 'app/utils/useVersionUpdater'
+import { useEffect, useState } from 'react'
+import { useTranslation } from 'react-i18next'
+
+/**
+ * Component that checks for version updates and prompts users to refresh.
+ *
+ * Web-only: This component polls the /api/version endpoint to detect when
+ * a new version has been deployed. When a mismatch is detected, it shows
+ * a dialog prompting the user to refresh the application.
+ *
+ * For native, use VersionUpdater.native.tsx which returns null.
+ *
+ * Based on the pattern from packages/app/features/sendpot/SendpotRiskDialog.tsx
+ *
+ * @param props Configuration options
+ */
+export function VersionUpdater(props: { intervalTimeInSeconds?: number }) {
+  const { data } = useVersionUpdater(props)
+  const [dismissed, setDismissed] = useState(false)
+  const [isOpen, setIsOpen] = useState(false)
+  const { t } = useTranslation('common')
+
+  useEffect(() => {
+    setIsOpen(data?.didChange ?? false)
+  }, [data?.didChange])
+
+  const handleRefresh = () => {
+    window.location.reload()
+  }
+
+  const handleDismiss = () => {
+    setIsOpen(false)
+    setDismissed(true)
+  }
+
+  // Don't render if no version change detected or user dismissed
+  if (!data?.didChange || dismissed) {
+    return null
+  }
+
+  return (
+    <Dialog open={isOpen} onOpenChange={handleDismiss}>
+      <Dialog.Portal>
+        <Dialog.Overlay />
+        <Dialog.Content
+          key="version-updater-dialog"
+          gap="$4"
+          maxWidth="90%"
+          $gtMd={{ maxWidth: '40%' }}
+        >
+          <YStack gap="$4" testID="versionUpdaterDialog">
+            <H2>{t('versionUpdater.title')}</H2>
+            <Paragraph>{t('versionUpdater.description')}</Paragraph>
+            <YStack gap="$2" justifyContent="flex-end" $gtSm={{ flexDirection: 'row' }}>
+              <Dialog.Close asChild>
+                <Button theme="gray" br="$2" flex={1} $gtSm={{ flex: 0 }}>
+                  <Button.Text>{t('versionUpdater.actions.dismiss')}</Button.Text>
+                </Button>
+              </Dialog.Close>
+              <Button
+                testID="versionUpdaterRefreshButton"
+                theme="green"
+                onPress={handleRefresh}
+                br="$2"
+                flex={1}
+                $gtSm={{ flex: 0 }}
+              >
+                <RefreshCw size={16} />
+                <Button.Text color="$color0" $theme-light={{ color: '$color12' }}>
+                  {t('versionUpdater.actions.refresh')}
+                </Button.Text>
+              </Button>
+            </YStack>
+          </YStack>
+        </Dialog.Content>
+      </Dialog.Portal>
+    </Dialog>
+  )
+}

packages/app/i18n/resources/common/en.json

@@ -10,5 +10,13 @@
     "applied": "Referral code applied",
     "cta": "Got a referral? Enter the code to get rewards!",
     "referredBy": "Referred by"
+  },
+  "versionUpdater": {
+    "title": "New Version Available",
+    "description": "A new version of the app is available. Please refresh to get the latest features and improvements.",
+    "actions": {
+      "refresh": "Refresh Now",
+      "dismiss": "Dismiss"
+    }
   }
 }

packages/app/provider/index.tsx

@@ -2,6 +2,7 @@ import type { Session } from '@supabase/supabase-js'
 import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
 import type { i18n } from 'i18next'
 import { Concerns } from 'app/concerns'
+import { VersionUpdater } from 'app/components/VersionUpdater'
 import { getI18n } from 'app/i18n'
 import ScrollDirectionProvider from 'app/provider/scroll/ScrollDirectionProvider'
 import type React from 'react'
@@ -44,6 +45,7 @@ export function Provider({
         <ShimmerProvider duration={2000}>
           <Providers>
             <Concerns>{children}</Concerns>
+            <VersionUpdater />
             {process.env.NEXT_PUBLIC_REACT_QUERY_DEV_TOOLS && <ReactQueryDevtools />}
           </Providers>
         </ShimmerProvider>

packages/app/utils/useVersionUpdater.ts

@@ -0,0 +1,89 @@
+import { useQuery } from '@tanstack/react-query'
+
+/**
+ * Current version of the app that is running.
+ * This is set on first fetch and compared on subsequent fetches.
+ */
+let version: string | null = null
+
+/**
+ * Default interval time in seconds to check for new version.
+ * By default, it is set to 120 seconds (2 minutes).
+ */
+const DEFAULT_REFETCH_INTERVAL = 120
+
+/**
+ * Environment variable to override the default refetch interval.
+ * Can be set via NEXT_PUBLIC_VERSION_UPDATER_REFETCH_INTERVAL_SECONDS.
+ */
+const VERSION_UPDATER_REFETCH_INTERVAL_SECONDS =
+  process.env.NEXT_PUBLIC_VERSION_UPDATER_REFETCH_INTERVAL_SECONDS
+
+interface VersionUpdaterResult {
+  currentVersion: string
+  oldVersion: string | null
+  didChange: boolean
+}
+
+interface UseVersionUpdaterProps {
+  /**
+   * Optional override for the refetch interval in seconds.
+   * If not provided, uses the environment variable or default (120s).
+   */
+  intervalTimeInSeconds?: number
+  /**
+   * Whether to enable version checking.
+   * Defaults to true. Set to false to disable in development or testing.
+   */
+  enabled?: boolean
+}
+
+/**
+ * Hook to check for version changes between client and server.
+ *
+ * This hook polls the /api/version endpoint at regular intervals
+ * to detect when a new version has been deployed. When a version
+ * mismatch is detected, it returns didChange: true.
+ *
+ * Example from packages/app/utils/useOFACGeoBlock.ts
+ *
+ * @param props Configuration options
+ * @returns Query result with version information
+ */
+export function useVersionUpdater(props: UseVersionUpdaterProps = {}) {
+  const { intervalTimeInSeconds, enabled = true } = props
+
+  const interval = VERSION_UPDATER_REFETCH_INTERVAL_SECONDS
+    ? Number(VERSION_UPDATER_REFETCH_INTERVAL_SECONDS)
+    : DEFAULT_REFETCH_INTERVAL
+
+  const refetchInterval = (intervalTimeInSeconds ?? interval) * 1000
+
+  // Start fetching new version after half of the interval time
+  const staleTime = refetchInterval / 2
+
+  return useQuery<VersionUpdaterResult>({
+    queryKey: ['version-updater'],
+    staleTime,
+    gcTime: refetchInterval,
+    refetchIntervalInBackground: true,
+    refetchInterval,
+    enabled,
+    queryFn: async () => {
+      const response = await fetch('/api/version')
+      const currentVersion = await response.text()
+
+      const oldVersion = version
+      version = currentVersion
+
+      // Only mark as changed if we had a previous version and it differs
+      const didChange = oldVersion !== null && currentVersion !== oldVersion
+
+      return {
+        currentVersion,
+        oldVersion,
+        didChange,
+      }
+    },
+  })
+}