🛣️ Order routes

Order routes are SDK composers, not Express middleware. Compose them through the matching features, then mount the service as shown in the Order integration guide.

Inventory

Route	Method / protocol	Path	Schema	Validators	Success status
createOrderRoute	POST / HTTP	/orders	createOrderSchema	isAuthenticated(), some(checkIdentityType(['admin']), isSelf(['params', 'requestBody', 'identityId']))	201
getOrderRoute	GET / HTTP	/orders/:orderId	getOrderSchema	isAuthenticated(), some(checkIdentityType(['admin']), ownsOrder(['params', 'requestParams', 'orderId']))	200
findOrdersRoute	GET / HTTP	/orders	findOrdersSchema	isAuthenticated(), some(checkIdentityType(['admin']), isSelf(['params', 'requestQuery', 'identityId']))	200
updateOrderRoute	PATCH / HTTP	/orders/:orderId	updateOrderSchema	isAuthenticated(), some(checkIdentityType(['admin']), ownsOrder(['params', 'requestParams', 'orderId']))	200
deleteOrderRoute	DELETE / HTTP	/orders/:orderId	deleteOrderSchema	isAuthenticated(), some(checkIdentityType(['admin']), ownsOrder(['params', 'requestParams', 'orderId']))	204
findOrdersByOrganizationIdRoute	GET / HTTP	/orders/organizations/:organizationId	findByOrganizationIdSchema	isAuthenticated(), hasOrgRole(['owner', 'admin', 'member'], ['params', 'requestParams', 'organizationId'])	200

Details

createOrderRoute

Implementation

Endpoint: POST /orders

Creates an order for the supplied identityId, then reads it back before responding.

Access: Authenticated administrator, or an authenticated identity whose ID equals requestBody.identityId.

Request: createOrderSchema requires an application/json body with identityId, items, and total.

Pipeline: createOrder → getOrderById → createOrderTerminator.

Success: 201 with the created order object. The terminator removes MongoDB _id.

Failure: The handlers can report missing request data (400), creation failure (400), a missing reread order (404), or database errors (500). Authentication and authorization failures originate in the shared and local validators.

View complete source

export const createOrderRoute = withRoute({
  handler: compose(
    withLogging(createOrder),
    flatMapAsync(withLogging(getOrderById)),
    lift(withLogging(createOrderTerminator)),
  ),
  method: 'POST',
  path: '/orders',
  validators: [isAuthenticated(), some(checkIdentityType(['admin']), isSelf(['params', 'requestBody', 'identityId']))],
});

getOrderRoute

Implementation

Endpoint: GET /orders/:orderId

Gets one order and normalizes its public response.

Access: Authenticated administrator, or an authenticated identity that owns the order.

Request: getOrderSchema requires path parameter orderId.

Pipeline: getOrderById → normalizeOrderTerminator.

Success: Default Express JSON behavior produces 200 with the order object; the terminator removes _id.

Failure: getOrderById returns 400 without an ID, 404 when the order is absent, and 500 for a database failure. The terminator also throws 404 if no order reaches it.

View complete source

export const getOrderRoute = withRoute({
  handler: compose(withLogging(getOrderById), lift(withLogging(normalizeOrderTerminator))),
  method: 'GET',
  path: '/orders/:orderId',
  validators: [
    isAuthenticated(),
    some(checkIdentityType(['admin']), ownsOrder(['params', 'requestParams', 'orderId'])),
  ],
});

findOrdersRoute

Implementation

Endpoint: GET /orders

Finds orders from validated query fields. The pagination wrapper is part of the route pipeline.

Access: Authenticated administrator, or an authenticated identity whose ID equals query identityId.

Request: findOrdersSchema accepts the documented filters and pagination query parameters; it has no body.

Pipeline: findOrders → normalizeOrdersListTerminator, wrapped by withPagination(...) and logging.

Success: Default Express JSON behavior produces 200 with { data, metadata: { pagination } }; _id is removed from each order.

Failure: The handler turns database failure into 500; the list terminator throws 500 if the pipeline did not produce a supported list shape.

View complete source

export const findOrdersRoute = withRoute({
  handler: compose(withPagination(withLogging(findOrdersHandler)), lift(withLogging(normalizeOrdersListTerminator))),
  method: 'GET',
  path: '/orders',
  validators: [isAuthenticated(), some(checkIdentityType(['admin']), isSelf(['params', 'requestQuery', 'identityId']))],
});

updateOrderRoute

Implementation

Endpoint: PATCH /orders/:orderId

Updates an order, rereads it, and returns the normalized result.

Access: Authenticated administrator, or an authenticated identity that owns the order.

Request: updateOrderSchema requires path orderId and an application/json body; the schema permits an empty object, but the handler rejects an empty body.

Pipeline: updateOrder → getOrderById → normalizeOrderTerminator.

Success: Default Express JSON behavior produces 200 with the updated order, without _id.

Failure: updateOrder reports missing ID or body (400), no matching order (404), no modification (400), and database failure (500); the reread and normalizer have their documented 400/404/500 behavior.

View complete source

export const updateOrderRoute = withRoute({
  handler: compose(
    withLogging(updateOrder),
    flatMapAsync(withLogging(getOrderById)),
    lift(withLogging(normalizeOrderTerminator)),
  ),
  method: 'PATCH',
  path: '/orders/:orderId',
  validators: [
    isAuthenticated(),
    some(checkIdentityType(['admin']), ownsOrder(['params', 'requestParams', 'orderId'])),
  ],
});

deleteOrderRoute

Implementation

Endpoint: DELETE /orders/:orderId

Deletes one order.

Access: Authenticated administrator, or an authenticated identity that owns the order.

Request: deleteOrderSchema requires path orderId; there is no request body.

Pipeline: deleteOrder → deleteOrderTerminator.

Success: 204; its descriptor has no data, so the service calls res.status(204).json(undefined).

Failure: The delete handler reports missing ID (400), an absent order (404), or deletion/database failure (500); the terminator throws 500 if the deletion flag is absent.

View complete source

export const deleteOrderRoute = withRoute({
  handler: compose(withLogging(deleteOrder), lift(withLogging(deleteOrderTerminator))),
  method: 'DELETE',
  path: '/orders/:orderId',
  validators: [
    isAuthenticated(),
    some(checkIdentityType(['admin']), ownsOrder(['params', 'requestParams', 'orderId'])),
  ],
});

findOrdersByOrganizationIdRoute

Implementation

Endpoint: GET /orders/organizations/:organizationId

Finds paginated orders for one organization through the reusable database block path.

Access: Authenticated identity with owner, admin, or member role in the path organization.

Request: findByOrganizationIdSchema requires organizationId and validates its pagination query parameters.

Pipeline: buildOrganizationIdFilter → buildWithoutMongoIdFindOptions → findOrders → applySpec(...) → orThrow(...). The block lookup is wrapped in pagination and logging.

Success: Default Express JSON behavior produces 200 with { data, metadata: { pagination } }. buildWithoutMongoIdFindOptions removes _id in the database projection.

Failure: orThrow maps an OrderDbBlockError from the block to 500; validator failures occur before this pipeline.

View complete source

export const findOrdersByOrganizationIdRoute = withRoute({
  handler: compose(
    withLogging(applyPayloadArgs(buildOrganizationIdFilter, [['params', 'requestParams', 'organizationId']], 'filter')),
    flatMapAsync(withLogging(applyPayloadArgs(buildWithoutMongoIdFindOptions, [], 'options'))),
    flatMapAsync(
      withPagination(
        withLogging(
          applyPayloadArgs(
            findOrders,
            [
              ['context', 'db', 'orders'],
              ['context', 'data', 'filter'],
              ['context', 'data', 'options'],
            ],
            'paginatedOrders',
          ),
        ),
      ),
    ),
    flatMapAsync(
      applyPayloadArgs(
        applySpec({data: nthArg(0), metadata: {pagination: nthArg(1)}}),
        [
          ['context', 'data', 'paginatedOrders', 'data'],
          ['context', 'data', 'paginatedOrders', 'metadata'],
        ],
        'normalizedBody',
      ),
    ),
    lift(withLogging(orThrow([[OrderDbBlockError, 500]], [['context', 'data', 'normalizedBody']]))),
  ),
  method: 'GET',
  path: '/orders/organizations/:organizationId',
  validators: [
    isAuthenticated(),
    hasOrgRole(['owner', 'admin', 'member'], ['params', 'requestParams', 'organizationId']),
  ],
});