[BE-20] Waitlist — queue members for fully-booked workspaces and notify on availability

[yusuftomilola]

Overview

When a workspace is fully booked for a requested range, members currently just get a 409. A waitlist converts that dead end into demand capture: join the queue, get notified the moment a cancellation frees the slot.

Proposed Design

New module backend/src/waitlist/. WaitlistEntry: userId, workspaceId, requestedStart, requestedEnd, seatCount, status (WAITING, NOTIFIED, CONVERTED, EXPIRED, CANCELLED), notifiedAt.

Flow:

1. POST /waitlist — allowed only when the requested range genuinely has insufficient seats (validate against the live availability from [BE-01]).
2. On booking cancellation/expiry ([BE-08]/[BE-03]) for that workspace: find the oldest WAITING entry whose range now fits → status NOTIFIED, send notification + email with a booking deep link, start a claim window (WAITLIST_CLAIM_HOURS, default 24).
3. If the member books within the window (detect on booking creation), mark CONVERTED; when the window lapses, a job expires the entry and notifies the next in line.
4. GET /waitlist/me, DELETE /waitlist/:id (leave queue); admin list per workspace.

Acceptance Criteria

• Joining a waitlist for an available slot returns 400 with the availability info.
• A cancellation notifies exactly one (the oldest fitting) waitlist entry.
• An unclaimed notification passes to the next member after the claim window.
• Migration included.

Dependencies

Blocked by [BE-01]. Uses the jobs module ([BE-03]) for claim-window expiry.

Notes for Contributors

Emit the existing WebSocket notification plus email. Comment below to be assigned.

[jewelnsan687-lab]

@jewelnsan687-lab has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

Good day maintainer I'm positive I can help you with this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @jewelnsan687-lab to this issue.

[almuslavish]

@almuslavish has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

I would like to work on this issue pls 🙏🙏🙏🙏🙏🙏🙏🙏🙏🙏🙏🙏🙏

ℹ️ Repo Maintainers: To accept this application, review their application or assign @almuslavish to this issue.

[inteee]

@inteee has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

Hi there, I'd like to contribute to this.

I'm a full-stack developer with solid experience in modern JavaScript/TypeScript, REST APIs, and frontend frameworks like React. I enjoy working in open source and following existing project conventions.

I've gone through the details of this issue and I'm confident I can deliver a clean, well-tested solution that fits the codebase.

Looking forward to contributing — please assign this issue to me.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @inteee to this issue.

[drips-wave]

Congratulations, @inteee! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on July 30, 2026.

🧑‍💻 @inteee: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign | FWC26 campaign!

@inteee's PR #1568 was approved and merged by @yusuftomilola.

🏆 @inteee: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (344 total points). Track your full progress on GrantFox.

👏 Great work, @inteee! Keep contributing to DistinctCodes.

[drips-wave]

This issue has been completed by @inteee as part of the Stellar Wave Program's 7th Wave 🥳

😎 @inteee: You earned 200 Points for completing this issue! After the current Wave ends, you'll be eligible for a percentage of the Wave's reward pool based on the percentage of total points you've earned. Learn more here. You can also Leave a review to share your experience working on this issue.

🧑‍💻 Repo maintainers: How'd the contributor do? Leave a review to share your experience working with them.