Litelead-mcp

getOrderStatus Tool

Overview

The getOrderStatus tool retrieves the current status information for a specific order by its numeric order ID from the Firebase/Firestore database.

Location

tools/getOrderStatus.js

Description

Retrieves essential status information for an order by searching for it using the orderId field (not the document ID). This is a lightweight alternative to getOrderById when you only need status information.

Input Schema

{
  orderId: number;  // REQUIRED: Numeric order ID (not document ID)
}

Parameters

Parameter Type Required Default Description
orderId number Yes - Numeric order ID to search for

Output Schema

{
  status: OrderStatus | ErrorStatus;
}

OrderStatus Object (Success)

{
  orderId: number;     // The order ID
  stage: number;       // Current stage/status number
  closed: boolean;     // Whether the order is closed
  title: string;       // Order title
}

ErrorStatus Object (Not Found)

{
  error: "not-found";
  message: string;     // Error message
}

Usage Examples

Basic Usage

// Get status for order with ID 1234
const result = await getOrderStatus(context, {
  orderId: 1234
});

if (result.status.error) {
  console.log(result.status.message);  // "Order with ID 1234 not found."
} else {
  console.log(`Order #${result.status.orderId}: ${result.status.title}`);
  console.log(`Stage: ${result.status.stage}`);
  console.log(`Closed: ${result.status.closed}`);
}

Checking if Order is Closed

const result = await getOrderStatus(context, {
  orderId: 1234
});

if (!result.status.error && result.status.closed) {
  console.log("This order is closed");
} else if (!result.status.error) {
  console.log(`Order is open, currently at stage ${result.status.stage}`);
}

Error Handling Example

const result = await getOrderStatus(context, {
  orderId: 9999
});

if (result.status.error === "not-found") {
  console.log("Order does not exist");
} else {
  console.log("Order found:", result.status);
}

Implementation Details

Query Method

Unlike getOrderById, this tool searches by the orderId field rather than document ID:

const ordersRef = collection(db, "Accounts", accountId, "Orders");
const q = query(ordersRef, where("orderId", "==", Number(orderId)));
const snapshot = await getDocs(q);

Data Extraction

Returns only essential status fields:

return {
  status: {
    orderId: orderData.orderId,
    stage: orderData.stage,
    closed: orderData.closed,
    title: orderData.title,
  },
};

Validation

The tool validates that orderId is provided:

if (orderId === undefined || orderId === null) {
  throw new Error("The 'orderId' parameter is required.");
}

Not Found Handling

Returns a structured error response when order is not found:

if (snapshot.empty) {
  return {
    status: {
      error: "not-found",
      message: `Order with ID ${orderId} not found.`,
    },
  };
}

Error Handling

Common Errors

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

Not Found Response

When an order is not found, the tool returns a structured error object instead of throwing:

{
  status: {
    error: "not-found",
    message: "Order with ID 1234 not found."
  }
}

Error Response

Firestore errors are logged and re-thrown:

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

Performance Considerations

  1. Lightweight Query: Only returns 4 essential fields, much faster than full order fetch
  2. Indexed Field: Queries by orderId field which should be indexed in production
  3. No Reference Population: Does not fetch related customer, contact, or staff data
  4. Use Case: Ideal for status checks, dashboards, or when full order details aren’t needed

When to Use

Use getOrderStatus when:

Use getOrderById when:

Firestore Collection Structure

/Accounts/{accountId}/Orders/{documentId}
  - orderId: number (queried field)
  - stage: number
  - closed: boolean
  - title: string
  - ... other fields

See Also