orders-pagination.test.ts

packages/plinth-client/test/orders-pagination.test.ts

1. /**
2. * Plinth pagination counts product lines, not orders.
3. *
4. * `limit` and `offset` on orders.fetch are measured in product lines. Against
5. * the live API:
6. *
7. * limit=100 offset=0 -> 61 orders, 100 lines
8. * limit=100 offset=100 -> 57 orders, 100 lines
9. * limit=500 offset=0 -> 297 orders, 500 lines
10. *
11. * A loop that stops on `batch.length < limit`, comparing orders against a line
12. * budget, stops after the first page every time. Because Plinth returns orders
13. * oldest first, the surviving slice is the oldest days of the window, mostly
14. * terminal, with the design queue reading zero: nothing looks broken, and the
15. * board describes a different fortnight while labelling it as this one.
16. *
17. * These tests count in the unit the API counts in. A fake that returned a page
18. * of orders rather than a page of lines would let that mistake pass, so the
19. * fakes below deliberately model many-lines-per-order.
20. */
22. import { describe, expect, it } from 'vitest'
23. import { OrdersResource } from '../src/resources/orders.js'
24. import type { PlinthClient } from '../src/http.js'
26. /** One order carrying `lines` product rows. */
27. function order(id: number, lines: number) {
28. const product: Record<string, unknown> = {}
29. for (let i = 0; i < lines; i++) {
30. product[String(i)] = {
31. line_ref: id * 100 + i,
32. item_ref: 1,
33. item_name: 'Mesh Banner',
34. qty: 1,
35. unit_price: '10.00',
36. line_status: 'Delivered',
37. }
38. }
39. return {
40. order_ref: id,
41. status_label: 'Delivered',
42. status_code: 189,
43. closed_on: '2026-07-01 10:00:00',
44. first_name: 'A',
45. last_name: 'B',
46. grand_total: '10.00',
47. lines: product,
48. }
49. }
51. /** Builds a page holding exactly `lines` product rows, spread over few orders. */
52. function pageOfLines(startId: number, lines: number, linesPerOrder = 5) {
53. const order_map: Record<string, unknown> = {}
54. let made = 0
55. let id = startId
56. while (made < lines) {
57. const n = Math.min(linesPerOrder, lines - made)
58. order_map[String(id)] = order(id, n)
59. made += n
60. id++
61. }
62. return { order_map }
63. }
65. /** Records the params of every call and replays scripted pages. */
66. function fake(pages: unknown[]) {
67. const calls: Record<string, unknown>[] = []
68. const client = {
69. async call(_m: string, params: Record<string, unknown>) {
70. calls.push(params)
71. return pages[calls.length - 1] ?? { order_map: {} }
72. },
73. } as unknown as PlinthClient
74. return { client, calls }
75. }
77. describe('the page break compares lines, not orders', () => {
78. it('keeps paging when a full page of lines came back from few orders', async () => {
79. // 100 lines across 20 orders. The old condition (20 orders < 100) stopped
80. // here and returned a twelfth of the window.
81. const { client, calls } = fake([
82. pageOfLines(1, 100),
83. pageOfLines(100, 100),
84. pageOfLines(200, 30), // short in lines -> genuine end
85. ])
86. const res = await new OrdersResource(client).linesInWindow(
87. '2026-06-26', '2026-08-25', 100,
88. )
89. expect(calls).toHaveLength(3)
90. expect(res.lines).toHaveLength(230)
91. expect(res.pages).toBe(3)
92. expect(res.truncated).toBe(false)
93. })
95. it('stops on the first page only when that page is short in LINES', async () => {
96. const { client, calls } = fake([pageOfLines(1, 40)])
97. const res = await new OrdersResource(client).linesInWindow(
98. '2026-06-26', '2026-08-25', 100,
99. )
100. expect(calls).toHaveLength(1)
101. expect(res.lines).toHaveLength(40)
102. expect(res.truncated).toBe(false)
103. })
105. it('does not stop on a page of exactly limit lines held by one order', async () => {
106. // The pathological shape: 1 order, 100 lines. Counting orders, 1 < 100.
107. const { client, calls } = fake([
108. { order_map: { '1': order(1, 100) } },
109. pageOfLines(2, 10),
110. ])
111. const res = await new OrdersResource(client).linesInWindow(
112. '2026-06-26', '2026-08-25', 100,
113. )
114. expect(calls).toHaveLength(2)
115. expect(res.lines).toHaveLength(110)
116. })
118. it('advances offset by the line limit, not by the order count', async () => {
119. const { client, calls } = fake([
120. pageOfLines(1, 100),
121. pageOfLines(100, 100),
122. pageOfLines(200, 1),
123. ])
124. await new OrdersResource(client).linesInWindow('2026-06-26', '2026-08-25', 100)
125. expect(calls.map((c) => c.offset)).toEqual([0, 100, 200])
126. expect(calls.map((c) => c.limit)).toEqual([100, 100, 100])
127. })
128. })
130. describe('a capped sweep says so', () => {
131. it('reports truncated when maxPages runs out before a short page', async () => {
132. // Every page full: the window is wider than this can fetch. The counts are a
133. // floor, and the caller has to be able to know that.
134. const { client } = fake([pageOfLines(1, 50), pageOfLines(50, 50), pageOfLines(100, 50)])
135. const res = await new OrdersResource(client).linesInWindow(
136. '2026-06-26', '2026-08-25', 50, 3,
137. )
138. expect(res.pages).toBe(3)
139. expect(res.truncated).toBe(true)
140. })
142. it('reports not-truncated when it reached the end of the window', async () => {
143. const { client } = fake([pageOfLines(1, 50), pageOfLines(50, 20)])
144. const res = await new OrdersResource(client).linesInWindow(
145. '2026-06-26', '2026-08-25', 50, 3,
146. )
147. expect(res.truncated).toBe(false)
148. })
150. it('treats an empty first page as a complete empty window, not a truncated one', async () => {
151. // Plinth returns null for "Invalid request", which is also how it says zero
152. // results. Zero and truncated must not look the same.
153. const { client } = fake([{ order_map: undefined }])
154. const res = await new OrdersResource(client).linesInWindow('2026-06-26', '2026-08-25')
155. expect(res.lines).toEqual([])
156. expect(res.truncated).toBe(false)
157. expect(res.pages).toBe(1)
158. })
159. })
161. describe('the window it actually asks for', () => {
162. it('sends the dates it was given, converted to Plinth format', async () => {
163. const { client, calls } = fake([pageOfLines(1, 1)])
164. await new OrdersResource(client).linesInWindow('2026-06-26', '2026-08-25')
165. // toPlinthDate turns ISO into yyyymmdd; assert the shape, not the algorithm.
166. expect(String(calls[0]!.since)).toMatch(/^\d{8}$/)
167. expect(String(calls[0]!.until)).toMatch(/^\d{8}$/)
168. })
170. it('defaults to a limit that fetches a 60-day window in few calls', async () => {
171. // 60 days is ~780 lines live. At a page size of 100 that is 8 requests
172. // against a 10-per-10-second rate limit.
173. const { client, calls } = fake([pageOfLines(1, 10)])
174. await new OrdersResource(client).linesInWindow('2026-06-26', '2026-08-25')
175. expect(Number(calls[0]!.limit)).toBeGreaterThanOrEqual(500)
176. })
177. })