feat: implement expo device token registration

Author: damlayildiz

README.md

@@ -44,8 +44,11 @@ Build real-time, collaborative mobile apps that work seamlessly offline and auto
 - [`@react-native-community/netinfo`](https://github.com/react-native-netinfo/react-native-netinfo) **^11.0.0**
 - [SQLite Cloud](https://sqlitecloud.io/) account
 - **Optional (for push mode):**
-  - [`expo-notifications`](https://docs.expo.dev/versions/latest/sdk/notifications/)
-  - [`expo-constants`](https://docs.expo.dev/versions/latest/sdk/constants/)
+  - [`expo-notifications`](https://docs.expo.dev/versions/latest/sdk/notifications/) - Push notification handling
+  - [`expo-constants`](https://docs.expo.dev/versions/latest/sdk/constants/) - EAS project ID for push tokens
+  - [`expo-application`](https://docs.expo.dev/versions/latest/sdk/application/) - Device ID for push token registration
+  - [`expo-secure-store`](https://docs.expo.dev/versions/latest/sdk/securestore/) - Persisting background sync config and push token state
+  - [`expo-task-manager`](https://docs.expo.dev/versions/latest/sdk/task-manager/) - Background/terminated notification sync
 
 > **Note:** This library is **native-only** (iOS/Android). Web is not supported.
 
@@ -62,7 +65,7 @@ yarn add @sqliteai/sqlite-sync-react-native @op-engineering/op-sqlite @react-nat
 **Optional: For push mode (Expo projects only)**
 
 ```bash
-npx expo install expo-notifications expo-constants
+npx expo install expo-notifications expo-constants expo-application expo-secure-store expo-task-manager
 ```
 
 ### 2. Platform Setup

examples/sync-demo-expo/package.json

@@ -22,6 +22,7 @@
     "@react-native-community/netinfo": "^11.4.1",
     "@sqliteai/sqlite-sync-react-native": "*",
     "expo": "~54.0.25",
+    "expo-application": "~7.0.8",
     "expo-build-properties": "~1.0.0",
     "expo-constants": "~18.0.13",
     "expo-dev-client": "~6.0.20",

src/core/common/optionalDependencies.ts

@@ -38,6 +38,14 @@ try {
   // Not available
 }
 
+// Load expo-application
+export let ExpoApplication: any = null;
+try {
+  ExpoApplication = require('expo-application');
+} catch {
+  // Not available
+}
+
 // Compound availability check
 export const isBackgroundSyncAvailable = () =>
   ExpoNotifications !== null &&

src/core/pushNotifications/registerPushToken.ts

@@ -0,0 +1,119 @@
+import {
+  ExpoSecureStore,
+  ExpoApplication,
+} from '../common/optionalDependencies';
+import type { Logger } from '../common/logger';
+
+const TOKEN_REGISTERED_KEY = 'sqlite_sync_push_token_registered';
+const CLOUDSYNC_BASE_URL = 'https://cloudsync-staging.fly.dev/v2';
+
+async function getDeviceId(): Promise<string> {
+  if (!ExpoApplication) {
+    throw new Error(
+      'expo-application is required for push notification token registration. Install it with: npx expo install expo-application'
+    );
+  }
+
+  const { Platform } = require('react-native');
+  if (Platform.OS === 'ios') {
+    return await ExpoApplication.getIosIdForVendorAsync();
+  }
+  // Android
+  return ExpoApplication.getAndroidId();
+}
+
+interface RegisterPushTokenParams {
+  expoToken: string;
+  databaseName: string;
+  siteId?: string;
+  platform: string;
+  connectionString: string;
+  apiKey?: string;
+  accessToken?: string;
+  logger: Logger;
+}
+
+/**
+ * Register an Expo push token with the SQLite Cloud backend.
+ * Only sends the token once per installation (persisted via SecureStore).
+ */
+export async function registerPushToken(
+  params: RegisterPushTokenParams
+): Promise<void> {
+  const {
+    expoToken,
+    databaseName,
+    siteId,
+    platform,
+    connectionString,
+    apiKey,
+    accessToken,
+    logger,
+  } = params;
+
+  // Check if token was already registered
+  if (ExpoSecureStore) {
+    try {
+      const registered = await ExpoSecureStore.getItemAsync(
+        TOKEN_REGISTERED_KEY
+      );
+      if (registered === expoToken) {
+        logger.info('📱 Push token already registered, skipping');
+        return;
+      }
+    } catch {
+      // Continue with registration
+    }
+  }
+
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+  };
+
+  if (accessToken) {
+    headers.Authorization = `Bearer ${accessToken}`;
+  } else if (apiKey) {
+    headers.Authorization = `Bearer ${connectionString}?apikey=${apiKey}`;
+  }
+
+  const deviceId = await getDeviceId();
+
+  const body = {
+    expoToken,
+    deviceId,
+    database: databaseName,
+    siteId: siteId ?? '',
+    platform,
+  };
+
+  const url = `${CLOUDSYNC_BASE_URL}/cloudsync/notifications/tokens`;
+  logger.info(
+    '📱 Registering push token with backend...',
+    url,
+    JSON.stringify(body)
+  );
+
+  const response = await fetch(url, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const text = await response.text().catch(() => '');
+    throw new Error(
+      `Failed to register push token: ${response.status} ${text}`
+    );
+  }
+
+  logger.info('📱 Push token registered successfully');
+
+  // Persist that this token has been registered
+  if (ExpoSecureStore) {
+    try {
+      await ExpoSecureStore.setItemAsync(TOKEN_REGISTERED_KEY, expoToken);
+    } catch {
+      // Non-critical
+    }
+  }
+}

src/core/pushNotifications/usePushNotificationSync.ts

@@ -22,6 +22,9 @@ import {
   unregisterBackgroundSync,
 } from '../background/backgroundSyncRegistry';
 import { setForegroundSyncCallback } from './pushNotificationSyncCallbacks';
+import { Platform } from 'react-native';
+import { isForegroundSqliteCloudNotification } from './isSqliteCloudNotification';
+import { registerPushToken } from './registerPushToken';
 
 /**
  * Parameters for usePushNotificationSync hook
@@ -105,8 +108,6 @@ export interface PushNotificationSyncParams {
   }) => ReactNode;
 }
 
-import { isForegroundSqliteCloudNotification } from './isSqliteCloudNotification';
-
 export function usePushNotificationSync(params: PushNotificationSyncParams): {
   permissionPromptNode: ReactNode;
 } {
@@ -268,7 +269,38 @@ export function usePushNotificationSync(params: PushNotificationSyncParams): {
 
         if (token?.data) {
           logger.info('📱 Expo Push Token:', token.data);
-          // TODO: Send token to backend
+
+          let siteId: string | undefined;
+          try {
+            const firstTable = tablesToBeSynced[0];
+            if (firstTable && writeDbRef.current) {
+              const initResult = await writeDbRef.current.execute(
+                'SELECT cloudsync_init(?);',
+                [firstTable.name]
+              );
+              const firstRow = initResult.rows?.[0];
+              siteId = firstRow
+                ? String(Object.values(firstRow)[0])
+                : undefined;
+            }
+          } catch {
+            logger.warn('⚠️ Could not retrieve siteId');
+          }
+
+          try {
+            await registerPushToken({
+              expoToken: token.data,
+              databaseName,
+              siteId,
+              platform: Platform.OS,
+              connectionString,
+              apiKey,
+              accessToken,
+              logger,
+            });
+          } catch (registerError) {
+            logger.warn('⚠️ Failed to register push token:', registerError);
+          }
         }
       } catch (error) {
         // Network errors and other temporary failures - don't fallback
@@ -277,7 +309,8 @@ export function usePushNotificationSync(params: PushNotificationSyncParams): {
     };
 
     requestPermissions();
-  }, [isSyncReady, syncMode, writeDbRef, logger]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- runs once per mount, guarded by hasRequestedPermissionsRef
+  }, [isSyncReady, syncMode]);
 
   /** NOTIFICATION LISTENERS */
   useEffect(() => {

yarn.lock

@@ -3768,6 +3768,7 @@ __metadata:
     "@react-native-community/netinfo": "npm:^11.4.1"
     "@sqliteai/sqlite-sync-react-native": "npm:*"
     expo: "npm:~54.0.25"
+    expo-application: "npm:~7.0.8"
     expo-build-properties: "npm:~1.0.0"
     expo-constants: "npm:~18.0.13"
     expo-dev-client: "npm:~6.0.20"