getOrders.ts

mcp-server/src/tools/getOrders.ts

1. import { z } from "zod";
2. import type { ToolModule } from "./types.js";
3. import { plinthRequest, type PlinthParams } from "../lib/http.js";
4. import { toRequestDate } from "../lib/dates.js";
6. /**
7. * get_orders: retrieve one order or a batch (Plinth method `orders.fetch`).
8. *
9. * Wire notes:
10. * - `order_ref` is a RAW integer, not the MD-prefixed display number (resolve
11. * that via lib/orderNumber.ts first).
12. * - `customer_ref` ALONE errors ({"error":"Invalid request"}); it must be paired
13. * with since/until dates.
14. * - Request dates are yyyymmdd (lib/dates.ts:toRequestDate); ISO is rejected.
15. * - Response container is `order_map`, orders keyed `ord_{order_ref}`; `lines`
16. * and `shipments` are ordinal-keyed (lib/collections.ts:normalizeCollection).
17. */
18. export const getOrders: ToolModule = {
19. name: "get_orders",
20. config: {
21. title: "Get orders",
22. description:
23. "Retrieve one order or a batch, filterable by order ref, customer, shop, status, or date range. Read-only.",
24. inputSchema: {
25. orderId: z.number().int().positive().optional().describe("Raw integer order_ref (not the MD display number)."),
26. compare: z.enum(["below", "above"]).optional().describe("With orderId: orders below/above that ref."),
27. customerId: z.number().int().positive().optional().describe("Customer ref; MUST be paired with fromDate + toDate."),
28. shop: z.string().optional().describe("Shop id, e.g. '2'."),
29. includeSubshops: z.boolean().optional().describe("With shop: include its child shops (default true)."),
30. statusCode: z.string().optional().describe("Status code from get_status_catalog."),
31. fromDate: z.string().optional().describe("ISO YYYY-MM-DD; converted to yyyymmdd on the wire."),
32. toDate: z.string().optional().describe("ISO YYYY-MM-DD; converted to yyyymmdd on the wire."),
33. offset: z.number().int().min(0).optional(),
34. limit: z.number().int().min(1).max(100).optional().describe("Documented cap 100; observed default may be 50."),
35. },
36. },
37. async handler(args, ctx) {
38. const { orderId, compare, customerId, shop, includeSubshops, statusCode, fromDate, toDate, offset, limit } =
39. args as {
40. orderId?: number;
41. compare?: "below" | "above";
42. customerId?: number;
43. shop?: string;
44. includeSubshops?: boolean;
45. statusCode?: string;
46. fromDate?: string;
47. toDate?: string;
48. offset?: number;
49. limit?: number;
50. };
52. if (customerId !== undefined && (fromDate === undefined || toDate === undefined)) {
53. return {
54. content: [
55. { type: "text", text: "customerId must be combined with both fromDate and toDate (the API rejects it otherwise)." },
56. ],
57. isError: true,
58. };
59. }
61. const params: PlinthParams = {
62. order_ref: orderId,
63. ref_cmp: compare,
64. customer_ref: customerId,
65. shop,
66. subshops: shop !== undefined && includeSubshops !== undefined ? (includeSubshops ? 1 : 0) : undefined,
67. status_code: statusCode,
68. since: fromDate !== undefined ? toRequestDate(fromDate) : undefined,
69. until: toDate !== undefined ? toRequestDate(toDate) : undefined,
70. offset,
71. limit,
72. };
74. const body = await plinthRequest(ctx, "orders.fetch", params);
75. return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }] };
76. },
77. };