From d5c357b29177fd37be9b0a91b1ea73acae4b4192 Mon Sep 17 00:00:00 2001 From: Jose Olarte III Date: Wed, 22 Jul 2026 20:56:20 +0800 Subject: [PATCH] Document dedicated Notification API URL configuration. Describe VITE_DEFAULT_NOTIFY_API_SERVER / DEFAULT_NOTIFY_API_SERVER, the debug-override resolution order, and replace outdated APP_SERVER assumptions in build and notification testing docs. --- BUILDING.md | 6 ++++ doc/android-physical-device-guide.md | 1 + doc/local-android-testing-ngrok.md | 8 ++--- doc/local-ios-testing-ngrok.md | 6 ++-- doc/notification-debug-panel.md | 49 +++++++++++++++++++++++++--- docker/README.md | 3 ++ 6 files changed, 62 insertions(+), 11 deletions(-) diff --git a/BUILDING.md b/BUILDING.md index d0a4cf36..cdbfb565 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -164,6 +164,7 @@ cp .env.example .env.development # - VITE_DEFAULT_ENDORSER_API_SERVER # - VITE_DEFAULT_PARTNER_API_SERVER # - VITE_DEFAULT_IMAGE_API_SERVER +# - VITE_DEFAULT_NOTIFY_API_SERVER ``` #### Platform-Specific Development @@ -1650,6 +1651,7 @@ The build system supports multiple environment file patterns for different scena VITE_DEFAULT_ENDORSER_API_SERVER=https://api.endorser.ch VITE_DEFAULT_PARTNER_API_SERVER=https://partner-api.endorser.ch VITE_DEFAULT_IMAGE_API_SERVER=https://image-api.timesafari.app +VITE_DEFAULT_NOTIFY_API_SERVER=https://notify-api.timesafari.app # Platform Configuration VITE_PLATFORM=web|electron|capacitor @@ -1669,6 +1671,7 @@ VITE_BVC_MEETUPS_PROJECT_CLAIM_ID=https://endorser.ch/entity/01HWE8FWHQ1YGP7GFZY VITE_DEFAULT_ENDORSER_API_SERVER=http://localhost:3000 VITE_DEFAULT_PARTNER_API_SERVER=http://localhost:3000 VITE_DEFAULT_IMAGE_API_SERVER=https://test-image-api.timesafari.app +VITE_DEFAULT_NOTIFY_API_SERVER=https://test-notify-api.timesafari.app VITE_APP_SERVER=http://localhost:8080 ``` @@ -1679,6 +1682,7 @@ VITE_APP_SERVER=http://localhost:8080 VITE_DEFAULT_ENDORSER_API_SERVER=https://test-api.endorser.ch VITE_DEFAULT_PARTNER_API_SERVER=https://test-partner-api.endorser.ch VITE_DEFAULT_IMAGE_API_SERVER=https://test-image-api.timesafari.app +VITE_DEFAULT_NOTIFY_API_SERVER=https://test-notify-api.timesafari.app VITE_APP_SERVER=https://test.timesafari.app ``` @@ -1689,6 +1693,7 @@ VITE_APP_SERVER=https://test.timesafari.app VITE_DEFAULT_ENDORSER_API_SERVER=https://api.endorser.ch VITE_DEFAULT_PARTNER_API_SERVER=https://partner-api.endorser.ch VITE_DEFAULT_IMAGE_API_SERVER=https://image-api.timesafari.app +VITE_DEFAULT_NOTIFY_API_SERVER=https://notify-api.timesafari.app VITE_APP_SERVER=https://timesafari.app ``` @@ -1946,6 +1951,7 @@ The build system supports multiple environment file patterns: VITE_DEFAULT_ENDORSER_API_SERVER=https://api.endorser.ch VITE_DEFAULT_PARTNER_API_SERVER=https://partner-api.endorser.ch VITE_DEFAULT_IMAGE_API_SERVER=https://image-api.timesafari.app +VITE_DEFAULT_NOTIFY_API_SERVER=https://notify-api.timesafari.app # Platform Configuration VITE_PLATFORM=web|electron|capacitor diff --git a/doc/android-physical-device-guide.md b/doc/android-physical-device-guide.md index 22ddba76..96c27f33 100644 --- a/doc/android-physical-device-guide.md +++ b/doc/android-physical-device-guide.md @@ -135,6 +135,7 @@ Create or edit `.env.development` with your computer's IP: VITE_DEFAULT_ENDORSER_API_SERVER=http://192.168.1.100:3000 VITE_DEFAULT_PARTNER_API_SERVER=http://192.168.1.100:3000 VITE_DEFAULT_IMAGE_API_SERVER=https://test-image-api.timesafari.app +VITE_DEFAULT_NOTIFY_API_SERVER=https://test-notify-api.timesafari.app VITE_APP_SERVER=http://192.168.1.100:8080 ``` diff --git a/doc/local-android-testing-ngrok.md b/doc/local-android-testing-ngrok.md index 2f18990d..00a9754d 100644 --- a/doc/local-android-testing-ngrok.md +++ b/doc/local-android-testing-ngrok.md @@ -275,9 +275,9 @@ Before ngrok end-to-end testing, confirm: ## 6. Configure the Notification Debug Panel backend override -The app normally calls `APP_SERVER` (from `VITE_APP_SERVER`). For local wakeup testing, override the notification API base URL without rebuilding. +The app normally calls `DEFAULT_NOTIFY_API_SERVER` (from `VITE_DEFAULT_NOTIFY_API_SERVER`, falling back to `AppString.PROD_NOTIFY_API_SERVER`). That is independent of `APP_SERVER`. For local wakeup testing, override the notification API base URL in the Debug Panel without rebuilding. -For a full panel reference (configuration, authentication, and troubleshooting), see [notification-debug-panel.md](./notification-debug-panel.md). +For a full panel reference (configuration, URL resolution order, authentication, and troubleshooting), see [notification-debug-panel.md](./notification-debug-panel.md). ### Open the panel @@ -578,7 +578,7 @@ curl -sS -w "\nHTTP %{http_code}\n" "$BASE/health" 3. Confirm **Backend Status → URL** matches the saved ngrok host. 4. Enable **Test Mode** if using dev backend behavior. -**Expected outcome:** **Active** URL in the panel equals your ngrok `https://…` host. Subsequent app requests use that base (not production `APP_SERVER`) for `/notifications/register` and `/notifications/refresh`. +**Expected outcome:** **Active** URL in the panel equals your ngrok `https://…` host. Subsequent app requests use that base (not `DEFAULT_NOTIFY_API_SERVER`) for `/notifications/register` and `/notifications/refresh`. --- @@ -893,7 +893,7 @@ Compare with panel **Backend Status** and Event Log error text. **Verification:** Compare panel URL to current `ngrok http` **Forwarding** line; `curl -sS "$NEW_URL/health"`. -**Fixes:** Copy new HTTPS URL → **Save Backend URL** in panel; or clear override only if intentionally returning to `APP_SERVER`. +**Fixes:** Copy new HTTPS URL → **Save Backend URL** in panel; or clear override only if intentionally returning to `DEFAULT_NOTIFY_API_SERVER`. --- diff --git a/doc/local-ios-testing-ngrok.md b/doc/local-ios-testing-ngrok.md index 2c5a6866..12d982a9 100644 --- a/doc/local-ios-testing-ngrok.md +++ b/doc/local-ios-testing-ngrok.md @@ -281,9 +281,9 @@ Before ngrok end-to-end testing, confirm: ## 6. Configure the Notification Debug Panel backend override -The app normally calls `APP_SERVER` (from `VITE_APP_SERVER`). For local wakeup testing, override the notification API base URL without rebuilding. +The app normally calls `DEFAULT_NOTIFY_API_SERVER` (from `VITE_DEFAULT_NOTIFY_API_SERVER`, falling back to `AppString.PROD_NOTIFY_API_SERVER`). That is independent of `APP_SERVER`. For local wakeup testing, override the notification API base URL in the Debug Panel without rebuilding. -For a full panel reference (configuration, authentication, and troubleshooting), see [notification-debug-panel.md](./notification-debug-panel.md). +For a full panel reference (configuration, URL resolution order, authentication, and troubleshooting), see [notification-debug-panel.md](./notification-debug-panel.md). ### Open the panel @@ -507,7 +507,7 @@ Confirm parameters (token vs deviceId, auth headers) in that repo’s README or ### Stale ngrok URL - After restarting ngrok, update **Notification Backend URL** in the panel and tap **Save** -- Or clear override (empty field + Save) only if you intend to hit `APP_SERVER` again +- Or clear override (empty field + Save) only if you intend to hit `DEFAULT_NOTIFY_API_SERVER` again ### Plugin / JWT errors after refresh diff --git a/doc/notification-debug-panel.md b/doc/notification-debug-panel.md index ff49ee6c..0bba83b8 100644 --- a/doc/notification-debug-panel.md +++ b/doc/notification-debug-panel.md @@ -1,12 +1,50 @@ # Notification Debug Panel **Created:** 2026-07-07 +**Updated:** 2026-07-22 **Audience:** Developers testing notification registration, refresh, and WAKEUP_PING flows on native (iOS/Android) dev builds. The **Notification Debug Panel** is a dev-only UI for exercising the same notification orchestration paths the production app uses: FCM token registration, backend refresh, wakeup handling, and local schedule inspection. It does not duplicate scheduling logic. --- +## Notification API base URL + +Notification HTTP calls (`/notifications/register`, `/notifications/refresh`, `/debug/send-wakeup`, etc.) do **not** use `APP_SERVER`. They use a dedicated Notification API host, resolved at runtime by `getNotificationApiBaseUrl()` in `NotificationDebugConfig.ts`. + +### Configuration constants + +| Symbol | Location | Purpose | +|--------|----------|---------| +| `VITE_DEFAULT_NOTIFY_API_SERVER` | `.env.development` / `.env.test` / `.env.production` | Build-time default Notification API URL for that Vite mode (same pattern as other `VITE_DEFAULT_*` backends) | +| `DEFAULT_NOTIFY_API_SERVER` | `src/constants/app.ts` | Runtime constant: `import.meta.env.VITE_DEFAULT_NOTIFY_API_SERVER \|\| AppString.PROD_NOTIFY_API_SERVER` | +| `AppString.PROD_NOTIFY_API_SERVER` | `src/constants/app.ts` | Hardcoded production fallback: `https://notify-api.timesafari.app` | +| `AppString.TEST_NOTIFY_API_SERVER` | `src/constants/app.ts` | Hardcoded test host: `https://test-notify-api.timesafari.app` (for explicit UI/debug use; not the automatic fallback) | + +Production, test, and development builds get different Notification API URLs from their respective `.env.*` files. Runtime request code always goes through `DEFAULT_NOTIFY_API_SERVER` (via `getNotificationApiBaseUrl()`), not by reading the env var directly at each call site. + +Typical values today: + +| Build / env file | `VITE_DEFAULT_NOTIFY_API_SERVER` | +|------------------|----------------------------------| +| `.env.production` | `https://notify-api.timesafari.app` | +| `.env.test` | `https://test-notify-api.timesafari.app` | +| `.env.development` | `https://test-notify-api.timesafari.app` | + +### URL resolution order + +`getNotificationApiBaseUrl()` selects the base URL in this order: + +1. **Debug Panel backend override** — `localStorage` key `notificationDebug.backendBaseUrl` (set via **Save Backend URL** or `setBackendBaseUrl()`) +2. **`VITE_DEFAULT_NOTIFY_API_SERVER`** — baked into the build as part of `DEFAULT_NOTIFY_API_SERVER` +3. **`AppString.PROD_NOTIFY_API_SERVER`** — hardcoded fallback when the env var is unset (`https://notify-api.timesafari.app`) + +Clearing the Debug Panel override (empty field + Save) returns the app to step 2 / 3 (`DEFAULT_NOTIFY_API_SERVER`). The override never changes auth behavior by itself. + +`APP_SERVER` / `VITE_APP_SERVER` remain for deep links and the main app web host only — not for notification API traffic. + +--- + ## Access 1. Use a **non-production** build (for example `build:android:dev`, `build:ios:dev`, or `vite dev` with a non-`production` mode). @@ -23,7 +61,7 @@ Settings persist in `localStorage` via `NotificationDebugConfig.ts`: | Key | Default | Purpose | |-----|---------|---------| -| `notificationDebug.backendBaseUrl` | *(unset — use `APP_SERVER`)* | Override which notification server receives API calls | +| `notificationDebug.backendBaseUrl` | *(unset — use `DEFAULT_NOTIFY_API_SERVER`)* | Override which notification server receives API calls | | `notificationDebug.testMode` | `true` | Sent in JSON request bodies (`testMode: true/false`) | | `notificationDebug.bypassAuth` | `false` | When `true`, omit JWT `Authorization` headers on notification API calls | @@ -33,7 +71,7 @@ All notification API requests (`/notifications/register`, `/notifications/refres Paste a base URL (no trailing slash) and tap **Save Backend URL**. This changes **only** which server the app calls (`getNotificationApiBaseUrl()`). It does **not** disable JWT authentication. -Leave empty to use the built-in default (`APP_SERVER` from `VITE_APP_SERVER`). +Leave empty to use the configured build default (`DEFAULT_NOTIFY_API_SERVER`, from `VITE_DEFAULT_NOTIFY_API_SERVER` or `AppString.PROD_NOTIFY_API_SERVER`). The Debug Panel override still wins whenever a non-empty URL is saved. ### Test Mode @@ -59,9 +97,11 @@ The panel **Backend Status** section shows the active URL, `testMode`, and `bypa Example: `https://test-notify-api.timesafari.app` +On development and test builds, this host is already the default via `VITE_DEFAULT_NOTIFY_API_SERVER`. You can leave **Notification Backend URL** empty, or paste the same URL explicitly. + | Setting | Value | |---------|-------| -| **Notification Backend URL** | `https://test-notify-api.timesafari.app` | +| **Notification Backend URL** | Empty (use default) or `https://test-notify-api.timesafari.app` | | **Test Mode** | **ON** (if the server expects `testMode: true`) | | **Skip JWT Authentication** | **OFF** | @@ -175,8 +215,9 @@ See platform-specific guides for extended ngrok and FCM workflows: | File | Purpose | |------|---------| +| `src/constants/app.ts` | `DEFAULT_NOTIFY_API_SERVER`, `PROD_NOTIFY_API_SERVER`, `TEST_NOTIFY_API_SERVER` | | `src/components/dev/NotificationDebugPanel.vue` | Dev UI | -| `src/services/notifications/NotificationDebugConfig.ts` | Backend URL, testMode, bypassAuth persistence | +| `src/services/notifications/NotificationDebugConfig.ts` | Base URL resolution, testMode, bypassAuth persistence | | `src/services/notifications/notificationApiAuth.ts` | JWT vs unauthenticated headers | | `src/services/notifications/notificationApiDebugMode.ts` | Auth bypass gate | | `src/services/notifications/NotificationDebugService.ts` | Panel action handlers | diff --git a/docker/README.md b/docker/README.md index a4032778..69d9e0dc 100644 --- a/docker/README.md +++ b/docker/README.md @@ -133,6 +133,7 @@ VITE_DEFAULT_ENDORSER_API_SERVER=https://dev-api.endorser.ch VITE_DEFAULT_IMAGE_API_SERVER=https://dev-image-api.timesafari.app VITE_DEFAULT_PARTNER_API_SERVER=https://dev-partner-api.endorser.ch VITE_DEFAULT_PUSH_SERVER=https://dev.timesafari.app +VITE_DEFAULT_NOTIFY_API_SERVER=https://test-notify-api.timesafari.app VITE_PASSKEYS_ENABLED=true # .env.test @@ -141,6 +142,7 @@ VITE_DEFAULT_ENDORSER_API_SERVER=https://staging-api.endorser.ch VITE_DEFAULT_IMAGE_API_SERVER=https://staging-image-api.timesafari.app VITE_DEFAULT_PARTNER_API_SERVER=https://staging-partner-api.endorser.ch VITE_DEFAULT_PUSH_SERVER=https://staging.timesafari.app +VITE_DEFAULT_NOTIFY_API_SERVER=https://test-notify-api.timesafari.app VITE_PASSKEYS_ENABLED=true # .env.production @@ -149,6 +151,7 @@ VITE_DEFAULT_ENDORSER_API_SERVER=https://api.endorser.ch VITE_DEFAULT_IMAGE_API_SERVER=https://image-api.timesafari.app VITE_DEFAULT_PARTNER_API_SERVER=https://partner-api.endorser.ch VITE_DEFAULT_PUSH_SERVER=https://timesafari.app +VITE_DEFAULT_NOTIFY_API_SERVER=https://notify-api.timesafari.app VITE_PASSKEYS_ENABLED=true ```