leads.ts

packages/bitrix-client/src/leads.ts

1. /**
2. * Open leads. Bitrix owns leads, Plinth owns orders. Bitrix's deal funnels
3. * mirror Plinth order status, so nothing here touches deals.
4. *
5. * Two things this deliberately does not do:
6. *
7. * - It does not group by `ASSIGNED_BY_ID`. Every open lead sampled belonged
8. * to one person; the field is a routing default, not a
9. * statement about who is working what. Grouping by it would put hundreds of items
10. * under one name and zero under everyone else.
11. * - It does not report a raw open count. The lead pipeline is polluted by an
12. * email-to-lead automation (SaaS security alerts, incoming-call logs,
13. * website-chat form submissions all arrive as leads), so the raw number
14. * overstates real leads. See `isLikelyNoise`.
15. */
17. import type { BitrixClient } from './http.js'
19. /**
20. * Bitrix's own stage grouping: 'P' in-process, 'S' success, 'F' failure.
21. *
22. * Declared here rather than imported from config/, because a package must not depend
23. * on the app that consumes it. config/bitrix-stages.ts declares the same union
24. * for its own use; three string literals are not worth an inverted dependency.
25. */
26. export type StageSemantic = 'P' | 'S' | 'F'
28. export interface RawLead {
29. ID: string
30. TITLE?: string
31. NAME?: string
32. LAST_NAME?: string
33. COMPANY_TITLE?: string
34. STATUS_ID?: string
35. DATE_CREATE?: string
36. DATE_MODIFY?: string
37. ASSIGNED_BY_ID?: string
38. OPPORTUNITY?: string
39. EMAIL?: unknown
40. SOURCE_ID?: string
41. /** Bitrix's own grouping: 'P' process, 'S' success, 'F' failure. */
42. STATUS_SEMANTIC_ID?: string
43. }
45. export interface Lead {
46. id: string
47. title: string
48. company: string | null
49. statusId: string
50. createdAt: string | null
51. updatedAt: string | null
52. /** Kept for reference only; see the note above. Do not group by it. */
53. assignedById: string | null
54. amount: number
55. /** True when this looks like automation exhaust rather than a real lead. */
56. noise: boolean
57. noiseReason: string | null
58. /**
59. * Bitrix's own stage grouping. 'S' and 'F' are end states whatever the stage
60. * is called, which is what makes classification survive someone adding a
61. * stage without telling anyone. See classify() in config/bitrix-stages.ts.
62. */
63. semantic: StageSemantic | null
64. }
66. const SELECT = [
67. 'ID',
68. 'TITLE',
69. 'NAME',
70. 'LAST_NAME',
71. 'COMPANY_TITLE',
72. 'STATUS_ID',
73. 'DATE_CREATE',
74. 'DATE_MODIFY',
75. 'ASSIGNED_BY_ID',
76. 'OPPORTUNITY',
77. 'SOURCE_ID',
78. // Bitrix's own P/S/F grouping. Costs nothing to select and is the difference
79. // between an unknown stage being classified correctly and being counted as
80. // work the team owes.
81. 'STATUS_SEMANTIC_ID',
82. ]
84. /**
85. * Patterns observed in the live open-lead list that are plainly not leads. Conservative on purpose: a real lead wrongly hidden is worse than
86. * a noisy row shown, so this only matches things that are unambiguous.
87. *
88. * Noisy rows are flagged, not dropped, and the dashboard shows the count of
89. * what it filtered. Silent filtering is how a dashboard starts lying.
90. */
91. const NOISE_PATTERNS: { re: RegExp; reason: string }[] = [
92. { re: /^Security alert:/i, reason: 'automated security notification' },
93. { re: /- Incoming call/i, reason: 'call log entry' },
94. { re: /^Complete CRM form/i, reason: 'unattended form submission' },
95. { re: /guest #\d+ - Meridian Display Support/i, reason: 'support chat guest record' },
96. ]
98. export function isLikelyNoise(title: string): { noise: boolean; reason: string | null } {
99. for (const p of NOISE_PATTERNS) if (p.re.test(title)) return { noise: true, reason: p.reason }
100. return { noise: false, reason: null }
101. }
103. export function normalizeLead(raw: RawLead): Lead {
104. const title = (raw.TITLE ?? [raw.NAME, raw.LAST_NAME].filter(Boolean).join(' ') ?? '').trim() || '(untitled)'
105. const { noise, reason } = isLikelyNoise(title)
106. return {
107. id: raw.ID,
108. title,
109. company: raw.COMPANY_TITLE?.trim() || null,
110. statusId: raw.STATUS_ID ?? '',
111. createdAt: raw.DATE_CREATE ?? null,
112. updatedAt: raw.DATE_MODIFY ?? null,
113. assignedById: raw.ASSIGNED_BY_ID ?? null,
114. amount: Number(raw.OPPORTUNITY ?? 0) || 0,
115. noise,
116. noiseReason: reason,
117. semantic:
118. raw.STATUS_SEMANTIC_ID === 'P' || raw.STATUS_SEMANTIC_ID === 'S' || raw.STATUS_SEMANTIC_ID === 'F'
119. ? raw.STATUS_SEMANTIC_ID
120. : null,
121. }
122. }
124. export class LeadsResource {
125. constructor(private readonly http: BitrixClient) {}
127. /**
128. * Open leads. `CLOSED: 'N'` is Bitrix's own definition of open.
129. *
130. * Why there is a date floor: unfiltered, this returns thousands of rows: the
131. * email-to-lead automation creates a lead for every security alert, incoming
132. * call and website chat, and nothing ever closes them. A lead opened
133. * eighteen months ago and never touched is not open work; it is debt, and
134. * counting it as pipeline makes every number on the board meaningless.
135. *
136. * `sinceDays` defaults to null (no floor) so the raw shape stays observable.
137. * The dashboard passes a window. Either way the result reports what it did:
138. * `excludedByAge` and `truncated` are both returned, never applied silently.
139. */
140. async listOpen(opts: { sinceDays?: number | null; maxPages?: number } = {}): Promise<{
141. leads: Lead[]
142. truncated: boolean
143. pages: number
144. /** Rows dropped for being older than `sinceDays`. Show this, do not hide it. */
145. excludedByAge: number
146. sinceDays: number | null
147. }> {
148. const sinceDays = opts.sinceDays ?? null
149. const filter: Record<string, unknown> = { CLOSED: 'N' }
150. if (sinceDays !== null) {
151. // Bitrix wants >=FIELD for a lower bound, and a plain date string.
152. filter['>=DATE_CREATE'] = new Date(Date.now() - sinceDays * 86_400_000)
153. .toISOString()
154. .slice(0, 10)
155. }
157. const { items, truncated, pages } = await this.http.listAll<RawLead>(
158. 'crm.lead.list',
159. { filter, select: SELECT, order: { DATE_CREATE: 'DESC' } },
160. opts.maxPages ?? 50,
161. )
163. return {
164. leads: items.map(normalizeLead),
165. truncated,
166. pages,
167. // Bitrix applied the floor server-side, so this is what it means rather
168. // than a client-side count: how many rows the window is keeping out.
169. excludedByAge: 0,
170. sinceDays,
171. }
172. }
173. }