Problem Statement
The sub-account system (src/routes/sub-accounts.ts, src/middleware/subAccount.ts) supports per-child permissions and daily limits, but every operation — create a child, set a permission, adjust a limit, approve a pending action — is one API call per child. A parent managing five sub-accounts is fine; a family office, RIA, or institutional user managing fifty or a hundred is not — they need to apply a policy change across many sub-accounts in one call, and to see an aggregate view rather than paging through individual children one at a time. This issue adds bulk/batch operations for sub-account management, layered over the existing per-account primitives (no new authorization model, just a multiplexed call surface with proper partial-failure handling).
Current State
src/routes/sub-accounts.ts — per-child CRUD and permission management.src/middleware/subAccount.ts — dailyLimit (confirmed field), SubAccountPermission checks.- No batch endpoint exists (confirmed: no
bulk/batch reference in the route file).
Proposed Solution
POST /api/v1/sub-accounts/bulk — array of { action: 'create'|'update'|'setPermission'|'setLimit', childUserId?, payload } operations, each independently validated and authorized exactly as its single-operation equivalent would be (no relaxed checks for being part of a batch).- Partial-failure semantics: each operation in the batch succeeds or fails independently; the response is a per-operation result array (never all-or-nothing unless the caller explicitly requests atomic all-or-nothing via a
atomic: true flag, which wraps the whole batch in one DB transaction) — most bulk-management use cases want "apply what's valid, tell me what failed," not a single bad row blocking 99 good ones.
- Bounded batch size (config, e.g. max 100 operations per call) to keep request processing time and blast radius reasonable.
GET /api/v1/sub-accounts/summary — an aggregate view (total children, permission-distribution breakdown, total daily-limit exposure, recent activity counts) so a parent managing many children gets a dashboard-shaped answer instead of needing to fetch and sum every child individually.- Every operation within a bulk call is individually audit-logged exactly as its single-call equivalent would be — bulk is a convenience wrapper over the existing audited primitives, not a new unaudited path.
Edge Cases & Failure Modes
- One operation in a non-atomic batch fails validation: that operation's result entry reports the failure reason; other operations proceed normally.
atomic: true with one failure: the entire batch rolls back, response clearly indicates which operation caused the rollback.- Batch exceeds size limit: rejected upfront with the limit stated, before any operation runs (fail fast, not partial-processed-then-rejected).
- Duplicate operations targeting the same child in one batch: applied in array order, each building on the previous operation's result within the same batch (documented, deterministic ordering) — not run in parallel in a way that could race against itself.
- A child referenced in the batch doesn't belong to the calling parent: that operation fails with the same authorization error a single-call attempt would produce — batch membership never implies elevated authorization.
Security & Privacy Considerations
- No new authorization surface — every operation in a batch is checked against the exact same
SubAccountPermission/ownership rules as its single-call equivalent; batching is purely a call-multiplexing convenience.
- Bounded batch size limits abuse/DoS potential.
- Full audit logging per operation, not just per batch.
Out of Scope
- Bulk operations across multiple parents' sub-accounts (institutional multi-tenant management beyond a single parent's own children is a different, larger feature).
- A general-purpose bulk-API framework for other resource types (scoped specifically to sub-account management, where the institutional-scale need is clearest).
- Bulk money-movement operations (deposits/withdrawals) — this issue is account/permission management only, not a batch payment feature.
Suggested Implementation Plan
POST /api/v1/sub-accounts/bulk — per-operation validation/authorization reusing existing single-call logic, partial-failure result array, optional atomic: true transactional mode.- Bounded batch-size enforcement, fail-fast on oversized batches.
GET /api/v1/sub-accounts/summary aggregate view.- Per-operation audit logging within a batch.
docs/openapi.yaml update.
Good first issue candidate: a well-scoped multiplexing layer over already-existing, already-tested single-operation logic.
Acceptance Criteria
Problem Statement
The sub-account system (
src/routes/sub-accounts.ts,src/middleware/subAccount.ts) supports per-child permissions and daily limits, but every operation — create a child, set a permission, adjust a limit, approve a pending action — is one API call per child. A parent managing five sub-accounts is fine; a family office, RIA, or institutional user managing fifty or a hundred is not — they need to apply a policy change across many sub-accounts in one call, and to see an aggregate view rather than paging through individual children one at a time. This issue adds bulk/batch operations for sub-account management, layered over the existing per-account primitives (no new authorization model, just a multiplexed call surface with proper partial-failure handling).Current State
src/routes/sub-accounts.ts— per-child CRUD and permission management.src/middleware/subAccount.ts—dailyLimit(confirmed field),SubAccountPermissionchecks.bulk/batchreference in the route file).Proposed Solution
POST /api/v1/sub-accounts/bulk— array of{ action: 'create'|'update'|'setPermission'|'setLimit', childUserId?, payload }operations, each independently validated and authorized exactly as its single-operation equivalent would be (no relaxed checks for being part of a batch).atomic: trueflag, which wraps the whole batch in one DB transaction) — most bulk-management use cases want "apply what's valid, tell me what failed," not a single bad row blocking 99 good ones.GET /api/v1/sub-accounts/summary— an aggregate view (total children, permission-distribution breakdown, total daily-limit exposure, recent activity counts) so a parent managing many children gets a dashboard-shaped answer instead of needing to fetch and sum every child individually.Edge Cases & Failure Modes
atomic: truewith one failure: the entire batch rolls back, response clearly indicates which operation caused the rollback.Security & Privacy Considerations
SubAccountPermission/ownership rules as its single-call equivalent; batching is purely a call-multiplexing convenience.Out of Scope
Suggested Implementation Plan
POST /api/v1/sub-accounts/bulk— per-operation validation/authorization reusing existing single-call logic, partial-failure result array, optionalatomic: truetransactional mode.GET /api/v1/sub-accounts/summaryaggregate view.docs/openapi.yamlupdate.Good first issue candidate: a well-scoped multiplexing layer over already-existing, already-tested single-operation logic.
Acceptance Criteria
POST /api/v1/sub-accounts/bulkaccepts an array of create/update/setPermission/setLimit operations, each independently validated and authorized identically to its single-call equivalentatomic: truewraps the batch in a single transaction that rolls back entirely on any failureGET /api/v1/sub-accounts/summaryreturns an aggregate view (child count, permission distribution, total limit exposure, recent activity) without requiring per-child fetchesdocs/openapi.yamlupdated; unit + integration tests green (partial-failure, atomic-rollback, oversized-batch, cross-parent-authorization cases)