Inbox Real-time

Browser pengguna tidak boleh memegang API key. Sebagai gantinya, server Anda meminta token subscriber berumur pendek, lalu meneruskannya ke browser.

1. Pengguna membuka halaman Anda; server Anda memanggil POST /v1/subscribers/{id}/inbox-token memakai API key.
2. Notifora membalas JWT (berlaku 1 jam) bersama socket_url.
3. Browser membuka koneksi WebSocket dengan token tersebut. Server socket memverifikasi tanda tangan dan hanya mengizinkan akses ke inbox subscriber itu.

curl -X POST https://api.notifora.my.id/v1/subscribers/usr_102/inbox-token \
  -H "Authorization: Bearer $NOTIFORA_KEY"
# → { "data": { "token": "eyJ…", "expires_in": 3600, "socket_url": "wss://ws.notifora.my.id" } }

Saat token hampir habis, server socket mengirim event auth:expired lalu memutus koneksi; minta token baru dan sambungkan ulang.

Contoh integrasi minimal dengan socket.io-client:

import { io } from 'socket.io-client';

async function connectInbox() {
  // endpoint milik aplikasi Anda; di dalamnya memanggil POST /v1/subscribers/{id}/inbox-token
  const { token, socket_url } = await (await fetch('/api/notifora/inbox-token')).json();

  const socket = io(socket_url, { auth: { token }, transports: ['websocket'] });

  socket.on('unread:count', ({ unreadCount }) => setBadge(unreadCount));
  socket.on('notification:received', (m) => prependToList(m));        // { id, title, body, action_url, data, created_at }
  socket.on('notification:read', ({ ids }) => markRead(ids));
  socket.on('auth:expired', () => { socket.close(); connectInbox(); }); // ambil token baru

  return {
    markRead: (ids) => socket.emit('notification:mark_read', { ids }),
    markAll: () => socket.emit('notification:mark_read', { all: true }),
  };
}

• Render teks pesan dengan textContent / x-text, jangan innerHTML, untuk mencegah XSS dari konten notifikasi.
• Jika WebSocket gagal tersambung, gunakan polling GET /inbox setiap ±30 detik sebagai cadangan (lewat server Anda).
• Pesan baru tampil di browser kurang dari ±1 detik setelah dikirim.

Database tetap menjadi sumber kebenaran: penandaan dibaca diteruskan server socket ke Notifora, lalu hasilnya disiarkan ke seluruh koneksi subscriber itu.