Added behavior journal, adjusted layout, and added some colors
Deploy / deploy-prod (push) Skipped
Deploy / deploy-dev (push) Successful in 4m18s

This commit is contained in:
Corey Blais committed 2026-10-05 15:20:00 -04:00
1 parent b1b89ad334
commit 3237cd7601
31 files changed
+2134 -274

No files matched your search

+7
View File
@@ -272,3 +272,10 @@ This starter now includes the account and flock foundation for monetization, plu
Stripe billing should be attached to `workspaces`, not `users`. Each flock has its own billing plan, subscription status, Stripe customer ID, and Stripe subscription ID, which lets one person own multiple household flocks with separate subscriptions while rescue flocks can stay on the free rescue path.
For account design, `standard` vs `rescue` is best treated as a flock type, not as a user role. If paid plans are added later, a separate `admin account mode` is usually less flexible than flock roles such as `owner`, `assistant`, `caregiver`, and `viewer`. That lets the same underlying account system work for both households and rescues without splitting product logic into unrelated account classes.
## Customer API documentation
Open `/api/docs/` on your FlockPal instance for the interactive integration API reference,
or download `/api/openapi.json`. Locally, use `http://localhost:5000/api/docs/`.
Create a token in Settings → Integration tokens and use **Authorize** to try requests.
See [the API reference](docs/API_REFERENCE.md) for details.
+266
View File
@@ -8,6 +8,7 @@
"name": "flockpal-backend",
"version": "0.1.0",
"dependencies": {
"@asteasolutions/zod-to-openapi": "7.3.4",
"@types/nodemailer": "^8.0.0",
"bullmq": "^5.76.4",
"cors": "2.8.5",
@@ -22,9 +23,11 @@
"qrcode": "^1.5.4",
"sharp": "^0.34.5",
"stripe": "^22.0.2",
"swagger-ui-express": "5.0.1",
"zod": "3.24.1"
},
"devDependencies": {
"@apidevtools/swagger-parser": "13.1.0",
"@types/cors": "2.8.17",
"@types/express": "4.17.21",
"@types/morgan": "1.9.9",
@@ -32,10 +35,79 @@
"@types/pdfkit": "^0.17.6",
"@types/pg": "8.11.10",
"@types/qrcode": "^1.5.6",
"@types/swagger-ui-express": "4.1.8",
"tsx": "4.19.2",
"typescript": "5.7.2"
}
},
"node_modules/@apidevtools/json-schema-ref-parser": {
"version": "16.0.3",
"resolved": "https://registry.npmjs.org/@apidevtools/json-schema-ref-parser/-/json-schema-ref-parser-16.0.3.tgz",
"integrity": "sha512-7lZp4XCTZhU/AgiGpIG+j4uJeWPdGbpQ+8wqXrzuHy+tboKsjSacjGH9/kNThRDIFhMWHF3ba+ejS8J3PeSI1Q==",
"dev": true,
"license": "MIT",
"dependencies": {
"js-yaml": "^5.4.2",
"undici": "^8.10.2"
},
"engines": {
"node": ">=22.19.0"
},
"peerDependencies": {
"@types/json-schema": "^7.0.15"
}
},
"node_modules/@apidevtools/openapi-schemas": {
"version": "2.1.0",
"resolved": "https://registry.npmjs.org/@apidevtools/openapi-schemas/-/openapi-schemas-2.1.0.tgz",
"integrity": "sha512-Zc1AlqrJlX3SlpupFGpiLi2EbteyP7fXmUOGup6/DnkRgjP9bgMM/ag+n91rsv0U1Gpz0H3VILA/o3bW7Ua6BQ==",
"dev": true,
"license": "MIT",
"engines": {
"node": ">=10"
}
},
"node_modules/@apidevtools/swagger-methods": {
"version": "3.0.2",
"resolved": "https://registry.npmjs.org/@apidevtools/swagger-methods/-/swagger-methods-3.0.2.tgz",
"integrity": "sha512-QAkD5kK2b1WfjDS/UQn/qQkbwF31uqRjPTrsCs5ZG9BQGAkjwvqGFjjPqAuzac/IYzpPtRzjCP1WrTuAIjMrXg==",
"dev": true,
"license": "MIT"
},
"node_modules/@apidevtools/swagger-parser": {
"version": "13.1.0",
"resolved": "https://registry.npmjs.org/@apidevtools/swagger-parser/-/swagger-parser-13.1.0.tgz",
"integrity": "sha512-dkCuqCWh5U7u0aurmmc/qvel2KeKDxHTwVtUdYonndIpD7mXV6AVaWNdvaja2HAy628z7FT/Qdz8sCgzwhgwKg==",
"dev": true,
"license": "MIT",
"dependencies": {
"@apidevtools/json-schema-ref-parser": "^16.0.3",
"@apidevtools/openapi-schemas": "^2.1.0",
"@apidevtools/swagger-methods": "^3.0.2",
"@types/json-schema": "^7.0.15",
"ajv": "^8.20.0",
"ajv-draft-04": "^1.0.0",
"call-me-maybe": "^1.0.2"
},
"engines": {
"node": ">=22.19.0"
},
"peerDependencies": {
"openapi-types": ">=7"
}
},
"node_modules/@asteasolutions/zod-to-openapi": {
"version": "7.3.4",
"resolved": "https://registry.npmjs.org/@asteasolutions/zod-to-openapi/-/zod-to-openapi-7.3.4.tgz",
"integrity": "sha512-/2rThQ5zPi9OzVwes6U7lK1+Yvug0iXu25olp7S0XsYmOqnyMfxH7gdSQjn/+DSOHRg7wnotwGJSyL+fBKdnEA==",
"license": "MIT",
"dependencies": {
"openapi3-ts": "^4.1.2"
},
"peerDependencies": {
"zod": "^3.20.2"
}
},
"node_modules/@emnapi/runtime": {
"version": "1.10.0",
"resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.10.0.tgz",
@@ -1027,6 +1099,13 @@
"url": "https://paulmillr.com/funding/"
}
},
"node_modules/@scarf/scarf": {
"version": "1.4.0",
"resolved": "https://registry.npmjs.org/@scarf/scarf/-/scarf-1.4.0.tgz",
"integrity": "sha512-xxeapPiUXdZAE3che6f3xogoJPeZgig6omHEy1rIY5WVsB3H2BHNnZH+gHG6x91SCWyQCzWGsuL2Hh3ClO5/qQ==",
"hasInstallScript": true,
"license": "Apache-2.0"
},
"node_modules/@swc/helpers": {
"version": "0.5.23",
"resolved": "https://registry.npmjs.org/@swc/helpers/-/helpers-0.5.23.tgz",
@@ -1100,6 +1179,13 @@
"dev": true,
"license": "MIT"
},
"node_modules/@types/json-schema": {
"version": "7.0.15",
"resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.15.tgz",
"integrity": "sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==",
"dev": true,
"license": "MIT"
},
"node_modules/@types/morgan": {
"version": "1.9.9",
"resolved": "https://registry.npmjs.org/@types/morgan/-/morgan-1.9.9.tgz",
@@ -1195,6 +1281,17 @@
"@types/node": "*"
}
},
"node_modules/@types/swagger-ui-express": {
"version": "4.1.8",
"resolved": "https://registry.npmjs.org/@types/swagger-ui-express/-/swagger-ui-express-4.1.8.tgz",
"integrity": "sha512-AhZV8/EIreHFmBV5wAs0gzJUNq9JbbSXgJLQubCC0jtIo6prnI9MIRRxnU4MZX9RB9yXxF1V4R7jtLl/Wcj31g==",
"dev": true,
"license": "MIT",
"dependencies": {
"@types/express": "*",
"@types/serve-static": "*"
}
},
"node_modules/accepts": {
"version": "1.3.8",
"resolved": "https://registry.npmjs.org/accepts/-/accepts-1.3.8.tgz",
@@ -1208,6 +1305,38 @@
"node": ">= 0.6"
}
},
"node_modules/ajv": {
"version": "8.20.0",
"resolved": "https://registry.npmjs.org/ajv/-/ajv-8.20.0.tgz",
"integrity": "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==",
"dev": true,
"license": "MIT",
"dependencies": {
"fast-deep-equal": "^3.1.3",
"fast-uri": "^3.0.1",
"json-schema-traverse": "^1.0.0",
"require-from-string": "^2.0.2"
},
"funding": {
"type": "github",
"url": "https://github.com/sponsors/epoberezkin"
}
},
"node_modules/ajv-draft-04": {
"version": "1.0.0",
"resolved": "https://registry.npmjs.org/ajv-draft-04/-/ajv-draft-04-1.0.0.tgz",
"integrity": "sha512-mv00Te6nmYbRp5DCwclxtt7yV/joXJPGS7nM+97GdxvuttCOfgI3K4U25zboyeX0O+myI8ERluxQe5wljMmVIw==",
"dev": true,
"license": "MIT",
"peerDependencies": {
"ajv": "^8.5.0"
},
"peerDependenciesMeta": {
"ajv": {
"optional": true
}
}
},
"node_modules/ansi-regex": {
"version": "5.0.1",
"resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
@@ -1232,6 +1361,13 @@
"url": "https://github.com/chalk/ansi-styles?sponsor=1"
}
},
"node_modules/argparse": {
"version": "2.0.1",
"resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
"integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==",
"dev": true,
"license": "Python-2.0"
},
"node_modules/array-flatten": {
"version": "1.1.1",
"resolved": "https://registry.npmjs.org/array-flatten/-/array-flatten-1.1.1.tgz",
@@ -1373,6 +1509,13 @@
"url": "https://github.com/sponsors/ljharb"
}
},
"node_modules/call-me-maybe": {
"version": "1.0.2",
"resolved": "https://registry.npmjs.org/call-me-maybe/-/call-me-maybe-1.0.2.tgz",
"integrity": "sha512-HpX65o1Hnr9HH25ojC1YGs7HCQLq0GCOibSaWER0eNpgJ/Z1MZv2mTc7+xh6WOPxbRVcmgbv4hGU+uSQ/2xFZQ==",
"dev": true,
"license": "MIT"
},
"node_modules/camelcase": {
"version": "5.3.1",
"resolved": "https://registry.npmjs.org/camelcase/-/camelcase-5.3.1.tgz",
@@ -1756,6 +1899,23 @@
"integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
"license": "MIT"
},
"node_modules/fast-uri": {
"version": "3.1.8",
"resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.8.tgz",
"integrity": "sha512-GZMtZUTNRpOVIECoXwLNZS5xUGE+mVNbTB8h/7Rwh2TFWcBQiPzTgyZi05BF9UMZKkLJv8XBRJTlU7zg8+ZfMg==",
"dev": true,
"funding": [
{
"type": "github",
"url": "https://github.com/sponsors/fastify"
},
{
"type": "opencollective",
"url": "https://opencollective.com/fastify"
}
],
"license": "BSD-3-Clause"
},
"node_modules/finalhandler": {
"version": "1.3.1",
"resolved": "https://registry.npmjs.org/finalhandler/-/finalhandler-1.3.1.tgz",
@@ -2055,6 +2215,36 @@
"integrity": "sha512-qR0HB5uP6wCuRMrWPTrkMaev7MJZwJuuw4fnwAzRgP4J4/F8RwtodOKpGp4XpqsLBFzzgqIO42efFAyz2Et6KQ==",
"license": "MIT"
},
"node_modules/js-yaml": {
"version": "5.4.2",
"resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-5.4.2.tgz",
"integrity": "sha512-m+aqu+LwO1O6sIopafj8HUVl5aawITwZQe/yHpMCKjaWBaA/d07B/QdMb3529REftiU+RMMHL3Vlsw3hON7vWg==",
"dev": true,
"funding": [
{
"type": "github",
"url": "https://github.com/sponsors/puzrin"
},
{
"type": "github",
"url": "https://github.com/sponsors/nodeca"
}
],
"license": "MIT",
"dependencies": {
"argparse": "^2.0.1"
},
"bin": {
"js-yaml": "bin/js-yaml.mjs"
}
},
"node_modules/json-schema-traverse": {
"version": "1.0.0",
"resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
"integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
"dev": true,
"license": "MIT"
},
"node_modules/linebreak": {
"version": "1.1.0",
"resolved": "https://registry.npmjs.org/linebreak/-/linebreak-1.1.0.tgz",
@@ -2329,6 +2519,23 @@
"node": ">= 0.8"
}
},
"node_modules/openapi-types": {
"version": "12.1.3",
"resolved": "https://registry.npmjs.org/openapi-types/-/openapi-types-12.1.3.tgz",
"integrity": "sha512-N4YtSYJqghVu4iek2ZUvcN/0aqH1kRDuNqzcycDxhOUpg7GdvLa2F3DgS6yBNhInhv2r/6I0Flkn7CqL8+nIcw==",
"dev": true,
"license": "MIT",
"peer": true
},
"node_modules/openapi3-ts": {
"version": "4.6.1",
"resolved": "https://registry.npmjs.org/openapi3-ts/-/openapi3-ts-4.6.1.tgz",
"integrity": "sha512-XW9MOldkhoICNeXVzzmXzmOW5G73ppOEGmh7fLCqHjgfdEYCGGN+00MlVCeUZgovjjfC56j9tvtDt1zGabNjjA==",
"license": "MIT",
"dependencies": {
"yaml": "^2.9.0"
}
},
"node_modules/p-limit": {
"version": "2.3.0",
"resolved": "https://registry.npmjs.org/p-limit/-/p-limit-2.3.0.tgz",
@@ -2732,6 +2939,16 @@
"node": ">=0.10.0"
}
},
"node_modules/require-from-string": {
"version": "2.0.2",
"resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz",
"integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==",
"dev": true,
"license": "MIT",
"engines": {
"node": ">=0.10.0"
}
},
"node_modules/require-main-filename": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/require-main-filename/-/require-main-filename-2.0.0.tgz",
@@ -3041,6 +3258,30 @@
}
}
},
"node_modules/swagger-ui-dist": {
"version": "5.33.0",
"resolved": "https://registry.npmjs.org/swagger-ui-dist/-/swagger-ui-dist-5.33.0.tgz",
"integrity": "sha512-wpdK+m6BU5yj6pmUdMskZVTSWYG4DLglAx3sIhylloY37i8O37IrH+YEpqdXNfpaTGxILRBFzUqLF2jKqbfI7A==",
"license": "Apache-2.0",
"dependencies": {
"@scarf/scarf": "=1.4.0"
}
},
"node_modules/swagger-ui-express": {
"version": "5.0.1",
"resolved": "https://registry.npmjs.org/swagger-ui-express/-/swagger-ui-express-5.0.1.tgz",
"integrity": "sha512-SrNU3RiBGTLLmFU8GIJdOdanJTl4TOmT27tt3bWWHppqYmAZ6IDuEuBvMU6nZq0zLEe6b/1rACXCgLZqO6ZfrA==",
"license": "MIT",
"dependencies": {
"swagger-ui-dist": ">=5.0.0"
},
"engines": {
"node": ">= v0.10.32"
},
"peerDependencies": {
"express": ">=4.0.0 || >=5.0.0-beta"
}
},
"node_modules/tiny-inflate": {
"version": "1.0.3",
"resolved": "https://registry.npmjs.org/tiny-inflate/-/tiny-inflate-1.0.3.tgz",
@@ -3109,6 +3350,16 @@
"node": ">=14.17"
}
},
"node_modules/undici": {
"version": "8.11.2",
"resolved": "https://registry.npmjs.org/undici/-/undici-8.11.2.tgz",
"integrity": "sha512-u4UB2/IrKdU6lFxumHmmo1a3fCQO5tzQllRorfoRS63txhrB7xTpSn1PftwC4qEHkOaqP95fCWW4lJzwErwzhQ==",
"dev": true,
"license": "MIT",
"engines": {
"node": ">=22.19.0"
}
},
"node_modules/undici-types": {
"version": "6.20.0",
"resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.20.0.tgz",
@@ -3203,6 +3454,21 @@
"integrity": "sha512-JKhqTOwSrqNA1NY5lSztJ1GrBiUodLMmIZuLiDaMRJ+itFd+ABVE8XBjOvIWL+rSqNDC74LCSFmlb/U4UZ4hJQ==",
"license": "ISC"
},
"node_modules/yaml": {
"version": "2.9.1",
"resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.1.tgz",
"integrity": "sha512-3NxN8+78OdzbT7C/WjGsyfPAtJaN3FNDsWxv7Y7mcDsT/oOmgW8BpyQQFFBnvZE3j9Y2Sdz1ULFLezL7Eb2yFw==",
"license": "ISC",
"bin": {
"yaml": "bin.mjs"
},
"engines": {
"node": ">= 14.6"
},
"funding": {
"url": "https://github.com/sponsors/eemeli"
}
},
"node_modules/yargs": {
"version": "15.4.1",
"resolved": "https://registry.npmjs.org/yargs/-/yargs-15.4.1.tgz",
+4
View File
@@ -14,6 +14,7 @@
"worker": "node dist/worker.js"
},
"dependencies": {
"@asteasolutions/zod-to-openapi": "7.3.4",
"@types/nodemailer": "^8.0.0",
"bullmq": "^5.76.4",
"cors": "2.8.5",
@@ -28,9 +29,11 @@
"qrcode": "^1.5.4",
"sharp": "^0.34.5",
"stripe": "^22.0.2",
"swagger-ui-express": "5.0.1",
"zod": "3.24.1"
},
"devDependencies": {
"@apidevtools/swagger-parser": "13.1.0",
"@types/cors": "2.8.17",
"@types/express": "4.17.21",
"@types/morgan": "1.9.9",
@@ -38,6 +41,7 @@
"@types/pdfkit": "^0.17.6",
"@types/pg": "8.11.10",
"@types/qrcode": "^1.5.6",
"@types/swagger-ui-express": "4.1.8",
"tsx": "4.19.2",
"typescript": "5.7.2"
}
+142 -214
View File
@@ -1,3 +1,43 @@
import { unassignedBirdMatchSchema, claimBirdSchema } from './birdMembershipSchemas.js';
import { hasUnassignedBird, removeBirdFromFlock, claimUnassignedBird } from './repositories/birdMembershipRepository.js';
import { behaviorTypeSchema, behaviorOccurrenceSchema, behaviorRangeSchema } from './behaviorSchemas.js';
import { listBehaviorTypes, createBehaviorType, listBehaviorOccurrences, saveBehaviorOccurrence, deleteBehaviorOccurrence } from './repositories/behaviorRepository.js';
import {
dateStringSchema,
chartColorSchema,
photoDataUrlSchema,
photoUrlSchema,
magicLinkRequestSchema,
switchWorkspaceSchema,
workspaceTypeSchema,
workspaceRoleSchema,
billingPlanSchema,
billingIntervalSchema,
integrationTokenScopeSchema,
birdGenderSchema,
rescueVerificationStatusSchema,
rescueOnboardingSchema,
workspaceSchema,
createWorkspaceSchema,
workspaceMemberSchema,
flockTransferSchema,
lostBirdReportSchema,
publicProfileCodeSchema,
birdTransferCodeSchema,
birdProfileListSchema,
verifiedLocationDetailsSchema,
locationSearchSchema,
birdSchema,
memorializeBirdSchema,
memorialReminderPreferenceSchema,
birdTimelineEventSchema,
weightSchema,
vetVisitSchema,
medicationSchema,
medicationAdministrationSchema,
flockNoteSchema,
} from './schemas.js';
import { mountApiDocs } from './docs/router.js';
import { buildEmailLayout } from './emails/emailLayout.js';
import { buildWeightReminderEmail } from './emails/weightReminderEmail.js';
import type { WeightReminder } from './reminders/weightReminders.js';
@@ -48,7 +88,6 @@ import {
findBirdsByBandId,
createVetVisitForBird,
createWeightForBird,
deleteBird,
deleteMedicationForBird,
deleteVetVisitForBird,
getBirdById,
@@ -207,163 +246,6 @@ const allowedOrigins = Array.from(
),
);
const dateStringSchema = z.string().regex(/^\d{4}-\d{2}-\d{2}$/);
const chartColorSchema = z.string().regex(/^#[0-9a-fA-F]{6}$/);
const photoDataUrlSchema = z
.string()
.regex(/^data:image\/(?:png|jpeg|jpg|webp|gif);base64,[A-Za-z0-9+/=]+$/)
.max(1_500_000);
const photoUrlSchema = z.string().trim().url().max(2000);
const magicLinkRequestSchema = z.object({
name: z.string().trim().max(160).optional().or(z.literal('')),
email: z.string().trim().email().max(255),
redirectTo: z.string().trim().url().max(2000).optional().or(z.literal('')),
});
const switchWorkspaceSchema = z.object({
workspaceId: z.coerce.number().int().positive(),
});
const workspaceTypeSchema = z.enum(['standard', 'rescue']);
const workspaceRoleSchema = z.enum(['owner', 'assistant', 'caregiver', 'viewer']);
const billingPlanSchema = z.enum(['household_basic', 'household_plus', 'household_macaw', 'household_hyacinth_macaw']);
const billingIntervalSchema = z.enum(['monthly', 'yearly']);
const integrationTokenScopeSchema = z.enum(['read_only', 'read_write']);
const birdGenderSchema = z.enum(['unknown', 'male', 'female', 'male_dna', 'female_dna']);
const rescueVerificationStatusSchema = z.enum(['pending', 'approved', 'rejected']);
const rescueOnboardingSchema = z.object({
name: z.string().trim().max(160).optional().or(z.literal('')),
city: z.string().trim().max(120).optional().or(z.literal('')),
state: z.string().trim().max(80).optional().or(z.literal('')),
ein: z.string().trim().max(32).optional().or(z.literal('')),
website: z.string().trim().url().max(2000).optional().or(z.literal('')),
});
const workspaceSchema = z.object({
name: z.string().trim().min(1).max(160),
workspaceType: workspaceTypeSchema,
billingEmail: z.string().trim().email().max(255).optional().or(z.literal('')),
billingPlan: billingPlanSchema.optional(),
billingInterval: billingIntervalSchema.optional(),
rescueOnboarding: rescueOnboardingSchema.optional(),
});
const createWorkspaceSchema = z.object({
name: z.string().trim().min(1).max(160),
workspaceType: workspaceTypeSchema,
billingEmail: z.string().trim().email().max(255).optional().or(z.literal('')),
billingPlan: billingPlanSchema.optional(),
billingInterval: billingIntervalSchema.optional(),
rescueOnboarding: rescueOnboardingSchema.optional(),
});
const workspaceMemberSchema = z.object({
name: z.string().trim().min(1).max(160),
email: z.string().trim().email().max(255),
role: workspaceRoleSchema,
});
const flockTransferSchema = z.object({
destinationOwnerEmail: z.string().trim().email().max(255),
});
const lostBirdReportSchema = z.object({
tagId: z.string().trim().min(1).max(80),
finderName: z.string().trim().max(160).optional().or(z.literal('')),
finderEmail: z.string().trim().email().max(255).optional().or(z.literal('')),
foundLocation: z.string().trim().max(255).optional().or(z.literal('')),
message: z.string().trim().max(1000).optional().or(z.literal('')),
});
const publicProfileCodeSchema = z.string().trim().regex(/^[A-Za-z0-9_-]{8,32}$/);
const birdTransferCodeSchema = z.string().trim().regex(/^[A-Za-z0-9_-]{12,32}$/);
const birdProfileListSchema = z
.string()
.trim()
.max(1000)
.refine(
(value) => value.split(/\r?\n/).map((item) => item.trim()).filter(Boolean).length <= 3,
'Use no more than three list items.',
)
.optional()
.or(z.literal(''));
const verifiedLocationDetailsSchema = z
.object({
label: z.string().trim().max(220).optional().or(z.literal('')),
city: z.string().trim().max(120).optional().or(z.literal('')),
region: z.string().trim().max(120).optional().or(z.literal('')),
country: z.string().trim().max(120).optional().or(z.literal('')),
countryCode: z.string().trim().max(2).optional().or(z.literal('')),
latitude: z.coerce.number().min(-90).max(90).optional().nullable().or(z.literal('')),
longitude: z.coerce.number().min(-180).max(180).optional().nullable().or(z.literal('')),
precision: z.enum(['city', 'region', 'country']).optional(),
provider: z.literal('mapbox').optional().nullable(),
providerPlaceId: z.string().trim().max(220).optional().or(z.literal('')),
})
.optional()
.nullable();
const locationSearchSchema = z.object({
q: z.string().trim().min(3).max(120),
});
const birdSchema = z.object({
name: z.string().trim().min(1).max(120),
tagId: z.string().trim().max(80).optional().or(z.literal('')),
species: z.string().trim().min(1).max(120),
motivators: birdProfileListSchema,
demotivators: birdProfileListSchema,
favoriteSnack: z.string().trim().max(160).optional().or(z.literal('')),
locationLabel: z.string().trim().max(160).optional().or(z.literal('')),
locationDetails: verifiedLocationDetailsSchema,
vetClinicName: z.string().trim().max(160).optional().or(z.literal('')),
vetClinicAddress: z.string().trim().max(500).optional().or(z.literal('')),
vetAccountNumber: z.string().trim().max(120).optional().or(z.literal('')),
vetDoctorName: z.string().trim().max(160).optional().or(z.literal('')),
gender: birdGenderSchema.optional(),
hatchDay: dateStringSchema.optional().or(z.literal('')),
dateOfBirth: dateStringSchema.optional().or(z.literal('')),
gotchaDay: dateStringSchema.optional().or(z.literal('')),
chartColor: chartColorSchema.optional(),
photoDataUrl: z.union([photoDataUrlSchema, photoUrlSchema, z.literal('')]).optional(),
notifyOnDob: z.boolean().optional(),
notifyOnGotchaDay: z.boolean().optional(),
publicProfileEnabled: z.boolean().optional(),
});
const memorializeBirdSchema = z.object({
memorializedOn: dateStringSchema,
memorialNote: z.string().trim().max(1000).optional().or(z.literal('')),
notifyOnMemorialDay: z.boolean().optional(),
});
const memorialReminderPreferenceSchema = z.object({
notifyOnMemorialDay: z.boolean(),
});
const birdTimelineEventSchema = z
.object({
eventType: z.enum(['location_updated', 'owner_changed', 'manual_note']),
eventDate: dateStringSchema.optional().or(z.literal('')),
locationLabel: z.string().trim().max(160).optional().or(z.literal('')),
locationDetails: verifiedLocationDetailsSchema,
note: z.string().trim().max(500).optional().or(z.literal('')),
})
.refine(
(value) =>
value.eventType === 'owner_changed' ||
Boolean(
value.locationLabel?.trim() ||
value.note?.trim() ||
value.locationDetails?.city?.trim() ||
value.locationDetails?.region?.trim() ||
value.locationDetails?.country?.trim(),
),
'Add a location or note for this timeline item.',
);
type VerifiedLocationDetailsInput = z.infer<typeof verifiedLocationDetailsSchema>;
const normalizeVerifiedLocationDetails = (value: VerifiedLocationDetailsInput) => {
@@ -483,57 +365,6 @@ const normalizeMapboxLocationFeature = (feature: MapboxGeocodeFeature): Verified
});
};
const weightSchema = z.object({
weightGrams: z.coerce.number().positive().max(10000),
recordedOn: dateStringSchema,
notes: z.string().trim().max(280).optional().or(z.literal('')),
});
const vetVisitSchema = z.object({
visitedOn: dateStringSchema,
clinicName: z.string().trim().min(1).max(160),
reason: z.string().trim().min(1).max(160),
notes: z.string().trim().max(1000).optional().or(z.literal('')),
});
const medicationSchema = z
.object({
name: z.string().trim().min(1).max(160),
dosage: z.string().trim().min(1).max(160),
frequency: z.enum(['once_daily', 'twice_daily', 'every_8_hours', 'every_6_hours', 'as_needed']),
doseSchedule: z
.array(
z.object({
key: z.string().trim().min(1).max(80),
label: z.string().trim().min(1).max(80),
time: z.string().trim().regex(/^$|^\d{2}:\d{2}$/),
}),
)
.min(1)
.max(8),
route: z.string().trim().max(80).optional().or(z.literal('')),
startDate: dateStringSchema,
endDate: dateStringSchema.optional().or(z.literal('')),
notes: z.string().trim().max(1000).optional().or(z.literal('')),
remindersEnabled: z.boolean().optional(),
})
.refine((value) => !value.endDate || value.endDate >= value.startDate, {
message: 'End date must be on or after start date.',
path: ['endDate'],
});
const medicationAdministrationSchema = z.object({
administeredOn: dateStringSchema,
administrationSlot: z.string().trim().min(1).max(80).default('dose-1'),
status: z.enum(['administered', 'missed']),
notes: z.string().trim().max(500).optional().or(z.literal('')),
});
const flockNoteSchema = z.object({
birdId: z.string().uuid().optional().nullable().or(z.literal('')),
body: z.string().trim().min(1).max(5000),
});
const integrationTokenCreateSchema = z.object({
name: z.string().trim().min(1).max(160),
scope: integrationTokenScopeSchema.default('read_write'),
@@ -1035,6 +866,7 @@ const oauthProviders = {
};
app.disable('x-powered-by');
mountApiDocs(app);
app.use(helmet({ crossOriginResourcePolicy: false }));
app.use(
cors({
@@ -3694,6 +3526,27 @@ app.get('/api/locations/search', requireAuth, locationSearchLimiter, async (req:
}
});
app.get('/api/birds/unassigned-match', requireAuth, requireWorkspaceRole(['owner', 'assistant', 'caregiver']), async (req: Request, res: Response, next: NextFunction) => {
const parsed = unassignedBirdMatchSchema.safeParse(req.query);
if (!parsed.success) { res.status(400).json({ error: 'Enter a known band ID.' }); return; }
try {
res.json({ available: await hasUnassignedBird(parsed.data.tagId) });
} catch (error) { next(error); }
});
app.post('/api/birds/claim', requireAuth, requireWriteAccess, requireWorkspaceRole(['owner', 'assistant', 'caregiver']), async (req: Request, res: Response, next: NextFunction) => {
const parsed = claimBirdSchema.safeParse(req.body);
if (!parsed.success) { res.status(400).json({ error: 'A known band ID and confirmation to bring in existing history are required.' }); return; }
try {
const birdId = await claimUnassignedBird(parsed.data.tagId, req.auth!.workspace.id, req.auth!.user.id);
if (!birdId) { res.status(409).json({ error: 'No unassigned bird is available with that band ID. It may already have joined a flock.' }); return; }
const bird = await getBirdById(birdId, req.auth!.workspace.id);
if (!bird) { res.status(409).json({ error: 'The bird is no longer in this flock. Refresh the flock to continue.' }); return; }
await writeAuditLog(req.auth!, 'bird.claimed', 'bird', bird.id, bird.name, { tagId: bird.tag_id });
res.status(200).json({ bird: normalizeBird(bird), historyImported: true });
} catch (error) { next(error); }
});
app.get('/api/birds', requireAuth, async (req: Request, res: Response, next: NextFunction) => {
try {
const [birds, memorializedBirds] = await Promise.all([
@@ -3842,6 +3695,11 @@ app.post('/api/birds', requireAuth, requireWriteAccess, requireWorkspaceRole(['o
let uploadedObjectKeyToCleanup: string | null = null;
try {
const tagId = normalizeBandId(parsed.data.tagId);
if (tagId && await hasUnassignedBird(tagId)) {
res.status(409).json({ code: 'bird_history_available', error: 'An unassigned bird has this band ID. Confirm adding the existing bird with its history instead of creating a new profile.' });
return;
}
const birdId = crypto.randomUUID();
const photoStorage = await resolveBirdPhotoStorage({
birdId,
@@ -4298,16 +4156,15 @@ app.delete('/api/birds/:birdId', requireAuth, requireWriteAccess, requireWorkspa
return;
}
const deleted = await deleteBird(req.params.birdId, req.auth!.workspace.id);
const removed = await removeBirdFromFlock(req.params.birdId, req.auth!.workspace.id, req.auth!.user.id);
if (!deleted) {
res.status(404).json({ error: 'Bird not found.' });
if (!removed) {
res.status(404).json({ error: 'Bird not found or no longer removable.' });
return;
}
await writeAuditLog(req.auth!, 'bird.deleted', 'bird', bird.id, bird.name);
await writeAuditLog(req.auth!, 'bird.removed_from_flock', 'bird', bird.id, bird.name);
res.status(204).send();
await deleteBirdPhotoObjectIfNeeded(bird.photo_object_key);
} catch (error) {
next(error);
}
@@ -4384,6 +4241,77 @@ app.patch('/api/birds/:birdId/memorial-reminders', requireAuth, requireWriteAcce
}
});
// Behavior types are flock-scoped; occurrences follow their bird across flock transfers.
app.get('/api/birds/:birdId/behavior-types', requireAuth, async (req: Request, res: Response, next: NextFunction) => {
try {
if (!z.string().uuid().safeParse(req.params.birdId).success) { res.status(400).json({ error: 'Invalid bird ID.' }); return; }
const bird = await getBirdById(req.params.birdId, req.auth!.workspace.id);
if (!bird) { res.status(404).json({ error: 'Bird not found.' }); return; }
res.json({ behaviorTypes: await listBehaviorTypes(req.auth!.workspace.id, bird.id) });
} catch (error) { next(error); }
});
app.post('/api/birds/:birdId/behavior-types', requireAuth, requireWriteAccess, requireWorkspaceRole(['owner', 'assistant', 'caregiver']), async (req: Request, res: Response, next: NextFunction) => {
const parsed = behaviorTypeSchema.safeParse(req.body);
if (!parsed.success || !z.string().uuid().safeParse(req.params.birdId).success) { res.status(400).json({ error: 'Invalid behavior type payload.' }); return; }
try {
const bird = await getBirdById(req.params.birdId, req.auth!.workspace.id);
if (!bird) { res.status(404).json({ error: 'Bird not found.' }); return; }
if (!ensureBirdWritable(bird, res)) return;
const behaviorType = await createBehaviorType(req.auth!.workspace.id, parsed.data.name, parsed.data.description);
await writeAuditLog(req.auth!, 'behavior_type.created', 'behavior_type', behaviorType.id, parsed.data.name);
res.status(201).json({ behaviorType });
} catch (error) { next(error); }
});
app.get('/api/birds/:birdId/behaviors', requireAuth, async (req: Request, res: Response, next: NextFunction) => {
const parsed = behaviorRangeSchema.safeParse(req.query);
if (!parsed.success || !z.string().uuid().safeParse(req.params.birdId).success) { res.status(400).json({ error: 'Invalid behavior date range or bird ID.' }); return; }
try {
const bird = await getBirdById(req.params.birdId, req.auth!.workspace.id);
if (!bird) { res.status(404).json({ error: 'Bird not found.' }); return; }
res.json({ occurrences: await listBehaviorOccurrences(bird.id, req.auth!.workspace.id, parsed.data.from, parsed.data.to, parsed.data.behaviorTypeId) });
} catch (error) { next(error); }
});
app.post('/api/birds/:birdId/behaviors', requireAuth, requireWriteAccess, requireWorkspaceRole(['owner', 'assistant', 'caregiver']), async (req: Request, res: Response, next: NextFunction) => {
if (!z.string().uuid().safeParse(req.params.birdId).success) { res.status(400).json({ error: 'Invalid ID.' }); return; }
const parsed = behaviorOccurrenceSchema.safeParse(req.body);
if (!parsed.success) { res.status(400).json({ error: 'Invalid behavior payload.', details: parsed.error.flatten() }); return; }
try {
const bird = await getBirdById(req.params.birdId, req.auth!.workspace.id);
if (!bird) { res.status(404).json({ error: 'Bird not found.' }); return; }
if (!ensureBirdWritable(bird, res)) return;
const occurrence = await saveBehaviorOccurrence(bird.id, req.auth!.workspace.id, parsed.data);
if (!occurrence) { res.status(404).json({ error: 'Occurrence or behavior type not found, or bird is no longer editable.' }); return; }
await writeAuditLog(req.auth!, 'behavior.created', 'behavior_occurrence', occurrence.id, bird.name, { birdId: bird.id });
res.status(201).json({ occurrence });
} catch (error) { next(error); }
});
app.put('/api/birds/:birdId/behaviors/:occurrenceId', requireAuth, requireWriteAccess, requireWorkspaceRole(['owner', 'assistant', 'caregiver']), async (req: Request, res: Response, next: NextFunction) => {
if (!z.string().uuid().safeParse(req.params.birdId).success || !z.string().uuid().safeParse(req.params.occurrenceId).success) { res.status(400).json({ error: 'Invalid ID.' }); return; }
const parsed = behaviorOccurrenceSchema.safeParse(req.body);
if (!parsed.success) { res.status(400).json({ error: 'Invalid behavior payload.', details: parsed.error.flatten() }); return; }
try {
const bird = await getBirdById(req.params.birdId, req.auth!.workspace.id);
if (!bird) { res.status(404).json({ error: 'Bird not found.' }); return; }
if (!ensureBirdWritable(bird, res)) return;
const occurrence = await saveBehaviorOccurrence(bird.id, req.auth!.workspace.id, parsed.data, req.params.occurrenceId);
if (!occurrence) { res.status(404).json({ error: 'Occurrence or behavior type not found, or bird is no longer editable.' }); return; }
await writeAuditLog(req.auth!, 'behavior.updated', 'behavior_occurrence', occurrence.id, bird.name, { birdId: bird.id });
res.status(200).json({ occurrence });
} catch (error) { next(error); }
});
app.delete('/api/birds/:birdId/behaviors/:occurrenceId', requireAuth, requireWriteAccess, requireWorkspaceRole(['owner', 'assistant', 'caregiver']), async (req: Request, res: Response, next: NextFunction) => {
if (!z.string().uuid().safeParse(req.params.birdId).success || !z.string().uuid().safeParse(req.params.occurrenceId).success) { res.status(400).json({ error: 'Invalid ID.' }); return; }
try {
const bird = await getBirdById(req.params.birdId, req.auth!.workspace.id);
if (!bird) { res.status(404).json({ error: 'Bird not found.' }); return; }
if (!ensureBirdWritable(bird, res)) return;
const occurrence = await deleteBehaviorOccurrence(bird.id, req.auth!.workspace.id, req.params.occurrenceId);
if (!occurrence) { res.status(404).json({ error: 'Occurrence or behavior type not found, or bird is no longer editable.' }); return; }
await writeAuditLog(req.auth!, 'behavior.deleted', 'behavior_occurrence', occurrence.id, bird.name, { birdId: bird.id });
res.status(204).send();
} catch (error) { next(error); }
});
app.get('/api/birds/:birdId/weights', requireAuth, async (req: Request, res: Response, next: NextFunction) => {
try {
const days = Math.min(Math.max(Number(req.query.days ?? 30), 1), 425);
+40
View File
@@ -0,0 +1,40 @@
import { z } from 'zod';
export const behaviorTypeSchema = z.object({
name: z.string().trim().min(1).max(120),
description: z.string().trim().max(2000).nullable().optional(),
});
export const behaviorOccurrenceSchema = z.object({
behaviorTypeId: z.string().uuid(),
occurredAt: z.string().datetime({ offset: true }),
durationSeconds: z.number().finite().positive().max(31536000).nullable().optional(),
severity: z.number().int().min(1).max(5).nullable().optional(),
notes: z.string().trim().max(10000).nullable().optional(),
});
export const behaviorRangeSchema = z.object({
from: z.string().datetime({ offset: true }),
to: z.string().datetime({ offset: true }),
behaviorTypeId: z.string().uuid().optional(),
}).refine(({ from, to }) => Date.parse(to) > Date.parse(from) && Date.parse(to) - Date.parse(from) <= 32 * 86400000, {
message: 'Choose a date range of up to 32 days, with to after from.',
});
export type BehaviorInput = z.infer<typeof behaviorOccurrenceSchema>;
export type BehaviorType = {
id: string;
name: string;
description: string | null;
createdAt: Date;
};
export type BehaviorOccurrence = {
id: string;
birdId: string;
behaviorTypeId: string;
behaviorName: string;
occurredAt: Date;
durationSeconds: number | null;
severity: number | null;
notes: string | null;
createdAt: Date;
updatedAt: Date;
};
+9
View File
@@ -0,0 +1,9 @@
import { z } from 'zod';
export const unassignedBirdMatchSchema = z.object({
tagId: z.string().trim().min(1).max(80).refine(
(value) => !['unknown', 'not recorded', 'n/a', 'na', 'none'].includes(value.toLowerCase()),
'Enter a known band ID.',
),
});
export const claimBirdSchema = unassignedBirdMatchSchema.extend({ confirmHistory: z.literal(true) });
+15
View File
@@ -23,6 +23,21 @@ export class DatabaseClient {
return this.pool.query<T>(text, params);
}
async transaction<T>(operation: (client: pg.PoolClient) => Promise<T>): Promise<T> {
const client = await this.pool.connect();
try {
await client.query('BEGIN');
const result = await operation(client);
await client.query('COMMIT');
return result;
} catch (error) {
await client.query('ROLLBACK');
throw error;
} finally {
client.release();
}
}
async close() {
await this.pool.end();
}
+37 -1
View File
@@ -303,7 +303,9 @@ export const ensureSchema = async (database: DatabaseClient = db) => {
ADD COLUMN IF NOT EXISTS notify_on_memorial_day BOOLEAN NOT NULL DEFAULT FALSE;
ALTER TABLE birds
ALTER COLUMN tag_id DROP NOT NULL;
ALTER COLUMN tag_id DROP NOT NULL,
ALTER COLUMN workspace_id DROP NOT NULL,
ALTER COLUMN workspace_id DROP DEFAULT;
UPDATE birds
SET tag_id = NULL
@@ -450,6 +452,9 @@ export const ensureSchema = async (database: DatabaseClient = db) => {
ON flock_notes (bird_id, updated_at DESC)
WHERE bird_id IS NOT NULL;
-- Bird-specific notes remain attached while their bird is between flocks.
ALTER TABLE flock_notes ALTER COLUMN workspace_id DROP NOT NULL;
CREATE TABLE IF NOT EXISTS audit_log_entries (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
workspace_id INTEGER NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
@@ -594,6 +599,37 @@ export const ensureSchema = async (database: DatabaseClient = db) => {
CREATE INDEX IF NOT EXISTS idx_medication_administrations_medication_date
ON medication_administrations (medication_id, administered_on DESC, created_at DESC);
CREATE TABLE IF NOT EXISTS behavior_types (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
workspace_id INTEGER REFERENCES workspaces(id) ON DELETE SET NULL,
name VARCHAR(120) NOT NULL,
is_default BOOLEAN NOT NULL DEFAULT FALSE,
description TEXT,
created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
);
CREATE UNIQUE INDEX IF NOT EXISTS idx_behavior_types_workspace_name
ON behavior_types (workspace_id, lower(name)) WHERE workspace_id IS NOT NULL;
CREATE UNIQUE INDEX IF NOT EXISTS idx_behavior_types_default_name
ON behavior_types (lower(name)) WHERE is_default;
INSERT INTO behavior_types (name, is_default) VALUES
('Screaming / vocalization', TRUE), ('Biting / aggression', TRUE), ('Feather plucking', TRUE),
('Repetitive behavior', TRUE), ('Excessive scratching', TRUE), ('Hiding / withdrawal', TRUE),
('Unusual posture', TRUE), ('Food refusal', TRUE), ('Other', TRUE)
ON CONFLICT DO NOTHING;
CREATE TABLE IF NOT EXISTS behavior_occurrences (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
bird_id UUID NOT NULL REFERENCES birds(id) ON DELETE CASCADE,
behavior_type_id UUID NOT NULL REFERENCES behavior_types(id),
occurred_at TIMESTAMPTZ NOT NULL,
duration_seconds DOUBLE PRECISION CHECK (duration_seconds > 0 AND duration_seconds <= 31536000),
severity SMALLINT CHECK (severity BETWEEN 1 AND 5),
notes TEXT,
created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX IF NOT EXISTS idx_behavior_occurrences_bird_time ON behavior_occurrences (bird_id, occurred_at DESC);
CREATE INDEX IF NOT EXISTS idx_behavior_occurrences_bird_type_time ON behavior_occurrences (bird_id, behavior_type_id, occurred_at DESC);
DO $$
BEGIN
IF EXISTS (
+117
View File
@@ -0,0 +1,117 @@
import assert from 'node:assert/strict';
import { readFile } from 'node:fs/promises';
import { once } from 'node:events';
import test from 'node:test';
import express from 'express';
import SwaggerParser from '@apidevtools/swagger-parser';
import ts from 'typescript';
import { customerOpenApi } from './openapi.js';
import { mountApiDocs } from './router.js';
import { birdSchema, medicationSchema } from '../schemas.js';
const appSource = await readFile(new URL('../app.ts', import.meta.url), 'utf8');
const ast = ts.createSourceFile('app.ts', appSource, ts.ScriptTarget.Latest, true);
test('customer specification is valid OpenAPI and has unique operation IDs', async () => {
await SwaggerParser.validate(JSON.parse(JSON.stringify(customerOpenApi)));
const ids = Object.values(customerOpenApi.paths).flatMap((path) => Object.values(path!).map((operation) => operation.operationId));
assert.equal(new Set(ids).size, ids.length);
assert.deepEqual(customerOpenApi.servers, [{ url: '/api', description: 'This FlockPal instance' }]);
});
test('documented operations exactly match customer integration routes and permissions', () => {
const expected: string[] = [];
for (const statement of ast.statements) {
if (!ts.isExpressionStatement(statement) || !ts.isCallExpression(statement.expression)) continue;
const call = statement.expression;
if (!ts.isPropertyAccessExpression(call.expression) || call.expression.expression.getText(ast) !== 'app') continue;
const method = call.expression.name.text;
if (!['get', 'post', 'put', 'delete', 'patch'].includes(method)) continue;
const [pathArg, ...args] = call.arguments;
if (!pathArg || !ts.isStringLiteral(pathArg)) continue;
const middleware = args.filter(ts.isIdentifier).map((arg) => arg.text);
if (!middleware.includes('requireAuth') || middleware.includes('requireSessionAuth') || middleware.includes('requireAdmin')) continue;
const path = pathArg.text.replace(/^\/api/, '').replace(/:(\w+)/g, '{$1}');
expected.push(`${method} ${path}`);
const operation = (customerOpenApi.paths[path] as Record<string, any> | undefined)?.[method];
assert.ok(operation, `Missing ${method} ${path}`);
assert.deepEqual(operation.security, [{ IntegrationToken: [] }]);
if (middleware.includes('requireWriteAccess')) {
assert.match(operation.description, /read_write/);
assert.ok(operation.responses['402']);
assert.ok(operation.responses['403']);
}
const roleCall = args.find((arg) => ts.isCallExpression(arg) && arg.expression.getText(ast) === 'requireWorkspaceRole');
if (roleCall && ts.isCallExpression(roleCall)) {
for (const match of roleCall.getText(ast).matchAll(/'([^']+)'/g)) assert.ok(operation.description.includes(match[1]));
}
}
const actual = Object.entries(customerOpenApi.paths).flatMap(([path, item]) => Object.keys(item!).map((method) => `${method} ${path}`));
assert.deepEqual(actual.sort(), expected.sort());
assert.equal(actual.length, 35);
});
test('response models cover the actual serialized fields', () => {
const components = customerOpenApi.components!.schemas!;
const names: Record<string, string> = { normalizeWorkspace: 'workspace', normalizeWorkspaceMember: 'member', normalizeBird: 'bird', normalizeWeight: 'weight', normalizeVetVisit: 'vetVisit', normalizeMedication: 'medication', normalizeMedicationAdministration: 'administration', normalizeFlockNote: 'note', normalizeBirdTimelineEvent: 'timeline' };
for (const statement of ast.statements) {
if (!ts.isVariableStatement(statement)) continue;
for (const declaration of statement.declarationList.declarations) {
const model = names[declaration.name.getText(ast)];
if (!model) continue;
const fn = declaration.initializer;
assert.ok(fn && ts.isArrowFunction(fn) && ts.isParenthesizedExpression(fn.body));
const body = fn.body.expression;
assert.ok(ts.isObjectLiteralExpression(body));
const keys = body.properties.map((property) => property.name!.getText(ast));
const schema = components[model];
assert.ok(schema && !('$ref' in schema));
assert.deepEqual(Object.keys(schema.properties!).sort(), keys.sort(), model);
}
}
});
test('shared validators retain custom rules and document required request fields', () => {
assert.equal(birdSchema.safeParse({ name: 'Yoda', species: 'Parrot', motivators: 'one\ntwo\nthree\nfour' }).success, false);
assert.equal(medicationSchema.safeParse({ name: 'Medicine', dosage: '1 ml', frequency: 'once_daily', doseSchedule: [{ key: 'morning', label: 'Morning', time: '08:00' }], startDate: '2026-09-27', endDate: '2026-09-26' }).success, false);
const bird = customerOpenApi.components!.schemas!.BirdInput;
assert.ok(!('$ref' in bird));
assert.deepEqual(bird.required, ['name', 'species']);
});
test('Swagger UI, initialization, assets and specification are served locally with compatible CSP', async (t) => {
const app = express();
mountApiDocs(app);
const server = app.listen(0, '127.0.0.1');
await once(server, 'listening');
t.after(() => new Promise<void>((resolve, reject) => server.close((error) => error ? reject(error) : resolve())));
const address = server.address();
assert.ok(address && typeof address !== 'string');
const base = `http://127.0.0.1:${address.port}`;
const page = await fetch(`${base}/api/docs/`);
assert.equal(page.status, 200);
const html = await page.text();
assert.match(html, /FlockPal API Reference/);
const csp = page.headers.get('content-security-policy')!;
assert.match(csp, /script-src 'self'/);
assert.match(csp, /connect-src 'self'/);
assert.ok(!csp.includes('upgrade-insecure-requests'));
for (const asset of ['swagger-ui.css', 'swagger-ui-bundle.js', 'swagger-ui-standalone-preset.js', 'swagger-ui-init.js']) {
const response = await fetch(`${base}/api/docs/${asset}`);
assert.equal(response.status, 200, asset);
const content = await response.text();
assert.ok(content.length > 0);
if (asset === 'swagger-ui-init.js') {
assert.match(content, /\/api\/openapi.json/);
assert.match(content, /"persistAuthorization": false/);
assert.match(content, /"validatorUrl": null/);
}
}
const spec = await fetch(`${base}/api/openapi.json`);
assert.equal(spec.status, 200);
assert.match(spec.headers.get('content-type')!, /application\/json/);
assert.deepEqual(await spec.json(), customerOpenApi);
const redirect = await fetch(`${base}/api/docs`, { redirect: 'manual' });
assert.equal(redirect.status, 301);
assert.equal(redirect.headers.get('location'), '/api/docs/');
});
+134
View File
@@ -0,0 +1,134 @@
import { unassignedBirdMatchSchema, claimBirdSchema } from '../birdMembershipSchemas.js';
import { behaviorTypeSchema, behaviorOccurrenceSchema } from '../behaviorSchemas.js';
import { z } from 'zod';
import { extendZodWithOpenApi, OpenAPIRegistry, OpenApiGeneratorV3, type RouteConfig } from '@asteasolutions/zod-to-openapi';
import { birdSchema, workspaceMemberSchema, workspaceRoleSchema, flockNoteSchema, locationSearchSchema,
weightSchema, vetVisitSchema, medicationSchema, medicationAdministrationSchema } from '../schemas.js';
import * as responses from './responses.js';
extendZodWithOpenApi(z);
const registry = new OpenAPIRegistry();
registry.registerComponent('securitySchemes', 'IntegrationToken', {
type: 'http', scheme: 'bearer', bearerFormat: 'flpt_…',
description: 'Paste your integration token, without the Bearer prefix. Create it in FlockPal Settings → Integration tokens.',
});
const models = Object.fromEntries(Object.entries(responses).map(([name, schema]) => [name, registry.register(name.replace('Response', ''), schema)]));
const error = registry.register('Error', z.object({
error: z.string(), code: z.string().optional(),
details: z.object({ formErrors: z.array(z.string()), fieldErrors: z.record(z.array(z.string())) }).optional(),
}));
const json = (schema: z.ZodTypeAny, example?: unknown) => ({ 'application/json': { schema, ...(example ? { example } : {}) } });
const errors: Record<number, string> = {
400: 'Invalid request.', 401: 'Missing, expired, revoked, or invalid integration token.',
402: 'Workspace is read-only: subscription must be active/trialing, or rescue verification approved.',
403: 'Insufficient token scope or workspace role.', 404: 'Resource not found in this workspace, or cannot be changed.',
409: 'Conflict: duplicate band/tag ID, duplicate weight date, or memorialized bird is read-only.',
500: 'Internal server error.', 502: 'Location provider request failed.', 503: 'Location search is not configured.',
};
type Endpoint = {
method: 'get' | 'post' | 'put' | 'delete'; path: string; summary: string; tag: string;
response?: z.ZodTypeAny; body?: z.ZodTypeAny; example?: unknown; query?: z.AnyZodObject;
description?: string; status?: number; errors?: number[]; roles?: string[];
};
const careRoles = ['owner', 'assistant', 'caregiver'];
function endpoint(config: Endpoint) {
const write = config.method !== 'get';
const params = Object.fromEntries([...config.path.matchAll(/\{(\w+)\}/g)].map((match) => [match[1], z.string().uuid()]));
const responseMap: RouteConfig['responses'] = {
[config.status ?? (config.method === 'delete' ? 204 : config.method === 'post' ? 201 : 200)]: {
description: config.method === 'delete' ? 'Deleted successfully. No response body.' : 'Success.',
...(config.response ? { content: json(config.response) } : {}),
},
429: { description: 'Rate limit exceeded. General limit: 300 requests per 15 minutes per IP; location search additionally allows 40 per 15 minutes.',
headers: { 'Retry-After': { schema: { type: 'string' }, description: 'Seconds until retry.' } },
content: { 'text/html': { schema: { type: 'string' } }, 'application/json': { schema: error } } },
};
for (const status of new Set([401, 500, ...(write ? [402, 403] : []), ...(config.body || config.query ? [400] : []), ...(config.errors ?? [])])) {
responseMap[status] = { description: errors[status], content: json(error) };
}
registry.registerPath({
method: config.method, path: config.path, summary: config.summary, tags: [config.tag],
operationId: `${config.method}_${config.path.replace(/[{}]/g, '').replace(/[^a-zA-Z0-9]+/g, '_').replace(/^_/, '')}`,
description: [config.description, write ? `Requires a read_write token and an active writable workspace. Allowed roles: ${(config.roles ?? careRoles).join(', ')}.` : 'Accepts read_only or read_write integration tokens.'].filter(Boolean).join('\n\n'),
security: [{ IntegrationToken: [] }],
request: {
...(Object.keys(params).length ? { params: z.object(params) } : {}),
...(config.query ? { query: config.query } : {}),
...(config.body ? { body: { required: true, content: json(config.body, config.example) } } : {}),
},
responses: responseMap,
});
}
const one = (name: string, model: z.ZodTypeAny) => z.object({ [name]: model });
const many = (name: string, model: z.ZodTypeAny) => one(name, z.array(model));
endpoint({ method: 'get', path: '/workspace', summary: 'Get the token’s workspace', tag: 'Workspace', response: one('workspace', models.workspaceResponse) });
endpoint({ method: 'get', path: '/workspace/members', summary: 'List workspace members', tag: 'Workspace', response: many('members', models.memberResponse) });
endpoint({ method: 'post', path: '/workspace/members', summary: 'Add or update a workspace member', tag: 'Workspace', body: registry.register('MemberInput', workspaceMemberSchema), response: one('member', models.memberResponse), roles: ['owner', 'assistant'] });
endpoint({ method: 'put', path: '/workspace/members/{memberId}', summary: 'Change a member’s role', tag: 'Workspace', body: z.object({ role: workspaceRoleSchema }), response: one('member', models.memberResponse), roles: ['owner', 'assistant'], errors: [404], description: 'Only the billing owner can promote collaborators to owner. Additional protections apply to changing your own or the billing owner’s membership.' });
endpoint({ method: 'delete', path: '/workspace/members/{memberId}', summary: 'Remove a workspace member', tag: 'Workspace', roles: ['owner', 'assistant'], errors: [404], description: 'Protected memberships cannot be removed.' });
endpoint({ method: 'get', path: '/notes', summary: 'List flock notes', tag: 'Notes', response: many('notes', models.noteResponse) });
endpoint({ method: 'post', path: '/notes', summary: 'Create a flock note', tag: 'Notes', body: registry.register('NoteInput', flockNoteSchema), response: one('note', models.noteResponse), errors: [404], example: { body: 'Enjoyed a new enrichment activity today.' } });
endpoint({ method: 'delete', path: '/notes/{noteId}', summary: 'Delete a flock note', tag: 'Notes', errors: [404] });
endpoint({ method: 'get', path: '/locations/search', summary: 'Search for a location', tag: 'Locations', query: locationSearchSchema, response: many('results', models.locationResponse), errors: [502, 503], description: 'Search cities, regions, and countries. Requires 3–120 characters; returns up to three matches. Additional rate limit: 40 requests per 15 minutes per IP.' });
endpoint({ method: 'get', path: '/birds/unassigned-match', summary: 'Check for an unassigned bird by band ID', tag: 'Birds', query: unassignedBirdMatchSchema, response: z.object({ available: z.boolean() }), errors: [403], description: 'Requires owner, assistant, or caregiver role. Returns only availability, not profile details. Matching ignores case and surrounding whitespace; partial and unknown IDs do not match.' });
endpoint({ method: 'post', path: '/birds/claim', summary: 'Add an unassigned bird with its existing history', tag: 'Birds', body: claimBirdSchema, response: z.object({ bird: models.birdResponse, historyImported: z.literal(true) }), status: 200, errors: [409], description: 'Requires confirmHistory: true. Atomically assigns the existing bird to the current flock, preserving its ID, profile, photo, and history. Existing profile details are used. Birds already in a flock cannot be claimed.' });
endpoint({ method: 'get', path: '/birds', summary: 'List active and memorialized birds', tag: 'Birds', response: z.object({ birds: z.array(models.birdResponse), memorializedBirds: z.array(models.birdResponse) }) });
const birdInput = registry.register('BirdInput', birdSchema);
const birdDescription = 'motivators and demotivators each allow up to three non-empty lines. hatchDay takes precedence over the legacy dateOfBirth field. photoDataUrl accepts an image data URL or HTTP(S) URL; returned photo links may expire.';
endpoint({ method: 'post', path: '/birds', summary: 'Create a bird', tag: 'Birds', body: birdInput, response: one('bird', models.birdResponse), errors: [409], description: birdDescription, example: { name: 'Yoda', species: 'African grey' } });
endpoint({ method: 'put', path: '/birds/{birdId}', summary: 'Update a bird', tag: 'Birds', body: birdInput, response: one('bird', models.birdResponse), errors: [404, 409], description: `Submit the full editable profile: omitted optional fields may be cleared or reset. ${birdDescription}` });
endpoint({ method: 'delete', path: '/birds/{birdId}', summary: 'Remove a bird from its flock', tag: 'Birds', errors: [404, 409], description: 'Unassigns the bird without deleting its profile, photo, or care history. Bird-specific notes follow the bird; flock-wide notes and workspace audit logs stay in the old flock. Public sharing is disabled and pending transfers are revoked. An exact band ID match can later bring the bird and its history into a flock.' });
endpoint({ method: 'get', path: '/birds/{birdId}/timeline', summary: 'List bird timeline events', tag: 'Birds', response: many('events', models.timelineResponse), errors: [404] });
for (const resource of [
{ path: 'weights', single: 'weight', plural: 'weights', id: 'weightId', tag: 'Weights', input: weightSchema, model: models.weightResponse },
{ path: 'vet-visits', single: 'vetVisit', plural: 'vetVisits', id: 'visitId', tag: 'Vet visits', input: vetVisitSchema, model: models.vetVisitResponse },
{ path: 'medications', single: 'medication', plural: 'medications', id: 'medicationId', tag: 'Medications', input: medicationSchema, model: models.medicationResponse },
]) {
const path = `/birds/{birdId}/${resource.path}`;
const body = registry.register(`${resource.single}Input`, resource.input);
const description = resource.path === 'medications' ? 'endDate must be on or after startDate. Supply 1–8 doseSchedule entries with unique application-defined keys; use a key as administrationSlot when recording a dose.' : undefined;
endpoint({ method: 'get', path, summary: `List ${resource.tag.toLowerCase()}`, tag: resource.tag, response: many(resource.plural, resource.model),
...(resource.path === 'weights' ? { query: z.object({ days: z.coerce.number().min(1).max(425).default(30) }), description: 'Lookback window in days; defaults to 30. Numeric values are clamped to 1–425. Returns an empty list when no matching records exist.' } : {}) });
endpoint({ method: 'post', path, summary: `Create ${resource.single === 'vetVisit' ? 'a vet visit' : `a ${resource.single}`}`, tag: resource.tag, body, response: one(resource.single, resource.model), errors: [404, 409], description,
...(resource.path === 'weights' ? { example: { weightGrams: 425, recordedOn: '2026-09-27', notes: 'Morning weight' } } : {}) });
endpoint({ method: 'put', path: `${path}/{${resource.id}}`, summary: `Update ${resource.single === 'vetVisit' ? 'a vet visit' : `a ${resource.single}`}`, tag: resource.tag, body, response: one(resource.single, resource.model), errors: [404, 409],
description: resource.path === 'weights' ? 'Only the three most recent weight records are editable. Older records return 404. One weight entry is allowed per bird per date.' : `Submit the full editable record; omitted optional fields may be reset. ${description ?? ''}` });
if (resource.path !== 'weights') endpoint({ method: 'delete', path: `${path}/{${resource.id}}`, summary: `Delete ${resource.single === 'vetVisit' ? 'a vet visit' : 'a medication'}`, tag: resource.tag, errors: [404, 409] });
}
endpoint({ method: 'get', path: '/birds/{birdId}/medication-administrations', summary: 'List medication administrations', tag: 'Medications', response: many('administrations', models.administrationResponse) });
endpoint({ method: 'post', path: '/birds/{birdId}/medications/{medicationId}/administrations', summary: 'Record or update a medication dose', tag: 'Medications', body: registry.register('AdministrationInput', medicationAdministrationSchema), response: one('administration', models.administrationResponse), errors: [404, 409], description: 'Creates or updates the record for this medication, date, and administrationSlot. Use a doseSchedule key for administrationSlot; it defaults to dose-1. Returns 201 for both creation and update.' });
const behaviorTypeResponse = registry.register('BehaviorType', z.object({
id: z.string().uuid(), name: z.string(), description: z.string().nullable(), createdAt: z.string().datetime(),
}));
const behaviorResponse = registry.register('BehaviorOccurrence', z.object({
id: z.string().uuid(), birdId: z.string().uuid(), behaviorTypeId: z.string().uuid(), behaviorName: z.string(),
occurredAt: z.string().datetime(), durationSeconds: z.number().nullable(), severity: z.number().int().min(1).max(5).nullable(),
notes: z.string().nullable(), createdAt: z.string().datetime(), updatedAt: z.string().datetime(),
}));
endpoint({ method: 'get', path: '/birds/{birdId}/behavior-types', summary: 'List available behavior types', tag: 'Behavior Journal', response: many('behaviorTypes', behaviorTypeResponse), errors: [400, 404], description: 'Includes common behaviors, flock custom behaviors, and behaviors in this bird’s transferred history.' });
endpoint({ method: 'post', path: '/birds/{birdId}/behavior-types', summary: 'Create a reusable flock behavior type', tag: 'Behavior Journal', body: behaviorTypeSchema, response: one('behaviorType', behaviorTypeResponse), errors: [404, 409], description: 'Names are unique within the flock, ignoring case. An existing type is returned for a duplicate name.' });
endpoint({ method: 'get', path: '/birds/{birdId}/behaviors', summary: 'List behavior occurrences in a date range', tag: 'Behavior Journal', response: many('occurrences', behaviorResponse), query: z.object({ from: z.string().datetime({ offset: true }), to: z.string().datetime({ offset: true }), behaviorTypeId: z.string().uuid().optional() }), errors: [404], description: 'From is inclusive; to is exclusive. The range must be positive and at most 32 days. Send local month boundaries with their UTC offsets or converted to UTC. Results are newest first; individual events are never aggregated.' });
endpoint({ method: 'post', path: '/birds/{birdId}/behaviors', summary: 'Record a behavior occurrence', tag: 'Behavior Journal', body: behaviorOccurrenceSchema, response: one('occurrence', behaviorResponse), errors: [404, 409], description: 'Duration is optional and measured in seconds. Intensity is optional, from 1 to 5. Occurrence timestamps require a time zone offset.' });
endpoint({ method: 'put', path: '/birds/{birdId}/behaviors/{occurrenceId}', summary: 'Edit a behavior occurrence', tag: 'Behavior Journal', body: behaviorOccurrenceSchema, response: one('occurrence', behaviorResponse), errors: [404, 409] });
endpoint({ method: 'delete', path: '/birds/{birdId}/behaviors/{occurrenceId}', summary: 'Delete a behavior occurrence', tag: 'Behavior Journal', errors: [400, 404, 409] });
export const customerOpenApi = new OpenApiGeneratorV3(registry.definitions).generateDocument({
openapi: '3.0.3',
info: { title: 'FlockPal Customer API', version: '0.1.0', description: `Connect your flock to scripts and automation tools such as n8n.
### Getting started
1. Sign in to FlockPal and open Settings → Integration tokens.
2. Create a read_only token for reading, or read_write for changes. Copy the secret when shown; it is only displayed once.
3. Click Authorize and paste the token (without the Bearer prefix). Requests send Authorization: Bearer flpt_….
Tokens are scoped to the workspace where they were created and use the creating user’s current membership permissions. Create separate tokens for other workspaces. Expired or revoked tokens return 401.
Writes require read_write scope, an allowed role, and an active/trialing subscription or approved rescue workspace. Memorialized birds are read-only. Try it out sends real requests to this FlockPal instance, including changes and deletions; authorization is not persisted across reloads.
This reference covers customer integration endpoints. Manage tokens, authentication, billing, transfers, and memorialization in the FlockPal application. Photo URLs returned by the API can be used directly and may expire.
The general rate limit is 300 requests per 15 minutes per IP; location search also has a 40-request limit. On 429, wait for Retry-After before retrying.` },
servers: [{ url: '/api', description: 'This FlockPal instance' }],
tags: ['Workspace', 'Birds', 'Weights', 'Vet visits', 'Medications', 'Notes', 'Locations', 'Behavior Journal'].map((name) => ({ name })),
});
+61
View File
@@ -0,0 +1,61 @@
import { z } from 'zod';
import { birdGenderSchema, workspaceRoleSchema } from '../schemas.js';
const id = z.string().uuid();
const text = z.string().nullable();
const date = z.string().regex(/^\d{4}-\d{2}-\d{2}$/);
const timestamp = z.string().datetime({ offset: true });
export const locationResponse = z.object({
label: text, city: text, region: text, country: text, countryCode: text,
latitude: z.number().nullable(), longitude: z.number().nullable(),
precision: z.enum(['city', 'region', 'country']).nullable(), verifiedAt: timestamp, provider: z.literal('mapbox').nullable(), providerPlaceId: text,
});
export const workspaceResponse = z.object({
id: z.number().int(), name: z.string(), workspaceType: z.enum(['standard', 'rescue']), billingEmail: text,
billingPlan: z.enum(['rescue_free', 'household_basic', 'household_plus', 'household_macaw', 'household_hyacinth_macaw']),
billingInterval: z.enum(['monthly', 'yearly']),
subscriptionStatus: z.enum(['active', 'trialing', 'past_due', 'canceled', 'unpaid', 'none']),
stripeCustomerId: text, stripeSubscriptionId: text,
rescueVerificationStatus: z.enum(['not_required', 'pending', 'approved', 'rejected']),
createdAt: timestamp, updatedAt: timestamp,
});
export const memberResponse = z.object({
id, workspaceId: z.number().int(), userId: id.nullable(), inviteEmail: z.string(), name: z.string(),
role: workspaceRoleSchema, acceptedAt: timestamp.nullable(), createdAt: timestamp,
});
export const birdResponse = z.object({
id, workspaceId: z.number().int(), name: z.string(), tagId: text, species: z.string(),
motivators: text, demotivators: text, favoriteSnack: text, locationLabel: text,
locationDetails: locationResponse.nullable(), vetClinicName: text, vetClinicAddress: text,
vetAccountNumber: text, vetDoctorName: text, gender: birdGenderSchema,
hatchDay: date.nullable(), dateOfBirth: date.nullable(), gotchaDay: date.nullable(), chartColor: z.string(),
photoDataUrl: text.describe('Photo URL or legacy data URL. Storage-backed URLs expire; refresh the bird list to obtain a new URL.'),
photoObjectKey: text, photoContentType: text, photoUpdatedAt: timestamp.nullable(),
notifyOnDob: z.boolean(), notifyOnGotchaDay: z.boolean(), publicProfileCode: text, publicProfileEnabled: z.boolean(),
memorializedAt: timestamp.nullable(), memorializedOn: date.nullable(), memorialNote: text,
notifyOnMemorialDay: z.boolean(), createdAt: timestamp,
latestWeightGrams: z.number().nullable(), latestRecordedOn: date.nullable(),
});
export const weightResponse = z.object({ id, birdId: id, weightGrams: z.number(), recordedOn: date, notes: text });
export const vetVisitResponse = z.object({ id, birdId: id, visitedOn: date, clinicName: z.string(), reason: z.string(), notes: text });
export const medicationResponse = z.object({
id, birdId: id, name: z.string(), dosage: z.string(),
frequency: z.enum(['once_daily', 'twice_daily', 'every_8_hours', 'every_6_hours', 'as_needed']),
doseSchedule: z.array(z.object({ key: z.string(), label: z.string(), time: z.string() })),
route: text, startDate: date, endDate: date.nullable(), notes: text, remindersEnabled: z.boolean(),
});
export const administrationResponse = z.object({
id, medicationId: id, birdId: id, administeredOn: date, administrationSlot: z.string(),
status: z.enum(['administered', 'missed']), notes: text, createdByUserId: id.nullable(), createdAt: timestamp,
});
export const noteResponse = z.object({
id, workspaceId: z.number().int(), birdId: id.nullable(), birdName: text, title: z.string(), body: z.string(),
createdByUserId: id.nullable(), createdByName: text, createdAt: timestamp, updatedAt: timestamp,
});
export const timelineResponse = z.object({
id, birdId: id, eventType: z.enum(['profile_created', 'transferred', 'location_updated', 'owner_changed', 'manual_note', 'removed_from_flock', 'joined_flock']),
fromWorkspaceId: z.number().int().nullable(), toWorkspaceId: z.number().int().nullable(),
fromWorkspaceName: text, toWorkspaceName: text, fromOwnerEmail: text, toOwnerEmail: text,
locationLabel: text, locationDetails: locationResponse.nullable(), note: text, eventDate: date,
createdByUserId: id.nullable(), createdAt: timestamp,
});
+24
View File
@@ -0,0 +1,24 @@
import type { Express } from 'express';
import helmet from 'helmet';
import swaggerUi from 'swagger-ui-express';
import { customerOpenApi } from './openapi.js';
// Mount before application middleware so docs do not consume API rate limits.
// Swagger assets and initialization are served locally; no external validator is used.
export function mountApiDocs(app: Express) {
app.get('/api/openapi.json', helmet(), (_req, res) => res.json(customerOpenApi));
app.use('/api/docs', helmet({
contentSecurityPolicy: { directives: {
'script-src': ["'self'"],
'connect-src': ["'self'"],
// Keep local HTTP development usable; production transport is handled by the proxy.
'upgrade-insecure-requests': null,
} },
}), swaggerUi.serve, swaggerUi.setup(undefined, {
customSiteTitle: 'FlockPal API Reference',
swaggerOptions: {
url: '/api/openapi.json', validatorUrl: null, persistAuthorization: false,
displayRequestDuration: true, docExpansion: 'none',
},
}));
}
@@ -0,0 +1,47 @@
import { db } from '../db/client.js';
import type { BehaviorInput, BehaviorType, BehaviorOccurrence } from '../behaviorSchemas.js';
const typeFields = `id, name, description, created_at AS "createdAt"`;
const occurrenceFields = `o.id, o.bird_id AS "birdId", o.behavior_type_id AS "behaviorTypeId",
t.name AS "behaviorName", o.occurred_at AS "occurredAt", o.duration_seconds AS "durationSeconds",
o.severity, o.notes, o.created_at AS "createdAt", o.updated_at AS "updatedAt"`;
export async function listBehaviorTypes(workspaceId: number, birdId: string) {
// Include types used by this bird before a flock transfer, without exposing other flock types.
return (await db.query<BehaviorType>(`SELECT ${typeFields} FROM behavior_types t
WHERE is_default OR workspace_id = $1 OR EXISTS (
SELECT 1 FROM behavior_occurrences o JOIN birds b ON b.id = o.bird_id
WHERE o.behavior_type_id = t.id AND b.id = $2 AND b.workspace_id = $1)
ORDER BY name`, [workspaceId, birdId])).rows;
}
export async function createBehaviorType(workspaceId: number, name: string, description?: string | null) {
return (await db.query<BehaviorType>(`INSERT INTO behavior_types (workspace_id, name, description) VALUES ($1, $2, $3)
ON CONFLICT (workspace_id, lower(name)) WHERE workspace_id IS NOT NULL
DO UPDATE SET name = behavior_types.name RETURNING ${typeFields}`, [workspaceId, name, description || null])).rows[0];
}
export async function listBehaviorOccurrences(birdId: string, workspaceId: number, from: string, to: string, typeId?: string) {
return (await db.query<BehaviorOccurrence>(`SELECT ${occurrenceFields} FROM behavior_occurrences o
JOIN birds b ON b.id = o.bird_id JOIN behavior_types t ON t.id = o.behavior_type_id
WHERE b.id = $1 AND b.workspace_id = $2 AND o.occurred_at >= $3 AND o.occurred_at < $4
AND ($5::uuid IS NULL OR o.behavior_type_id = $5) ORDER BY o.occurred_at DESC, o.id`,
[birdId, workspaceId, from, to, typeId || null])).rows;
}
export async function saveBehaviorOccurrence(birdId: string, workspaceId: number, input: BehaviorInput, id?: string) {
const params = [birdId, workspaceId, input.behaviorTypeId, input.occurredAt, input.durationSeconds ?? null, input.severity ?? null, input.notes || null];
// Keep authorization in the mutation as well as the route to protect against concurrent transfers.
const allowed = `EXISTS (SELECT 1 FROM birds b WHERE b.id = $1 AND b.workspace_id = $2 AND b.memorialized_at IS NULL)
AND EXISTS (SELECT 1 FROM behavior_types t WHERE t.id = $3 AND
(t.is_default OR t.workspace_id = $2 OR EXISTS
(SELECT 1 FROM behavior_occurrences previous WHERE previous.bird_id = $1 AND previous.behavior_type_id = t.id)))`;
const mutation = id
? `UPDATE behavior_occurrences SET behavior_type_id = $3, occurred_at = $4, duration_seconds = $5,
severity = $6, notes = $7, updated_at = CURRENT_TIMESTAMP WHERE bird_id = $1 AND id = $8 AND ${allowed} RETURNING *`
: `INSERT INTO behavior_occurrences (bird_id, behavior_type_id, occurred_at, duration_seconds, severity, notes)
SELECT $1, $3, $4, $5, $6, $7 WHERE ${allowed} RETURNING *`;
return (await db.query<BehaviorOccurrence>(`WITH saved AS (${mutation}) SELECT ${occurrenceFields}
FROM saved o JOIN behavior_types t ON t.id = o.behavior_type_id`, id ? [...params, id] : params)).rows[0];
}
export async function deleteBehaviorOccurrence(birdId: string, workspaceId: number, id: string) {
return (await db.query<{ id: string }>(`DELETE FROM behavior_occurrences o USING birds b WHERE o.bird_id = b.id
AND b.id = $1 AND b.workspace_id = $2 AND b.memorialized_at IS NULL AND o.id = $3 RETURNING o.id`, [birdId, workspaceId, id])).rows[0];
}
@@ -0,0 +1,50 @@
import { db } from '../db/client.js';
// Only reveal whether an exact normalized band match is available, never its profile or former flock.
export async function hasUnassignedBird(tagId: string): Promise<boolean> {
const result = await db.query<{ id: string }>(
`SELECT id FROM birds WHERE workspace_id IS NULL AND memorialized_at IS NULL
AND LOWER(BTRIM(tag_id)) = LOWER(BTRIM($1)) LIMIT 1`, [tagId],
);
return result.rows.length > 0;
}
export async function removeBirdFromFlock(birdId: string, workspaceId: number, userId: string): Promise<boolean> {
return db.transaction(async (client) => {
const result = await client.query<{ id: string }>(
`UPDATE birds SET workspace_id = NULL, public_profile_enabled = FALSE
WHERE id = $1 AND workspace_id = $2 AND memorialized_at IS NULL RETURNING id`, [birdId, workspaceId],
);
if (!result.rows.length) return false;
await client.query(`UPDATE flock_notes SET workspace_id = NULL WHERE bird_id = $1`, [birdId]);
await client.query(`UPDATE bird_transfer_codes SET revoked_at = CURRENT_TIMESTAMP
WHERE bird_id = $1 AND completed_at IS NULL AND revoked_at IS NULL`, [birdId]);
await client.query(`DELETE FROM pending_bird_transfers WHERE bird_id = $1 AND completed_at IS NULL`, [birdId]);
await client.query(`INSERT INTO bird_timeline_events
(bird_id, event_type, from_workspace_id, from_workspace_name, note, created_by_user_id)
SELECT $1, 'removed_from_flock', id, name, 'Removed from flock; profile and history retained.', $3
FROM workspaces WHERE id = $2`, [birdId, workspaceId, userId]);
return true;
});
}
export async function claimUnassignedBird(tagId: string, workspaceId: number, userId: string): Promise<string | null> {
return db.transaction(async (client) => {
// The row lock and repeated unassigned predicate prevent competing flocks from claiming the same bird.
const match = await client.query<{ id: string }>(
`SELECT id FROM birds WHERE workspace_id IS NULL AND memorialized_at IS NULL
AND LOWER(BTRIM(tag_id)) = LOWER(BTRIM($1)) FOR UPDATE`, [tagId],
);
if (!match.rows.length) return null;
const birdId = match.rows[0].id;
const claimed = await client.query(`UPDATE birds SET workspace_id = $2, public_profile_enabled = FALSE
WHERE id = $1 AND workspace_id IS NULL RETURNING id`, [birdId, workspaceId]);
if (!claimed.rows.length) return null;
await client.query(`UPDATE flock_notes SET workspace_id = $2 WHERE bird_id = $1 AND workspace_id IS NULL`, [birdId, workspaceId]);
await client.query(`INSERT INTO bird_timeline_events
(bird_id, event_type, to_workspace_id, to_workspace_name, note, created_by_user_id)
SELECT $1, 'joined_flock', id, name, 'Added by matching band ID; existing profile and history retained.', $3
FROM workspaces WHERE id = $2`, [birdId, workspaceId, userId]);
return birdId;
});
}
@@ -789,18 +789,6 @@ export const updateMemorialReminderPreference = async ({
return result.rows[0] ?? null;
};
export const deleteBird = async (birdId: string, workspaceId: number) => {
const result = await db.query<{ id: string }>(
`DELETE FROM birds
WHERE id = $1
AND workspace_id = $2
RETURNING id`,
[birdId, workspaceId],
);
return Boolean(result.rowCount);
};
export const transferBirdToWorkspace = async (birdId: string, sourceWorkspaceId: number, targetWorkspaceId: number) => {
const result = await db.query<BirdRow>(
`UPDATE birds
+211
View File
@@ -0,0 +1,211 @@
import { z } from 'zod';
// Shared runtime validation and API documentation schemas.
export const dateStringSchema = z.string().regex(/^\d{4}-\d{2}-\d{2}$/);
export const chartColorSchema = z.string().regex(/^#[0-9a-fA-F]{6}$/);
export const photoDataUrlSchema = z
.string()
.regex(/^data:image\/(?:png|jpeg|jpg|webp|gif);base64,[A-Za-z0-9+/=]+$/)
.max(1_500_000);
export const photoUrlSchema = z.string().trim().url().max(2000);
export const magicLinkRequestSchema = z.object({
name: z.string().trim().max(160).optional().or(z.literal('')),
email: z.string().trim().email().max(255),
redirectTo: z.string().trim().url().max(2000).optional().or(z.literal('')),
});
export const switchWorkspaceSchema = z.object({
workspaceId: z.coerce.number().int().positive(),
});
export const workspaceTypeSchema = z.enum(['standard', 'rescue']);
export const workspaceRoleSchema = z.enum(['owner', 'assistant', 'caregiver', 'viewer']);
export const billingPlanSchema = z.enum(['household_basic', 'household_plus', 'household_macaw', 'household_hyacinth_macaw']);
export const billingIntervalSchema = z.enum(['monthly', 'yearly']);
export const integrationTokenScopeSchema = z.enum(['read_only', 'read_write']);
export const birdGenderSchema = z.enum(['unknown', 'male', 'female', 'male_dna', 'female_dna']);
export const rescueVerificationStatusSchema = z.enum(['pending', 'approved', 'rejected']);
export const rescueOnboardingSchema = z.object({
name: z.string().trim().max(160).optional().or(z.literal('')),
city: z.string().trim().max(120).optional().or(z.literal('')),
state: z.string().trim().max(80).optional().or(z.literal('')),
ein: z.string().trim().max(32).optional().or(z.literal('')),
website: z.string().trim().url().max(2000).optional().or(z.literal('')),
});
export const workspaceSchema = z.object({
name: z.string().trim().min(1).max(160),
workspaceType: workspaceTypeSchema,
billingEmail: z.string().trim().email().max(255).optional().or(z.literal('')),
billingPlan: billingPlanSchema.optional(),
billingInterval: billingIntervalSchema.optional(),
rescueOnboarding: rescueOnboardingSchema.optional(),
});
export const createWorkspaceSchema = z.object({
name: z.string().trim().min(1).max(160),
workspaceType: workspaceTypeSchema,
billingEmail: z.string().trim().email().max(255).optional().or(z.literal('')),
billingPlan: billingPlanSchema.optional(),
billingInterval: billingIntervalSchema.optional(),
rescueOnboarding: rescueOnboardingSchema.optional(),
});
export const workspaceMemberSchema = z.object({
name: z.string().trim().min(1).max(160),
email: z.string().trim().email().max(255),
role: workspaceRoleSchema,
});
export const flockTransferSchema = z.object({
destinationOwnerEmail: z.string().trim().email().max(255),
});
export const lostBirdReportSchema = z.object({
tagId: z.string().trim().min(1).max(80),
finderName: z.string().trim().max(160).optional().or(z.literal('')),
finderEmail: z.string().trim().email().max(255).optional().or(z.literal('')),
foundLocation: z.string().trim().max(255).optional().or(z.literal('')),
message: z.string().trim().max(1000).optional().or(z.literal('')),
});
export const publicProfileCodeSchema = z.string().trim().regex(/^[A-Za-z0-9_-]{8,32}$/);
export const birdTransferCodeSchema = z.string().trim().regex(/^[A-Za-z0-9_-]{12,32}$/);
export const birdProfileListSchema = z
.string()
.trim()
.max(1000)
.refine(
(value) => value.split(/\r?\n/).map((item) => item.trim()).filter(Boolean).length <= 3,
'Use no more than three list items.',
)
.optional()
.or(z.literal(''));
export const verifiedLocationDetailsSchema = z
.object({
label: z.string().trim().max(220).optional().or(z.literal('')),
city: z.string().trim().max(120).optional().or(z.literal('')),
region: z.string().trim().max(120).optional().or(z.literal('')),
country: z.string().trim().max(120).optional().or(z.literal('')),
countryCode: z.string().trim().max(2).optional().or(z.literal('')),
latitude: z.coerce.number().min(-90).max(90).optional().nullable().or(z.literal('')),
longitude: z.coerce.number().min(-180).max(180).optional().nullable().or(z.literal('')),
precision: z.enum(['city', 'region', 'country']).optional(),
provider: z.literal('mapbox').optional().nullable(),
providerPlaceId: z.string().trim().max(220).optional().or(z.literal('')),
})
.optional()
.nullable();
export const locationSearchSchema = z.object({
q: z.string().trim().min(3).max(120),
});
export const birdSchema = z.object({
name: z.string().trim().min(1).max(120),
tagId: z.string().trim().max(80).optional().or(z.literal('')),
species: z.string().trim().min(1).max(120),
motivators: birdProfileListSchema,
demotivators: birdProfileListSchema,
favoriteSnack: z.string().trim().max(160).optional().or(z.literal('')),
locationLabel: z.string().trim().max(160).optional().or(z.literal('')),
locationDetails: verifiedLocationDetailsSchema,
vetClinicName: z.string().trim().max(160).optional().or(z.literal('')),
vetClinicAddress: z.string().trim().max(500).optional().or(z.literal('')),
vetAccountNumber: z.string().trim().max(120).optional().or(z.literal('')),
vetDoctorName: z.string().trim().max(160).optional().or(z.literal('')),
gender: birdGenderSchema.optional(),
hatchDay: dateStringSchema.optional().or(z.literal('')),
dateOfBirth: dateStringSchema.optional().or(z.literal('')),
gotchaDay: dateStringSchema.optional().or(z.literal('')),
chartColor: chartColorSchema.optional(),
photoDataUrl: z.union([photoDataUrlSchema, photoUrlSchema, z.literal('')]).optional(),
notifyOnDob: z.boolean().optional(),
notifyOnGotchaDay: z.boolean().optional(),
publicProfileEnabled: z.boolean().optional(),
});
export const memorializeBirdSchema = z.object({
memorializedOn: dateStringSchema,
memorialNote: z.string().trim().max(1000).optional().or(z.literal('')),
notifyOnMemorialDay: z.boolean().optional(),
});
export const memorialReminderPreferenceSchema = z.object({
notifyOnMemorialDay: z.boolean(),
});
export const birdTimelineEventSchema = z
.object({
eventType: z.enum(['location_updated', 'owner_changed', 'manual_note']),
eventDate: dateStringSchema.optional().or(z.literal('')),
locationLabel: z.string().trim().max(160).optional().or(z.literal('')),
locationDetails: verifiedLocationDetailsSchema,
note: z.string().trim().max(500).optional().or(z.literal('')),
})
.refine(
(value) =>
value.eventType === 'owner_changed' ||
Boolean(
value.locationLabel?.trim() ||
value.note?.trim() ||
value.locationDetails?.city?.trim() ||
value.locationDetails?.region?.trim() ||
value.locationDetails?.country?.trim(),
),
'Add a location or note for this timeline item.',
);
export const weightSchema = z.object({
weightGrams: z.coerce.number().positive().max(10000),
recordedOn: dateStringSchema,
notes: z.string().trim().max(280).optional().or(z.literal('')),
});
export const vetVisitSchema = z.object({
visitedOn: dateStringSchema,
clinicName: z.string().trim().min(1).max(160),
reason: z.string().trim().min(1).max(160),
notes: z.string().trim().max(1000).optional().or(z.literal('')),
});
export const medicationSchema = z
.object({
name: z.string().trim().min(1).max(160),
dosage: z.string().trim().min(1).max(160),
frequency: z.enum(['once_daily', 'twice_daily', 'every_8_hours', 'every_6_hours', 'as_needed']),
doseSchedule: z
.array(
z.object({
key: z.string().trim().min(1).max(80),
label: z.string().trim().min(1).max(80),
time: z.string().trim().regex(/^$|^\d{2}:\d{2}$/),
}),
)
.min(1)
.max(8),
route: z.string().trim().max(80).optional().or(z.literal('')),
startDate: dateStringSchema,
endDate: dateStringSchema.optional().or(z.literal('')),
notes: z.string().trim().max(1000).optional().or(z.literal('')),
remindersEnabled: z.boolean().optional(),
})
.refine((value) => !value.endDate || value.endDate >= value.startDate, {
message: 'End date must be on or after start date.',
path: ['endDate'],
});
export const medicationAdministrationSchema = z.object({
administeredOn: dateStringSchema,
administrationSlot: z.string().trim().min(1).max(80).default('dose-1'),
status: z.enum(['administered', 'missed']),
notes: z.string().trim().max(500).optional().or(z.literal('')),
});
export const flockNoteSchema = z.object({
birdId: z.string().uuid().optional().nullable().or(z.literal('')),
body: z.string().trim().min(1).max(5000),
});
+1 -1
View File
@@ -5,7 +5,7 @@ import { deleteS3Object, putS3Object } from '../storage/s3Client.js';
type BirdPhotoMigrationRow = {
id: string;
workspace_id: number;
workspace_id: number | null;
name: string;
photo_data_url: string;
};
+2 -2
View File
@@ -54,7 +54,7 @@ export const buildBirdPhotoObjectKey = ({
extension,
now = new Date(),
}: {
workspaceId: number;
workspaceId: number | null;
birdId: string;
extension: string;
now?: Date;
@@ -63,7 +63,7 @@ export const buildBirdPhotoObjectKey = ({
const safeExtension = extension.replace(/^\./, '').toLowerCase() || 'bin';
const timestamp = now.toISOString().replace(/[:.]/g, '-');
return `${prefix}/workspace-${workspaceId}/${birdId}/${timestamp}.${safeExtension}`;
return `${prefix}/${workspaceId === null ? 'unassigned' : `workspace-${workspaceId}`}/${birdId}/${timestamp}.${safeExtension}`;
};
export const getImageExtensionFromContentType = (contentType: string) => {
+5 -2
View File
@@ -123,7 +123,7 @@ export type IntegrationTokenRow = {
export type BirdRow = {
id: string;
workspace_id: number;
workspace_id: number | null;
name: string;
tag_id: string | null;
species: string;
@@ -158,6 +158,7 @@ export type BirdRow = {
};
export type LostBirdMatchRow = BirdRow & {
workspace_id: number;
workspace_name: string;
workspace_billing_email: string | null;
};
@@ -165,6 +166,7 @@ export type LostBirdMatchRow = BirdRow & {
export type BirdMilestoneReminderType = 'hatch_day' | 'gotcha_day' | 'memorial_day';
export type BirdMilestoneReminderCandidateRow = BirdRow & {
workspace_id: number;
workspace_name: string;
reminder_type: BirdMilestoneReminderType;
reminder_date: string;
@@ -205,7 +207,7 @@ export type BirdTransferCodeRow = {
created_at: string;
};
export type BirdTimelineEventType = 'profile_created' | 'transferred' | 'location_updated' | 'owner_changed' | 'manual_note';
export type BirdTimelineEventType = 'profile_created' | 'transferred' | 'location_updated' | 'owner_changed' | 'manual_note' | 'removed_from_flock' | 'joined_flock';
export type BirdTimelineEventRow = {
id: string;
@@ -263,6 +265,7 @@ export type MedicationDoseScheduleItem = {
};
export type MedicationReminderCandidateRow = BirdRow & {
workspace_id: number;
workspace_name: string;
medication_id: string;
medication_name: string;
@@ -0,0 +1,94 @@
// Run against the disposable database described in docs/BEHAVIOR_JOURNAL.md.
import assert from 'node:assert/strict';
import { createHash, randomUUID } from 'node:crypto';
import { spawn } from 'node:child_process';
import { once } from 'node:events';
import { fileURLToPath } from 'node:url';
Object.assign(process.env, {
POSTGRES_HOST: '127.0.0.1', POSTGRES_PORT: '55439', POSTGRES_DB: 'behavior_test',
POSTGRES_USER: 'postgres', POSTGRES_PASSWORD: 'behavior_test_only', PORT: '55440',
MILESTONE_REMINDERS_ENABLED: 'false', MEDICATION_REMINDERS_ENABLED: 'false', WEIGHT_REMINDERS_ENABLED: 'false',
});
const { db } = await import('../dist/db/client.js');
const { ensureSchema } = await import('../dist/db/schema.js');
let server;
let logs = '';
try {
await ensureSchema();
await ensureSchema(); // Schema and seed must be safe to re-run.
const workspace = 100000 + Math.floor(Math.random() * 1000000000);
const otherWorkspace = workspace + 1;
await db.query(`INSERT INTO workspaces (id, name, workspace_type, rescue_verification_status) VALUES ($1, 'Journal test', 'rescue', 'approved'), ($2, 'Other test', 'rescue', 'approved')`, [workspace, otherWorkspace]);
const user = randomUUID();
await db.query(`INSERT INTO users (id, email, name) VALUES ($1, $2, 'Journal tester')`, [user, `${user}@example.test`]);
await db.query(`INSERT INTO workspace_members (workspace_id, user_id, invite_email, name, role, accepted_at) VALUES ($1, $2, 'journal@example.test', 'Journal tester', 'owner', NOW())`, [workspace, user]);
const token = randomUUID();
await db.query(`INSERT INTO auth_sessions (user_id, active_workspace_id, token_hash, expires_at) VALUES ($1, $2, $3, NOW() + INTERVAL '1 hour')`, [user, workspace, createHash('sha256').update(token).digest('hex')]);
const bird = randomUUID(), otherBird = randomUUID(), secondBird = randomUUID();
for (const [id, flock] of [[bird, workspace], [secondBird, workspace], [otherBird, otherWorkspace]]) {
await db.query(`INSERT INTO birds (id, workspace_id, name, species) VALUES ($1, $2, 'Journal bird', 'Parrot')`, [id, flock]);
}
server = spawn(process.execPath, [fileURLToPath(new URL('../dist/app.js', import.meta.url))], { cwd: '/tmp', env: process.env, stdio: ['ignore', 'pipe', 'pipe'] });
server.stdout.on('data', (data) => { logs += data; }); server.stderr.on('data', (data) => { logs += data; });
for (let attempt = 0; attempt < 100 && !logs.includes('listening'); attempt++) await new Promise((resolve) => setTimeout(resolve, 100));
assert.match(logs, /listening/, logs);
async function api(path, method = 'GET', body, status = 200, authenticated = true) {
const response = await fetch(`http://127.0.0.1:55440/api${path}`, { method, headers: { 'Content-Type': 'application/json', ...(authenticated ? { Authorization: `Bearer ${token}` } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}) });
const data = response.status === 204 ? null : await response.json();
assert.equal(response.status, status, JSON.stringify(data)); return data;
}
const base = `/birds/${bird}`;
const range = '?from=2026-10-01T00:00:00-04:00&to=2026-11-01T00:00:00-04:00';
const types = (await api(`${base}/behavior-types`)).behaviorTypes;
assert.equal(types.length, 9);
const custom = (await api(`${base}/behavior-types`, 'POST', { name: 'Wing stretching', description: 'Observed stretching' }, 201)).behaviorType;
const duplicate = (await api(`${base}/behavior-types`, 'POST', { name: 'wing stretching' }, 201)).behaviorType;
assert.equal(custom.id, duplicate.id);
const foreignType = (await db.query(`INSERT INTO behavior_types (workspace_id, name) VALUES ($1, 'Private behavior') RETURNING id`, [otherWorkspace])).rows[0].id;
const input = { behaviorTypeId: custom.id, occurredAt: '2026-10-05T23:30:12.123-04:00', durationSeconds: 90, severity: 3, notes: 'Observed after play' };
const first = (await api(`${base}/behaviors`, 'POST', input, 201)).occurrence;
assert.equal(first.occurredAt, '2026-10-06T03:30:12.123Z');
const second = (await api(`${base}/behaviors`, 'POST', { ...input, behaviorTypeId: types[0].id }, 201)).occurrence;
await api(`${base}/behaviors`, 'POST', { ...input, occurredAt: '2026-11-01T00:00:00-04:00' }, 201);
assert.equal((await api(`${base}/behaviors${range}`)).occurrences.length, 2);
assert.equal((await api(`${base}/behaviors${range}&behaviorTypeId=${custom.id}`)).occurrences.length, 1);
assert.equal((await api(`/birds/${secondBird}/behaviors${range}`)).occurrences.length, 0);
const edited = (await api(`${base}/behaviors/${first.id}`, 'PUT', { ...input, notes: 'Edited note', severity: null, durationSeconds: null })).occurrence;
assert.equal(edited.notes, 'Edited note'); assert.equal(edited.severity, null); assert.equal(edited.durationSeconds, null);
assert.equal(edited.createdAt, first.createdAt); assert.equal(edited.occurredAt, first.occurredAt);
for (const bad of [{ severity: 6 }, { durationSeconds: -1 }, { occurredAt: '2026-02-30T12:00:00Z' }, { occurredAt: '2026-10-05T12:00:00' }]) await api(`${base}/behaviors`, 'POST', { ...input, ...bad }, 400);
await api(`${base}/behaviors`, 'POST', { ...input, behaviorTypeId: foreignType }, 404);
await api(`/birds/${otherBird}/behavior-types`, 'GET', undefined, 404);
await api(`/birds/${otherBird}/behaviors${range}`, 'GET', undefined, 404);
await api(`/birds/${otherBird}/behaviors`, 'POST', input, 404);
await api(`/birds/${secondBird}/behaviors/${first.id}`, 'PUT', input, 404);
await api(`/birds/${secondBird}/behaviors/${first.id}`, 'DELETE', undefined, 404);
await api(`${base}/behavior-types`, 'GET', undefined, 401, false);
await api(`${base}/behaviors?from=invalid&to=invalid`, 'GET', undefined, 400);
await db.query(`UPDATE workspace_members SET role = 'viewer' WHERE user_id = $1`, [user]);
await api(`${base}/behaviors`, 'POST', input, 403);
await api(`${base}/behaviors/${first.id}`, 'PUT', input, 403);
await api(`${base}/behaviors/${first.id}`, 'DELETE', undefined, 403);
await db.query(`UPDATE workspace_members SET role = 'owner' WHERE user_id = $1`, [user]);
await db.query(`UPDATE workspaces SET rescue_verification_status = 'pending' WHERE id = $1`, [workspace]);
await api(`${base}/behaviors`, 'POST', input, 402);
await db.query(`UPDATE workspaces SET rescue_verification_status = 'approved' WHERE id = $1`, [workspace]);
await db.query(`UPDATE birds SET memorialized_at = NOW() WHERE id = $1`, [bird]);
await api(`${base}/behaviors`, 'POST', input, 409);
await api(`${base}/behaviors/${first.id}`, 'DELETE', undefined, 409);
await db.query(`UPDATE birds SET memorialized_at = NULL WHERE id = $1`, [bird]);
await api(`${base}/behaviors/${second.id}`, 'DELETE', undefined, 204);
assert.equal((await api(`${base}/behaviors${range}`)).occurrences.length, 1);
// Transfer the bird: old flock loses access, new flock retains normalized history.
await db.query(`UPDATE birds SET workspace_id = $1 WHERE id = $2`, [otherWorkspace, bird]);
await api(`${base}/behaviors${range}`, 'GET', undefined, 404);
await db.query(`INSERT INTO workspace_members (workspace_id, user_id, invite_email, name, role, accepted_at) VALUES ($1, $2, 'journal@example.test', 'Journal tester', 'owner', NOW())`, [otherWorkspace, user]);
await db.query(`UPDATE auth_sessions SET active_workspace_id = $1 WHERE user_id = $2`, [otherWorkspace, user]);
assert.equal((await api(`${base}/behaviors${range}`)).occurrences[0].behaviorName, 'Wing stretching');
assert.ok((await api(`${base}/behavior-types`)).behaviorTypes.some((type) => type.id === custom.id));
await api(`${base}/behaviors/${first.id}`, 'PUT', input);
console.log('PASS: schema repeatability; defaults/custom types; create/edit/delete; bird/behavior/month filters; timestamp precision; auth/role/billing/memorial restrictions; flock isolation and transfer history.');
} finally {
if (server && server.exitCode === null) { const exited = once(server, 'exit'); server.kill('SIGTERM'); await exited; }
await db.close();
}
+116
View File
@@ -0,0 +1,116 @@
// Uses only the disposable database and API ports documented in docs/BIRD_MEMBERSHIP.md.
import assert from 'node:assert/strict';
import { createHash, randomUUID } from 'node:crypto';
import { spawn } from 'node:child_process';
import { once } from 'node:events';
import { fileURLToPath } from 'node:url';
Object.assign(process.env, {
POSTGRES_HOST: '127.0.0.1', POSTGRES_PORT: '55439', POSTGRES_DB: 'behavior_test',
POSTGRES_USER: 'postgres', POSTGRES_PASSWORD: 'behavior_test_only', PORT: '55440',
MILESTONE_REMINDERS_ENABLED: 'false', MEDICATION_REMINDERS_ENABLED: 'false', WEIGHT_REMINDERS_ENABLED: 'false',
});
const { db } = await import('../dist/db/client.js');
const { ensureSchema } = await import('../dist/db/schema.js');
const { removeBirdFromFlock, claimUnassignedBird } = await import('../dist/repositories/birdMembershipRepository.js');
let server;
let output = '';
try {
await ensureSchema();
await ensureSchema();
const baseId = 100000 + Math.floor(Math.random() * 1000000000);
const accounts = [];
for (let i = 0; i < 3; i++) {
const workspace = baseId + i, user = randomUUID(), token = randomUUID(), email = `${user}@example.test`;
await db.query(`INSERT INTO workspaces (id, name, workspace_type, rescue_verification_status) VALUES ($1, $2, 'rescue', 'approved')`, [workspace, `Membership test ${i}`]);
await db.query(`INSERT INTO users (id, email, name, education_opt_out) VALUES ($1, $2, 'Tester', TRUE)`, [user, email]);
await db.query(`INSERT INTO workspace_members (workspace_id, user_id, invite_email, name, role, accepted_at) VALUES ($1, $2, $3, 'Tester', 'owner', NOW())`, [workspace, user, email]);
await db.query(`INSERT INTO auth_sessions (user_id, active_workspace_id, token_hash, expires_at) VALUES ($1, $2, $3, NOW() + INTERVAL '1 hour')`, [user, workspace, createHash('sha256').update(token).digest('hex')]);
accounts.push({ workspace, user, token });
}
const [source, destination, rival] = accounts;
const bird = randomUUID(), tagId = `BAND-${randomUUID()}`, publicCode = randomUUID().slice(0, 20);
const photo = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+a2ioAAAAASUVORK5CYII=';
await db.query(`INSERT INTO birds (id, workspace_id, name, tag_id, species, photo_data_url, public_profile_code, public_profile_enabled)
VALUES ($1, $2, 'Preserved bird', $3, 'Parrot', $4, $5, TRUE)`, [bird, source.workspace, tagId, photo, publicCode]);
await db.query(`INSERT INTO weight_records (bird_id, weight_grams, recorded_on) VALUES ($1, 120, CURRENT_DATE)`, [bird]);
await db.query(`INSERT INTO vet_visits (bird_id, visited_on, clinic_name, reason) VALUES ($1, CURRENT_DATE, 'Clinic', 'Checkup')`, [bird]);
const med = (await db.query(`INSERT INTO medications (bird_id, name, dosage, frequency, start_date) VALUES ($1, 'Existing medication', '1 ml', 'Daily', CURRENT_DATE) RETURNING id`, [bird])).rows[0].id;
await db.query(`INSERT INTO medication_administrations (medication_id, bird_id, administered_on, status) VALUES ($1, $2, CURRENT_DATE, 'administered')`, [med, bird]);
const behaviorType = (await db.query(`INSERT INTO behavior_types (workspace_id, name) VALUES ($1, 'Existing custom behavior') RETURNING id`, [source.workspace])).rows[0].id;
await db.query(`INSERT INTO behavior_occurrences (bird_id, behavior_type_id, occurred_at, notes) VALUES ($1, $2, NOW(), 'Existing occurrence')`, [bird, behaviorType]);
const birdNote = (await db.query(`INSERT INTO flock_notes (workspace_id, bird_id, title, body) VALUES ($1, $2, 'Bird note', 'Keep with bird') RETURNING id`, [source.workspace, bird])).rows[0].id;
await db.query(`INSERT INTO flock_notes (workspace_id, title, body) VALUES ($1, 'Flock only', 'Keep in source flock')`, [source.workspace]);
const transferCode = randomUUID().slice(0, 20);
await db.query(`INSERT INTO bird_transfer_codes (code, bird_id, source_workspace_id, requested_by_user_id) VALUES ($1, $2, $3, $4)`, [transferCode, bird, source.workspace, source.user]);
await db.query(`INSERT INTO pending_bird_transfers (bird_id, source_workspace_id, destination_owner_email, requested_by_user_id) VALUES ($1, $2, 'pending@example.test', $3)`, [bird, source.workspace, source.user]);
// A late failure must roll back the bird, notes, and transfer changes together.
await assert.rejects(() => removeBirdFromFlock(bird, source.workspace, randomUUID()));
assert.equal((await db.query(`SELECT workspace_id FROM birds WHERE id = $1`, [bird])).rows[0].workspace_id, source.workspace);
assert.equal((await db.query(`SELECT revoked_at FROM bird_transfer_codes WHERE code = $1`, [transferCode])).rows[0].revoked_at, null);
server = spawn(process.execPath, [fileURLToPath(new URL('../dist/app.js', import.meta.url))], { cwd: '/tmp', env: process.env, stdio: ['ignore', 'pipe', 'pipe'] });
server.stdout.on('data', (data) => { output += data; }); server.stderr.on('data', (data) => { output += data; });
for (let i = 0; i < 100 && !output.includes('listening'); i++) await new Promise((resolve) => setTimeout(resolve, 100));
assert.match(output, /listening/, output);
async function api(account, path, method = 'GET', body, status = 200) {
const response = await fetch(`http://127.0.0.1:55440/api${path}`, { method, headers: { 'Content-Type': 'application/json', ...(account ? { Authorization: `Bearer ${account.token}` } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}) });
const data = response.status === 204 ? null : await response.json();
if (status !== null) assert.equal(response.status, status, JSON.stringify(data));
return { status: response.status, data };
}
const matchPath = `/birds/unassigned-match?${new URLSearchParams({ tagId })}`;
assert.deepEqual((await api(destination, matchPath)).data, { available: false });
await api(destination, '/birds/claim', 'POST', { tagId, confirmHistory: true }, 409);
await api(destination, `/birds/${bird}`, 'DELETE', undefined, 404);
await api(source, `/birds/${bird}`, 'DELETE', undefined, 204);
const removed = (await db.query(`SELECT * FROM birds WHERE id = $1`, [bird])).rows[0];
assert.equal(removed.workspace_id, null); assert.equal(removed.photo_data_url, photo); assert.equal(removed.public_profile_enabled, false);
for (const table of ['weight_records', 'vet_visits', 'medications', 'medication_administrations', 'behavior_occurrences', 'flock_notes']) {
assert.equal((await db.query(`SELECT COUNT(*)::int AS count FROM ${table} WHERE bird_id = $1`, [bird])).rows[0].count, 1, table);
}
assert.equal((await db.query(`SELECT workspace_id FROM flock_notes WHERE id = $1`, [birdNote])).rows[0].workspace_id, null);
assert.ok((await db.query(`SELECT revoked_at FROM bird_transfer_codes WHERE code = $1`, [transferCode])).rows[0].revoked_at);
assert.equal((await db.query(`SELECT COUNT(*)::int AS count FROM pending_bird_transfers WHERE bird_id = $1`, [bird])).rows[0].count, 0);
assert.equal((await api(source, '/birds')).data.birds.length, 0);
assert.equal((await api(source, '/notes')).data.notes.length, 1);
assert.equal((await api(source, `/birds/${bird}/weights`)).data.weights.length, 0);
await api(null, `/public/birds/${publicCode}`, 'GET', undefined, 404);
assert.deepEqual((await api(destination, matchPath)).data, { available: true });
await api(null, matchPath, 'GET', undefined, 401);
await api(destination, '/birds/unassigned-match?tagId=unknown', 'GET', undefined, 400);
assert.deepEqual((await api(destination, `/birds/unassigned-match?tagId=${encodeURIComponent(tagId.slice(0, -1))}`)).data, { available: false });
await api(destination, '/birds/claim', 'POST', { tagId }, 400);
await db.query(`UPDATE workspace_members SET role = 'viewer' WHERE user_id = $1`, [destination.user]);
await api(destination, matchPath, 'GET', undefined, 403);
await api(destination, '/birds/claim', 'POST', { tagId, confirmHistory: true }, 403);
await db.query(`UPDATE workspace_members SET role = 'owner' WHERE user_id = $1`, [destination.user]);
await db.query(`UPDATE workspaces SET rescue_verification_status = 'pending' WHERE id = $1`, [destination.workspace]);
await api(destination, '/birds/claim', 'POST', { tagId, confirmHistory: true }, 402);
await db.query(`UPDATE workspaces SET rescue_verification_status = 'approved' WHERE id = $1`, [destination.workspace]);
assert.equal((await api(destination, '/birds', 'POST', { name: 'New name should not replace existing', species: 'Parrot', tagId }, 409)).data.code, 'bird_history_available');
await assert.rejects(() => claimUnassignedBird(tagId, destination.workspace, randomUUID()));
assert.equal((await db.query(`SELECT workspace_id FROM birds WHERE id = $1`, [bird])).rows[0].workspace_id, null);
const claimed = (await api(destination, '/birds/claim', 'POST', { tagId: ` ${tagId.toLowerCase()} `, confirmHistory: true })).data;
assert.equal(claimed.bird.id, bird); assert.equal(claimed.bird.name, 'Preserved bird'); assert.equal(claimed.historyImported, true); assert.equal(claimed.bird.photoDataUrl, photo);
assert.equal((await api(destination, `/birds/${bird}/weights`)).data.weights.length, 1);
assert.equal((await api(destination, `/birds/${bird}/vet-visits`)).data.vetVisits.length, 1);
assert.equal((await api(destination, '/notes')).data.notes[0].id, birdNote);
assert.equal((await api(source, '/notes')).data.notes.length, 1);
assert.ok((await api(destination, `/birds/${bird}/behavior-types`)).data.behaviorTypes.some((type) => type.id === behaviorType));
const timeline = (await api(destination, `/birds/${bird}/timeline`)).data.events;
assert.ok(timeline.some((event) => event.eventType === 'removed_from_flock'));
assert.ok(timeline.some((event) => event.eventType === 'joined_flock'));
await api(source, `/birds/${bird}`, 'DELETE', undefined, 404);
await api(rival, '/birds/claim', 'POST', { tagId, confirmHistory: true }, 409);
// Remove again and race two different flocks. Exactly one claim must succeed.
await api(destination, `/birds/${bird}`, 'DELETE', undefined, 204);
const race = await Promise.all([source, rival].map((account) => api(account, '/birds/claim', 'POST', { tagId, confirmHistory: true }, null)));
assert.deepEqual(race.map((result) => result.status).sort(), [200, 409]);
const bandless = randomUUID();
await db.query(`INSERT INTO birds (id, workspace_id, name, species) VALUES ($1, $2, 'No band', 'Parrot')`, [bandless, source.workspace]);
await api(source, `/birds/${bandless}`, 'DELETE', undefined, 204);
assert.equal((await db.query(`SELECT workspace_id FROM birds WHERE id = $1`, [bandless])).rows[0].workspace_id, null);
console.log('PASS: reversible flock removal, retained profile/photo/all care records, notes isolation, sharing/transfer revocation, exact normalized band matching, explicit history consent, permissions, rollback, and concurrent claims.');
} finally {
if (server && server.exitCode === null) { const done = once(server, 'exit'); server.kill('SIGTERM'); await done; }
await db.close();
}
+46 -1
View File
@@ -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
@@ -933,7 +958,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.
@@ -941,6 +966,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`
@@ -1266,3 +1307,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.
+68
View File
@@ -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
```
+50
View File
@@ -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.
+1
View File
@@ -8,6 +8,7 @@
type="image/svg+xml"
href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E%3Cdefs%3E%3ClinearGradient id='featherFill' x1='0%25' y1='0%25' x2='100%25' y2='100%25'%3E%3Cstop offset='0%25' stop-color='%23cb3a35'/%3E%3Cstop offset='30%25' stop-color='%23f0b63f'/%3E%3Cstop offset='58%25' stop-color='%23238a5a'/%3E%3Cstop offset='100%25' stop-color='%232769b3'/%3E%3C/linearGradient%3E%3C/defs%3E%3Cpath d='M50.8 10.4C37.9 10.3 27 18.5 22.7 31.1c-3.1 9.1-2.1 18.5-8.6 24.8c-1.5 1.5-0.2 4 1.9 3.6c8.4-1.5 14.6-6.7 18.6-13.7c1 0.5 2.2 0.8 3.4 0.8c3.5 0 6.5-2.3 7.5-5.4c1.9-0.4 3.7-1.3 5.1-2.7c2-2 3-4.6 3.1-7.2c3.3-5.8 4.9-12.9 1.4-20.2c-0.7-1.3-2-0.7-4.3-0.7Z' fill='url(%23featherFill)'/%3E%3Cpath d='M18 56c8.5-3.4 14.2-9.8 18.1-17.8M26.9 48.9c6.9-7.2 13.5-14.8 20.3-22.1M31.8 41.2c6.4-1.3 12.1-4.6 16.5-9.4M36.8 33.8c4.9-0.9 9.2-3.4 12.6-7.1' fill='none' stroke='%23fff8ef' stroke-linecap='round' stroke-width='2.6'/%3E%3Cpath d='M18 56c8.5-3.4 14.2-9.8 18.1-17.8' fill='none' stroke='%2363562d' stroke-linecap='round' stroke-width='2.2'/%3E%3C/svg%3E"
/>
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&amp;icon_names=event" />
<title>FlockPal</title>
</head>
<body>
+121 -31
View File
@@ -1,3 +1,4 @@
import { BehaviorJournal } from './BehaviorJournal';
import { useEffect, useMemo, useState, type CSSProperties, type Dispatch, type SetStateAction } from 'react';
import birdSilhouette from './assets/bird-silhouette.jpg';
import flockPalLandingArt from './assets/flockpal-landing-art.png';
@@ -252,7 +253,7 @@ type AuditLogEntry = {
type BirdTimelineEvent = {
id: string;
birdId: string;
eventType: 'profile_created' | 'transferred' | 'location_updated' | 'owner_changed' | 'manual_note';
eventType: 'profile_created' | 'transferred' | 'location_updated' | 'owner_changed' | 'manual_note' | 'removed_from_flock' | 'joined_flock';
fromWorkspaceId: number | null;
toWorkspaceId: number | null;
fromWorkspaceName: string | null;
@@ -458,7 +459,7 @@ type WeightDropAlert = {
};
type DismissibleAlertType = 'weight-range' | 'weight-drop' | 'vet-visit';
type BirdDetailTab = 'info' | 'weight' | 'vet' | 'notes' | 'reports' | 'timeline' | 'audit';
type BirdDetailTab = 'behavior' | 'info' | 'weight' | 'vet' | 'notes' | 'reports' | 'timeline' | 'audit';
type DismissedAlertMap = Record<string, boolean>;
type PhotoCropState = {
@@ -1174,6 +1175,9 @@ const formatAuditAction = (value: string) =>
.join(' ');
const formatBirdTimelineTitle = (event: BirdTimelineEvent) => {
if (event.eventType === 'removed_from_flock') return 'Removed from flock';
if (event.eventType === 'joined_flock') return 'Joined flock with history';
if (event.eventType === 'profile_created') {
return 'Added to flock';
}
@@ -1194,6 +1198,9 @@ const formatBirdTimelineTitle = (event: BirdTimelineEvent) => {
};
const formatBirdTimelineDescription = (event: BirdTimelineEvent) => {
if (event.eventType === 'removed_from_flock') return `Left ${event.fromWorkspaceName || 'previous flock'}; history retained.`;
if (event.eventType === 'joined_flock') return `Joined ${event.toWorkspaceName || 'current flock'} with existing history.`;
if (event.eventType === 'profile_created') {
return event.locationLabel ? `Location: ${event.locationLabel}` : `Flock: ${event.toWorkspaceName || 'Unknown flock'}`;
}
@@ -1272,6 +1279,9 @@ const getBirdHatchDay = (bird: Pick<Bird, 'hatchDay' | 'dateOfBirth'>) => {
};
const getBirdTimelineGraphLabel = (event: BirdTimelineEvent) => {
if (event.eventType === 'removed_from_flock') return 'Removed from flock';
if (event.eventType === 'joined_flock') return 'Joined flock with history';
if (event.eventType === 'location_updated') {
return event.locationLabel || 'Location updated';
}
@@ -2208,6 +2218,12 @@ function App() {
const [integrationTokenForm, setIntegrationTokenForm] = useState<IntegrationTokenFormState>(emptyIntegrationTokenForm);
const [flockNoteForm, setFlockNoteForm] = useState<FlockNoteFormState>(emptyFlockNoteForm);
const [birdForm, setBirdForm] = useState<BirdFormState>(emptyBirdForm);
const [unassignedBirdMatch, setUnassignedBirdMatch] = useState<{
tagId: string; status: 'idle' | 'loading' | 'available' | 'none' | 'error';
}>({ tagId: '', status: 'idle' });
const matchingUnassignedBird = !editingBirdId && unassignedBirdMatch.status === 'available'
&& unassignedBirdMatch.tagId === birdForm.tagId.trim().toLowerCase();
const [birdImportPreview, setBirdImportPreview] = useState<BirdImportPreview | null>(null);
const [birdImportFileName, setBirdImportFileName] = useState('');
const [birdImportNotice, setBirdImportNotice] = useState('');
@@ -2332,12 +2348,33 @@ function App() {
[auditLogEntries, selectedBird],
);
useEffect(() => {
const tagId = birdForm.tagId.trim().toLowerCase();
if (!authToken || !birdEditorOpen || editingBirdId || !tagId || ['unknown', 'not recorded', 'n/a', 'na', 'none'].includes(tagId)) {
setUnassignedBirdMatch({ tagId, status: 'idle' });
return;
}
const controller = new AbortController();
setUnassignedBirdMatch({ tagId, status: 'loading' });
const timer = window.setTimeout(async () => {
try {
const response = await apiFetch(`/birds/unassigned-match?${new URLSearchParams({ tagId })}`, authToken, { signal: controller.signal });
if (!response.ok) throw new Error('Unable to check band ID.');
const data = await response.json() as { available: boolean };
if (!controller.signal.aborted) setUnassignedBirdMatch({ tagId, status: data.available ? 'available' : 'none' });
} catch {
if (!controller.signal.aborted) setUnassignedBirdMatch({ tagId, status: 'error' });
}
}, 350);
return () => { window.clearTimeout(timer); controller.abort(); };
}, [authToken, workspace?.id, birdEditorOpen, editingBirdId, birdForm.tagId]);
useEffect(() => {
setDismissedAlerts(readDismissedAlerts());
}, [workspace?.id]);
useEffect(() => {
setSelectedBirdTab('info');
setSelectedBirdTab((current) => current === 'behavior' ? 'behavior' : 'info');
setBirdTimelineEvents([]);
setBirdTimelineEventForm(emptyBirdTimelineEventForm);
setBirdTimelineNotice(null);
@@ -4224,6 +4261,37 @@ function App() {
}
};
const handleClaimUnassignedBird = async () => {
if (!matchingUnassignedBird || savingBird) return;
const tagId = birdForm.tagId.trim();
if (!window.confirm(`Add the bird with band ID ${tagId} to this flock?\n\nIts saved profile, photo, notes, and care history will be brought in. The existing profile details will be used instead of any new details entered here.`)) return;
setSavingBird(true);
setError('');
try {
const response = await apiFetch('/birds/claim', authToken, {
method: 'POST', headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ tagId, confirmHistory: true }),
});
if (!response.ok) throw new Error(await readErrorMessage(response, 'Unable to add the existing bird.'));
const data = await response.json() as { bird: Bird };
setBirds((current) => sortBirdsByName([...current.filter((bird) => bird.id !== data.bird.id), data.bird]));
setSelectedBirdId(data.bird.id);
setEditingBirdId(data.bird.id);
setBirdForm(toBirdForm(data.bird));
setBirdPhotoName('');
setBirdEditorOpen(false);
setActivePage('flock');
setUnassignedBirdMatch({ tagId: '', status: 'idle' });
// Refresh notes without treating a successful claim as failed if this secondary request fails.
void apiFetch('/notes', authToken).then(async (notesResponse) => {
if (notesResponse.ok) setFlockNotes(((await notesResponse.json()) as { notes: FlockNote[] }).notes);
}).catch(() => setError('Bird added with its history. Refresh the flock to load its notes.'));
window.alert(`${data.bird.name} was added with its existing profile and care history.`);
} catch (claimError) {
setError(claimError instanceof Error ? claimError.message : 'Unable to add the existing bird.');
} finally { setSavingBird(false); }
};
const handleBirdSubmit = async (event: React.FormEvent<HTMLFormElement>) => {
event.preventDefault();
setError('');
@@ -4842,7 +4910,7 @@ function App() {
}
const confirmed = window.confirm(
`Remove ${selectedBird.name} from the flock?\n\nThis will also remove weight records and vet visits for this flock member.`,
`Remove ${selectedBird.name} from the flock?\n\nThe bird will leave this flock, but its profile, photo, notes, and care history will be retained. Public sharing and pending transfers will be disabled. Someone adding its exact band ID can bring the bird and its history into their flock.${selectedBird.tagId ? '' : '\n\nThis bird has no band ID, so its history cannot be automatically matched later.'}`,
);
if (!confirmed) {
@@ -4862,6 +4930,7 @@ function App() {
}
const nextBirds = birds.filter((bird) => bird.id !== selectedBird.id);
setFlockNotes((current) => current.filter((note) => note.birdId !== selectedBird.id));
setBirds(nextBirds);
setAllBirdWeights((current) => {
const next = { ...current };
@@ -6193,17 +6262,17 @@ function App() {
</div>
<aside className="side-nav panel">
<div className="page-tabs" role="tablist" aria-label="Main navigation">
<button className={`page-tab ${activePage === 'overview' ? 'active' : ''}`} onClick={() => setActivePage('overview')} type="button">
<button data-tab="overview" className={`page-tab ${activePage === 'overview' ? 'active' : ''}`} onClick={() => setActivePage('overview')} type="button">
Overview
</button>
<button className={`page-tab ${activePage === 'flock' ? 'active' : ''}`} onClick={() => setActivePage('flock')} type="button">
<button data-tab="flock" className={`page-tab ${activePage === 'flock' ? 'active' : ''}`} onClick={() => setActivePage('flock')} type="button">
Flock
</button>
<button className={`page-tab ${activePage === 'settings' ? 'active' : ''}`} onClick={() => setActivePage('settings')} type="button">
<button data-tab="settings" className={`page-tab ${activePage === 'settings' ? 'active' : ''}`} onClick={() => setActivePage('settings')} type="button">
Settings
</button>
{authSession.isAdmin ? (
<button className={`page-tab ${activePage === 'admin' ? 'active' : ''}`} onClick={() => setActivePage('admin')} type="button">
<button data-tab="admin" className={`page-tab ${activePage === 'admin' ? 'active' : ''}`} onClick={() => setActivePage('admin')} type="button">
Admin
</button>
) : null}
@@ -7012,6 +7081,17 @@ function App() {
placeholder="Optional if unknown"
/>
</label>
{!editingBirdId && unassignedBirdMatch.status === 'loading' ? <p className="muted wide-field" role="status">Checking band ID for existing history…</p> : null}
{matchingUnassignedBird ? (
<div className="success-banner wide-field" role="status">
<strong>This band ID matches a bird that is not currently in a flock.</strong>
<p>Adding it will bring in its saved profile, photo, notes, and care history. Existing profile details will be used.</p>
<button className="primary-button" type="button" disabled={savingBird} onClick={() => void handleClaimUnassignedBird()}>
{savingBird ? 'Adding…' : 'Add bird with existing history'}
</button>
</div>
) : null}
{!editingBirdId && unassignedBirdMatch.status === 'error' ? <p className="muted wide-field" role="status">Could not check for existing history. The band ID will still be checked when you save.</p> : null}
<label className="species-picker-field wide-field">
Species
<div className="species-picker">
@@ -7090,7 +7170,7 @@ function App() {
<span className="gender-symbol-mark">{getBirdGenderSymbol({ gender })}</span>
</span>
<BirdGenderSourceIcon bird={{ gender }} />
{getBirdGenderLabel({ gender })}
<span className="gender-option-label">{getBirdGenderLabel({ gender })}</span>
</button>
))}
</div>
@@ -7308,7 +7388,7 @@ function App() {
</div>
</section>
<div className="settings-save-row">
<button className="primary-button" type="submit" disabled={savingBird}>
<button className="primary-button" type="submit" disabled={savingBird || matchingUnassignedBird || (!editingBirdId && unassignedBirdMatch.status === 'loading')}>
{savingBird ? 'Saving...' : editingBird ? 'Save profile changes' : 'Save bird profile'}
</button>
</div>
@@ -7448,7 +7528,7 @@ function App() {
<section className="settings-nested-card settings-danger-card">
<div className="settings-nested-header">
<p className="eyebrow">Danger zone</p>
<h3>Destructive profile actions</h3>
<h3>Remove or memorialize</h3>
</div>
<form className="form-panel inline-form care-entry-form" onSubmit={handleMemorializeBird}>
<label>
@@ -7474,7 +7554,7 @@ function App() {
</button>
</div>
</form>
<p className="muted">Removing permanently deletes weight records, vet visits, and medication history for this bird.</p>
<p className="muted">Removing only takes this bird out of your flock. Its profile, photo, notes, and care history are retained and can be brought into a flock later using its exact band ID.</p>
<div className="button-row">
<button className="danger-button" onClick={handleRemoveBird} type="button" disabled={deletingBird}>
{deletingBird ? 'Removing...' : 'Remove from flock'}
@@ -7489,7 +7569,7 @@ function App() {
<section className="panel flock-member-panel bird-detail-panel">
<div className="bird-detail-tabs" role="tablist" aria-label={`${selectedBird.name} detail sections`}>
<button
className={`bird-detail-tab ${selectedBirdTab === 'info' ? 'active' : ''}`}
data-tab="info" className={`bird-detail-tab ${selectedBirdTab === 'info' ? 'active' : ''}`}
onClick={() => setSelectedBirdTab('info')}
type="button"
role="tab"
@@ -7502,7 +7582,7 @@ function App() {
</svg>
</button>
<button
className={`bird-detail-tab ${selectedBirdTab === 'weight' ? 'active' : ''}`}
data-tab="weight" className={`bird-detail-tab ${selectedBirdTab === 'weight' ? 'active' : ''}`}
onClick={() => setSelectedBirdTab('weight')}
type="button"
role="tab"
@@ -7514,21 +7594,11 @@ function App() {
<path d="M240-200h480l-57-400H297l-57 400Zm240-480q17 0 28.5-11.5T520-720q0-17-11.5-28.5T480-760q-17 0-28.5 11.5T440-720q0 17 11.5 28.5T480-680Zm113 0h70q30 0 52 20t27 49l57 400q5 36-18.5 63.5T720-120H240q-37 0-60.5-27.5T161-211l57-400q5-29 27-49t52-20h70q-3-10-5-19.5t-2-20.5q0-50 35-85t85-35q50 0 85 35t35 85q0 11-2 20.5t-5 19.5ZM240-200h480-480Z" />
</svg>
</button>
<button
className={`bird-detail-tab ${selectedBirdTab === 'vet' ? 'active' : ''}`}
onClick={() => setSelectedBirdTab('vet')}
type="button"
role="tab"
aria-selected={selectedBirdTab === 'vet'}
aria-label="Vet"
title="Vet"
>
<svg className="vet-tab-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false">
<path d="M20 6h-4V4c0-1.11-.89-2-2-2h-4c-1.11 0-2 .89-2 2v2H4c-1.11 0-2 .89-2 2v12c0 1.11.89 2 2 2h16c1.11 0 2-.89 2-2V8c0-1.11-.89-2-2-2ZM10 4h4v2h-4V4Zm6 11h-3v3h-2v-3H8v-2h3v-3h2v3h3v2Z" />
</svg>
<button data-tab="behavior" className={`bird-detail-tab ${selectedBirdTab === 'behavior' ? 'active' : ''}`} type="button" role="tab" aria-selected={selectedBirdTab === 'behavior'} aria-label="Behavior Journal" title="Behavior Journal" onClick={() => setSelectedBirdTab('behavior')}>
<span className="material-symbols-outlined behavior-tab-icon" aria-hidden="true">event</span>
</button>
<button
className={`bird-detail-tab ${selectedBirdTab === 'notes' ? 'active' : ''}`}
data-tab="notes" className={`bird-detail-tab ${selectedBirdTab === 'notes' ? 'active' : ''}`}
onClick={() => setSelectedBirdTab('notes')}
type="button"
role="tab"
@@ -7541,7 +7611,20 @@ function App() {
</svg>
</button>
<button
className={`bird-detail-tab ${selectedBirdTab === 'reports' ? 'active' : ''}`}
data-tab="vet" className={`bird-detail-tab ${selectedBirdTab === 'vet' ? 'active' : ''}`}
onClick={() => setSelectedBirdTab('vet')}
type="button"
role="tab"
aria-selected={selectedBirdTab === 'vet'}
aria-label="Vet"
title="Vet"
>
<svg className="vet-tab-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false">
<path d="M20 6h-4V4c0-1.11-.89-2-2-2h-4c-1.11 0-2 .89-2 2v2H4c-1.11 0-2 .89-2 2v12c0 1.11.89 2 2 2h16c1.11 0 2-.89 2-2V8c0-1.11-.89-2-2-2ZM10 4h4v2h-4V4Zm6 11h-3v3h-2v-3H8v-2h3v-3h2v3h3v2Z" />
</svg>
</button>
<button
data-tab="reports" className={`bird-detail-tab ${selectedBirdTab === 'reports' ? 'active' : ''}`}
onClick={() => setSelectedBirdTab('reports')}
type="button"
role="tab"
@@ -7554,7 +7637,7 @@ function App() {
</svg>
</button>
<button
className={`bird-detail-tab ${selectedBirdTab === 'timeline' ? 'active' : ''}`}
data-tab="timeline" className={`bird-detail-tab ${selectedBirdTab === 'timeline' ? 'active' : ''}`}
onClick={() => setSelectedBirdTab('timeline')}
type="button"
role="tab"
@@ -7565,7 +7648,7 @@ function App() {
<svg className="timeline-tab-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M21 6a2 2 0 0 0-1.93 2.51l-3.55 3.56A2.15 2.15 0 0 0 15 12c-.18 0-.36.02-.52.07l-2.55-2.55c.05-.16.07-.34.07-.52a2 2 0 1 0-4 0c0 .18.02.36.07.52l-4.56 4.55A2.03 2.03 0 0 0 3 14a2 2 0 1 0 1.93 1.49l4.55-4.56c.16.05.34.07.52.07s.36-.02.52-.07l2.55 2.55c-.05.16-.07.34-.07.52a2 2 0 1 0 4 0c0-.18-.02-.36-.07-.52l3.56-3.55A2 2 0 1 0 21 6Z" /></svg>
</button>
<button
className={`bird-detail-tab ${selectedBirdTab === 'audit' ? 'active' : ''}`}
data-tab="audit" className={`bird-detail-tab ${selectedBirdTab === 'audit' ? 'active' : ''}`}
onClick={() => setSelectedBirdTab('audit')}
type="button"
role="tab"
@@ -7729,6 +7812,10 @@ function App() {
</div>
) : null}
{selectedBirdTab === 'behavior' && authToken ? <BehaviorJournal
key={`${workspace?.id}-${selectedBird.id}`} bird={selectedBird} birds={birds} onSelectBird={setSelectedBirdId} token={authToken} apiFetch={apiFetch}
writable={!selectedBird.memorializedAt && ['owner', 'assistant', 'caregiver'].includes(activeMembership?.role ?? '') && Boolean(authSession?.isAdmin || (workspace?.workspaceType === 'rescue' ? workspace.rescueVerificationStatus === 'approved' : workspace && subscriptionAllowsFlockWrites(workspace.subscriptionStatus)))}
/> : null}
{selectedBirdTab === 'weight' ? (
<div className="flock-member-sections" role="tabpanel">
<section className="panel inset-panel">
@@ -9116,7 +9203,10 @@ function App() {
{expandedSettingsSection === 'integration-tokens' ? (
<>
<p className="muted">
Create a flock-scoped token for automations like n8n. The secret is shown only once, so store it in your automation tool when it appears.
Create a flock-scoped token for automations like n8n. The secret is shown only once, so store it in your automation tool when it appears.{' '}
<a href={`${apiBaseUrl.replace(/\/$/, '')}/docs/`} target="_blank" rel="noopener noreferrer">
Browse the API reference
</a>.
</p>
<form className="form-panel" onSubmit={handleCreateIntegrationToken}>
<label>
+132
View File
@@ -0,0 +1,132 @@
import { useEffect, useMemo, useState, type FormEvent } from 'react';
import './behaviorJournal.css';
type BehaviorType = { id: string; name: string; description: string | null };
type Occurrence = {
id: string; birdId: string; behaviorTypeId: string; behaviorName: string; occurredAt: string;
durationSeconds: number | null; severity: number | null; notes: string | null; createdAt: string; updatedAt: string;
};
type Props = {
bird: { id: string; name: string }; birds: { id: string; name: string }[]; onSelectBird: (id: string) => void; token: string; writable: boolean;
apiFetch: (path: string, token?: string, init?: RequestInit) => Promise<Response>;
};
const localDate = (date: Date) => `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
const localTime = (date: Date) => `${localDate(date)}T${String(date.getHours()).padStart(2, '0')}:${String(date.getMinutes()).padStart(2, '0')}:${String(date.getSeconds()).padStart(2, '0')}`;
const emptyForm = () => ({ behaviorTypeId: '', occurredAt: localTime(new Date()), duration: '', severity: '', notes: '' });
export function BehaviorJournal({ bird, birds, onSelectBird, token, writable, apiFetch }: Props) {
const [month, setMonth] = useState(() => new Date(new Date().getFullYear(), new Date().getMonth(), 1));
const [day, setDay] = useState(() => localDate(new Date()));
const [filter, setFilter] = useState('');
const [types, setTypes] = useState<BehaviorType[]>([]);
const [entries, setEntries] = useState<Occurrence[]>([]);
const [form, setForm] = useState(emptyForm);
const [editing, setEditing] = useState<Occurrence | null>(null);
const [showForm, setShowForm] = useState(false);
const [customName, setCustomName] = useState('');
const [customDescription, setCustomDescription] = useState('');
const [loading, setLoading] = useState(true);
const [saving, setSaving] = useState(false);
const [error, setError] = useState('');
const [notice, setNotice] = useState('');
const [revision, setRevision] = useState(0);
const base = `/birds/${bird.id}`;
async function request(path: string, init?: RequestInit) {
const response = await apiFetch(path, token, { ...init, headers: { 'Content-Type': 'application/json', ...init?.headers } });
if (response.status === 204) return null;
const data = await response.json();
if (!response.ok) throw new Error(data.error || 'Unable to update the journal.');
return data;
}
useEffect(() => {
let active = true;
setLoading(true); setError(''); setEntries([]);
const query = new URLSearchParams({ from: month.toISOString(), to: new Date(month.getFullYear(), month.getMonth() + 1, 1).toISOString() });
if (filter) query.set('behaviorTypeId', filter);
Promise.all([request(`${base}/behavior-types`), request(`${base}/behaviors?${query}`)])
.then(([typeData, occurrenceData]) => { if (active) { setTypes(typeData.behaviorTypes); setEntries(occurrenceData.occurrences); } })
.catch((e) => { if (active) setError(e instanceof Error ? e.message : 'Unable to load journal.'); })
.finally(() => { if (active) setLoading(false); });
return () => { active = false; };
}, [bird.id, token, month, filter, revision]);
const byDay = useMemo(() => {
const result = new Map<string, Occurrence[]>();
entries.forEach((entry) => { const key = localDate(new Date(entry.occurredAt)); result.set(key, [...(result.get(key) || []), entry]); });
return result;
}, [entries]);
function navigate(offset: number) {
const next = new Date(month.getFullYear(), month.getMonth() + offset, 1);
setMonth(next); setDay(localDate(next));
}
function edit(entry: Occurrence) {
setEditing(entry); setShowForm(true); setError(''); setNotice('');
setForm({ behaviorTypeId: entry.behaviorTypeId, occurredAt: localTime(new Date(entry.occurredAt)), duration: entry.durationSeconds === null ? '' : String(entry.durationSeconds), severity: entry.severity === null ? '' : String(entry.severity), notes: entry.notes || '' });
}
async function save(event: FormEvent) {
event.preventDefault(); setSaving(true); setError(''); setNotice('');
try {
let typeId = form.behaviorTypeId;
if (typeId === 'custom') {
const data = await request(`${base}/behavior-types`, { method: 'POST', body: JSON.stringify({ name: customName, description: customDescription }) });
typeId = data.behaviorType.id;
setTypes((previous) => [...previous.filter((type) => type.id !== typeId), data.behaviorType]);
setForm((previous) => ({ ...previous, behaviorTypeId: typeId }));
}
// Preserve sub-second precision if the timestamp was not edited.
const occurredAt = editing && form.occurredAt === localTime(new Date(editing.occurredAt)) ? editing.occurredAt : new Date(form.occurredAt).toISOString();
await request(`${base}/behaviors${editing ? `/${editing.id}` : ''}`, { method: editing ? 'PUT' : 'POST', body: JSON.stringify({ behaviorTypeId: typeId, occurredAt, durationSeconds: form.duration === '' ? null : Number(form.duration), severity: form.severity === '' ? null : Number(form.severity), notes: form.notes || null }) });
const savedDate = new Date(occurredAt);
setMonth(new Date(savedDate.getFullYear(), savedDate.getMonth(), 1)); setDay(localDate(savedDate));
setFilter(''); setShowForm(false); setEditing(null); setRevision((value) => value + 1); setNotice('Occurrence saved.');
} catch (e) { setError(e instanceof Error ? e.message : 'Unable to save occurrence.'); }
finally { setSaving(false); }
}
async function remove(entry: Occurrence) {
if (!window.confirm(`Delete this ${entry.behaviorName} occurrence?`)) return;
setSaving(true); setError(''); setNotice('');
try {
await request(`${base}/behaviors/${entry.id}`, { method: 'DELETE' });
if (editing?.id === entry.id) { setShowForm(false); setEditing(null); }
setRevision((value) => value + 1); setNotice('Occurrence deleted.');
} catch (e) { setError(e instanceof Error ? e.message : 'Unable to delete occurrence.'); }
finally { setSaving(false); }
}
const days = new Date(month.getFullYear(), month.getMonth() + 1, 0).getDate();
return <section className="panel inset-panel behavior-journal" role="tabpanel" aria-label="Behavior Journal">
<div className="panel-header"><div><p className="eyebrow">{bird.name}</p><h2>Behavior Journal</h2></div>
{writable && <button type="button" className="primary-button" disabled={saving} onClick={() => { setForm(emptyForm()); setEditing(null); setCustomName(''); setCustomDescription(''); setShowForm(true); setError(''); setNotice(''); }}>Record behavior</button>}
</div>
<p className="muted">Record what you observed and review when it happened. Dates and times use your device’s local time zone.</p>
{error && <p className="error-banner" role="alert">{error}</p>}
{notice && <p className="success-banner" role="status">{notice}</p>}
{showForm && writable && <form onSubmit={save} className="behavior-form">
<h3>{editing ? 'Edit occurrence' : 'Record occurrence'}</h3>
<fieldset disabled={saving}>
<label>Behavior<select aria-label="Behavior" required value={form.behaviorTypeId} onChange={(e) => setForm({ ...form, behaviorTypeId: e.target.value })}><option value="">Select behavior</option>{types.map((type) => <option key={type.id} value={type.id}>{type.name}</option>)}<option value="custom">Create custom behavior…</option></select></label>
{form.behaviorTypeId === 'custom' && <><label>Custom behavior name<input required maxLength={120} value={customName} onChange={(e) => setCustomName(e.target.value)} /></label><label>Description (optional)<input maxLength={2000} value={customDescription} onChange={(e) => setCustomDescription(e.target.value)} /></label></>}
<label className="behavior-wide">Date and time<input type="datetime-local" step="1" required value={form.occurredAt} onChange={(e) => setForm({ ...form, occurredAt: e.target.value })} /></label>
<label>Duration in seconds (optional)<input type="number" min="0.001" max="31536000" step="any" value={form.duration} onChange={(e) => setForm({ ...form, duration: e.target.value })} /></label>
<label>Intensity (optional)<select aria-label="Intensity (optional)" value={form.severity} onChange={(e) => setForm({ ...form, severity: e.target.value })}><option value="">Not recorded</option>{[1, 2, 3, 4, 5].map((value) => <option key={value} value={value}>{value}{value === 1 ? ' — Low' : value === 5 ? ' — High' : ''}</option>)}</select></label>
<label className="behavior-wide">Notes (optional)<textarea maxLength={10000} rows={3} value={form.notes} onChange={(e) => setForm({ ...form, notes: e.target.value })} /></label>
<div className="behavior-actions"><button className="primary-button" type="submit">{saving ? 'Saving…' : 'Save occurrence'}</button><button className="secondary-button" type="button" onClick={() => { setShowForm(false); setEditing(null); }}>Cancel</button></div>
</fieldset>
</form>}
<label>Bird<select aria-label="Bird" value={bird.id} disabled={saving} onChange={(e) => onSelectBird(e.target.value)}>{birds.map((item) => <option key={item.id} value={item.id}>{item.name}</option>)}</select></label>
<label>Show behavior<select aria-label="Show behavior" value={filter} disabled={saving} onChange={(e) => setFilter(e.target.value)}><option value="">All behaviors</option>{types.map((type) => <option key={type.id} value={type.id}>{type.name}</option>)}</select></label>
<div className="behavior-month"><button className="secondary-button" type="button" aria-label="Previous month" onClick={() => navigate(-1)}>‹</button><h3 aria-live="polite">{month.toLocaleDateString(undefined, { month: 'long', year: 'numeric' })}</h3><button className="secondary-button" type="button" aria-label="Next month" onClick={() => navigate(1)}>›</button></div>
<p aria-live="polite">{loading ? 'Loading occurrences…' : `${entries.length} occurrence${entries.length === 1 ? '' : 's'} this month`}</p>
<div className="behavior-calendar" aria-label="Monthly behavior occurrences" aria-busy={loading}>
{['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'].map((label) => <span className="behavior-weekday" key={label}>{label}</span>)}
{Array.from({ length: month.getDay() }, (_, index) => <span key={`blank-${index}`} />)}
{Array.from({ length: days }, (_, index) => {
const date = new Date(month.getFullYear(), month.getMonth(), index + 1); const key = localDate(date); const count = byDay.get(key)?.length || 0;
return <button type="button" key={key} className={`behavior-day ${count ? 'has-occurrences' : ''}`} aria-pressed={key === day} aria-current={key === localDate(new Date()) ? 'date' : undefined} aria-label={`${date.toLocaleDateString()}: ${count} occurrences`} onClick={() => setDay(key)}><span>{index + 1}</span>{count > 0 && <><span className="behavior-dots" aria-hidden="true">{'●'.repeat(Math.min(count, 3))}{count > 3 ? '+' : ''}</span><small>{count}</small></>}</button>;
})}
</div>
<h3>{new Date(`${day}T12:00:00`).toLocaleDateString(undefined, { dateStyle: 'long' })}</h3>
{!loading && !(byDay.get(day)?.length) && <p className="muted">No occurrences recorded for this day{filter ? ' for the selected behavior' : ''}.</p>}
{(byDay.get(day) || []).map((entry) => <details key={entry.id} className="behavior-entry"><summary><strong>{entry.behaviorName}</strong><span>{new Date(entry.occurredAt).toLocaleString()}</span>{entry.durationSeconds !== null && <span>Duration: {entry.durationSeconds} seconds</span>}{entry.severity !== null && <span>Intensity: {entry.severity}/5</span>}{entry.notes && <span className="behavior-note-preview">{entry.notes}</span>}</summary><div>{entry.notes && <p className="behavior-notes">{entry.notes}</p>}<p className="muted">Created: {new Date(entry.createdAt).toLocaleString()}<br />Updated: {new Date(entry.updatedAt).toLocaleString()}</p>{writable && <div className="behavior-actions"><button className="secondary-button" type="button" disabled={saving} onClick={() => edit(entry)}>Edit</button><button className="danger-button" type="button" disabled={saving} onClick={() => void remove(entry)}>Delete</button></div>}</div></details>)}
</section>;
}
+24
View File
@@ -0,0 +1,24 @@
.behavior-journal { min-width: 0; }
.behavior-journal > label + label { margin-top: .75rem; }
.behavior-journal label { display: grid; gap: .4rem; }
.behavior-month { display: flex; justify-content: space-between; align-items: center; gap: .5rem; margin-top: 1rem; }
.behavior-calendar { display: grid; grid-template-columns: repeat(7, minmax(0, 1fr)); gap: .3rem; }
.behavior-weekday { text-align: center; font-size: .8rem; }
.behavior-day { min-height: 76px; min-width: 0; border: 1px solid #c5d4ce; border-radius: .6rem; background: #fff; color: #244338; display: flex; flex-direction: column; align-items: center; justify-content: center; gap: .15rem; cursor: pointer; }
.behavior-day.has-occurrences { background: #e4f2e9; }
.behavior-day[aria-pressed="true"] { outline: 3px solid #326b56; outline-offset: -3px; }
.behavior-day[aria-current="date"] > span:first-child { text-decoration: underline; font-weight: bold; }
.behavior-dots { font-size: .65rem; letter-spacing: .04em; }
.behavior-day:focus-visible { outline: 3px solid #1c5ba3; }
.behavior-form { margin: 1rem 0; }
.behavior-form fieldset { border: 0; padding: 0; display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 1rem; }
.behavior-wide { grid-column: 1 / -1; }
.behavior-form input, .behavior-form select, .behavior-form textarea { min-width: 0; width: 100%; box-sizing: border-box; }
.behavior-form .behavior-actions { grid-column: 1 / -1; }
.behavior-actions { display: flex; flex-wrap: wrap; gap: .5rem; }
.behavior-entry { padding: 1rem; margin: .75rem 0; border: 1px solid #c5d4ce; border-radius: .6rem; }
.behavior-entry summary { cursor: pointer; }
.behavior-entry summary > span { display: block; margin-top: .3rem; }
.behavior-note-preview { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
.behavior-notes { white-space: pre-wrap; overflow-wrap: anywhere; }
@media (max-width: 540px) { .behavior-form fieldset { grid-template-columns: 1fr; } .behavior-day { min-height: 64px; padding: .2rem; } .behavior-calendar { gap: .15rem; } .behavior-weekday { font-size: .7rem; } }
+81 -10
View File
@@ -44,6 +44,30 @@ body,
width: 100%;
}
/* Keep the page width steady when switching between short and long tabs. */
html {
overflow-y: scroll;
background-color: #e9ddba;
scrollbar-color: #898b93 transparent;
}
/* Keep native scrollbar tracks from painting a white strip over the page. */
html::-webkit-scrollbar {
width: 14px;
background: transparent;
}
html::-webkit-scrollbar-track {
background: transparent;
}
html::-webkit-scrollbar-thumb {
background-color: #898b93;
border: 3px solid transparent;
background-clip: padding-box;
border-radius: 999px;
}
body {
min-height: 100vh;
color: var(--ink);
@@ -510,11 +534,26 @@ textarea {
text-align: left;
}
/* Background X colors and their lighter tones give every tab a distinct active fill. */
.page-tab[data-tab="overview"] { --tab-active-color: #5bb3b7; }
.page-tab[data-tab="flock"] { --tab-active-color: #7eb773; }
.page-tab[data-tab="settings"] { --tab-active-color: #f3a24a; }
.page-tab[data-tab="admin"] { --tab-active-color: #9698a0; }
.bird-detail-tab[data-tab="info"] { --tab-active-color: #9ed2d4; }
.bird-detail-tab[data-tab="weight"] { --tab-active-color: #b9c945; }
.bird-detail-tab[data-tab="behavior"] { --tab-active-color: #f7c27d; }
.bird-detail-tab[data-tab="notes"] { --tab-active-color: #b4d5ad; }
.bird-detail-tab[data-tab="vet"] { --tab-active-color: #71ad80; }
.bird-detail-tab[data-tab="reports"] { --tab-active-color: #b9bac0; }
.bird-detail-tab[data-tab="timeline"] { --tab-active-color: #d4ba64; }
.bird-detail-tab[data-tab="audit"] { --tab-active-color: #78a8ad; }
.page-tab.active {
background: linear-gradient(135deg, #d89a2f, #3c8f65 58%, #2f8f98);
color: #fffdf9;
border-color: transparent;
background: var(--tab-active-color);
color: var(--ink);
border-color: rgba(31, 42, 42, 0.32);
box-shadow: 0 14px 26px rgba(88, 110, 62, 0.2);
font-weight: 700;
}
.page-tab:hover {
@@ -1679,6 +1718,20 @@ textarea {
transition: border-color 0.2s ease, box-shadow 0.2s ease, color 0.2s ease, transform 0.2s ease;
}
.bird-detail-tab .behavior-tab-icon {
font-family: 'Material Symbols Outlined';
font-size: 24px;
font-weight: normal;
font-style: normal;
line-height: 1;
letter-spacing: normal;
text-transform: none;
white-space: nowrap;
font-feature-settings: 'liga';
font-variation-settings: 'FILL' 0, 'wght' 400, 'GRAD' 0, 'opsz' 24;
-webkit-font-smoothing: antialiased;
}
.bird-detail-tab svg {
width: 20px;
height: 20px;
@@ -1715,9 +1768,9 @@ textarea {
}
.bird-detail-tab.active {
border-color: rgba(35, 138, 90, 0.42);
background: rgba(240, 248, 244, 0.95);
color: var(--accent-green);
border-color: rgba(31, 42, 42, 0.32);
background: var(--tab-active-color);
color: var(--ink);
box-shadow: 10px 10px 20px rgba(39, 105, 179, 0.1);
}
@@ -1793,11 +1846,12 @@ textarea {
.segmented-control {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(8.5rem, 1fr));
grid-template-columns: repeat(auto-fit, minmax(min(13rem, 100%), 1fr));
gap: 0.55rem;
}
.segmented-option {
min-width: 0;
display: inline-flex;
align-items: center;
justify-content: center;
@@ -1810,6 +1864,17 @@ textarea {
transition: border-color 0.2s ease, box-shadow 0.2s ease, transform 0.2s ease;
}
.segmented-option .gender-symbol,
.segmented-option .gender-source-icon {
flex-shrink: 0;
}
.gender-option-label {
min-width: 0;
white-space: normal;
overflow-wrap: anywhere;
}
.segmented-option.active {
border-color: rgba(35, 138, 90, 0.4);
box-shadow: 0 10px 20px rgba(39, 105, 179, 0.1);
@@ -2883,8 +2948,14 @@ label {
min-width: 520px;
}
.overview-chart-card {
min-height: 230px;
.chart-card.overview-chart-card {
min-height: 0;
overflow: hidden;
}
.overview-chart-card .weight-chart {
min-width: 0;
min-height: 0;
}
.chart-footer {
@@ -3004,7 +3075,7 @@ label {
}
.segmented-control {
grid-template-columns: repeat(auto-fit, minmax(min(8rem, 100%), 1fr));
grid-template-columns: repeat(auto-fit, minmax(min(13rem, 100%), 1fr));
}
.segmented-option {
@@ -0,0 +1,138 @@
// Optional browser check. Requires Playwright in a disposable frontend install; see docs/BEHAVIOR_JOURNAL.md.
import assert from 'node:assert/strict';
import { randomUUID, createHash } from 'node:crypto';
import { spawn } from 'node:child_process';
import { once } from 'node:events';
import { fileURLToPath } from 'node:url';
import { chromium } from 'playwright';
Object.assign(process.env, {
POSTGRES_HOST: '127.0.0.1', POSTGRES_PORT: '55439', POSTGRES_DB: 'behavior_test', POSTGRES_USER: 'postgres',
POSTGRES_PASSWORD: 'behavior_test_only', PORT: '55440', FRONTEND_URL: 'http://127.0.0.1:55441',
VITE_API_BASE_URL: 'http://127.0.0.1:55440/api',
MILESTONE_REMINDERS_ENABLED: 'false', MEDICATION_REMINDERS_ENABLED: 'false', WEIGHT_REMINDERS_ENABLED: 'false',
});
const { db } = await import('../../backend/dist/db/client.js');
const children = [];
let browser;
let page;
async function start(path, args, marker) {
let output = '';
const child = spawn(process.execPath, [fileURLToPath(path), ...args], { cwd: fileURLToPath(new URL('../', import.meta.url)), env: process.env, stdio: ['ignore', 'pipe', 'pipe'] });
children.push(child);
child.stdout.on('data', (data) => { output += data; }); child.stderr.on('data', (data) => { output += data; });
for (let i = 0; i < 100 && !output.includes(marker); i++) await new Promise((resolve) => setTimeout(resolve, 100));
assert.ok(output.includes(marker), output);
}
try {
const workspace = 100000 + Math.floor(Math.random() * 1000000000);
const user = randomUUID(), bird = randomUUID(), secondBird = randomUUID(), token = randomUUID();
await db.query(`INSERT INTO workspaces (id, name, workspace_type, rescue_verification_status) VALUES ($1, 'Browser test', 'rescue', 'approved')`, [workspace]);
await db.query(`INSERT INTO users (id, email, name, education_opt_out) VALUES ($1, $2, 'Browser tester', TRUE)`, [user, `${user}@example.test`]);
await db.query(`INSERT INTO workspace_members (workspace_id, user_id, invite_email, name, role, accepted_at) VALUES ($1, $2, $3, 'Browser tester', 'owner', NOW())`, [workspace, user, `${user}@example.test`]);
await db.query(`INSERT INTO auth_sessions (user_id, active_workspace_id, token_hash, expires_at) VALUES ($1, $2, $3, NOW() + INTERVAL '1 hour')`, [user, workspace, createHash('sha256').update(token).digest('hex')]);
await db.query(`INSERT INTO birds (id, workspace_id, name, species) VALUES ($1, $2, 'Piper', 'Parrot'), ($3, $2, 'Willow', 'Parrot')`, [bird, workspace, secondBird]);
const type = (await db.query(`SELECT id FROM behavior_types WHERE is_default ORDER BY name LIMIT 1`)).rows[0].id;
for (const timestamp of ['2026-10-01T03:59:59Z', '2026-10-01T04:00:00Z', '2026-11-01T05:30:00Z', '2026-11-01T06:30:00Z']) {
await db.query(`INSERT INTO behavior_occurrences (bird_id, behavior_type_id, occurred_at) VALUES ($1, $2, $3)`, [bird, type, timestamp]);
}
await start(new URL('../../backend/dist/app.js', import.meta.url), [], 'listening');
await start(new URL('../node_modules/vite/bin/vite.js', import.meta.url), ['--host', '127.0.0.1', '--port', '55441'], 'Local:');
browser = await chromium.launch({ headless: true });
const context = await browser.newContext({ timezoneId: 'America/New_York', viewport: { width: 1280, height: 1000 } });
page = await context.newPage();
const errors = []; page.on('pageerror', (e) => errors.push(e.message));
await page.addInitScript((value) => localStorage.setItem('flockpal_auth_token', value), token);
await page.clock.setFixedTime(new Date('2026-10-05T16:00:00Z'));
await page.goto('http://127.0.0.1:55441');
await page.getByRole('button', { name: 'Flock', exact: true }).click();
await page.locator('.bird-card-select').filter({ hasText: 'Piper' }).click();
await page.getByRole('tab', { name: 'Behavior Journal' }).click();
const journal = page.getByRole('tabpanel', { name: 'Behavior Journal' });
await journal.getByText('1 occurrence this month', { exact: true }).waitFor();
await journal.getByRole('button', { name: 'Record behavior' }).click();
assert.match(await journal.getByLabel('Date and time', { exact: true }).inputValue(), /^2026-10-05T12:00(:00)?$/);
await journal.getByLabel('Behavior', { exact: true }).selectOption('custom');
await journal.getByLabel('Custom behavior name').fill('Wing stretching');
await journal.getByLabel('Description (optional)').fill('Wings extended');
await journal.getByLabel('Date and time', { exact: true }).fill('2026-10-05T23:30:12');
await journal.getByLabel('Duration in seconds (optional)').fill('90');
await journal.getByLabel('Intensity (optional)').selectOption('3');
await journal.getByLabel('Notes (optional)').fill('Observed after play');
await journal.getByRole('button', { name: 'Save occurrence' }).click();
await journal.getByText('Occurrence saved.', { exact: true }).waitFor();
await journal.getByRole('button', { name: 'Record behavior' }).click();
await journal.getByLabel('Behavior', { exact: true }).selectOption({ label: 'Wing stretching' });
await journal.getByLabel('Date and time', { exact: true }).fill('2026-10-05T22:00');
await journal.getByRole('button', { name: 'Save occurrence' }).click();
await journal.getByText('3 occurrences this month', { exact: true }).waitFor();
const day = journal.getByRole('button', { name: '10/5/2026: 2 occurrences', exact: true });
await day.click(); assert.equal(await journal.locator('details').count(), 2);
const entry = journal.locator('details').filter({ hasText: 'Observed after play' });
await entry.locator('summary').click();
await entry.getByRole('button', { name: 'Edit', exact: true }).click();
await journal.getByLabel('Notes (optional)').fill('Edited observation');
await journal.getByRole('button', { name: 'Save occurrence' }).click();
await journal.getByText('Edited observation', { exact: true }).first().waitFor();
await journal.getByLabel('Show behavior', { exact: true }).selectOption({ label: 'Wing stretching' });
await journal.getByText('2 occurrences this month', { exact: true }).waitFor();
await journal.getByRole('button', { name: 'Next month' }).click();
await journal.getByText('0 occurrences this month', { exact: true }).waitFor();
await journal.getByLabel('Show behavior', { exact: true }).selectOption('');
await journal.getByText('2 occurrences this month', { exact: true }).waitFor();
await journal.getByRole('button', { name: '11/1/2026: 2 occurrences', exact: true }).click();
assert.equal(await journal.locator('details').count(), 2); // Both sides of fall-back belong to Nov 1.
await journal.locator('details').first().locator('summary').click();
await journal.locator('details').first().getByRole('button', { name: 'Edit', exact: true }).click();
await journal.getByLabel('Notes (optional)').fill('Later repeated hour retained');
await journal.getByRole('button', { name: 'Save occurrence' }).click();
await journal.getByText('Occurrence saved.', { exact: true }).waitFor();
const repeated = (await db.query(`SELECT occurred_at FROM behavior_occurrences WHERE bird_id = $1 AND notes = 'Later repeated hour retained'`, [bird])).rows[0];
assert.equal(repeated.occurred_at.toISOString(), '2026-11-01T06:30:00.000Z');
await journal.getByRole('button', { name: 'Previous month' }).click();
await journal.getByRole('button', { name: 'Previous month' }).click();
await journal.getByText('1 occurrence this month', { exact: true }).waitFor(); // UTC Oct 1 before local midnight.
await journal.getByRole('button', { name: 'Next month' }).click();
await journal.getByRole('button', { name: '10/5/2026: 2 occurrences', exact: true }).click();
await page.setViewportSize({ width: 390, height: 844 });
await journal.scrollIntoViewIfNeeded();
await page.screenshot({ path: '/tmp/flockpal-behavior-mobile.png', fullPage: true });
assert.equal(await journal.evaluate((element) => element.scrollWidth <= element.clientWidth + 1), true, 'Journal must fit mobile width');
const editedEntry = journal.locator('details').filter({ hasText: 'Edited observation' });
await editedEntry.locator('summary').click();
page.once('dialog', (dialog) => dialog.accept());
await editedEntry.getByRole('button', { name: 'Delete', exact: true }).click();
await journal.getByText('Occurrence deleted.', { exact: true }).waitFor();
await journal.getByRole('button', { name: '10/5/2026: 1 occurrences', exact: true }).waitFor();
await journal.getByLabel('Bird', { exact: true }).selectOption(secondBird);
await journal.getByText('0 occurrences this month', { exact: true }).waitFor();
await journal.getByLabel('Bird', { exact: true }).selectOption(bird);
await journal.getByText('2 occurrences this month', { exact: true }).waitFor();
await page.setViewportSize({ width: 1280, height: 1000 });
await journal.scrollIntoViewIfNeeded();
await page.screenshot({ path: '/tmp/flockpal-behavior-desktop.png', fullPage: true });
const utcContext = await browser.newContext({ timezoneId: 'UTC', viewport: { width: 1280, height: 1000 } });
const utcPage = await utcContext.newPage();
await utcPage.addInitScript((value) => localStorage.setItem('flockpal_auth_token', value), token);
await utcPage.clock.setFixedTime(new Date('2026-10-05T16:00:00Z'));
await utcPage.goto('http://127.0.0.1:55441');
await utcPage.getByRole('button', { name: 'Flock', exact: true }).click();
await utcPage.locator('.bird-card-select').filter({ hasText: 'Piper' }).click();
await utcPage.getByRole('tab', { name: 'Behavior Journal' }).click();
const utcJournal = utcPage.getByRole('tabpanel', { name: 'Behavior Journal' });
await utcJournal.getByText('3 occurrences this month', { exact: true }).waitFor();
await utcJournal.getByRole('button', { name: '10/1/2026: 2 occurrences', exact: true }).waitFor();
await utcContext.close();
assert.deepEqual(errors, []);
console.log('PASS: browser create/custom type/edit/delete, bird/behavior filters, month navigation, multiple events/day, local midnight and DST, and mobile layout.');
} catch (error) {
if (page) {
console.error(await page.locator('.behavior-journal').innerText().catch(() => 'Journal unavailable'));
await page.screenshot({ path: '/tmp/flockpal-behavior-failure.png', fullPage: true });
}
throw error;
} finally {
if (browser) await browser.close();
for (const child of children.reverse()) if (child.exitCode === null) { const done = once(child, 'exit'); child.kill('SIGTERM'); await done; }
await db.close();
}
@@ -0,0 +1,91 @@
// Optional browser integration check; use the disposable setup in docs/BIRD_MEMBERSHIP.md.
import assert from 'node:assert/strict';
import { randomUUID, createHash } from 'node:crypto';
import { spawn } from 'node:child_process';
import { once } from 'node:events';
import { fileURLToPath } from 'node:url';
import { chromium } from 'playwright';
Object.assign(process.env, {
POSTGRES_HOST: '127.0.0.1', POSTGRES_PORT: '55439', POSTGRES_DB: 'behavior_test', POSTGRES_USER: 'postgres',
POSTGRES_PASSWORD: 'behavior_test_only', PORT: '55440', FRONTEND_URL: 'http://127.0.0.1:55441',
VITE_API_BASE_URL: 'http://127.0.0.1:55440/api',
MILESTONE_REMINDERS_ENABLED: 'false', MEDICATION_REMINDERS_ENABLED: 'false', WEIGHT_REMINDERS_ENABLED: 'false',
});
const { db } = await import('../../backend/dist/db/client.js');
const children = [];
let browser;
async function start(path, args, marker) {
let output = '';
const child = spawn(process.execPath, [fileURLToPath(path), ...args], { cwd: fileURLToPath(new URL('../', import.meta.url)), env: process.env, stdio: ['ignore', 'pipe', 'pipe'] });
children.push(child);
child.stdout.on('data', (data) => { output += data; }); child.stderr.on('data', (data) => { output += data; });
for (let i = 0; i < 100 && !output.includes(marker); i++) await new Promise((resolve) => setTimeout(resolve, 100));
assert.ok(output.includes(marker), output);
}
try {
const accounts = [];
const baseId = 100000 + Math.floor(Math.random() * 1000000000);
for (let i = 0; i < 2; i++) {
const workspace = baseId + i, user = randomUUID(), token = randomUUID(), email = `${user}@example.test`;
await db.query(`INSERT INTO workspaces (id, name, workspace_type, rescue_verification_status) VALUES ($1, $2, 'rescue', 'approved')`, [workspace, `Browser membership ${i}`]);
await db.query(`INSERT INTO users (id, email, name, education_opt_out) VALUES ($1, $2, 'Browser tester', TRUE)`, [user, email]);
await db.query(`INSERT INTO workspace_members (workspace_id, user_id, invite_email, name, role, accepted_at) VALUES ($1, $2, $3, 'Browser tester', 'owner', NOW())`, [workspace, user, email]);
await db.query(`INSERT INTO auth_sessions (user_id, active_workspace_id, token_hash, expires_at) VALUES ($1, $2, $3, NOW() + INTERVAL '1 hour')`, [user, workspace, createHash('sha256').update(token).digest('hex')]);
accounts.push({ workspace, token });
}
const [source, destination] = accounts;
const bird = randomUUID(), tagId = `FP-${randomUUID()}`;
await db.query(`INSERT INTO birds (id, workspace_id, name, tag_id, species) VALUES ($1, $2, 'Piper', $3, 'Parrot')`, [bird, source.workspace, tagId]);
await db.query(`INSERT INTO weight_records (bird_id, weight_grams, recorded_on) VALUES ($1, 120, CURRENT_DATE)`, [bird]);
await db.query(`INSERT INTO flock_notes (workspace_id, bird_id, title, body) VALUES ($1, $2, 'Existing note', 'Enjoys morning play')`, [source.workspace, bird]);
await start(new URL('../../backend/dist/app.js', import.meta.url), [], 'listening');
await start(new URL('../node_modules/vite/bin/vite.js', import.meta.url), ['--host', '127.0.0.1', '--port', '55441'], 'Local:');
browser = await chromium.launch({ headless: true });
const sourcePage = await browser.newPage({ viewport: { width: 1280, height: 1000 } });
await sourcePage.addInitScript((value) => localStorage.setItem('flockpal_auth_token', value), source.token);
await sourcePage.goto('http://127.0.0.1:55441', { waitUntil: 'domcontentloaded' });
await sourcePage.getByRole('button', { name: 'Flock', exact: true }).click();
await sourcePage.locator('.bird-card-select').filter({ hasText: 'Piper' }).click();
await sourcePage.getByRole('button', { name: 'Edit details for Piper' }).click();
sourcePage.once('dialog', async (dialog) => { assert.match(dialog.message(), /history will be retained/); await dialog.accept(); });
await sourcePage.getByRole('button', { name: 'Remove from flock', exact: true }).click();
await sourcePage.locator('.bird-card-select').filter({ hasText: 'Piper' }).waitFor({ state: 'detached' });
assert.equal((await db.query(`SELECT workspace_id FROM birds WHERE id = $1`, [bird])).rows[0].workspace_id, null);
const page = await browser.newPage({ viewport: { width: 390, height: 844 } });
const pageErrors = []; page.on('pageerror', (error) => pageErrors.push(error.message));
await page.addInitScript((value) => localStorage.setItem('flockpal_auth_token', value), destination.token);
await page.goto('http://127.0.0.1:55441', { waitUntil: 'domcontentloaded' });
await page.getByRole('button', { name: 'Flock', exact: true }).click();
await page.getByRole('button', { name: 'Add bird', exact: true }).click();
const bandInput = page.getByLabel('Band ID, if known', { exact: true });
await bandInput.fill(tagId.slice(0, -1));
await page.getByText('Checking band ID for existing history…').waitFor({ state: 'hidden' });
assert.equal(await page.getByRole('button', { name: 'Add bird with existing history' }).count(), 0);
await bandInput.fill(` ${tagId.toLowerCase()} `);
const claimButton = page.getByRole('button', { name: 'Add bird with existing history' });
await claimButton.waitFor();
assert.equal(await page.getByRole('button', { name: 'Save bird profile', exact: true }).isDisabled(), true);
const notice = page.getByRole('status').filter({ hasText: 'This band ID matches' });
assert.equal(await notice.evaluate((element) => element.scrollWidth <= element.clientWidth), true);
await notice.screenshot({ path: '/tmp/flockpal-existing-history-notice.png' });
page.once('dialog', async (dialog) => { assert.match(dialog.message(), /history will be brought in/); await dialog.dismiss(); });
await claimButton.click();
assert.equal((await db.query(`SELECT workspace_id FROM birds WHERE id = $1`, [bird])).rows[0].workspace_id, null);
// Only a band ID is needed: no replacement name or species should be required to claim history.
assert.equal(await page.getByLabel('Bird name', { exact: true }).inputValue(), '');
page.on('dialog', (dialog) => dialog.accept());
await claimButton.click();
await page.getByRole('tab', { name: 'Weight', exact: true }).waitFor();
assert.equal((await db.query(`SELECT workspace_id FROM birds WHERE id = $1`, [bird])).rows[0].workspace_id, destination.workspace);
assert.equal((await db.query(`SELECT COUNT(*)::int AS count FROM birds WHERE LOWER(tag_id) = LOWER($1)`, [tagId])).rows[0].count, 1);
await page.getByRole('tab', { name: 'Notes', exact: true }).click();
await page.getByText('Enjoys morning play', { exact: true }).waitFor();
await page.getByRole('tab', { name: 'Timeline', exact: true }).click();
await page.getByText('Joined flock with history', { exact: true }).first().waitFor();
assert.deepEqual(pageErrors, []);
console.log('PASS: desktop removal retains history; mobile exact band match notice, cancellation, confirmation, claim without replacement fields, and restored notes/timeline.');
} finally {
if (browser) await browser.close();
for (const child of children.reverse()) if (child.exitCode === null) { const done = once(child, 'exit'); child.kill('SIGTERM'); await done; }
await db.close();
}