Merge dev into production release without education
This commit is contained in:
commit
fc541f024d
50 files changed
+2986
-458
No files matched your search
+46
-1
@@ -1,5 +1,30 @@
|
||||
# FlockPal API Reference
|
||||
|
||||
## Customer integration reference
|
||||
|
||||
The interactive customer API reference is available at **`/api/docs/`** on your
|
||||
FlockPal instance (locally, `http://localhost:5000/api/docs/`). Download the
|
||||
OpenAPI 3.0 specification at **`/api/openapi.json`**. There is also a link in
|
||||
Settings → Integration tokens.
|
||||
|
||||
Create an integration token in Settings, then paste it into Swagger's **Authorize**
|
||||
dialog without the `Bearer` prefix. Use `read_only` for reading or `read_write`
|
||||
for changes. Tokens apply to their originating workspace and the creator's
|
||||
current membership permissions. Swagger's **Try it out** makes real API requests.
|
||||
|
||||
The customer reference covers integration-token endpoints only. The broader
|
||||
application reference below also includes browser-session and administrative APIs.
|
||||
|
||||
### Maintaining the interactive reference
|
||||
|
||||
- Request validators live in `backend/src/schemas.ts` and are shared with route handlers.
|
||||
- Customer operations are explicitly registered in `backend/src/docs/openapi.ts`.
|
||||
- Response models live in `backend/src/docs/responses.ts`; update them when serialized responses change.
|
||||
- `backend/src/docs/openapi.test.ts` validates OpenAPI, compares customer coverage against actual route middleware, and checks locally served Swagger assets and security headers.
|
||||
- Run `npm run build` and `npm test` in `backend` after changes.
|
||||
- The Zod-to-OpenAPI dependency is pinned to the Zod 3-compatible release; upgrade both together.
|
||||
|
||||
|
||||
This document describes the HTTP API currently implemented in `backend/src/app.ts`.
|
||||
|
||||
## Base URLs
|
||||
@@ -966,7 +991,7 @@ Possible errors:
|
||||
|
||||
#### `DELETE /api/birds/:birdId`
|
||||
|
||||
Requires auth with write access and role `owner`, `assistant`, or `caregiver`. Deletes a bird.
|
||||
Requires auth with write access and role `owner`, `assistant`, or `caregiver`. Removes the bird from its current flock without deleting its profile, photo, or care history. Bird-specific notes stay with the bird. Public sharing is disabled and pending transfers are revoked. Workspace audit logs and flock-wide notes remain in the source flock.
|
||||
|
||||
Response `204` with no body.
|
||||
|
||||
@@ -974,6 +999,22 @@ Possible errors:
|
||||
|
||||
- `404` if the bird does not exist in the active workspace
|
||||
|
||||
#### `GET /api/birds/unassigned-match?tagId=…`
|
||||
|
||||
Requires auth and role `owner`, `assistant`, or `caregiver`. Returns `{ "available": true }` only for an unassigned, non-memorialized bird whose band ID matches exactly after trimming and ignoring letter case. No profile, history, or former-flock details are disclosed. Blank/unknown IDs return `400`; partial IDs do not match.
|
||||
|
||||
#### `POST /api/birds/claim`
|
||||
|
||||
Requires auth with write access and role `owner`, `assistant`, or `caregiver`.
|
||||
|
||||
```json
|
||||
{ "tagId": "BAND-123", "confirmHistory": true }
|
||||
```
|
||||
|
||||
Returns `200` with `{ "bird": { ... }, "historyImported": true }`. Adds the existing unassigned bird to the current flock using its saved profile and history. The bird's ID and photo are preserved; bird-specific notes follow it. Public sharing remains disabled until explicitly enabled. Competing requests are serialized so only one flock can claim a bird.
|
||||
|
||||
Returns `400` without explicit history confirmation, or `409` if no matching unassigned bird remains. Creating a new profile via `POST /api/birds` with an unassigned bird's band ID returns `409` with code `bird_history_available` instead of duplicating or overwriting its profile.
|
||||
|
||||
### Weights
|
||||
|
||||
#### `GET /api/birds/:birdId/weights`
|
||||
@@ -1299,3 +1340,7 @@ curl -X POST http://localhost:5000/api/auth/magic-link/request \
|
||||
curl http://localhost:5000/api/auth/session \
|
||||
-H 'Authorization: Bearer YOUR_SESSION_TOKEN'
|
||||
```
|
||||
|
||||
### Behavior Journal
|
||||
|
||||
Behavior types and occurrences are available under `/birds/{birdId}/behavior-types` and `/birds/{birdId}/behaviors`. The interactive reference documents request/response schemas and permissions. See [Behavior Journal](BEHAVIOR_JOURNAL.md) for timestamp semantics, flock scoping, and isolated workflow tests.
|
||||
@@ -0,0 +1,68 @@
|
||||
# Behavior Journal
|
||||
|
||||
Open **Flock → select a bird → Behavior Journal** (calendar tab). Select a behavior or create a custom one, confirm the current date/time, and save. Duration in seconds, intensity from 1–5, and notes are optional. Open a day's occurrence to see its details, edit it, or delete it with confirmation.
|
||||
|
||||
The bird and behavior selectors filter the journal. The calendar displays one month at a time, daily counts and up to three dots (plus a `+` for additional events). Select a day to review its individual events. The count above the calendar reflects the selected behavior and displayed month.
|
||||
|
||||
## Storage and access
|
||||
|
||||
The existing `ensureSchema` startup migration creates `behavior_types` and `behavior_occurrences` and idempotently seeds nine common behaviors. No separate migration command is required. Occurrences reference existing birds and normalized behavior types. They retain `TIMESTAMPTZ` occurrence, created, and updated timestamps; optional duration in seconds; optional intensity; and notes. Indexes support bird/date and bird/behavior/date queries.
|
||||
|
||||
Custom behavior names are reusable within a flock and unique ignoring case. Default types are explicitly marked so orphaned custom types never become public. A transferred bird retains its occurrences and the types used in those occurrences, even if its old flock is deleted. Other custom types from its former flock remain private.
|
||||
|
||||
Existing session/integration-token authentication, flock roles, subscription restrictions, memorialized-bird restrictions, and audit logging apply. Owners, assistants, and caregivers can record/edit/delete; viewers can read. Queries and mutations check the bird's current flock. Writes also check flock ownership and memorialization inside the SQL statement.
|
||||
|
||||
The browser uses its device time zone for entry and calendar grouping, consistently with local date/time controls. Month boundaries are converted to UTC for the API's inclusive `from`, exclusive `to` range. Stored timestamps are not replaced by dates or daily totals. An unchanged edit retains the original timestamp, including sub-second precision. During a daylight-saving repeated hour, a newly entered ambiguous local time uses the browser's earlier offset; an existing event retains its original instant when its time is unchanged.
|
||||
|
||||
This feature records observations and occurrence timing. It adds no diagnostic interpretation or behavioral analysis.
|
||||
|
||||
## API
|
||||
|
||||
The interactive API reference includes these endpoints:
|
||||
|
||||
| Method | Path | Purpose |
|
||||
| --- | --- | --- |
|
||||
| GET | `/api/birds/:birdId/behavior-types` | Available default, flock, and transferred-history types |
|
||||
| POST | `/api/birds/:birdId/behavior-types` | Create/reuse a custom type (`name`, optional `description`) |
|
||||
| GET | `/api/birds/:birdId/behaviors?from=…&to=…&behaviorTypeId=…` | Events in a positive range of at most 32 days; optional type filter |
|
||||
| POST | `/api/birds/:birdId/behaviors` | Create an occurrence |
|
||||
| PUT | `/api/birds/:birdId/behaviors/:occurrenceId` | Replace the editable fields |
|
||||
| DELETE | `/api/birds/:birdId/behaviors/:occurrenceId` | Delete an occurrence |
|
||||
|
||||
Occurrence input: `behaviorTypeId`, offset-bearing `occurredAt`, optional/null `durationSeconds` (positive, at most one year), `severity` (integer 1–5), and `notes` (at most 10,000 characters). Responses include the behavior name and timestamps, allowing complete details to open without another request.
|
||||
|
||||
## Isolated verification
|
||||
|
||||
Use a disposable copy/install when the local dependency or build directories belong to a container. Do not point these scripts at a real flock database. The integration scripts use fixed test-only database settings on port 55439 and API port 55440. They create fixtures with distinct flock IDs and leave them in the disposable database for inspection.
|
||||
|
||||
```sh
|
||||
docker run --detach --rm --name flockpal-behavior-test-db \
|
||||
-e POSTGRES_PASSWORD=behavior_test_only -e POSTGRES_DB=behavior_test \
|
||||
-p 127.0.0.1:55439:5432 postgres:16-alpine
|
||||
cd backend
|
||||
npm ci
|
||||
npm run build
|
||||
npm test
|
||||
node test-integration/behaviorJournal.mjs
|
||||
```
|
||||
|
||||
The API integration check covers schema repeatability, seeded/custom types, duplicate custom names, independent events, create/edit/delete, bird/behavior/month filters, timestamp precision, invalid inputs, unauthenticated requests, viewer/read-only/memorialized restrictions, cross-flock access, and transfer history.
|
||||
|
||||
For the optional browser check, install Playwright in a disposable frontend install (it is not an application dependency), with the built backend alongside it:
|
||||
|
||||
```sh
|
||||
cd ../frontend
|
||||
npm ci
|
||||
npm run build
|
||||
npm install --no-save --package-lock=false playwright
|
||||
npx playwright install chromium
|
||||
node test-integration/behaviorJournal.mjs
|
||||
```
|
||||
|
||||
The browser check starts and stops its own API and Vite server (port 55441). It covers the complete entry/custom behavior/edit/delete workflow, bird and behavior filters, day selection and daily counts, month navigation, local midnight and daylight-saving boundaries, and a 390px mobile layout. It writes screenshots to `/tmp/flockpal-behavior-mobile.png` and `/tmp/flockpal-behavior-desktop.png`.
|
||||
|
||||
After verification, stop only the disposable database:
|
||||
|
||||
```sh
|
||||
docker stop flockpal-behavior-test-db
|
||||
```
|
||||
@@ -0,0 +1,50 @@
|
||||
# Removing and re-adding a bird
|
||||
|
||||
**Remove from flock** now unassigns the bird. It does not delete the bird profile, photo, weights, vet visits, medication/dose records, Behavior Journal, timeline, or bird-specific notes.
|
||||
|
||||
The bird disappears from the old flock's lists and care-record access. Its public profile is disabled, open transfer codes are revoked, and pending transfers are cancelled. Existing reminders find birds through their current flock, so unassigned birds do not enter future reminder selections. Removal is recorded in the bird timeline and the old flock's audit log.
|
||||
|
||||
Bird-specific notes follow the bird. Flock-wide notes and workspace audit history stay with the original flock. Removal and claiming keep the bird's ID, so care history is preserved without copying or combining records.
|
||||
|
||||
## Adding an existing unassigned bird
|
||||
|
||||
In **Add bird**, enter the band ID. FlockPal checks for an unassigned, non-memorialized match after typing pauses. Matching follows the existing global band-ID convention: ignore surrounding whitespace and letter case, but otherwise require the entire ID. Blank/unknown placeholders and partial IDs cannot recover a bird.
|
||||
|
||||
A match displays a notice that the saved profile, photo, notes, and care history will be brought in, with an **Add bird with existing history** button. Confirmation is required. Saved profile details are used rather than overwriting them with draft fields. No new name or species is required for this path. Before confirmation, the lookup returns only availability, not the previous profile or flock details.
|
||||
|
||||
A bird already assigned to a flock cannot be claimed this way; use the existing transfer flow. Claims use a database row lock so simultaneous requests from different flocks cannot both succeed. Memorialized birds remain read-only.
|
||||
|
||||
Birds without band IDs can still be removed and retained, but they cannot be automatically recovered through the band-ID workflow. The removal confirmation explains this. Previously hard-deleted records cannot be restored by this change.
|
||||
|
||||
## Schema and API
|
||||
|
||||
The startup `ensureSchema` migration allows `birds.workspace_id` and bird-specific `flock_notes.workspace_id` to be null. Removal, note reassignment, transfer revocation, and timeline recording run in a transaction. Claiming and its note/timeline changes also run in a transaction. A failure rolls the entire change back.
|
||||
|
||||
The existing `DELETE /api/birds/:birdId` now removes flock membership and still returns `204`. New endpoints:
|
||||
|
||||
- `GET /api/birds/unassigned-match?tagId=…` returns `{ "available": true | false }`.
|
||||
- `POST /api/birds/claim` accepts `{ "tagId": "…", "confirmHistory": true }` and returns the existing bird plus `historyImported: true`.
|
||||
|
||||
Both require authenticated owner, assistant, or caregiver membership. Claiming also requires write access. Creating a new profile with an unassigned band's ID returns `409` / `bird_history_available`; it never overwrites history.
|
||||
|
||||
## Verification
|
||||
|
||||
Use the disposable PostgreSQL/API setup in [Behavior Journal testing](BEHAVIOR_JOURNAL.md#isolated-verification), then run:
|
||||
|
||||
```sh
|
||||
cd backend
|
||||
npm run build
|
||||
npm test
|
||||
node test-integration/birdMembership.mjs
|
||||
```
|
||||
|
||||
The integration check covers repeated schema startup, retained profile/photo/history, notes separation, source access removal, disabled sharing, transfer revocation, exact/case-insensitive band matching, explicit confirmation, role/billing restrictions, transaction rollback, and competing claims.
|
||||
|
||||
With Playwright installed in the disposable frontend install as described in that guide:
|
||||
|
||||
```sh
|
||||
cd frontend
|
||||
node test-integration/birdMembership.mjs
|
||||
```
|
||||
|
||||
The browser check exercises desktop removal, the mobile match notice, cancellation, confirmed recovery without replacement profile fields, and restored notes/timeline. It uses ports 55439–55441 and writes a notice screenshot to `/tmp/flockpal-existing-history-notice.png`. No real flock data is used.
|
||||
@@ -0,0 +1,34 @@
|
||||
# Weight reminder tests
|
||||
|
||||
From the repository root, run the unit tests and builds:
|
||||
|
||||
```bash
|
||||
npm ci --prefix backend
|
||||
npm ci --prefix frontend
|
||||
npm test --prefix backend
|
||||
npm run build --prefix backend
|
||||
npm run build --prefix frontend
|
||||
```
|
||||
|
||||
The integration test uses real Postgres 16, Redis 7, two worker processes, and
|
||||
Mailpit to capture SMTP messages locally. It requires Docker and free localhost
|
||||
ports 25432, 26379, 21025, and 28025. Port 21026 must remain unused for the SMTP
|
||||
failure check. Test addresses use `.test`; Mailpit does not relay mail externally.
|
||||
|
||||
```bash
|
||||
docker compose -p flockpal-weight-test -f backend/test-integration/compose.weight-reminders.yml up -d --wait
|
||||
node backend/test-integration/weightReminders.mjs
|
||||
docker compose -p flockpal-weight-test -f backend/test-integration/compose.weight-reminders.yml down --volumes
|
||||
```
|
||||
|
||||
Always run the last command when finished, including after a failed test. Start
|
||||
fresh containers for each run. Postgres data is disposable and held in tmpfs.
|
||||
The test overrides database, Redis, and SMTP environment variables to use only
|
||||
these local services. It does not use the application's configured SMTP account.
|
||||
|
||||
Coverage includes repeatable schema initialization, overdue and recent weights,
|
||||
birds without weights, memorial exclusions, accepted care roles, concurrent
|
||||
claims, one daily job across two workers, removal of the old five-minute schedule, grouped emails, embedded branding and portraits, HTML escaping, flock
|
||||
isolation, daily repeats, fresh weight resets, SMTP failures and recovery,
|
||||
worker shutdown, and disabling the scheduler. Repeat timing is tested by aging
|
||||
delivery timestamps rather than waiting two days.
|
||||
Reference in new issue
Block a user