🛣️ Order Routes

Order routes provide pre-configured HTTP endpoints for order management operations in Nodeblocks applications. These routes combine handlers, validators, and middleware to create complete API endpoints with proper authentication, authorization, and error handling.

---

🎯 Overview

Order routes are designed to:

• Provide complete API endpoints for order management operations
• Combine handlers with validators for secure operations
• Include authentication and authorization checks
• Support functional composition patterns
• Handle logging and error management automatically

---

📋 Route Structure

Each order route follows a consistent pattern:

• HTTP Method: Defines the operation type (GET, POST, PATCH, DELETE)
• Path: Specifies the endpoint URL with parameters
• Handler: Composed function chain for business logic
• Validators: Authentication and authorization checks

---

🔧 Available Order Routes

createOrderRoute

Creates a new order and returns the created resource.

Purpose: Handles order creation with full resource retrieval

Route Details:

• Method: POST
• Path: /orders
• Authentication: Required (Bearer token)

Handlers: createOrder, getOrderById, createOrderTerminator

Validators: isAuthenticated, some(checkIdentityType(['admin']), isSelf(['params', 'requestBody', 'identityId']))

Usage:

import { routes } from '@nodeblocks/backend-sdk';

// Register route with Express app
app.use('/api', routes.createOrderRoute);

---

getOrderRoute

Retrieves a specific order by ID.

Purpose: Fetches order data with access control

Route Details:

• Method: GET
• Path: /orders/:orderId
• Authentication: Required (Bearer token)

Handlers: getOrderById, normalizeOrderTerminator

Validators: isAuthenticated, some(checkIdentityType(['admin']), ownsOrder(['params', 'requestParams', 'orderId']))

Usage:

import { routes } from '@nodeblocks/backend-sdk';

// Register route with Express app
app.use('/api', routes.getOrderRoute);

---

findOrdersRoute

Retrieves all orders with normalized list format.

Purpose: Lists orders with pagination and access control

Route Details:

• Method: GET
• Path: /orders
• Authentication: Required (Bearer token)

Handlers: findOrders, normalizeOrdersListTerminator

Validators: isAuthenticated, some(checkIdentityType(['admin']), isSelf(['params', 'requestQuery', 'identityId']))

Usage:

import { routes } from '@nodeblocks/backend-sdk';

// Register route with Express app
app.use('/api', routes.findOrdersRoute);

---

updateOrderRoute

Updates an existing order and returns the updated resource.

Purpose: Modifies order data with access control

Route Details:

• Method: PATCH
• Path: /orders/:orderId
• Authentication: Required (Bearer token)

Handlers: updateOrder, getOrderById, normalizeOrderTerminator

Validators: isAuthenticated, some(checkIdentityType(['admin']), ownsOrder(['params', 'requestParams', 'orderId']))

Usage:

import { routes } from '@nodeblocks/backend-sdk';

// Register route with Express app
app.use('/api', routes.updateOrderRoute);

---

deleteOrderRoute

Deletes an order by ID.

Purpose: Removes order with access control

Route Details:

• Method: DELETE
• Path: /orders/:orderId
• Authentication: Required (Bearer token)

Handlers: deleteOrder, deleteOrderTerminator

Validators: isAuthenticated, some(checkIdentityType(['admin']), ownsOrder(['params', 'requestParams', 'orderId']))

Usage:

import { routes } from '@nodeblocks/backend-sdk';

// Register route with Express app
app.use('/api', routes.deleteOrderRoute);

---

findOrdersByOrganizationIdRoute

Retrieves orders by organization ID via GET /orders/organizations/:organizationId.

Purpose: Provides organization-scoped access to orders with proper authorization controls and pagination support.

Route Details:

• Method: GET
• Path: /orders/organizations/:organizationId
• Authentication: Required (Bearer token)
• Authorization: Organization role-based (hasOrgRole(['owner', 'admin', 'member']))

Handlers: buildOrganizationIdFilter, buildWithoutMongoIdFindOptions, findOrders, applySpec, orThrow

Validators: isAuthenticated, hasOrgRole(['owner', 'admin', 'member'], ['params', 'requestParams', 'organizationId'])

Query Parameters:

Parameter	Type	Required	Default	Description
page	number	❌	1	Page number for pagination
limit	number	❌	10	Number of orders per page

Usage:

import { routes } from '@nodeblocks/backend-sdk';

// Register route with Express app
app.use('/api', routes.findOrdersByOrganizationIdRoute);

Response (200 - Success):

{
  "data": [
    {
      "id": "order-123",
      "organizationId": "org-456",
      "currency": "USD",
      "status": "confirmed",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "metadata": {
    "pagination": {
      "hasNext": false,
      "hasPrev": false,
      "limit": 10,
      "page": 1,
      "total": 1,
      "totalPages": 1
    }
  }
}

Error Responses:

• 401: Unauthorized - Invalid or missing authentication token
• 403: Forbidden - User lacks organization access or insufficient role permissions
• 500: Internal Server Error - Database or normalization error

Key Features:

• Organization Scoping: Orders are automatically filtered by organization ID from path parameter
• Role-Based Authorization: Access restricted to organization owners, admins, and members
• Pagination Support: Full pagination with metadata for large order collections
• Data Normalization: Automatic document normalization via buildWithoutMongoIdFindOptions
• Type Safety: Comprehensive error handling with OrderDbBlockError