PLINTH-API.md

docs/PLINTH-API.md

1. # Plinth API reference
3. Plinth is Meridian Display Co.'s order system: orders, customers, the status
4. catalog, split shipments, products and stock. Like the company, it is
5. fictional. This is the reference the server in `mcp-server/` is written
6. against, and the one its code comments point to.
8. ## Transport
10. | Item | Value |
11. |---|---|
12. | Endpoint | `https://orders.meridiandisplay.example/api/v2/dispatch` |
13. | Style | One endpoint; the action is chosen by the `method` query parameter |
14. | HTTP method | GET for reads |
15. | Format | JSON |
16. | Environment | **Production only.** There is no sandbox; every call reads live data. |
17. | Auth | Static key in the `api_key` query parameter on every call, with global **read** scope |
18. | Rate limit | 10 requests per 10 seconds, across every caller sharing the key |
20. The key reads every customer's full record, so the API has no per-customer
21. scoping of its own. Anything that exposes its data to someone other than staff
22. has to verify identity first (see `mcp-server/src/lib/classification.ts`).
24. ## Methods
26. | Method | Kind | What it returns |
27. |---|---|---|
28. | `orders.fetch` | read | One order or a batch |
29. | `statuses.list` | read | The status catalog (a lookup table) |
30. | `customers.fetch` | read | Customer records |
31. | `orders.splitShipments` | read | Per-destination breakdown of a multi-address order |
32. | `products.fetch` | read | Product specs and turnaround (schema not yet probed) |
33. | `inventory.fetch` | read | Stock levels (schema not yet probed) |
34. | `orders.setStatus` | **write** | Changes an order's status and can email the customer |
35. | `inventory.adjust` | **write** | Changes stock levels |
37. The server never dispatches a write method; see the four-layer guard in
38. `mcp-server/src/lib/guard.ts`.
40. ## Rules that hold across methods
42. - **Request dates are `yyyymmdd`**, with no separators. ISO dates are rejected
43. with `{"error": "Bad since date"}`.
44. - **Response dates differ by method:** `orders.fetch` returns MySQL
45. `YYYY-MM-DD HH:MM:SS`; `orders.splitShipments` returns plain `YYYY-MM-DD`.
46. - **Two error shapes**, both on HTTP 200: `{"error": "…"}` and
47. `{"notice": "No match"}`. Success bodies never carry either key.
48. - **Collections switch type:** an empty one arrives as `[]`, a populated one
49. as an object keyed `"1".."N"`.
50. - **Numbers arrive as strings** in some records and as numbers in others.
51. - **Fail-open filters:** a parameter the method doesn't know is ignored, not
52. rejected, so a typo returns the unfiltered set.
53. - **One misspelled key**, `carier_name`, is part of the contract. Map it once.
55. ## Method notes
57. **`orders.fetch`**
58. - Parameters:
59. - `order_ref` (a raw integer);
60. - `ref_cmp` (`below` or `above`, relative to `order_ref`);
61. - `customer_ref`, which errors unless paired with both dates;
62. - `shop` and `subshops` (`1` to include child shops);
63. - `status_code`;
64. - `since` and `until`;
65. - `offset` and `limit` (cap 100).
66. - Response: `order_map`, with orders keyed `ord_{order_ref}`. `lines` and
67. `shipments` are ordinal-keyed.
68. - `closed_on` holds the date the order was **placed**, despite its name.
70. **`statuses.list`**
71. - Ignores every filter.
72. - `status_code` is the stable identifier and is what orders carry.
73. - The `row_N` keys are **not** stable: the catalog gained an entry and
74. reshuffled between two pulls. Map by `status_code`.
76. **`customers.fetch`**
77. - Filters on exact `email`, or on a `since`/`until` range over
78. `date_field` = `signup` (default) or `last_login`.
79. - Records are keyed `cust_{n}`.
80. - **There is no phone filter.** A phone parameter is silently dropped and the
81. full customer list comes back.
83. **`orders.splitShipments`**
84. - The only method whose top level is a bare array, one entry per destination.
85. - `{"notice": "No match"}` for a valid single-address order means "not a
86. multi-address order", not a failure.
87. - `split_lines` can be an array or an ordinal-keyed object within one
88. response.
90. ## Order numbers
92. Customers and staff quote the **display** number, which the API neither
93. accepts nor returns:
95. - **Current:** `MD` + the order's two-digit year + `order_ref`. Order 39582
96. placed in 2026 is `MD2639582`.
97. - **Legacy:** `M-` + six digits, from before Plinth. These don't map to an
98. `order_ref` by rule, so route them to a person.