http.ts

packages/ninety-client/src/http.ts

1. /**
2. * HTTP layer: bearer auth, rate limiting, retry, and error mapping.
3. *
4. * Uses global fetch only. No Node built-ins, so this runs unchanged in a
5. * Cloudflare Worker, in Node 20+, and in vitest.
6. */
8. import {
9. NinetyAuthError,
10. NinetyError,
11. NinetyForbiddenError,
12. NinetyRateLimitError,
13. type NinetyErrorContext,
14. } from './errors.js'
15. import { TokenBucket, backoffMs, sleep } from '@meridian/shared'
17. export interface HttpOptions {
18. token: string
19. baseUrl?: string
20. /**
21. * Requests per second. Ninety documents 25 per user; the default is 20 so a
22. * burst at the start of a sync does not trip 429 and turn a fast job slow.
23. */
24. rps?: number
25. maxRetries?: number
26. /** Injectable for tests and for Workers. */
27. fetchImpl?: typeof fetch
28. sleep?: (ms: number) => Promise<void>
29. debug?: boolean
30. }
32. export interface RequestOptions {
33. body?: unknown
34. query?: Record<string, string | number | boolean | undefined>
35. /** Included in error messages so a failure names its page. */
36. pageIndex?: number
37. signal?: AbortSignal
38. }
40. const DEFAULT_BASE_URL = 'https://api.public.ninety.io/v1'
41. /** Retry jitter, so parallel workers do not resynchronize. */
42. const JITTER_MS = 250
44. export class HttpClient {
45. private readonly token: string
46. private readonly baseUrl: string
47. private readonly limiter: TokenBucket
48. private readonly maxRetries: number
49. private readonly fetchImpl: typeof fetch
50. private readonly sleep: (ms: number) => Promise<void>
51. private readonly debug: boolean
53. constructor(opts: HttpOptions) {
54. if (!opts.token) {
55. throw new Error(
56. 'NINETY_TOKEN is missing. Generate a Personal Access Token at ' +
57. 'Ninety > User Settings > Developer Settings.',
58. )
59. }
60. this.token = opts.token
61. this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '')
62. const rps = opts.rps ?? 20
63. this.limiter = new TokenBucket(rps, rps)
64. this.maxRetries = opts.maxRetries ?? 3
65. this.fetchImpl = opts.fetchImpl ?? globalThis.fetch.bind(globalThis)
66. this.sleep = opts.sleep ?? sleep
67. this.debug = opts.debug ?? false
68. }
70. async get<T = unknown>(path: string, opts: RequestOptions = {}): Promise<T> {
71. return this.request<T>('GET', path, opts)
72. }
74. /** Note: Ninety's list endpoints are POST /{resource}/query, not GET. */
75. async post<T = unknown>(path: string, opts: RequestOptions = {}): Promise<T> {
76. return this.request<T>('POST', path, opts)
77. }
79. async request<T = unknown>(method: string, path: string, opts: RequestOptions = {}): Promise<T> {
80. const url = this.buildUrl(path, opts.query)
81. const ctx: NinetyErrorContext = { endpoint: `${method} ${path}` }
82. if (opts.pageIndex !== undefined) ctx.pageIndex = opts.pageIndex
84. let lastRetryAfter: number | undefined
86. for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
87. await this.limiter.acquire()
89. if (this.debug) {
90. console.error(`[ninety] ${method} ${path}${opts.pageIndex !== undefined ? ` page=${opts.pageIndex}` : ''}${attempt > 0 ? ` retry=${attempt}` : ''}`)
91. }
93. let res: Response
94. try {
95. const init: RequestInit = {
96. method,
97. headers: {
98. Authorization: `Bearer ${this.token}`,
99. Accept: 'application/json',
100. ...(opts.body !== undefined ? { 'Content-Type': 'application/json' } : {}),
101. },
102. ...(opts.body !== undefined ? { body: JSON.stringify(opts.body) } : {}),
103. ...(opts.signal ? { signal: opts.signal } : {}),
104. }
105. res = await this.fetchImpl(url, init)
106. } catch (cause) {
107. // Network-level failure. Retry, then give up with context.
108. if (attempt < this.maxRetries) {
109. await this.sleep(backoffMs(attempt, JITTER_MS))
110. continue
111. }
112. throw new NinetyError(`Network error reaching Ninety: ${String(cause)}`, ctx)
113. }
115. if (res.ok) {
116. if (res.status === 204) return undefined as T
117. try {
118. return (await res.json()) as T
119. } catch (cause) {
120. throw new NinetyError(`Ninety returned a non-JSON body: ${String(cause)}`, ctx, res.status)
121. }
122. }
124. // 429 and 5xx are retryable. Everything else is not.
125. if (res.status === 429) {
126. lastRetryAfter = parseRetryAfter(res.headers.get('Retry-After'))
127. if (attempt < this.maxRetries) {
128. await this.sleep(lastRetryAfter ?? backoffMs(attempt, JITTER_MS))
129. continue
130. }
131. throw new NinetyRateLimitError(ctx, lastRetryAfter)
132. }
134. if (res.status >= 500 && attempt < this.maxRetries) {
135. await this.sleep(backoffMs(attempt, JITTER_MS))
136. continue
137. }
139. ctx.body = truncate(await safeText(res), 500)
140. if (res.status === 401) throw new NinetyAuthError(ctx)
141. if (res.status === 403) throw new NinetyForbiddenError(ctx)
142. throw new NinetyError(`Ninety returned ${res.status} ${res.statusText}`, ctx, res.status)
143. }
145. // Unreachable: every path above either returns or throws.
146. throw new NinetyError('Exhausted retries', ctx)
147. }
149. private buildUrl(path: string, query?: RequestOptions['query']): string {
150. const url = new URL(`${this.baseUrl}${path.startsWith('/') ? path : `/${path}`}`)
151. if (query) {
152. for (const [k, v] of Object.entries(query)) {
153. if (v !== undefined) url.searchParams.set(k, String(v))
154. }
155. }
156. return url.toString()
157. }
158. }
160. function parseRetryAfter(header: string | null): number | undefined {
161. if (!header) return undefined
162. const seconds = Number(header)
163. if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000)
164. const date = Date.parse(header)
165. if (Number.isFinite(date)) return Math.max(0, date - Date.now())
166. return undefined
167. }
169. async function safeText(res: Response): Promise<string> {
170. try {
171. return await res.text()
172. } catch {
173. return '<unreadable body>'
174. }
175. }
177. function truncate(s: string, n: number): string {
178. return s.length <= n ? s : `${s.slice(0, n)}...`
179. }