# SeaHaven Dev Postman collection

This directory contains the complete SeaHaven backend **dev** API collection,
generated from the live OpenAPI contract. The generated collection currently
contains every operation in the contract (368 operations across 330 paths),
including all documented parameters, request bodies, schemas, and response
codes.

## Files

| File | Purpose |
| --- | --- |
| `SeaHaven-Dev.postman_collection.json` | Complete OpenAPI-derived Postman v2.1 collection, grouped by API tag |
| `SeaHaven-Dev.postman_environment.json` | Dev authentication environment with secret username, password, and reusable bearer token |
| `../scripts/generate-postman-collection.mjs` | Deterministic generator and coverage checker |

## Getting started

1. Import `SeaHaven-Dev.postman_collection.json` into Postman.
2. Import `SeaHaven-Dev.postman_environment.json` and select **SeaHaven - Dev**.
3. Enter the dev test account's `username` and `password` in the environment.
   They are empty and secret by default; never commit or share populated values.
4. Run **Setup → Authentication - Login**. The pre-request script clears any
   stale token, skips the request when either credential is missing, and never
   logs credentials. A successful response stores only its non-empty `token`
   field in the environment's `token` variable.
5. All generated API requests inherit collection-level `Bearer {{token}}`
   authentication. They reuse the captured token automatically.

## Generated requests and examples

Every OpenAPI operation is included under its first alphabetically sorted tag.
Path, query, and header parameters retain their required/optional status,
schema hint, and description. JSON request bodies use recursively generated
illustrative placeholders from local OpenAPI schemas; multipart requests use
form-data fields and mark binary fields as files. These examples are not live
records: replace placeholder values with a valid dev fixture before sending.
No response bodies, credentials, tokens, or other dev data are stored in this
repository.

The generated test script only checks that the response status is one of the
codes documented by OpenAPI. It does not assume every operation returns `200`.

## Regenerate or check coverage

From the backend repository root:

```bash
node scripts/generate-postman-collection.mjs
node scripts/generate-postman-collection.mjs --check
```

The generator fetches `https://api.dev.seahaven.com/swagger/v1/swagger.json`,
fails on a non-JSON/non-success response, and rewrites the collection and the
empty-credential environment deterministically. `--check` compares the checked
in collection with the current contract and verifies operation count, unique
operation keys, request-body coverage, Bearer inheritance, and the explicit
no-auth login exception.

## Safety

This collection is **dev-only**. Do not point it at staging or production. Keep
`username`, `password`, and `token` local to your Postman workspace; never mark
them shared, export them, or commit them. Review every illustrative body and
parameter before running a mutating request.