http.ts

packages/plinth-client/src/http.ts

1. /**
2. * Plinth HTTP layer.
3. *
4. * Single endpoint, method dispatched by query parameter, static token. Every
5. * guard from hazards.ts is applied here so no call site can bypass one:
6. *
7. * - method allowlist (a GET with method=orders.setStatus would write and email customers)
8. * - param allowlist (unknown params are dropped and return unfiltered results)
9. * - 9-per-10s throttle (documented limit is 10/10s; one request of headroom)
10. * - ambiguous errors ("Invalid request" means no rows or bad request; never retry it)
11. */
13. import { TokenBucket, sleep } from '@meridian/shared'
14. import {
15. assertKnownParams,
16. assertReadMethod,
17. isEmptyOrInvalid,
18. readError,
19. type ReadMethod,
20. } from './hazards.js'
21. import { PLINTH_BASE_URL, PLINTH_RATE_LIMIT } from './constants.js'
23. export interface PlinthOptions {
24. token: string
25. baseUrl?: string
26. maxRetries?: number
27. fetchImpl?: typeof fetch
28. sleep?: (ms: number) => Promise<void>
29. debug?: boolean
30. }
32. export class PlinthError extends Error {
33. constructor(message: string, readonly method: string, readonly status?: number) {
34. super(`${message} [${method}]`)
35. this.name = 'PlinthError'
36. }
37. }
39. /** Rate limiting is transient here and should be retried, unlike "Invalid request". */
40. export class PlinthRateLimitError extends PlinthError {
41. constructor(method: string) {
42. super('Plinth rate limit exceeded. Throttle is 9 per 10 seconds; something is calling faster.', method, 429)
43. this.name = 'PlinthRateLimitError'
44. }
45. }
47. export class PlinthClient {
48. private readonly token: string
49. private readonly baseUrl: string
50. private readonly limiter: TokenBucket
51. private readonly maxRetries: number
52. private readonly fetchImpl: typeof fetch
53. private readonly sleep: (ms: number) => Promise<void>
54. private readonly debug: boolean
56. constructor(opts: PlinthOptions) {
57. if (!opts.token) throw new Error('PLINTH_API_KEY is not set.')
58. this.token = opts.token
59. this.baseUrl = opts.baseUrl ?? PLINTH_BASE_URL
60. this.limiter = new TokenBucket(PLINTH_RATE_LIMIT.capacity, PLINTH_RATE_LIMIT.refillPerSecond)
61. this.maxRetries = opts.maxRetries ?? 3
62. this.fetchImpl = opts.fetchImpl ?? globalThis.fetch.bind(globalThis)
63. this.sleep = opts.sleep ?? sleep
64. this.debug = opts.debug ?? false
65. }
67. /**
68. * Returns the parsed body, or null when Plinth reports the ambiguous
69. * "Invalid request", which means no rows, a bad request, or both, and cannot be
70. * told apart. Callers treat null as empty and must not retry.
71. */
72. async call<T = unknown>(
73. method: ReadMethod,
74. params: Record<string, string | number | undefined> = {},
75. allowedParams: readonly string[] = [],
76. ): Promise<T | null> {
77. assertReadMethod(method)
78. if (allowedParams.length) assertKnownParams(method, params, allowedParams)
80. const url = new URL(this.baseUrl)
81. url.searchParams.set('api_key', this.token)
82. url.searchParams.set('method', method)
83. for (const [k, v] of Object.entries(params)) {
84. if (v !== undefined) url.searchParams.set(k, String(v))
85. }
87. for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
88. await this.limiter.acquire()
89. if (this.debug) console.error(`[plinth] ${method}${attempt ? ` retry=${attempt}` : ''}`)
91. const res = await this.fetchImpl(url.toString(), { headers: { Accept: 'application/json' } })
92. let body: unknown
93. try {
94. body = await res.json()
95. } catch {
96. throw new PlinthError(`Non-JSON response (${res.status})`, method, res.status)
97. }
99. const err = readError(body)
101. if (err?.startsWith('Too many requests')) {
102. if (attempt < this.maxRetries) {
103. await this.sleep(10_000)
104. continue
105. }
106. throw new PlinthRateLimitError(method)
107. }
109. // Ambiguous by design. Never retried: a retry cannot turn "no rows" into rows.
110. if (isEmptyOrInvalid(body)) return null
112. if (err) throw new PlinthError(err, method, res.status)
113. return body as T
114. }
116. throw new PlinthRateLimitError(method)
117. }
118. }