# Token Notifikasi Push

Pendaftaran token Firebase Cloud Messaging (FCM) milik instalasi aplikasi, supaya server nanti dapat
mengirim notifikasi push ke karyawan yang sedang login. Konvensi umum ada di [README.md](README.md).

| Atribut | Nilai |
|---|---|
| Endpoint | `PUT /me/push-token`, `DELETE /me/push-token` |
| Sumber kode | `PushTokenController`, `RegisterPushTokenRequest`, `PushTokenResource`, `PushTokenService`, model `PushToken` (tabel `push_tokens`) |
| Contoh direkam | 2026-11-15 21:05 WIB, HTTP kernel Laravel, basis data MySQL sekali pakai berisi dua perusahaan (`nusantara-logistik` WIB, `borneo-retail` WITA), `APP_LOCALE=id` |
| Data uji | Token FCM di contoh adalah string uji berformat FCM, bukan token perangkat sungguhan |

Seluruh endpoint di berkas ini wajib token (`Authorization: Bearer <token>`) dan melewati
`auth:sanctum` + `EnsureSubscriptionActive`.

> **Status pengiriman:** server baru **menyimpan** token. Pengiriman notifikasi push belum aktif karena
> kredensial Firebase (service account) belum dipasang di server. Aplikasi tetap wajib mendaftarkan token
> sekarang agar pengiriman langsung berjalan begitu server siap, tanpa rilis aplikasi baru.

---

## Kapan client memanggil

| Peristiwa di aplikasi | Panggilan |
|---|---|
| Login berhasil (termasuk login perangkat pinjaman) | `PUT /me/push-token` dengan token FCM saat ini |
| `FirebaseMessagingService.onNewToken()` selama masih login | `PUT /me/push-token` dengan token baru |
| Pengguna mematikan notifikasi di pengaturan aplikasi | `DELETE /me/push-token` |
| Logout | cukup `POST /auth/logout`; token push ikut terhapus di server |

Token push terikat ke **token login (Sanctum) yang dipakai saat mendaftar**, bukan ke karyawan secara
umum. Akibatnya:

- Logout, ganti kata sandi (`PUT /me/password` mencabut seluruh token login), login ulang di perangkat
  yang sama, dan berakhirnya perangkat pinjaman otomatis menghapus token push sesi itu. Karena itu client
  wajib mendaftar ulang **setiap kali login**.
- Satu sesi login menyimpan satu token push. Mendaftar lagi mengganti token sebelumnya.
- Bila token FCM yang sama didaftarkan dari sesi lain **di perusahaan yang sama** (aplikasi yang sama
  dipakai karyawan lain, mis. perangkat pinjaman), baris lama dihapus. Notifikasi karyawan sebelumnya
  tidak pernah sampai ke orang yang kini memegang perangkat.

---

## Daftarkan token

**`PUT /me/push-token`**

Deskripsi: menyimpan atau mengganti token FCM untuk sesi login saat ini. Idempoten: mengirim token yang
sama berulang kali tetap menghasilkan satu baris.

| Auth & Middleware | |
|---|---|
| Token | ya |
| Middleware | `auth:sanctum`, `EnsureSubscriptionActive` |
| Route name | `api.v1.me.push-token.update` |

**Header:** `Accept: application/json`, `Content-Type: application/json`, `Authorization: Bearer <token>`

**Parameter** (`RegisterPushTokenRequest`)

| Nama | Lokasi | Tipe | Wajib | Aturan validasi (FormRequest) |
|---|---|---|---|---|
| `token` | body | string | ya | `required`, `min:20`, `max:512`, hanya huruf, angka, `_`, `:`, `-` |
| `app_version` | body | string | tidak | `nullable`, `max:50`. Tidak dikirim berarti `null` (nilai lama diganti) |

**Contoh Request**

```http
PUT /api/v1/me/push-token HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <token>

{
  "token": "eXm3Qd1RTPa9vK2LzA7bYc:APA91bHXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-Zq",
  "app_version": "1.0.0"
}
```

**Contoh Response Sukses** (`200`, 2026-11-15 21:05 WIB)

```json
{
  "success": true,
  "message": "Token notifikasi tersimpan.",
  "data": {
    "app_version": "1.0.0",
    "registered_at": "2026-11-15T14:05:55+00:00"
  }
}
```

**Field `data`**

| Field | Tipe | Null | Keterangan |
|---|---|---|---|
| `app_version` | string | ya | nilai `app_version` dari request terakhir |
| `registered_at` | string ISO 8601 UTC | tidak | waktu pendaftaran terakhir |

Token FCM sendiri tidak dikirim balik.

**Contoh Response Gagal**

Body kosong (`422`):

```json
{
  "success": false,
  "message": "Data yang dikirim tidak lolos pemeriksaan.",
  "errors": {
    "token": [
      "Kolom token notifikasi wajib diisi."
    ]
  }
}
```

Format token salah, `{"token": "bukan token fcm!"}` (`422`):

```json
{
  "success": false,
  "message": "Data yang dikirim tidak lolos pemeriksaan.",
  "errors": {
    "token": [
      "Kolom token notifikasi minimal 20 karakter.",
      "Format token notifikasi tidak dikenali."
    ]
  }
}
```

Tanpa token login (`401`):

```json
{
  "success": false,
  "message": "Token tidak sah atau sudah kedaluwarsa. Silakan masuk kembali.",
  "errors": {}
}
```

Langganan perusahaan terkunci: `402`, lihat README bagian 5.1.

---

## Hapus token

**`DELETE /me/push-token`**

Deskripsi: menghapus token FCM sesi login saat ini. Sesi login tetap berlaku. Idempoten: memanggil saat
belum ada token tetap dijawab `200`.

| Auth & Middleware | |
|---|---|
| Token | ya |
| Middleware | `auth:sanctum`, `EnsureSubscriptionActive` |
| Route name | `api.v1.me.push-token.destroy` |

**Header:** `Accept: application/json`, `Authorization: Bearer <token>`

**Parameter:** tidak ada.

**Contoh Request**

```http
DELETE /api/v1/me/push-token HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
```

**Contoh Response Sukses** (`200`, 2026-11-15 21:05 WIB)

```json
{
  "success": true,
  "message": "Token notifikasi dihapus.",
  "data": {}
}
```

**Contoh Response Gagal:** `401` dan `402` sama dengan `PUT /me/push-token`.

---

## Catatan untuk Client

- Jangan menyimpan status "sudah terdaftar" di perangkat lintas login. Setiap login adalah sesi baru dan
  wajib mendaftar ulang.
- Kegagalan `PUT /me/push-token` tidak boleh menghalangi pemakaian aplikasi. Coba lagi pada pembukaan
  aplikasi berikutnya.
- Isi notifikasi dan halaman tujuan (deep link) akan didokumentasikan saat pengiriman push diaktifkan.
