f7push/README.md

# F7 Push

Mobile push delivery for **F7cloud** accounts via Firebase Cloud Messaging.

Portable: install on any F7cloud server, configure via `occ`, no hardcoded hostnames.

## Architecture

```text
F7cloud app (f7support, spreed, …)
        │
        ▼
   f7push (this app) ──FCM HTTP v1──► Google FCM ──► Android APK (WebView)
        ▲                                      │
        └──── POST /devices (user session) ──────┘
              APK registers FCM token per account
```

- **Server:** f7push stores devices in `oc_f7push_devices`, sends via Firebase service account.
- **Client:** WebView APK (`android-webview`) registers token after login using WebView cookies.
- **FCM:** free transport layer; required for reliable background push on stock Android.

## Install on a server

```bash
git clone git@git.f7cloud.ru:root/f7push.git /var/www/f7cloud/apps/f7push
cd /var/www/f7cloud
sudo -u www-data php occ app:enable f7push
```

Database table `oc_f7push_devices` is created by migration on enable/upgrade.

## Setup checklist (new instance)

| Step | Action |
|------|--------|
| 1 | Clone repo → `apps/f7push`, `occ app:enable f7push` |
| 2 | Firebase project + Android app `ru.forbion.f7cloud` → `google-services.json` into APK (see android-webview README) |
| 3 | Firebase service account JSON → `occ config:app:set f7push firebase_*` |
| 4 | Build & install APK; user logs in and grants notifications |
| 5 | Test: `POST …/push/test` or send from Firebase Console |

### forbion.f7cloud.ru (May 2026)

| Item | Status |
|------|--------|
| f7push v0.1.0 enabled | done |
| `oc_f7push_devices` table | done |
| Firebase project **F7push** (`project_id`: `f7push`) | done |
| APK `google-services.json` + release build v1.5 | done |
| `firebase_project_id` + `firebase_credentials` in occ | done |
| End-to-end push test on device | **pending** |
| `F7_PUSH_SECRET` / webhook for support API | done |

## Configuration (`occ`)

```bash
# Enable / disable
sudo -u www-data php occ config:app:set f7push enabled --value=yes

# Firebase — from Project settings → Service accounts → Generate new private key
sudo -u www-data php occ config:app:set f7push firebase_project_id --value=f7push
sudo -u www-data php occ config:app:set f7push firebase_credentials --value="$(cat /path/to/service-account.json)"

# Optional: default URL when notification has no link
sudo -u www-data php occ config:app:set f7push default_click_url --value=https://YOUR-SERVER.f7cloud.ru

# Filter sources (comma-separated app ids, or * for all)
sudo -u www-data php occ config:app:set f7push enabled_sources --value='spreed,f7support,files'

# Relay F7cloud bell notifications to push
sudo -u www-data php occ config:app:set f7push listen_notifications --value=yes

# API secret — shared with support.f7cloud.ru as F7_PUSH_SECRET
sudo -u www-data php occ config:app:set f7push api_secret --value='YOUR_SECRET'
# Or regenerate (also updates f7support push_webhook_secret):
bash scripts/generate-secret.sh --regenerate
sudo -u www-data php occ config:app:set f7support push_webhook_secret --value="$(sudo -u www-data php occ config:app:get f7push api_secret)"
```

**Secrets:** never commit `firebase_credentials`, `api_secret`, `F7_PUSH_SECRET`, or `google-services.json` to git.

### support.f7cloud.ru → F7cloud push

When a support agent replies to a ticket, **support API** calls f7support webhook:

```env
# support server .env
F7_PUSH_SECRET=<same as f7push api_secret>
F7_PUSH_URL=https://YOUR-SERVER.f7cloud.ru/ocs/v2.php/apps/f7support/api/v1/push
```

```http
POST …/apps/f7support/api/v1/push
X-F7-Push-Secret: <F7_PUSH_SECRET>
Content-Type: application/json

{ "userId": "…", "ticketNumber": "…", "ticketSubject": "…", "body": "…" }
```

See **f7support** repo: `README.md`, `push.env.example`.

Verify configuration:

```bash
sudo -u www-data php occ config:app:get f7push firebase_project_id
curl -H 'OCS-APIRequest: true' -H 'Accept: application/json' \
  'https://YOUR-SERVER/ocs/v2.php/apps/f7push/api/v1/status'
```

## API (OCS)

Base: `/ocs/v2.php/apps/f7push/api/v1/`

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/devices` | User session | Register FCM token |
| DELETE | `/devices/{deviceId}` | User session | Unregister device |
| GET | `/devices` | User session | List own devices |
| GET | `/status` | Public | Push enabled / Firebase configured |
| POST | `/push` | `X-F7-Push-Secret` | Send push to user account |
| POST | `/push/test` | User session | Test push to own devices |

### Register device (APK)

```json
POST /ocs/v2.php/apps/f7push/api/v1/devices
Header: OCS-APIRequest: true
Cookie: <WebView session>

{
  "deviceId": "uuid-generated-by-apk",
  "fcmToken": "...",
  "platform": "android",
  "clientApp": "f7cloud-apk"
}
```

### Send push (f7support / other apps)

```json
POST /ocs/v2.php/apps/f7push/api/v1/push
Header: X-F7-Push-Secret: <secret>

{
  "userId": "username",
  "title": "Support",
  "body": "New reply",
  "url": "https://server/apps/f7support",
  "source": "f7support",
  "priority": "normal"
}
```

## Android APK

Path on forbion: `/var/www/f7cloud/android-webview/`  
Build docs: `README_ANDROID_BUILD.md` in that directory.

1. Place Firebase `google-services.json` in `android-webview/app/`.
2. `./gradlew assembleRelease` → install APK on device.
3. User logs into F7cloud in WebView; device appears in `GET /devices`.

APK v1.5 (versionCode 6): `F7PushRegistrar`, `F7FirebaseMessagingService`, channel `f7cloud_default`.

## Development workflow

```bash
# Edit in git clone
cd /root/git-sync/f7push
# … changes …
rsync -a --delete /root/git-sync/f7push/ /var/www/f7cloud/apps/f7push/
sudo -u www-data php occ app:enable f7push   # or upgrade if version bumped
git add -A && git commit -m "…" && git push origin master
```

## Version

0.1.0 — device registry, FCM send, notification relay, OCS API.