Litelead-mcp

getOrderById Tool

Overview

The getOrderById tool retrieves a single order record by its document ID from the Firebase/Firestore database, with automatic population of related customer, contact, and staff references.

Location

tools/getOrderById.js

Description

Retrieves a specific order by document ID with all related references populated. The order is retrieved from the Firestore path: /Accounts/{accountId}/Orders/{orderId}, and the tool automatically fetches and includes the referenced customer, contact, technician, and responsible staff documents.

Input Schema

{
  orderId: string;  // REQUIRED: Order document ID
}

Parameters

Parameter Type Required Default Description
orderId string Yes - Firestore document ID of the order

Output Schema

{
  order: Order | null;
}

Order Object

{
  id: string;                        // Firestore document ID
  path: string;                      // Full Firestore path
  orderId: number;                   // Unique order ID
  title: string;                     // Order title
  description: string;               // Order description
  stage: number;                     // Order stage/status number
  closed: boolean;                   // Whether order is closed
  createdAt: string | Date;          // Creation timestamp (locale string)
  lastCommentAt: string | Date;      // Last comment timestamp (locale string)
  deadline?: string | Date;          // Deadline (locale string)
  customer: Customer | null;         // Populated customer object
  contact: Contact | null;           // Populated contact object
  technician_staff: Staff | null;    // Populated technician staff object
  responsible_staff: Staff | null;   // Populated responsible staff object
  // ... other order fields
}

Populated Reference Objects

The following references are automatically fetched and populated:

Usage Examples

Basic Usage

// Get a specific order by ID with all references populated
const result = await getOrderById(context, {
  orderId: "order123"
});

if (result.order) {
  console.log(result.order.title);
  console.log(result.order.customer?.name);           // Customer name
  console.log(result.order.contact?.email);           // Contact email
  console.log(result.order.technician_staff?.name);   // Technician name
} else {
  console.log("Order not found");
}

const result = await getOrderById(context, {
  orderId: "order123"
});

if (result.order) {
  // Access order details
  console.log(`Order #${result.order.orderId}: ${result.order.title}`);
  console.log(`Stage: ${result.order.stage}, Closed: ${result.order.closed}`);

  // Access customer information
  if (result.order.customer) {
    console.log(`Customer: ${result.order.customer.name}`);
    console.log(`Address: ${result.order.customer.address}, ${result.order.customer.city}`);
  }

  // Access contact information
  if (result.order.contact) {
    console.log(`Contact: ${result.order.contact.firstName} ${result.order.contact.lastName}`);
    console.log(`Email: ${result.order.contact.email}`);
  }

  // Access staff information
  if (result.order.technician_staff) {
    console.log(`Technician: ${result.order.technician_staff.name}`);
  }
}

Implementation Details

Reference Population

The tool automatically populates related documents:

// Fetch the main order document
const orderDoc = await getDocumentById(db, `Accounts/${accountId}/Orders`, orderId);

// Populate referenced documents
const customer = await getDocument(db, orderDoc.customer);
const contact = await getDocument(db, orderDoc.contact);
const technician = await getDocumentById(db, `Accounts/${accountId}/Staff`, orderDoc.technician_staff);
const responsible = await getDocumentById(db, `Accounts/${accountId}/Staff`, orderDoc.responsible_staff);

Data Transformation

The tool transforms the Firestore document by:

  1. Adding the document id and full path
  2. Converting timestamps to locale strings (de-DE format)
  3. Populating all reference fields with full documents
  4. Handling missing references gracefully (returns null)

Validation

The tool validates that orderId is provided:

if (!orderId) {
  throw new Error("The 'orderId' parameter is required.");
}

Not Found Handling

If the order document doesn’t exist, the tool returns { order: null }. If any referenced documents don’t exist, those fields are set to null.

Error Handling

Common Errors

Error Cause Solution
“The ‘orderId’ parameter is required.” Missing orderId Provide orderId in params
“Failed to fetch order with id [id].” Firestore error Check Firebase connection and permissions

Error Response

Errors are logged with the order ID and re-thrown:

catch (error) {
  console.error(`Error fetching order with id ${orderId}:`, error);
  throw new Error(`Failed to fetch order with id ${orderId}.`);
}

Performance Considerations

  1. Multiple Queries: This tool makes up to 5 separate Firestore reads (order + 4 potential references)
  2. Parallel Fetching: Referenced documents could be fetched in parallel for better performance
  3. Reference Existence: Missing references are handled gracefully without throwing errors
  4. Use Case: Best for detailed order views where all related data is needed

Firestore Collection Structure

/Accounts/{accountId}/Orders/{orderId}
  - orderId: number
  - title: string
  - description: string
  - stage: number
  - closed: boolean
  - createdAt: timestamp
  - lastCommentAt: timestamp
  - deadline: timestamp
  - customer: string (reference path)
  - contact: string (reference path)
  - technician_staff: string (staff ID)
  - responsible_staff: string (staff ID)

See Also