http.ts

packages/bitrix-client/src/http.ts

1. /**
2. * Bitrix24 REST client.
3. *
4. * Bitrix has TWO independent limits with inverted-looking error codes. Getting
5. * them confused means retrying the wrong way, so they are handled separately
6. * here and nowhere else.
7. *
8. * 503 + QUERY_LIMIT_EXCEEDED request rate (leaky bucket)
9. * -> global backoff, slow down everything
10. * 429 + OPERATION_TIME_LIMIT accumulated execution time for ONE method
11. * -> suspend that method only, until operating_reset_at
12. *
13. * Note 503 is the rate limit and 429 is not. Ninety uses those codes the
14. * other way round, so its status handling must not be copied here.
15. */
17. import { TokenBucket, backoffMs, sleep } from '@meridian/shared'
19. export interface BitrixOptions {
20. /** Inbound webhook base, e.g. https://acme.bitrix24.com/rest/1/abc123/ */
21. webhookUrl: string
22. /**
23. * Requests per second. Tariff allows 2/s sustained (5 on Enterprise) with a
24. * burst of 50. Default matches the house 7-per-8-seconds used by the Bitrix
25. * MCP connector: deliberately conservative, and low enough that the cron and
26. * the MCP server together stay under the shared quota.
27. */
28. rps?: number
29. /** Burst capacity. Tariff allows 50; we stay well under. */
30. burst?: number
31. maxRetries?: number
32. fetchImpl?: typeof fetch
33. sleep?: (ms: number) => Promise<void>
34. debug?: boolean
35. }
37. export interface BitrixResponse<T> {
38. result: T
39. total?: number
40. next?: number
41. time?: { operating?: number; operating_reset_at?: number }
42. }
44. export class BitrixError extends Error {
45. constructor(
46. message: string,
47. readonly code: string | null,
48. readonly status: number | undefined,
49. readonly method: string,
50. ) {
51. super(`${message} [${method}]`)
52. this.name = 'BitrixError'
53. }
54. }
56. export class BitrixRateLimitError extends BitrixError {
57. constructor(method: string) {
58. super('Request rate limit (503 QUERY_LIMIT_EXCEEDED). Slow down.', 'QUERY_LIMIT_EXCEEDED', 503, method)
59. this.name = 'BitrixRateLimitError'
60. }
61. }
63. export class BitrixOperationTimeError extends BitrixError {
64. constructor(method: string, readonly resetAt: number | null) {
65. super(
66. `Method execution-time limit (429 OPERATION_TIME_LIMIT). This method is suspended; ` +
67. `other methods still work.${resetAt ? ` Retry after ${new Date(resetAt * 1000).toLocaleString('en-US', { timeZone: 'America/Chicago' })} CT.` : ''}`,
68. 'OPERATION_TIME_LIMIT',
69. 429,
70. method,
71. )
72. this.name = 'BitrixOperationTimeError'
73. }
74. }
76. export class BitrixClient {
77. private readonly base: string
78. private readonly limiter: TokenBucket
79. private readonly maxRetries: number
80. private readonly fetchImpl: typeof fetch
81. private readonly sleep: (ms: number) => Promise<void>
82. private readonly debug: boolean
83. /** method -> unix seconds until which it is suspended by OPERATION_TIME_LIMIT. */
84. private readonly suspended = new Map<string, number>()
85. /** Last reported accumulated execution time, for proactive backoff. */
86. lastOperating = 0
88. constructor(opts: BitrixOptions) {
89. if (!opts.webhookUrl) {
90. throw new Error('BITRIX_WEBHOOK_URL is not set. Expected https://<domain>/rest/<user>/<key>/')
91. }
92. this.base = opts.webhookUrl.endsWith('/') ? opts.webhookUrl : `${opts.webhookUrl}/`
93. const rps = opts.rps ?? 7 / 8
94. this.limiter = new TokenBucket(opts.burst ?? 7, rps)
95. this.maxRetries = opts.maxRetries ?? 3
96. this.fetchImpl = opts.fetchImpl ?? globalThis.fetch.bind(globalThis)
97. this.sleep = opts.sleep ?? sleep
98. this.debug = opts.debug ?? false
99. }
101. async call<T = unknown>(method: string, params: Record<string, unknown> = {}): Promise<BitrixResponse<T>> {
102. const until = this.suspended.get(method)
103. if (until && Date.now() / 1000 < until) {
104. throw new BitrixOperationTimeError(method, until)
105. }
107. for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
108. await this.limiter.acquire()
109. if (this.debug) console.error(`[bitrix] ${method}${attempt ? ` retry=${attempt}` : ''}`)
111. const res = await this.fetchImpl(`${this.base}${method}.json`, {
112. method: 'POST',
113. headers: { 'Content-Type': 'application/json' },
114. body: JSON.stringify(params),
115. })
117. let body: unknown
118. try {
119. body = await res.json()
120. } catch {
121. throw new BitrixError(`Non-JSON response (${res.status})`, null, res.status, method)
122. }
124. const err = body as { error?: string; error_description?: string }
126. // 503: request-rate limit. Global problem; back off and retry.
127. if (res.status === 503 || err.error === 'QUERY_LIMIT_EXCEEDED') {
128. if (attempt < this.maxRetries) {
129. await this.sleep(backoffMs(attempt))
130. continue
131. }
132. throw new BitrixRateLimitError(method)
133. }
135. // 429: execution-time limit for THIS method. Retrying now cannot help.
136. if (res.status === 429 || err.error === 'OPERATION_TIME_LIMIT') {
137. const t = body as BitrixResponse<never>
138. const resetAt = t.time?.operating_reset_at ?? null
139. if (resetAt) this.suspended.set(method, resetAt)
140. throw new BitrixOperationTimeError(method, resetAt)
141. }
143. if (err.error) {
144. throw new BitrixError(err.error_description ?? err.error, err.error, res.status, method)
145. }
147. const ok = body as BitrixResponse<T>
148. if (typeof ok.time?.operating === 'number') this.lastOperating = ok.time.operating
149. return ok
150. }
152. throw new BitrixRateLimitError(method)
153. }
155. /**
156. * Page a *.list method to completion, or to the cap.
157. *
158. * Uses `start` offsets. The open-lead count is far larger than the working
159. * pipeline suggests: the email-to-lead automation turns security alerts,
160. * call logs and website chats into leads that nobody closes, so a sweep can
161. * run past the page cap.
162. *
163. * Hitting the cap does not throw. Throwing would discard every row already
164. * fetched and render the whole source as failed; truncated and labelled
165. * beats absent (rule 5). The caller must check `truncated` and say so, since
166. * a silently capped list is a count that is quietly wrong.
167. */
168. async listAll<T = unknown>(
169. method: string,
170. params: Record<string, unknown> = {},
171. maxPages = 50,
172. ): Promise<{ items: T[]; truncated: boolean; pages: number }> {
173. const out: T[] = []
174. let start = 0
175. for (let i = 0; i < maxPages; i++) {
176. const page = await this.call<T[]>(method, { ...params, start })
177. const items = Array.isArray(page.result) ? page.result : []
178. out.push(...items)
179. if (page.next === undefined || items.length === 0) {
180. return { items: out, truncated: false, pages: i + 1 }
181. }
182. start = page.next
183. }
184. return { items: out, truncated: true, pages: maxPages }
185. }
186. }