Litelead-mcp

getCustomerById Tool

Overview

The getCustomerById tool retrieves a single customer record by its document ID from the Firebase/Firestore database.

Location

tools/getCustomerById.js

Description

Retrieves a specific customer by document ID. The customer is retrieved from the Firestore path: /Accounts/{accountId}/Customers/{customerId}.

Input Schema

{
  customerId: string;  // REQUIRED: Customer document ID
}

Parameters

Parameter Type Required Default Description
customerId string Yes - Firestore document ID of the customer

Output Schema

{
  customer: Customer | null;
}

Customer Object

{
  id: string;                    // Firestore document ID
  path: string;                  // Full Firestore path
  address: string;               // Customer address
  city: string;                  // City
  country: string;               // Country
  createdAt: string | Date;      // Creation timestamp (converted to locale string)
  createdBy: string;             // Creator user ID
  customerId: number;            // Unique customer ID
  metadata: Record<string, any>; // Additional metadata
  name: string;                  // Customer name
  ownedBy: string;               // Owner user ID
  zip: string;                   // Postal code
}

Usage Examples

Basic Usage

// Get a specific customer by ID
const result = await getCustomerById(context, {
  customerId: "abc123"
});

if (result.customer) {
  console.log(result.customer.name);     // Customer name
  console.log(result.customer.email);    // Customer email
} else {
  console.log("Customer not found");
}

Checking if Customer Exists

const result = await getCustomerById(context, {
  customerId: "abc123"
});

if (result.customer === null) {
  console.log("Customer does not exist");
}

Implementation Details

Data Transformation

The tool transforms the Firestore document by:

  1. Adding the document id and full path
  2. Converting createdAt timestamp to locale string (de-DE format)
  3. Preserving all other fields as-is
const data = docSnap.data();
return {
  customer: {
    id: docSnap.id,
    path: docSnap.ref.path,
    ...data,
    createdAt: safeToLocaleString(data.createdAt) || data.createdAt,
  },
};

Validation

The tool validates that customerId is provided:

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

Not Found Handling

If the customer document doesn’t exist, the tool returns { customer: null } instead of throwing an error.

Error Handling

Common Errors

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

Error Response

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

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

Performance Considerations

  1. Direct Document Access: Uses getDoc() for efficient single document retrieval
  2. No Pagination: This is a single-document fetch, no pagination overhead
  3. Indexed Reads: Document ID lookups are always indexed

Firestore Collection Structure

/Accounts/{accountId}/Customers/{customerId}
  - address: string
  - city: string
  - country: string
  - createdAt: timestamp
  - createdBy: string
  - customerId: number
  - metadata: object
  - name: string
  - ownedBy: string
  - zip: string

See Also