> **Client contract note:** Apply [`shared/response-envelope.md`](../shared/response-envelope.md) to JSON responses after the response-contract release. Legacy wrapper examples below may reflect the prior API; the documented endpoint-specific payload fields are still useful. Not staging-verified.

# Flutter — Push API | Complete source-reviewed module

**Repository:** `alalmiyalhura/outlet` (`main`, reviewed 2026-11-22). **Base path:** `/api/v1`. **Scope:** the Push module exposes exactly **one HTTP route**, `POST /push/test`. Device registration and notification preferences are separate modules; do not mistake them for Push-module routes. This is a source-code contract review, **not** a staging/FCM delivery certification.

## Endpoint inventory

| Method | Endpoint | Authentication | Throttle | HTTP success | Purpose |
|---|---|---|---|---|---|
| POST | `/api/v1/push/test` | `auth:sanctum` | 5 requests/minute (`throttle:5,1`) | 202 Accepted | Queue a test push for the signed-in user's registered devices |

## POST `/api/v1/push/test`

### Request contract

| Component | Field | Type | Required | Contract |
|---|---|---|---|---|
| Header | `Authorization` | string | Yes | `Bearer <access_token>` (Sanctum) |
| Header | `Accept` | string | Recommended | `application/json` |
| Query | — | — | No | Controller reads no query parameters |
| Path | — | — | No | No path parameters |
| Body | — | — | No | No JSON fields are read or validated |

```http
POST /api/v1/push/test HTTP/1.1
Authorization: Bearer <access_token>
Accept: application/json
```

### Response contract — `202 Accepted`

```json
{
  "data": {
    "queued": true
  }
}
```

| JSON path | Type | Required | Meaning |
|---|---|---|---|
| `data` | object | Yes | Standard API response envelope |
| `data.queued` | boolean | Yes | `true` means dispatch was requested, **not** that FCM or a device acknowledged receipt |

The controller queues a `PushMessage` with title `Test notification`, body `If you can read this, push works.`, and data `{ "type": "test" }`. These are **server-defined push-message values**, not fields the Flutter client sends.

### Error and retry handling

| HTTP | Code | Client action | Evidence |
|---|---|---|---|
| 401 | `unauthenticated` | Sign in / refresh session before retrying | Sanctum middleware and Core exception renderer |
| 429 | `too_many_attempts` | Respect `Retry-After` when present; do not rapidly retry | `throttle:5,1` middleware |
| 500 | `server_error` (generic unexpected error) | Display a retry option; log request ID | Core exception renderer; not a claim that every backend failure uses this code |

Typical Core error shape (values illustrative):

```json
{
  "error": {
    "code": "unauthenticated",
    "message": "Unauthenticated.",
    "request_id": null
  }
}
```

`PushRejected` declares a `push_rejected` domain code, but **this controller does not explicitly throw it**; do not treat it as a guaranteed response of this endpoint.

## Delivery lifecycle and Flutter implementation

1. Register the device token through the **Devices** module first. This endpoint does **not** register or refresh tokens.
2. Call `POST /push/test` while signed in. Show **“Test notification queued”**, not **“Delivered”**, on HTTP 202.
3. Wait for the actual foreground/background notification callback in Flutter to confirm reception; a 202 response alone cannot prove it.
4. `PushService::notify()` delegates to `PushQueue`. `QueuePushDispatcher` dispatches `DeliverPushJob` after transaction commit.
5. The queued job loads tokens belonging to the target user; if there are none, the delivery path returns without sending. Thus **202 is possible with zero registered devices**.
6. The FCM gateway classifies invalid tokens for removal and retryable failures for rescheduling. The default push configuration is `max_attempts=4`, `backoff=[30,120,600]` seconds; these are **server internals**, not a client retry schedule.
7. Backend driver may be `null`, `log`, or `fcm` (`PUSH_DRIVER`, default `null` in source). Successful HTTP response therefore **does not prove production FCM is configured**.
8. Real notification delivery and opt-out preferences are covered by the Notifications and Devices modules, not this test endpoint.

### Flutter pseudocode

```dart
final response = await dio.post('/api/v1/push/test');
if (response.statusCode == 202 && response.data['data']?['queued'] == true) {
  showQueuedMessage(); // Do NOT mark as received yet.
}
```

## Source traceability and verification boundary

| Source | What was checked |
|---|---|
| `modules/Push/Routes/api.php` | Only exposed route; Sanctum and 5/min throttle |
| `modules/Push/Interfaces/Http/Controllers/PushTestController.php` | No request inputs; test payload; 202 response |
| `modules/Push/Application/PushService.php` | Queue dispatch; delivery to registered tokens; dead-token cleanup |
| `modules/Push/Infrastructure/QueuePushDispatcher.php` | After-commit job dispatch |
| `modules/Push/Infrastructure/DeliverPushJob.php` | Retry-only transient failures; configured attempt limit |
| `modules/Push/Config/push.php` | Driver modes, retry defaults, FCM settings |
| `modules/Push/Tests/PushTest.php` | Repository tests cover test endpoint, FCM token handling and notification opt-out; tests were **read, not executed** |

**Source-review status:** 1/1 Push-module HTTP endpoints covered, with complete request/response contract. **Operational status:** staging request, queue-worker execution, registered-device delivery and real FCM reception **not tested in this review**.
