bump version to 1.4.4 build 70

AGENTS.md

@@ -0,0 +1,20 @@
+# Agent Instructions for crowd-funder-for-time-pwa
+
+## Android Build — Google Play Services / FOSS Compatibility
+
+**Firebase is opt-in. Do NOT enable it accidentally.**
+
+`android/google-services.json` is gitignored and may be present on disk for push notification development, but Firebase is only activated when you explicitly pass `-PfirebaseEnabled` to Gradle:
+
+- **FOSS / APK / Aurora / Zapstore / F-Droid builds**: just `./gradlew assembleRelease` — Firebase stays off even if `google-services.json` is on disk.
+- **Firebase / FCM / Play Store builds**: `./gradlew bundleRelease -PfirebaseEnabled` — explicitly opt in.
+
+This guard is in `android/app/build.gradle`. Do NOT change this conditional to activate Firebase unconditionally based on file presence alone — that was the bug that broke FOSS distribution in June 2026.
+
+`google-services.json` is intentionally excluded from git (`android/.gitignore`). Never commit it.
+
+Full details, incident history, and F-Droid notes: `doc/development/android-firebase-gms.md`
+
+## Android Build — MLKit Barcode Scanner
+
+`@capacitor-mlkit/barcode-scanning` depends on `com.google.android.gms:play-services-code-scanner`, which merges `com.google.android.gms.version` into the APK manifest. This is a known long-term issue for strict FOSS/F-Droid builds. For now, the dependency is accepted; barcode scanning simply will not work on GMS-less devices (it fails gracefully at scan time, not at startup). Do not add additional GMS/Firebase dependencies without explicitly acknowledging this trade-off.

BUILDING.md

@@ -1140,7 +1140,7 @@ export GEM_PATH=$shortened_path
 ##### 1. Bump the version in package.json & CHANGELOG.md for `MARKETING_VERSION`, then `grep CURRENT_PROJECT_VERSION ios/App/App.xcodeproj/project.pbxproj` and add 1 for the numbered version here:
 
 ```bash
-cd ios/App && xcrun agvtool new-version 69 && perl -p -i -e "s/MARKETING_VERSION = .*;/MARKETING_VERSION = 1.4.3;/g" App.xcodeproj/project.pbxproj && cd -
+cd ios/App && xcrun agvtool new-version 70 && perl -p -i -e "s/MARKETING_VERSION = .*;/MARKETING_VERSION = 1.4.4;/g" App.xcodeproj/project.pbxproj && cd -
 # Unfortunately this edits Info.plist directly.
 #xcrun agvtool new-marketing-version 0.4.5
 ```
@@ -1419,8 +1419,8 @@ The recommended way to build for Android is using the automated build script:
 ##### 1. Bump the version in package.json, then update these versions & run:
 
 ```bash
-perl -p -i -e 's/versionCode .*/versionCode 69/g' android/app/build.gradle
-perl -p -i -e 's/versionName .*/versionName "1.4.3"/g' android/app/build.gradle
+perl -p -i -e 's/versionCode .*/versionCode 70/g' android/app/build.gradle
+perl -p -i -e 's/versionName .*/versionName "1.4.4"/g' android/app/build.gradle
 ```
 
 ##### 2. Build
@@ -1458,17 +1458,18 @@ cd -
 
 - Setup by adding the app/gradle.properties.secrets file (see properties at top
   of app/build.gradle) and the app/time-safari-upload-key-pkcs12.jks file
-- In app/build.gradle, bump the versionCode and maybe the versionName
 - Then `bundleRelease`:
 
 ```bash
 cd android
-./gradlew bundleRelease -Dlint.baselines.continue=true
+./gradlew bundleRelease -Dlint.baselines.continue=true -PfirebaseEnabled
 cd -
 ```
 
 ... and find your `aab` file at app/build/outputs/bundle/release
 
+* Note that F-Droid builds should omit `-PfirebaseEnabled`.
+
 At play.google.com/console:
 
 - Go to Production or the Closed Testing and either Create Track or Manage Track.

CHANGELOG.md

@@ -6,6 +6,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [1.4.4] - 2026.06.21
+### Changed
+- More checks for Firebase so that it won't break, eg in Aurora store.
+
+
 ## [1.4.3] - 2026.06.19
 ### Removed
 - Automatic "Check your starred projects" daily notification

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

android/app/build.gradle

@@ -37,8 +37,8 @@ android {
         applicationId "app.timesafari.app"
         minSdkVersion rootProject.ext.minSdkVersion
         targetSdkVersion rootProject.ext.targetSdkVersion
-        versionCode 69
-        versionName "1.4.3"
+        versionCode 70
+        versionName "1.4.4"
         testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
         aaptOptions {
              // Files and dirs to omit from the packaged assets dir, modified to accommodate modern web apps.
@@ -130,11 +130,20 @@ dependencies {
 
 apply from: 'capacitor.build.gradle'
 
+// Firebase / Google Play Services are opt-in. Pass -PfirebaseEnabled to any Gradle command
+// to activate Firebase (FCM push notifications). Without this flag the build works on
+// F-Droid, Aurora, Zapstore, and plain APK sideloading even when google-services.json
+// is present on disk (it is gitignored; see AGENTS.md for the full story).
 try {
     def servicesJSON = file('google-services.json')
-    if (servicesJSON.text) {
+    if (servicesJSON.exists() && servicesJSON.text && project.hasProperty('firebaseEnabled')) {
         apply plugin: 'com.google.gms.google-services'
+        logger.info("Firebase enabled: google-services plugin applied")
+    } else if (servicesJSON.exists() && !project.hasProperty('firebaseEnabled')) {
+        logger.info("google-services.json present but firebaseEnabled not set — skipping Firebase plugin (pass -PfirebaseEnabled to enable)")
+    } else {
+        logger.info("google-services.json not found — Firebase plugin not applied")
     }
 } catch(Exception e) {
-    logger.info("google-services.json not found, google-services plugin not applied. Push Notifications won't work")
+    logger.info("google-services plugin not applied: ${e.message}")
 }

doc/android-firebase-gms.md

@@ -0,0 +1,66 @@
+# Android — Firebase, Google Play Services, and FOSS Distribution
+
+## Overview
+
+The app is designed to work on Android devices with and without Google Play Services (GMS). Firebase/FCM push notifications are an opt-in feature at build time; all other functionality works on GMS-less devices (F-Droid, LineageOS without OpenGApps, etc.).
+
+## How the opt-in guard works
+
+`android/app/build.gradle` applies the `com.google.gms.google-services` Gradle plugin only when **both** conditions are true:
+
+1. `android/google-services.json` is present on disk
+2. The Gradle property `firebaseEnabled` is explicitly passed
+
+```groovy
+if (servicesJSON.exists() && servicesJSON.text && project.hasProperty('firebaseEnabled')) {
+    apply plugin: 'com.google.gms.google-services'
+}
+```
+
+This means the file can live on disk for development purposes without accidentally activating Firebase.
+
+## Build commands
+
+| Target | Command | Firebase |
+|---|---|---|
+| APK / sideload / Zapstore | `./gradlew assembleRelease` | off |
+| Aurora / Play Store without FCM | `./gradlew bundleRelease` | off |
+| Play Store with FCM push notifications | `./gradlew bundleRelease -PfirebaseEnabled` | on |
+| F-Droid | `./gradlew assembleRelease` | off (required) |
+
+## Behavior on non-GMS devices
+
+When built with `-PfirebaseEnabled`, Firebase SDKs check for GMS availability at startup and degrade gracefully if it is absent:
+
+- Firebase initializes but detects no GMS
+- FCM skips token registration silently (no token, no notifications)
+- The app continues to work normally
+
+This means a single Play Store AAB (`bundleRelease -PfirebaseEnabled`) covers both GMS and non-GMS users. GMS users get push notifications; non-GMS users get a fully functional app without them.
+
+**Aurora Store** pulls the exact APK from Play Store servers, so Aurora users get whichever variant was uploaded. The Play Store AAB built with `-PfirebaseEnabled` is correct for Aurora.
+
+**F-Droid** is stricter: their build policy rejects any APK with GMS dependencies at the binary level, even with graceful degradation. F-Droid submission would require a separate `assembleRelease` build (no flag) and a dedicated F-Droid listing.
+
+## The `google-services.json` file
+
+- Gitignored (`android/.gitignore` line 80) — never commit it
+- Contains Firebase project credentials (project number, app ID, API key)
+- Safe to leave on disk; has no effect unless `-PfirebaseEnabled` is passed
+- Obtain from the Firebase console: Project Settings → Your apps → Android app → Download `google-services.json`
+
+## Known GMS dependency: MLKit barcode scanner
+
+`@capacitor-mlkit/barcode-scanning` unconditionally depends on `com.google.android.gms:play-services-code-scanner` (present since the plugin was first added at v6.0.0). This merges `com.google.android.gms.version` and `GoogleApiActivity` into the APK manifest regardless of the `-PfirebaseEnabled` flag.
+
+Practical impact:
+- **GMS devices**: barcode scanning works normally
+- **Non-GMS devices**: barcode scanning fails at scan time (not at startup); the app launches and runs normally otherwise
+
+This is an accepted trade-off. Removing it would require either forking the plugin or introducing a `foss` product flavor that excludes the MLKit plugin entirely — work to undertake if/when F-Droid submission is planned.
+
+## Incident: June 2026
+
+Jose Olarte III's `notify-api` branch placed a production `google-services.json` in `android/` to test Firebase Cloud Messaging. The branch was never merged to `master`, but because the file is gitignored it persisted on disk after switching branches. At the time, the Gradle conditional activated Firebase based on file presence alone (no opt-in flag), so all subsequent local builds embedded Firebase and required Google Play Services. This silently broke APK/Aurora/Zapstore distribution.
+
+**Fix applied:** deleted `google-services.json` from disk, changed the Gradle conditional to require `-PfirebaseEnabled`, and documented the rule in `AGENTS.md`.

doc/deep-link-debugging-guide.md

@@ -0,0 +1,308 @@
+# Deep Link Debugging Guide for TimeSafari
+
+This guide helps you debug and fix deep link issues in the TimeSafari Capacitor application.
+
+## Quick Start
+
+1. **Check logs**: Use browser dev tools or device console to see detailed logging
+2. **Test manually**: Use the testing script or browser console commands
+3. **Verify configuration**: Ensure all platform configurations are correct
+
+## Common Issues and Solutions
+
+### Issue 1: App opens but doesn't navigate to the correct page
+
+**Symptoms:**
+- Deep link opens the app
+- App stays on home screen or current page
+- No error messages visible
+
+**Debugging Steps:**
+
+1. **Check console logs** in browser dev tools or device console:
+   ```bash
+   # Android
+   adb logcat | grep -E "(TimeSafari|DeepLink|appUrlOpen)"
+   
+   # iOS Simulator
+   xcrun simctl spawn booted log stream --predicate 'process == "TimeSafari"'
+   ```
+
+2. **Verify listener registration**:
+   Look for these log messages:
+   ```
+   [DeepLink] Registering appUrlOpen listener...
+   [DeepLink] Listener registered successfully
+   ```
+
+3. **Check for event reception**:
+   Look for:
+   ```
+   [DeepLink] ========== DEEP LINK EVENT RECEIVED ==========
+   [DeepLink] URL: timesafari://your/url/here
+   ```
+
+4. **Verify URL parsing**:
+   Check if URL components are parsed correctly:
+   ```
+   [DeepLinkHandler.parseDeepLink] Parse result: {"path":"claim","params":{"id":"123"},"query":{}}
+   ```
+
+### Issue 2: Listener not receiving events
+
+**Symptoms:**
+- No deep link logs appear
+- App opens but no event processing
+
+**Solutions:**
+
+1. **Rebuild and reinstall** the app completely:
+   ```bash
+   npm run build:capacitor
+   npx cap sync
+   npx cap run android  # or ios
+   ```
+
+2. **Check capacitor.config.json**:
+   ```json
+   {
+     "plugins": {
+       "App": {
+         "appUrlOpen": {
+           "handlers": [
+             {
+               "url": "timesafari://*",
+               "autoVerify": true
+             }
+           ]
+         }
+       }
+     }
+   }
+   ```
+
+3. **Verify native configuration**:
+   - **Android**: Check `android/app/src/main/AndroidManifest.xml`
+   - **iOS**: Check `ios/App/App/Info.plist`
+
+### Issue 3: URL scheme not recognized by OS
+
+**Symptoms:**
+- "No app found to handle this link" error
+- OS doesn't open your app
+
+**Solutions:**
+
+1. **Android**: Verify intent filter in AndroidManifest.xml:
+   ```xml
+   <intent-filter>
+       <action android:name="android.intent.action.VIEW" />
+       <category android:name="android.intent.category.DEFAULT" />
+       <category android:name="android.intent.category.BROWSABLE" />
+       <data android:scheme="timesafari" />
+   </intent-filter>
+   ```
+
+2. **iOS**: Verify URL types in Info.plist:
+   ```xml
+   <key>CFBundleURLTypes</key>
+   <array>
+       <dict>
+           <key>CFBundleURLName</key>
+           <string>app.timesafari</string>
+           <key>CFBundleURLSchemes</key>
+           <array>
+               <string>timesafari</string>
+           </array>
+       </dict>
+   </array>
+   ```
+
+## Testing Tools
+
+### 1. Automated Testing Script
+
+Use the provided testing script:
+
+```bash
+# Test all URLs on Android
+./scripts/test-deep-links.sh android
+
+# Test specific URL on iOS
+./scripts/test-deep-links.sh ios "timesafari://claim/test123"
+
+# Monitor logs
+./scripts/test-deep-links.sh android-logs
+```
+
+### 2. Manual Testing Commands
+
+**Android Emulator:**
+```bash
+adb shell am start -W -a android.intent.action.VIEW -d "timesafari://claim/test123" app.timesafari
+```
+
+**iOS Simulator:**
+```bash
+xcrun simctl openurl booted "timesafari://claim/test123"
+```
+
+### 3. Browser Console Testing
+
+For web/PWA testing, use the browser console:
+
+```javascript
+// Test deep link processing directly
+window.testSingleDeepLink("timesafari://claim/test123");
+
+// Run all test URLs
+window.testDeepLinks();
+```
+
+## Debugging Steps Checklist
+
+### Pre-Testing Setup
+
+- [ ] App is installed on device/emulator
+- [ ] App has been launched at least once
+- [ ] Device/emulator is properly connected
+- [ ] Debugging tools are accessible
+
+### During Testing
+
+- [ ] Check console for initialization logs
+- [ ] Verify listener registration
+- [ ] Test with simple URL first (e.g., `timesafari://claim/test`)
+- [ ] Monitor URL parsing logs
+- [ ] Check router navigation logs
+
+### Post-Testing Analysis
+
+- [ ] Review complete log sequence
+- [ ] Identify where process fails
+- [ ] Check error messages for clues
+- [ ] Test with different URL formats
+
+## Common Log Patterns
+
+### Successful Deep Link Flow
+
+```
+[DeepLink] Registering appUrlOpen listener...
+[DeepLink] Listener registered successfully
+[DeepLink] ========== DEEP LINK EVENT RECEIVED ==========
+[DeepLink] URL: timesafari://claim/test123
+[DeepLinkHandler] Starting handleDeepLink with URL: timesafari://claim/test123
+[DeepLinkHandler.parseDeepLink] Parse result: {"path":"claim","params":{"id":"test123"},"query":{}}
+[DeepLinkHandler.validateAndRoute] Route validation passed. Route name: claim
+[DeepLinkHandler.validateAndRoute] Router navigation completed successfully
+[DeepLink] Deep link handled successfully
+```
+
+### Failed URL Parsing
+
+```
+[DeepLinkHandler.parseDeepLink] Route not found: invalid-route
+[DeepLinkHandler.parseDeepLink] Available routes: ["claim","project","contact-import",...]
+[DeepLinkHandler.validateAndRoute] Redirecting to deep-link-error page
+```
+
+### Router Navigation Issues
+
+```
+[DeepLinkHandler.validateAndRoute] Error routing to route name claim
+[DeepLinkHandler.validateAndRoute] Navigation params: {"name":"claim","params":{"id":"test123"}}
+```
+
+## Platform-Specific Issues
+
+### Android
+
+**Issue**: Deep links work in development but not in production build
+- **Solution**: Ensure `android:exported="true"` in MainActivity
+
+**Issue**: App doesn't respond to links when running in background
+- **Solution**: Check `android:launchMode="singleTask"` in AndroidManifest.xml
+
+### iOS
+
+**Issue**: Deep links don't work in iOS simulator
+- **Solution**: Use `xcrun simctl openurl` instead of opening URLs in Safari
+
+**Issue**: App launches but doesn't process URL
+- **Solution**: Check for Associated Domains if using universal links
+
+## Advanced Debugging
+
+### Enable Capacitor Native Logging
+
+Add to `capacitor.config.json`:
+
+```json
+{
+  "ios": {
+    "loggingBehavior": "debug"
+  },
+  "android": {
+    "loggingBehavior": "debug"
+  }
+}
+```
+
+### Add Custom Debug Points
+
+Insert additional logging in your deep link handler:
+
+```typescript
+// Add at strategic points in DeepLinkHandler
+console.log('[DEBUG] Custom checkpoint:', { data: yourData });
+```
+
+### Network Debugging
+
+If deep links involve network requests:
+
+```bash
+# Monitor network traffic (Android)
+adb shell dumpsys connectivity
+
+# Monitor network traffic (iOS)
+# Use Xcode Network Debugger
+```
+
+## Recovery Strategies
+
+### If deep links stop working completely:
+
+1. **Clean rebuild**:
+   ```bash
+   rm -rf node_modules
+   npm install
+   npm run build:capacitor
+   npx cap sync
+   ```
+
+2. **Reset device/emulator**:
+   - Clear app data
+   - Uninstall and reinstall
+   - Restart emulator
+
+3. **Verify basic functionality**:
+   - Test simple navigation within app
+   - Test URL schemes with minimal URLs
+   - Gradually increase complexity
+
+## Support Resources
+
+- [Capacitor Deep Links Documentation](https://capacitorjs.com/docs/guides/deep-links)
+- [Android Intent Filter Guide](https://developer.android.com/guide/components/intents-filters)
+- [iOS URL Scheme Guide](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app)
+
+## Contact and Feedback
+
+If you encounter issues not covered in this guide:
+
+1. Check the project's issue tracker
+2. Review recent commits for deep link changes
+3. Test with minimal reproduction case
+4. Document exact steps and environment details 

ios/App/App.xcodeproj/project.pbxproj

@@ -524,7 +524,7 @@
 				ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
 				CODE_SIGN_ENTITLEMENTS = App/App.entitlements;
 				CODE_SIGN_STYLE = Automatic;
-				CURRENT_PROJECT_VERSION = 69;
+				CURRENT_PROJECT_VERSION = 70;
 				DEVELOPMENT_TEAM = GM3FS5JQPH;
 				ENABLE_APP_SANDBOX = NO;
 				ENABLE_USER_SCRIPT_SANDBOXING = NO;
@@ -535,7 +535,7 @@
 					"$(inherited)",
 					"@executable_path/Frameworks",
 				);
-				MARKETING_VERSION = 1.4.3;
+				MARKETING_VERSION = 1.4.4;
 				OTHER_SWIFT_FLAGS = "$(inherited) \"-D\" \"COCOAPODS\" \"-DDEBUG\"";
 				PRODUCT_BUNDLE_IDENTIFIER = app.timesafari;
 				PRODUCT_NAME = "$(TARGET_NAME)";
@@ -553,7 +553,7 @@
 				ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
 				CODE_SIGN_ENTITLEMENTS = App/App.entitlements;
 				CODE_SIGN_STYLE = Automatic;
-				CURRENT_PROJECT_VERSION = 69;
+				CURRENT_PROJECT_VERSION = 70;
 				DEVELOPMENT_TEAM = GM3FS5JQPH;
 				ENABLE_APP_SANDBOX = NO;
 				ENABLE_USER_SCRIPT_SANDBOXING = NO;
@@ -564,7 +564,7 @@
 					"$(inherited)",
 					"@executable_path/Frameworks",
 				);
-				MARKETING_VERSION = 1.4.3;
+				MARKETING_VERSION = 1.4.4;
 				PRODUCT_BUNDLE_IDENTIFIER = app.timesafari;
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				SWIFT_ACTIVE_COMPILATION_CONDITIONS = "";
@@ -582,7 +582,7 @@
 				CLANG_ENABLE_OBJC_WEAK = YES;
 				CODE_SIGN_ENTITLEMENTS = TimeSafariShareExtension/TimeSafariShareExtension.entitlements;
 				CODE_SIGN_STYLE = Automatic;
-				CURRENT_PROJECT_VERSION = 69;
+				CURRENT_PROJECT_VERSION = 70;
 				DEVELOPMENT_TEAM = GM3FS5JQPH;
 				GCC_C_LANGUAGE_STANDARD = gnu17;
 				GENERATE_INFOPLIST_FILE = YES;
@@ -596,7 +596,7 @@
 					"@executable_path/../../Frameworks",
 				);
 				LOCALIZATION_PREFERS_STRING_CATALOGS = YES;
-				MARKETING_VERSION = 1.4.3;
+				MARKETING_VERSION = 1.4.4;
 				MTL_ENABLE_DEBUG_INFO = INCLUDE_SOURCE;
 				MTL_FAST_MATH = YES;
 				PRODUCT_BUNDLE_IDENTIFIER = app.timesafari.TimeSafariShareExtension;
@@ -620,7 +620,7 @@
 				CLANG_ENABLE_OBJC_WEAK = YES;
 				CODE_SIGN_ENTITLEMENTS = TimeSafariShareExtension/TimeSafariShareExtension.entitlements;
 				CODE_SIGN_STYLE = Automatic;
-				CURRENT_PROJECT_VERSION = 69;
+				CURRENT_PROJECT_VERSION = 70;
 				DEVELOPMENT_TEAM = GM3FS5JQPH;
 				GCC_C_LANGUAGE_STANDARD = gnu17;
 				GENERATE_INFOPLIST_FILE = YES;
@@ -634,7 +634,7 @@
 					"@executable_path/../../Frameworks",
 				);
 				LOCALIZATION_PREFERS_STRING_CATALOGS = YES;
-				MARKETING_VERSION = 1.4.3;
+				MARKETING_VERSION = 1.4.4;
 				MTL_FAST_MATH = YES;
 				PRODUCT_BUNDLE_IDENTIFIER = app.timesafari.TimeSafariShareExtension;
 				PRODUCT_NAME = "$(TARGET_NAME)";

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "giftopia",
-  "version": "1.4.3",
+  "version": "1.4.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "giftopia",
-      "version": "1.4.3",
+      "version": "1.4.4",
       "dependencies": {
         "@capacitor-community/electron": "^5.0.1",
         "@capacitor-community/sqlite": "^7.0.3",

package.json

@@ -1,7 +1,7 @@
 
 {
   "name": "giftopia",
-  "version": "1.4.3",
+  "version": "1.4.4",
   "description": "Giftopia App",
   "author": {
     "name": "Gift Economies Team"