Litelead-mcp

getOrderStatus Tool

Overview

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

Important: orderId is the human-facing numeric ID stored as a field on the order document — not the Firestore document ID. If you have a Firestore document ID, use getOrderById instead.

Location

tools/getOrderStatus.js

Description

Retrieves essential status information for an order by querying the Orders collection where orderId == <number>. This is a lightweight alternative to getOrderById when you only need status information and you only know the numeric orderId.

Input Schema

{
  orderId: number;  // REQUIRED: Numeric sequential orderId (NOT the Firestore document ID)
}

Parameters

Parameter Type Required Default Description
orderId integer Yes - Numeric sequential orderId (the human-facing ID). Use getOrderById if you have a Firestore document ID.

Output Schema

{
  status: OrderStatus | ErrorStatus;
}

OrderStatus Object (Success)

{
  orderId: number;          // The numeric orderId
  stage: number | null;     // Current stage/status number (null if unset)
  closed: boolean;          // Whether the order is closed
  title: string;            // Order title (empty string if unset)
}

ErrorStatus Object (Not Found)

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

Usage Examples

Basic Usage

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

if (result.status.error) {
  console.log(result.status.message);  // "Order 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 the Firestore document ID:

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

Data Extraction

Returns only essential status fields, with safe defaults for missing data:

return {
  status: {
    orderId: data.orderId,
    stage: data.stage ?? null,
    closed: !!data.closed,
    title: data.title || "",
  },
};

Validation

The tool uses the Zod inputSchema to validate that orderId is provided as an integer. Missing or non-integer values will throw a ZodError.

Not Found Handling

Returns a structured error response when no order matches the given orderId:

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

Error Handling

Common Errors

Error Cause Solution
ZodError (orderId required / not an integer) Missing or non-numeric orderId Provide a numeric integer orderId in params
Failed to fetch order status: ... 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 1234 not found"
  }
}

Error Response

Firestore errors are logged via the project logger and re-thrown:

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

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