# Outlook Reader API v1

Baca kode OTP dan isi inbox akun Outlook/Hotmail langsung dari aplikasi atau bot kamu sendiri.

Base URL: `http://localhost:3010` (ganti dengan domain produksi)

---

## Ringkasan endpoint

| Method | Path | Auth | Fungsi |
| --- | --- | --- | --- |
| POST | `/api/v1/otp` | API key | Baca 1 akun, balikin OTP terbaru + seluruh pesan |
| POST | `/api/v1/otp/bulk` | API key | Sama, maks 25 akun dalam 1 request |
| POST | `/api/v1/check` | API key | Cek status akun LIVE / DIE / UNKNOWN |
| POST | `/api/v1/renew` | API key | Perbarui refresh_token |
| GET | `/api/v1/whoami` | API key | Status key + statistik pemakaian |
| POST | `/api/v1/keys/request` | — | Ajukan key (menunggu approval admin) |

---

## Autentikasi

Header di setiap request:

```
X-API-Key: rdr_8d69ffccbf494b02cc84e545b274299a...
```

Key disimpan sebagai hash SHA-256, hanya ditampilkan sekali saat dibuat.

---

## POST /api/v1/otp

### Body

| Field | Tipe | Keterangan |
| --- | --- | --- |
| `credentials` | string | `email\|password\|refresh_token\|client_id` (password diabaikan) |
| `email` | string | Alternatif: alamat email |
| `refresh_token` | string | Alternatif: refresh token OAuth2 |
| `client_id` | string | Alternatif: client ID Azure AD |
| `mode` | string | `oauth2` (default, scope Mail.Read) atau `graph` (scope .default) |
| `top` | number | Jumlah pesan, default 20, maks 50 |

### Contoh

```bash
curl -X POST http://localhost:3010/api/v1/otp \
  -H "X-API-Key: rdr_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"credentials":"user@outlook.com|pass|M.C5_SN1...|9e5f94bc-..."}'
```

### Response 200

```json
{
  "success": true,
  "email": "user@outlook.com",
  "modeUsed": "oauth2",
  "code": "482913",
  "codeSource": {
    "subject": "Your verification code",
    "from": "Microsoft account team",
    "fromEmail": "account-security-noreply@microsoft.com",
    "receivedAt": "2026-08-18T05:22:41Z"
  },
  "messageCount": 20,
  "messages": [
    {
      "subject": "Your verification code",
      "from": "Microsoft account team",
      "fromEmail": "account-security-noreply@microsoft.com",
      "date": "2026-08-18T05:22:41Z",
      "preview": "Use code 482913 to sign in...",
      "body": "Use code 482913 to sign in.",
      "isRead": false
    }
  ]
}
```

`code` bernilai `null` kalau tidak ada kode terdeteksi. Bukan error — cek `messages`.

---

## POST /api/v1/otp/bulk

```bash
curl -X POST http://localhost:3010/api/v1/otp/bulk \
  -H "X-API-Key: rdr_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"credentials":"user1@outlook.com|pass|rt1|cid\nuser2@outlook.com|pass|rt2|cid"}'
```

```json
{
  "success": true,
  "count": 2,
  "results": [
    { "email": "user1@outlook.com", "success": true, "code": "482913", "messageCount": 20, "messages": [] },
    { "email": "user2@outlook.com", "success": false, "error": "Account rejected by Microsoft: ..." }
  ]
}
```

Response selalu `200` selama request valid; kegagalan per akun ada di `success: false`.

---

## POST /api/v1/check

```json
{
  "success": true,
  "total": 2,
  "counts": { "live": 1, "die": 1, "unknown": 0 },
  "results": [
    { "email": "user1@outlook.com", "status": "LIVE", "modeUsed": "oauth2" },
    { "email": "user2@outlook.com", "status": "DIE" }
  ]
}
```

- `LIVE` — token valid, inbox bisa dibaca
- `DIE` — token ditolak Microsoft (kedaluwarsa/dicabut/password diganti), bukan berarti akun banned
- `UNKNOWN` — gagal jaringan/timeout, coba ulang

---

## POST /api/v1/renew

```json
{
  "success": true,
  "count": 1,
  "results": [
    {
      "email": "user@outlook.com",
      "success": true,
      "refreshToken": "M.C5_new...",
      "credentials": "user@outlook.com|pass|M.C5_new...|9e5f94bc-..."
    }
  ]
}
```

---

## GET /api/v1/whoami

```json
{
  "success": true,
  "label": "budi-reseller",
  "rateLimitPerMin": 60,
  "requestCount": 128,
  "lastUsedAt": "2026-08-18T05:46:46Z",
  "createdAt": "2026-08-10T09:00:00Z"
}
```

---

## Rate limit

60 request/menit per key, dihitung per request (bukan per akun). Kena limit:

```
HTTP/1.1 429 Too Many Requests
Retry-After: 42

{"success": false, "error": "Rate limit exceeded (60 req/min). Retry after 42s."}
```

Pakai `/api/v1/otp/bulk` untuk banyak akun: 25 akun = 1 request.

---

## Kode error

| Status | Arti |
| --- | --- |
| 400 | Request tidak valid |
| 401 | API key kosong/salah/dicabut |
| 410 | Public link kedaluwarsa |
| 422 | Akun ditolak Microsoft |
| 429 | Rate limit |
| 502 | Graph API gangguan |
| 500 | Server error |

Semua error: `{ "success": false, "error": "..." }`

---

## Polling (bukan webhook)

API bersifat pull. Pantau inbox = panggil, tunggu, panggil lagi. Interval diatur di bot.

```js
// monitor.js — Node 18+
const API = 'http://localhost:3010/api/v1/otp';
const KEY = process.env.OUTLOOK_READER_KEY;
const ACCOUNT = process.env.ACCOUNT;
const seen = new Set();
let primed = false;

async function tick() {
  try {
    const res = await fetch(API, {
      method: 'POST',
      headers: { 'X-API-Key': KEY, 'Content-Type': 'application/json' },
      body: JSON.stringify({ credentials: ACCOUNT }),
    });
    if (res.status === 429) {
      const wait = Number(res.headers.get('Retry-After')) || 30;
      return setTimeout(tick, wait * 1000);
    }
    const data = await res.json();
    for (const m of (data.messages || [])) {
      const id = `${m.subject}|${m.date}|${m.fromEmail}`;
      if (seen.has(id)) continue;
      seen.add(id);
      if (!primed) continue;
      if (/verification|security|kode/i.test(m.subject || '')) console.log('ALERT:', m.subject);
    }
    primed = true;
  } catch (e) {
    console.error(e.message);
  }
  setTimeout(tick, 5000);
}
tick();
```

Rumus: `req/menit = (60 / interval_detik) × request_per_putaran`, jaga di bawah 60.

---

## Brief untuk AI

```
Buatkan bot pemantau inbox berdasarkan Outlook Reader API v1.

Base URL: <isi>
Endpoint:
- POST /api/v1/otp        baca 1 akun, balikin OTP terbaru + seluruh pesan
- POST /api/v1/otp/bulk   sama, sampai 25 akun dalam 1 request
- POST /api/v1/check      cek status akun LIVE/DIE/UNKNOWN
- GET  /api/v1/whoami     cek status + kuota key

Aturan:
- Auth header X-API-Key, baca dari environment variable, jangan di-log.
- Kredensial: email|password|refresh_token|client_id di field JSON "credentials".
- Pull, bukan push. Polling di sisi bot.
- Rate limit 60 req/menit per key. Banyak akun -> /otp/bulk.
- Dedup pesan: subject+date+fromEmail. Putaran pertama seed tanpa alert.
- Tangani 400/401/422/429 (Retry-After)/502.
```
