API Routes

Overview

All routes are registered in /src/routes/index.ts and mounted under the root path. Each route module exports an Express Router that defines endpoints for a specific domain.

Route Registration Pattern

// src/routes/index.ts
import { Router } from 'express';
import authRoutes from './auth.routes';
import userRoutes from './user.routes';
// ... other imports

const router = Router();

// Health check (no auth required)
router.get('/health', (_req, res) => {
  res.json({ status: 'ok', timestamp: new Date().toISOString() });
});

// Mount all route modules
router.use('/auth', authRoutes);
router.use('/users', userRoutes);
router.use('/books', bookRoutes);
// ... etc

export default router;

Route Modules

Authentication (/auth)

File: src/routes/auth.routes.ts

Handles user authentication and session management.

Method	Endpoint	Auth	Description
POST	/auth/guest	None	Create guest user account
POST	/auth/signup	None	Register new user account
POST	/auth/login	None	Login with email/password
POST	/auth/refresh	None	Refresh access token
POST	/auth/migrate-guest	Required	Migrate guest to full account
POST	/auth/logout	Required	Logout and revoke token

Users (/users)

File: src/routes/user.routes.ts

User profile and settings management.

Method	Endpoint	Auth	Description
GET	/users/me	Required	Get current user profile
PATCH	/users/me	Required	Update user profile
GET	/users/:username	Optional	Get public profile by username
POST	/users/home-store	Required	Set home store
POST	/users/push-token	Required	Register FCM push token

User Preferences (/user-preferences)

File: src/routes/user-preferences.routes.ts

Method	Endpoint	Auth	Description
GET	/user-preferences	Required	Get user preferences
PATCH	/user-preferences	Required	Update preferences

Books (/books)

File: src/routes/book.routes.ts

Book catalog and metadata.

Method	Endpoint	Auth	Description
GET	/books?q={query}	Optional	Search books by title/author/ISBN
GET	/books/:id	Optional	Get book details by ID
GET	/books/isbn/:isbn	Optional	Get book by ISBN
GET	/books/:id/availability	Required	Check availability at stores
GET	/books/:id/lines	Optional	Get lines (posts) for a book
GET	/books/:id/reviews	Optional	Get reviews for a book

Wishlists (/wishlists)

File: src/routes/wishlist.routes.ts

User wishlist management.

Method	Endpoint	Auth	Description
GET	/wishlists	Required	Get user's wishlists
POST	/wishlists	Required	Create new wishlist
GET	/wishlists/:id	Required	Get wishlist details
PATCH	/wishlists/:id	Required	Update wishlist
DELETE	/wishlists/:id	Required	Delete wishlist
POST	/wishlists/:id/items	Required	Add book to wishlist
DELETE	/wishlists/:id/items/:itemId	Required	Remove book from wishlist
PATCH	/wishlists/:id/items/:itemId	Required	Update wishlist item

Stores (/stores)

File: src/routes/store.routes.ts

Bookstore management and discovery.

Method	Endpoint	Auth	Description
GET	/stores	Optional	List/search stores
POST	/stores	Required	Create new store
GET	/stores/:id	Optional	Get store details
PATCH	/stores/:id	Owner	Update store settings
GET	/stores/:id/inventory	Optional	Get store inventory
POST	/stores/:id/follow	Required	Follow store
DELETE	/stores/:id/follow	Required	Unfollow store

Store Subscriptions (/stores)

File: src/routes/store-subscription.routes.ts

WEB-ONLY - Bookstore subscription billing (mounted under /stores).

Method	Endpoint	Auth	Description
POST	/stores/:storeId/subscription/checkout	Owner	Create Stripe checkout session
POST	/stores/:storeId/subscription/portal	Owner	Create customer portal session
GET	/stores/:storeId/subscription/status	Owner	Get subscription status

Inventory

File: src/routes/inventory.routes.ts

Store inventory management and Square OAuth (mounted at root /).

Method	Endpoint	Auth	Description
POST	/stores/:storeId/inventory	Store Access	Add inventory item
PATCH	/inventory/:id	Store Access	Update inventory item
DELETE	/inventory/:id	Store Access	Delete inventory item
GET	/square/auth	Required	Get Square OAuth URL
GET	/square/callback	None	Square OAuth callback
POST	/square/sync/:storeId	Store Access	Trigger manual sync

Orders (/orders)

File: src/routes/order.routes.ts

Order management for customers and stores.

Method	Endpoint	Auth	Description
GET	/orders	Required	Get user's orders
GET	/orders/:id	Required	Get order details
POST	/orders/:id/cancel	Required	Cancel order
GET	/stores/:storeId/orders	Store Access	Get store orders
PATCH	/stores/:storeId/orders/:id	Store Access	Update order status

Checkout (/checkout)

File: src/routes/checkout.routes.ts

Order checkout flow.

Method	Endpoint	Auth	Description
POST	/checkout/create-payment-intent	Required	Create Stripe PaymentIntent
POST	/checkout/confirm-order	Required	Confirm order after payment

Cart (/cart)

File: src/routes/cart.routes.ts

Shopping cart operations (in-memory, no persistence).

Method	Endpoint	Auth	Description
POST	/cart/validate	Required	Validate cart items
POST	/cart/calculate	Required	Calculate totals with tax/shipping

Point of Sale (/pos)

File: src/routes/pos.routes.ts

In-store POS operations.

Method	Endpoint	Auth	Description
POST	/pos/sales	Store Staff	Create POS sale
GET	/pos/sales	Store Staff	Get store sales
GET	/pos/sales/:id	Store Staff	Get sale details

Trade Credit (/trade-credit)

File: src/routes/trade-credit.routes.ts

Store credit and trade-in operations.

Method	Endpoint	Auth	Description
GET	/trade-credit/balance/:storeId	Required	Get credit balance
POST	/trade-credit/trade-in	Store Staff	Process trade-in
GET	/trade-credit/transactions/:storeId	Required	Get transaction history

Lines (/lines)

File: src/routes/line.routes.ts

Social posts (lines) for books.

Method	Endpoint	Auth	Description
POST	/lines	Required	Create line
GET	/lines/:id	Optional	Get line details
DELETE	/lines/:id	Required	Delete own line
POST	/lines/:id/like	Required	Like line
DELETE	/lines/:id/like	Required	Unlike line
POST	/lines/:id/replies	Required	Reply to line
GET	/lines/:id/replies	Optional	Get line replies

Reviews (/reviews)

File: src/routes/review.routes.ts

Book reviews and ratings.

Method	Endpoint	Auth	Description
POST	/reviews	Required	Create review
GET	/reviews/:id	Optional	Get review
PATCH	/reviews/:id	Required	Update own review
DELETE	/reviews/:id	Required	Delete own review
POST	/reviews/:id/like	Required	Like review
DELETE	/reviews/:id/like	Required	Unlike review

Notes (/notes)

File: src/routes/note.routes.ts

Personal book notes (private).

Method	Endpoint	Auth	Description
GET	/notes	Required	Get user's notes
POST	/notes	Required	Create note
GET	/notes/:id	Required	Get note
PATCH	/notes/:id	Required	Update note
DELETE	/notes/:id	Required	Delete note

Follow (/follows)

File: src/routes/follow.routes.ts

Social following system.

Method	Endpoint	Auth	Description
POST	/follows	Required	Follow user
DELETE	/follows/:userId	Required	Unfollow user
GET	/follows/followers	Required	Get followers list
GET	/follows/following	Required	Get following list

Feed (/feed)

File: src/routes/feed.routes.ts

Activity feed (lines from followed users).

Method	Endpoint	Auth	Description
GET	/feed	Required	Get personalized feed

Search (/search)

File: src/routes/search.routes.ts

Global search across multiple entities.

Method	Endpoint	Auth	Description
GET	/search?q={query}&type={type}	Optional	Search books, stores, users

Clubs (/clubs)

File: src/routes/club.routes.ts

Book club management.

Method	Endpoint	Auth	Description
GET	/clubs	Optional	List clubs
POST	/clubs	Required	Create club
GET	/clubs/:id	Optional	Get club details
PATCH	/clubs/:id	Host	Update club
DELETE	/clubs/:id	Host	Delete club
POST	/clubs/:id/join	Required	Join club
POST	/clubs/:id/leave	Required	Leave club
POST	/clubs/:id/books	Host	Add book to club

Challenges (/challenges)

File: src/routes/challenge.routes.ts

Reading challenges.

Method	Endpoint	Auth	Description
GET	/challenges	Optional	List challenges
POST	/challenges	Required	Create challenge
GET	/challenges/:id	Optional	Get challenge details
PATCH	/challenges/:id	Host	Update challenge
DELETE	/challenges/:id	Host	Delete challenge
POST	/challenges/:id/join	Required	Join challenge
POST	/challenges/:id/leave	Required	Leave challenge

Notifications (/notifications)

File: src/routes/notification.routes.ts

User notifications.

Method	Endpoint	Auth	Description
GET	/notifications	Required	Get user notifications
PATCH	/notifications/:id/read	Required	Mark as read
POST	/notifications/read-all	Required	Mark all as read

Addresses (/addresses)

File: src/routes/address.routes.ts

User shipping addresses.

Method	Endpoint	Auth	Description
GET	/addresses	Required	Get user addresses
POST	/addresses	Required	Create address
PATCH	/addresses/:id	Required	Update address
DELETE	/addresses/:id	Required	Delete address

Stock Alerts (/stock-alerts)

File: src/routes/stock-alert.routes.ts

Stock availability alerts.

Method	Endpoint	Auth	Description
POST	/stock-alerts	Required	Create stock alert
GET	/stock-alerts	Required	Get user's alerts
DELETE	/stock-alerts/:id	Required	Delete alert

Moderation

File: src/routes/moderation.routes.ts

Content moderation and user blocking (mounted at root /).

Method	Endpoint	Auth	Description
POST	/users/:id/block	Required	Block user or store
DELETE	/users/:id/block	Required	Unblock user or store
POST	/reports	Required	Submit content report
GET	/admin/reports	Admin	Get all reports
PATCH	/admin/reports/:id	Admin	Update report status

Billing (/billing)

File: src/routes/billing.routes.ts

WEB-ONLY - Premium subscription billing via Stripe.

Method	Endpoint	Auth	Description
POST	/billing/premium/checkout	Required	Create premium checkout session
GET	/billing/premium/plans	None	Get available premium plans

Webhooks (/webhooks)

File: src/routes/webhook.routes.ts

Webhook handlers for external services.

Method	Endpoint	Auth	Description
POST	/webhooks/stripe	Signature	Stripe webhook events
POST	/webhooks/square	Signature	Square webhook events
POST	/webhooks/revenuecat	Secret	RevenueCat webhook events

Common Middleware Patterns

Authentication Middleware

import { authenticate, optionalAuth } from '../middleware/auth.middleware';

// Required authentication
router.get('/protected', authenticate, controller.handler);

// Optional authentication (user may or may not be logged in)
router.get('/public', optionalAuth, controller.handler);

Tier Gating Middleware

import { requireTier } from '../middleware/tier.middleware';
import { UserTier } from '@prisma/client';

// Require premium tier
router.post('/premium-feature', authenticate, requireTier(UserTier.premium), controller.handler);

Store Access Middleware

import { requireStoreAccess, requireStoreOwnership } from '../middleware/store-owner.middleware';

// Require owner or staff access
router.patch('/stores/:storeId/settings', authenticate, requireStoreAccess, controller.handler);

// Require owner only
router.delete('/stores/:storeId', authenticate, requireStoreOwnership, controller.handler);

Route Organization

Routes are organized by domain (entity type):

• Authentication: User auth and session management
• Core Entities: Users, Books, Stores
• Commerce: Inventory, Orders, Checkout, Cart, POS
• Social: Lines, Reviews, Notes, Follow, Feed
• Programs: Clubs, Challenges
• Support: Notifications, Addresses, Stock Alerts, Moderation
• Integrations: Webhooks, Billing

Error Responses

All routes return consistent error responses:

{
  "error": "ErrorCode",
  "message": "Human-readable error message"
}

Common error codes:

• Unauthorized (401) - Missing or invalid authentication
• Forbidden (403) - Insufficient permissions
• NotFound (404) - Resource not found
• BadRequest (400) - Invalid request data
• InternalServerError (500) - Server error

Pagination

Routes that return lists support cursor-based pagination:

GET /endpoint?cursor={cursor}&limit={limit}

Response:
{
  "data": [...],
  "nextCursor": "abc123",
  "hasMore": true
}

Default limit: 20, Max limit: 100