expense

Chat mode imported from briosoemilio/ambagan-be (.github/chatmodes/expense.chatmode.md). Copyright stays with the author.

Master agent for the expenses Firestore collection in this Express/Firebase Functions backend. An "expense" is money spent out of a project's collected funds — the counterpart to an ambag (money coming in). This is the newest of the four collections (see recent history: "Initial changes to expenses feature"), so expect rougher edges than ambags/projects.

Scope

Owns everything related to the expenses collection: its routes, request validation schema, and ownership authorization. Aware of but does not own: projects (every expense belongs to one project via projectId; creating or deleting an expense updates the parent project's expensesCount and expensesTotal, and project metrics compute totalExpenses/ remainingBalance from this collection — see the project agent's buildProjectMetrics), and uploads (a receipt photo can link an expense back to an upload document, same pattern as ambags).

Key files

• functions/src/routes/expenses.ts — CRUD routes, all mounted behind authenticated: GET / (requires projectId query param + project membership), GET /:id, POST / (checks project.expensesEnabled before allowing creation), PATCH /:id, DELETE /:id, plus POST /upload for receipt photo upload (delegates to handleFileUpload, identical to the ambags upload route).
• functions/src/schemas/ExpenseSchema.ts — Zod schema: projectId, amount (number), createdAt (optional, coercible date), note, receipt {photoUrl, uploadId}. Notably no contributor/payer field unlike AmbagSchema — an expense currently has no record of who it was paid to or by beyond createdBy. PATCH uses ExpenseSchema.omit({createdAt: true}).partial().
• functions/src/middlewares/authorizeExpenseOwner.ts — allows the expense's createdBy user or the parent project's createdBy (owner) to PATCH/DELETE; 403 otherwise. 500s on data-integrity issues (missing projectId, orphaned project reference), same pattern as authorizeAmbagOwner.
• functions/src/middlewares/authorizeProjectMember.ts — gates GET / (list) to project members/creator; shared with the ambag/project agents' scope.
• functions/src/middlewares/validateBody.ts — generic Zod-based body validator used by POST/PATCH.
• functions/src/utils/handleFileUpload.ts — shared upload handler, same as the one used by POST /ambags/upload.
• functions/src/constants/Collection.ts — Collection.EXPENSES.

Conventions to follow

• Auth: router-level expensesRouter.use(authenticated) plus a redundant per-route authenticated — keep both when adding routes (same intentional redundancy as ambagsRouter).
• POST / checks projectDoc.data()?.expensesEnabled === false inside the transaction and throws "Expenses are disabled for this project" (mapped to a 403) if so. This is a project-level feature flag, analogous to progressEnabled in the project agent's scope — preserve this check if touching POST /.
• Side effects on create/delete: always keep projectRef.update({expensesCount: FieldValue.increment(...), expensesTotal: FieldValue.increment(...)}) in sync when touching create/delete — unlike ambags (count only), expenses track both a count and a running total, and the delete path guards amount with a typeof === "number" check before negating it. Don't drop that guard.
• All expenses.ts handlers (GET, POST, PATCH, DELETE) consistently return res.status(...)... on every branch, including success paths — keep that pattern for any new branches.
• Firestore access always goes through admin.firestore().collection(Collection.EXPENSES) — never hardcode "expenses".
• Multi-document writes (expense + upload link) use admin.firestore().runTransaction; the expensesCount/expensesTotal increment happens outside that transaction, after it commits — same non-atomic pattern as ambags, follow it rather than folding it in unless asked to make it atomic.
• Timestamps: createdAt accepts a client-supplied value and falls back to FieldValue.serverTimestamp(); updatedAt on PATCH is always server-set.

Known gaps to flag before extending

• No payer/recipient info on an expense (no contributor-equivalent field) — if asked to show "who paid this expense" in metrics or UI-facing data, this field doesn't exist yet and needs to be added to ExpenseSchema first.

When making changes

• Keep routes/expenses.ts focused on request handling; validation lives in ExpenseSchema, ownership checks live in authorizeExpenseOwner.
• If a change affects amount or the create/delete paths, double check both the expensesCount and expensesTotal increments/decrements on the related project still balance.
• If a change affects the receipt shape, check it stays structurally identical to AmbagSchema's receipt field — both feed the same handleFileUpload flow.
• Run lint/build via the functions package (npm run lint, npm run build inside functions/) before considering a change done.