@hogsend/engine 0.43.0 → 0.45.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (58) hide show
  1. package/package.json +12 -9
  2. package/src/container.ts +289 -13
  3. package/src/destinations/define-destination.ts +7 -3
  4. package/src/destinations/presets/posthog.ts +31 -0
  5. package/src/index.ts +99 -0
  6. package/src/journeys/execute-journey-run.ts +93 -0
  7. package/src/journeys/journey-context.ts +4 -0
  8. package/src/lib/analytics-providers-from-env.ts +106 -43
  9. package/src/lib/attribution-backfill.ts +285 -0
  10. package/src/lib/attribution.ts +239 -0
  11. package/src/lib/contacts.ts +71 -0
  12. package/src/lib/conversion-dispatch.ts +326 -0
  13. package/src/lib/conversions.ts +197 -0
  14. package/src/lib/crm-deals.ts +320 -0
  15. package/src/lib/crm-ingest.ts +341 -0
  16. package/src/lib/crm-provider-registry.ts +41 -0
  17. package/src/lib/crm-registry-singleton.ts +22 -0
  18. package/src/lib/deal-money-events.ts +85 -0
  19. package/src/lib/email-service-types.ts +16 -1
  20. package/src/lib/event-names.ts +1 -1
  21. package/src/lib/funnel-progress.ts +76 -0
  22. package/src/lib/funnel-registry.ts +108 -0
  23. package/src/lib/funnel-transitions.ts +280 -0
  24. package/src/lib/holdout.ts +62 -0
  25. package/src/lib/ingestion.ts +218 -9
  26. package/src/lib/lift-stats.ts +125 -0
  27. package/src/lib/mailer.ts +1 -0
  28. package/src/lib/operator.ts +31 -0
  29. package/src/lib/outbound.ts +51 -0
  30. package/src/lib/posthog-scopes.ts +30 -6
  31. package/src/lib/revenue.ts +116 -0
  32. package/src/lib/sms-service-types.ts +7 -1
  33. package/src/lib/sms-tracked.ts +35 -0
  34. package/src/lib/tracked.ts +40 -0
  35. package/src/lib/tracking-events.ts +26 -0
  36. package/src/lib/unconfigured-email-provider.ts +45 -0
  37. package/src/lib/webhook-signing.ts +7 -0
  38. package/src/routes/admin/analytics.ts +14 -5
  39. package/src/routes/admin/attribution.ts +414 -0
  40. package/src/routes/admin/contacts.ts +71 -11
  41. package/src/routes/admin/conversions.ts +247 -0
  42. package/src/routes/admin/deals.ts +472 -0
  43. package/src/routes/admin/funnels.ts +228 -0
  44. package/src/routes/admin/index.ts +8 -0
  45. package/src/routes/admin/journeys.ts +158 -1
  46. package/src/routes/admin/readiness.ts +97 -2
  47. package/src/routes/admin/templates.ts +28 -1
  48. package/src/routes/events/index.ts +12 -0
  49. package/src/routes/tracking/click-pipeline.ts +26 -18
  50. package/src/routes/webhooks/crm-provider.ts +117 -0
  51. package/src/routes/webhooks/index.ts +5 -1
  52. package/src/sources/define-contact-source.ts +159 -0
  53. package/src/sources/registry.ts +71 -0
  54. package/src/sources/webhook-source.ts +109 -0
  55. package/src/worker.ts +4 -0
  56. package/src/workflows/crm-reconcile.ts +129 -0
  57. package/src/workflows/dispatch-conversion.ts +31 -0
  58. package/src/workflows/send-campaign.ts +5 -0
@@ -0,0 +1,320 @@
1
+ import type {
2
+ CanonicalStage,
3
+ CrmStageEvent,
4
+ PipelineLadder,
5
+ } from "@hogsend/core";
6
+ import { canonicalStageRank, DEFAULT_PIPELINE_LADDER } from "@hogsend/core";
7
+ import { crmLinks, type Database, deals } from "@hogsend/db";
8
+ import { and, eq } from "drizzle-orm";
9
+ import type { Logger } from "./logger.js";
10
+
11
+ /**
12
+ * The deals projection + external-id alias map
13
+ * (docs/revenue-attribution-plan.md §4.2). Events stay the append-only truth;
14
+ * this module materializes current deal state with the MONOTONIC stage rule:
15
+ * a change applies only when it advances the canonical rank (heals
16
+ * webhook+poll double-detection and out-of-order delivery), `lost` applies
17
+ * from any non-sold state, and a deal value update always lands (latest
18
+ * value wins — quotes get revised).
19
+ */
20
+
21
+ /** The synthetic provider id for deals minted by funnel event triggers —
22
+ * reserved (a `CrmProvider` may not register under it). */
23
+ export const EVENTS_DEAL_PROVIDER = "events";
24
+
25
+ /** Resolve a CRM contact via the alias map: contact link, then deal link. */
26
+ export async function resolveCrmLinkedContact(opts: {
27
+ db: Database;
28
+ providerId: string;
29
+ event: Pick<CrmStageEvent, "contactId" | "dealId">;
30
+ }): Promise<string | null> {
31
+ const { db, providerId, event } = opts;
32
+ const candidates: Array<{ kind: "contact" | "deal"; externalId: string }> = [
33
+ ...(event.contactId
34
+ ? [{ kind: "contact" as const, externalId: event.contactId }]
35
+ : []),
36
+ { kind: "deal" as const, externalId: event.dealId },
37
+ ];
38
+ for (const candidate of candidates) {
39
+ const rows = await db
40
+ .select({ contactId: crmLinks.contactId })
41
+ .from(crmLinks)
42
+ .where(
43
+ and(
44
+ eq(crmLinks.provider, providerId),
45
+ eq(crmLinks.kind, candidate.kind),
46
+ eq(crmLinks.externalId, candidate.externalId),
47
+ ),
48
+ )
49
+ .limit(1);
50
+ if (rows[0]) return rows[0].contactId;
51
+ }
52
+ return null;
53
+ }
54
+
55
+ /** Mint the alias rows (idempotent) so future events resolve without email. */
56
+ export async function ensureCrmLinks(opts: {
57
+ db: Database;
58
+ providerId: string;
59
+ contactId: string;
60
+ event: Pick<CrmStageEvent, "contactId" | "dealId">;
61
+ }): Promise<void> {
62
+ const { db, providerId, contactId, event } = opts;
63
+ const rows = [
64
+ ...(event.contactId
65
+ ? [
66
+ {
67
+ provider: providerId,
68
+ kind: "contact" as const,
69
+ externalId: event.contactId,
70
+ contactId,
71
+ },
72
+ ]
73
+ : []),
74
+ {
75
+ provider: providerId,
76
+ kind: "deal" as const,
77
+ externalId: event.dealId,
78
+ contactId,
79
+ },
80
+ ];
81
+ await db.insert(crmLinks).values(rows).onConflictDoNothing();
82
+ }
83
+
84
+ export interface AppliedStageChange {
85
+ dealId: string;
86
+ /** The deal FIRST reached the ladder's quote stage with this event. */
87
+ freshQuoted: boolean;
88
+ /** The deal FIRST reached the ladder's sold stage with this event. */
89
+ freshSold: boolean;
90
+ /** Current projected value after this event. */
91
+ value: number | null;
92
+ currency: string | null;
93
+ canonicalStage: CanonicalStage | null;
94
+ }
95
+
96
+ /**
97
+ * Apply one stage event to the projection. `canonicalStage` is the engine's
98
+ * stage-map resolution (null = unmapped: native fields still record, the
99
+ * canonical stage holds). `event` is the minimal projection input — the CRM
100
+ * path passes a full {@link CrmStageEvent}; the event-trigger path builds
101
+ * one synthetically (providerId "events").
102
+ */
103
+ export async function applyCrmStageEvent(opts: {
104
+ db: Database;
105
+ logger: Logger;
106
+ providerId: string;
107
+ contactId: string;
108
+ event: Pick<
109
+ CrmStageEvent,
110
+ "dealId" | "stageId" | "pipelineId" | "value" | "occurredAt"
111
+ >;
112
+ canonicalStage: CanonicalStage | null;
113
+ /** The claiming funnel's ladder; defaults to the built-in five. */
114
+ ladder?: PipelineLadder;
115
+ /** The claiming funnel's id (stamped on the deal). */
116
+ funnelId?: string | null;
117
+ /**
118
+ * Skip the "latest value wins" update when the deal is already terminal
119
+ * (sold/lost). The event-trigger path sets this — a new-cycle trigger
120
+ * colliding with a closed synthetic row must not clobber its realized
121
+ * value. CRM paths keep the default (post-sale value revisions are real).
122
+ */
123
+ protectTerminalValue?: boolean;
124
+ }): Promise<AppliedStageChange> {
125
+ const { db, logger, providerId, contactId, event, canonicalStage } = opts;
126
+ const ladder = opts.ladder ?? DEFAULT_PIPELINE_LADDER;
127
+ const funnelId = opts.funnelId ?? null;
128
+ const occurredAt = new Date(event.occurredAt);
129
+ const rank = canonicalStage
130
+ ? canonicalStageRank(canonicalStage, ladder)
131
+ : null;
132
+
133
+ const insertValues = {
134
+ provider: providerId,
135
+ externalId: event.dealId,
136
+ contactId,
137
+ pipelineId: event.pipelineId ?? null,
138
+ funnelId,
139
+ stageId: event.stageId,
140
+ canonicalStage: canonicalStage ?? ladder.stages[0],
141
+ stageRank: rank !== null && rank >= 0 ? rank : 0,
142
+ value: event.value?.amount ?? null,
143
+ currency: event.value?.currency?.toUpperCase() ?? null,
144
+ // quotedAt marks the deal ACTUALLY reaching the quote stage — a deal
145
+ // first observed at sold does not retro-claim a quote event.
146
+ quotedAt: canonicalStage === ladder.quotedStage ? occurredAt : null,
147
+ soldAt: canonicalStage === ladder.soldStage ? occurredAt : null,
148
+ lostAt: canonicalStage === "lost" ? occurredAt : null,
149
+ lastStageAt: occurredAt,
150
+ };
151
+
152
+ // Insert-first: the common case for a new deal. A concurrent insert (the
153
+ // webhook/poll race) falls through to the update path below.
154
+ const inserted = await db
155
+ .insert(deals)
156
+ .values(insertValues)
157
+ .onConflictDoNothing({ target: [deals.provider, deals.externalId] })
158
+ .returning();
159
+ if (inserted[0]) {
160
+ return {
161
+ dealId: inserted[0].id,
162
+ freshQuoted: inserted[0].quotedAt !== null,
163
+ freshSold: inserted[0].soldAt !== null,
164
+ value: inserted[0].value,
165
+ currency: inserted[0].currency,
166
+ canonicalStage,
167
+ };
168
+ }
169
+
170
+ // The monotonic guard is compute-then-write, so the read must be
171
+ // serialized against the webhook/poll race (API + worker processes can
172
+ // apply different stage events to the same deal concurrently — an
173
+ // unguarded late `quoted` committing after `sold` would regress it).
174
+ // SELECT ... FOR UPDATE holds the row until this event's write commits.
175
+ return db.transaction(async (tx) => {
176
+ const existingRows = await tx
177
+ .select()
178
+ .from(deals)
179
+ .where(
180
+ and(eq(deals.provider, providerId), eq(deals.externalId, event.dealId)),
181
+ )
182
+ .limit(1)
183
+ .for("update");
184
+ const existing = existingRows[0];
185
+ if (!existing) {
186
+ // Unreachable outside a delete race; surface rather than throw.
187
+ logger.warn("crm deal projection row vanished mid-apply", {
188
+ provider: providerId,
189
+ dealId: event.dealId,
190
+ });
191
+ return {
192
+ dealId: "",
193
+ freshQuoted: false,
194
+ freshSold: false,
195
+ value: insertValues.value,
196
+ currency: insertValues.currency,
197
+ canonicalStage,
198
+ };
199
+ }
200
+
201
+ // A deal belongs to ONE funnel. A stage event that routes to a DIFFERENT
202
+ // funnel (the CRM moved the deal across pipelines) must not apply another
203
+ // ladder's ranks/designations to this row — that mints phantom money
204
+ // events and can flip sold→lost. The stage change still lands on the
205
+ // event spine; the projection ignores it and says so.
206
+ if (
207
+ funnelId &&
208
+ existing.funnelId !== null &&
209
+ existing.funnelId !== funnelId
210
+ ) {
211
+ logger.warn("cross-funnel stage event ignored by the deals projection", {
212
+ provider: providerId,
213
+ dealId: event.dealId,
214
+ dealFunnel: existing.funnelId,
215
+ eventFunnel: funnelId,
216
+ stageId: event.stageId,
217
+ });
218
+ return {
219
+ dealId: existing.id,
220
+ freshQuoted: false,
221
+ freshSold: false,
222
+ value: existing.value,
223
+ currency: existing.currency,
224
+ canonicalStage: existing.canonicalStage,
225
+ };
226
+ }
227
+
228
+ const set: Partial<typeof deals.$inferInsert> = { updatedAt: new Date() };
229
+ // Latest value always lands (quotes get revised), independent of stage
230
+ // direction — unless the caller protects terminal rows (see opts).
231
+ const terminal = existing.soldAt !== null || existing.lostAt !== null;
232
+ if (event.value && !(opts.protectTerminalValue && terminal)) {
233
+ set.value = event.value.amount;
234
+ set.currency = event.value.currency?.toUpperCase() ?? existing.currency;
235
+ }
236
+
237
+ // Adoption: a pre-funnel row (funnelId null) joins the claiming funnel —
238
+ // but its stored rank was computed on ANOTHER ladder's scale, so re-base
239
+ // it from the stage NAME in the new ladder before any comparison. A
240
+ // stage the new ladder doesn't know can't be re-based: leave the row
241
+ // untouched rather than guess.
242
+ let existingRank = existing.stageRank;
243
+ if (funnelId && existing.funnelId === null) {
244
+ if (existing.canonicalStage !== "lost") {
245
+ const rebased = canonicalStageRank(existing.canonicalStage, ladder);
246
+ if (rebased === null) {
247
+ logger.warn(
248
+ "pre-funnel deal stage is foreign to the claiming funnel — projection untouched",
249
+ {
250
+ provider: providerId,
251
+ dealId: event.dealId,
252
+ dealStage: existing.canonicalStage,
253
+ funnel: funnelId,
254
+ },
255
+ );
256
+ return {
257
+ dealId: existing.id,
258
+ freshQuoted: false,
259
+ freshSold: false,
260
+ value: existing.value,
261
+ currency: existing.currency,
262
+ canonicalStage: existing.canonicalStage,
263
+ };
264
+ }
265
+ existingRank = rebased;
266
+ set.stageRank = rebased;
267
+ }
268
+ set.funnelId = funnelId;
269
+ }
270
+
271
+ let freshQuoted = false;
272
+ let freshSold = false;
273
+ const advances =
274
+ canonicalStage !== null &&
275
+ canonicalStage !== "lost" &&
276
+ rank !== null &&
277
+ rank > existingRank &&
278
+ existing.canonicalStage !== "lost";
279
+ const losing =
280
+ canonicalStage === "lost" &&
281
+ existing.canonicalStage !== (ladder.soldStage ?? "sold");
282
+
283
+ if (advances) {
284
+ set.canonicalStage = canonicalStage;
285
+ set.stageRank = rank;
286
+ set.stageId = event.stageId;
287
+ set.pipelineId = event.pipelineId ?? existing.pipelineId;
288
+ set.lastStageAt = occurredAt;
289
+ if (canonicalStage === ladder.quotedStage && existing.quotedAt === null) {
290
+ set.quotedAt = occurredAt;
291
+ freshQuoted = true;
292
+ }
293
+ if (canonicalStage === ladder.soldStage && existing.soldAt === null) {
294
+ set.soldAt = occurredAt;
295
+ freshSold = true;
296
+ }
297
+ } else if (losing) {
298
+ set.canonicalStage = "lost";
299
+ set.stageId = event.stageId;
300
+ set.lastStageAt = occurredAt;
301
+ if (existing.lostAt === null) set.lostAt = occurredAt;
302
+ }
303
+
304
+ const updated = await tx
305
+ .update(deals)
306
+ .set(set)
307
+ .where(eq(deals.id, existing.id))
308
+ .returning();
309
+ const row = updated[0] ?? existing;
310
+
311
+ return {
312
+ dealId: row.id,
313
+ freshQuoted,
314
+ freshSold,
315
+ value: row.value,
316
+ currency: row.currency,
317
+ canonicalStage,
318
+ };
319
+ });
320
+ }
@@ -0,0 +1,341 @@
1
+ import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
2
+ import type { AnalyticsProvider, CrmStageEvent } from "@hogsend/core";
3
+ import { DEFAULT_PIPELINE_LADDER } from "@hogsend/core";
4
+ import type { JourneyRegistry } from "@hogsend/core/registry";
5
+ import { contacts, type Database, deals } from "@hogsend/db";
6
+ import { and, eq, isNull } from "drizzle-orm";
7
+ import { resolveOrCreateContact } from "./contacts.js";
8
+ import {
9
+ applyCrmStageEvent,
10
+ EVENTS_DEAL_PROVIDER,
11
+ ensureCrmLinks,
12
+ resolveCrmLinkedContact,
13
+ } from "./crm-deals.js";
14
+ import { mintDealMoneyEvents } from "./deal-money-events.js";
15
+ import type { FunnelRegistry } from "./funnel-registry.js";
16
+ import { ingestEvent } from "./ingestion.js";
17
+ import type { Logger } from "./logger.js";
18
+ import { emitOutbound } from "./outbound.js";
19
+
20
+ /**
21
+ * Land normalized {@link CrmStageEvent}s on the spine — the shared sink of
22
+ * BOTH the webhook route and the reconciliation poll
23
+ * (docs/revenue-attribution-plan.md §4).
24
+ *
25
+ * Per event: (1) resolve the contact — `crm_links` alias first (works with
26
+ * zero PII in the payload), else the payload email (minting the links so the
27
+ * NEXT event resolves aliased); (2) ingest `funnel.stage_changed` (valued, flat
28
+ * native ids + the stage-map's canonical resolution, idempotent across
29
+ * webhook/poll double-detection); (3) apply the deals projection (monotonic);
30
+ * (4) on a FRESH canonical transition, ingest the money events
31
+ * `deal.quoted` / `deal.sold` (once per deal per stage, ever) with
32
+ * the projected deal value; (5) fan the family out on the outbound spine.
33
+ */
34
+
35
+ export const FUNNEL_STAGE_CHANGED = "funnel.stage_changed" as const;
36
+ export const DEAL_QUOTED = "deal.quoted" as const;
37
+ export const DEAL_SOLD = "deal.sold" as const;
38
+
39
+ export async function ingestCrmStageEvents(opts: {
40
+ db: Database;
41
+ registry: JourneyRegistry;
42
+ hatchet: HatchetClient;
43
+ logger: Logger;
44
+ analytics?: AnalyticsProvider;
45
+ providerId: string;
46
+ events: CrmStageEvent[];
47
+ /** Funnel routing (which funnel claims each (provider, pipeline)). */
48
+ funnels?: FunnelRegistry;
49
+ }): Promise<{ ingested: number; skipped: number }> {
50
+ const {
51
+ db,
52
+ registry,
53
+ hatchet,
54
+ logger,
55
+ analytics,
56
+ providerId,
57
+ events,
58
+ funnels,
59
+ } = opts;
60
+ let ingested = 0;
61
+ let skipped = 0;
62
+
63
+ for (const event of events) {
64
+ try {
65
+ // (1) Identity: alias map first, then the payload email. The resolver
66
+ // needs a KEY (the contactId pin alone is provenance, not identity), so
67
+ // the links path loads the contact's canonical key and round-trips it
68
+ // as userId — the pin guarantees it folds onto that exact row.
69
+ let contactId: string | null = null;
70
+ let canonicalKey: string | null = null;
71
+ const linked = await resolveCrmLinkedContact({ db, providerId, event });
72
+ if (linked) {
73
+ const rows = await db
74
+ .select({
75
+ id: contacts.id,
76
+ externalId: contacts.externalId,
77
+ anonymousId: contacts.anonymousId,
78
+ })
79
+ .from(contacts)
80
+ .where(eq(contacts.id, linked))
81
+ .limit(1);
82
+ if (rows[0]) {
83
+ contactId = rows[0].id;
84
+ canonicalKey =
85
+ rows[0].externalId ?? rows[0].anonymousId ?? rows[0].id;
86
+ }
87
+ }
88
+ if (!contactId && event.email) {
89
+ const resolved = await resolveOrCreateContact({
90
+ db,
91
+ email: event.email,
92
+ });
93
+ contactId = resolved.id;
94
+ canonicalKey = resolved.resolvedKey;
95
+ }
96
+ if (!contactId || !canonicalKey) {
97
+ logger.warn("funnel.stage_changed skipped: no resolvable identity", {
98
+ provider: providerId,
99
+ dealId: event.dealId,
100
+ stageId: event.stageId,
101
+ });
102
+ skipped++;
103
+ continue;
104
+ }
105
+ await ensureCrmLinks({ db, providerId, contactId, event });
106
+
107
+ // Which funnel claims this (provider, pipeline)? The matched binding
108
+ // translates native stage ids; a miss falls through to the SAME
109
+ // funnel's provider-`"*"` binding (a `"*"` map doubles as a per-stage
110
+ // fallback for the funnel's own pipeline-specific bindings), then the
111
+ // universal won/lost status hint. The container always registers a
112
+ // "default" funnel, so the built-in fallback only covers direct
113
+ // callers.
114
+ const claimed = funnels?.resolve(providerId, event.pipelineId);
115
+ const funnel = claimed?.funnel;
116
+ const funnelId = funnel?.meta.id ?? null;
117
+ const ladder = funnel?.ladder ?? DEFAULT_PIPELINE_LADDER;
118
+
119
+ // Callback-form resolvers are arbitrary consumer code: a throw must
120
+ // not swallow the event (the route 200s and the poll cursor advances
121
+ // regardless — the transition would be lost forever), and an output
122
+ // outside the ladder must not be stamped verbatim onto a fresh deal.
123
+ const resolveVia = (
124
+ binding: NonNullable<typeof claimed>["binding"],
125
+ ): string | null => {
126
+ if (!binding) return null;
127
+ try {
128
+ const out = binding.resolve(event);
129
+ if (out === null || out === "lost" || ladder.stages.includes(out)) {
130
+ return out;
131
+ }
132
+ logger.warn("funnel binding resolved to a stage outside the ladder", {
133
+ funnel: funnelId,
134
+ provider: providerId,
135
+ stageId: event.stageId,
136
+ resolved: out,
137
+ });
138
+ } catch (error) {
139
+ logger.warn("funnel binding resolve threw — treating as unmapped", {
140
+ funnel: funnelId,
141
+ provider: providerId,
142
+ stageId: event.stageId,
143
+ error: error instanceof Error ? error.message : String(error),
144
+ });
145
+ }
146
+ return null;
147
+ };
148
+ const wildcardBinding =
149
+ claimed?.binding?.pipeline === "*"
150
+ ? undefined
151
+ : funnel?.meta.bindings?.find(
152
+ (b) => b.provider === providerId && b.pipeline === "*",
153
+ );
154
+ const canonicalStage =
155
+ resolveVia(claimed?.binding) ??
156
+ resolveVia(wildcardBinding) ??
157
+ (event.status === "won"
158
+ ? (ladder.soldStage ?? null)
159
+ : event.status === "lost"
160
+ ? "lost"
161
+ : null);
162
+ if (!canonicalStage) {
163
+ logger.warn("crm stage unmapped — recording native ids only", {
164
+ provider: providerId,
165
+ pipelineId: event.pipelineId ?? null,
166
+ stageId: event.stageId,
167
+ });
168
+ }
169
+
170
+ // (2) The raw stage-change on the spine. Idempotency spans webhook+poll:
171
+ // both observe the same CRM change timestamp.
172
+ const idempotencyKey = [
173
+ "crm",
174
+ providerId,
175
+ event.dealId,
176
+ event.pipelineId ?? "",
177
+ event.stageId,
178
+ event.status ?? "",
179
+ event.occurredAt,
180
+ ].join(":");
181
+
182
+ const result = await ingestEvent({
183
+ db,
184
+ registry,
185
+ hatchet,
186
+ logger,
187
+ analytics,
188
+ event: {
189
+ event: FUNNEL_STAGE_CHANGED,
190
+ userId: canonicalKey,
191
+ userEmail: event.email,
192
+ contactId,
193
+ eventProperties: {
194
+ crm: providerId,
195
+ deal_id: event.dealId,
196
+ ...(event.contactId ? { contact_id: event.contactId } : {}),
197
+ ...(event.pipelineId ? { pipeline_id: event.pipelineId } : {}),
198
+ stage_id: event.stageId,
199
+ ...(event.stageName ? { stage_name: event.stageName } : {}),
200
+ ...(event.status ? { status: event.status } : {}),
201
+ ...(canonicalStage ? { canonical_stage: canonicalStage } : {}),
202
+ ...(funnelId ? { funnel_id: funnelId } : {}),
203
+ },
204
+ ...(event.value
205
+ ? {
206
+ value: event.value.amount,
207
+ ...(event.value.currency
208
+ ? { currency: event.value.currency }
209
+ : {}),
210
+ }
211
+ : {}),
212
+ occurredAt: event.occurredAt,
213
+ idempotencyKey,
214
+ source: "crm",
215
+ },
216
+ });
217
+ if (!result.stored) {
218
+ // Duplicate observation (webhook + poll): projection already applied.
219
+ continue;
220
+ }
221
+ ingested++;
222
+
223
+ // (2b) Adopt an open event-minted deal: the event-native path may have
224
+ // opened this contact's deal in the same funnel before the CRM ever
225
+ // saw it. The CRM identity is stickier (native id, reconcilable), so
226
+ // re-key the synthetic row onto (provider, dealId) instead of minting
227
+ // an open sibling that would ping-pong stats and double-mint. Only the
228
+ // implicit single-deal row adopts — `deal_id`-addressed rows are
229
+ // deliberate multi-deal and stay separate.
230
+ if (funnelId) {
231
+ const existingCrmRow = await db
232
+ .select({ id: deals.id })
233
+ .from(deals)
234
+ .where(
235
+ and(
236
+ eq(deals.provider, providerId),
237
+ eq(deals.externalId, event.dealId),
238
+ ),
239
+ )
240
+ .limit(1);
241
+ if (!existingCrmRow[0]) {
242
+ const adopted = await db
243
+ .update(deals)
244
+ .set({
245
+ provider: providerId,
246
+ externalId: event.dealId,
247
+ ...(event.pipelineId ? { pipelineId: event.pipelineId } : {}),
248
+ updatedAt: new Date(),
249
+ })
250
+ .where(
251
+ and(
252
+ eq(deals.provider, EVENTS_DEAL_PROVIDER),
253
+ eq(deals.externalId, `${funnelId}:${contactId}`),
254
+ isNull(deals.soldAt),
255
+ isNull(deals.lostAt),
256
+ ),
257
+ )
258
+ .returning({ id: deals.id })
259
+ .catch(() => []); // unique-key race: another writer took the key
260
+ if (adopted[0]) {
261
+ logger.info("event-minted deal adopted by CRM identity", {
262
+ provider: providerId,
263
+ dealId: event.dealId,
264
+ funnel: funnelId,
265
+ });
266
+ }
267
+ }
268
+ }
269
+
270
+ // (3) Projection (monotonic; latest value wins).
271
+ const applied = await applyCrmStageEvent({
272
+ db,
273
+ logger,
274
+ providerId,
275
+ contactId,
276
+ event,
277
+ canonicalStage,
278
+ ladder,
279
+ funnelId,
280
+ });
281
+
282
+ const outboundPayload = {
283
+ provider: providerId,
284
+ dealId: event.dealId,
285
+ pipelineId: event.pipelineId ?? null,
286
+ funnelId,
287
+ canonicalStage,
288
+ value: applied.value,
289
+ currency: applied.currency,
290
+ userId: result.contactKey,
291
+ at: event.occurredAt,
292
+ };
293
+ void emitOutbound({
294
+ db,
295
+ hatchet,
296
+ logger,
297
+ event: FUNNEL_STAGE_CHANGED,
298
+ payload: {
299
+ ...outboundPayload,
300
+ stageId: event.stageId,
301
+ stageName: event.stageName ?? null,
302
+ status: event.status ?? null,
303
+ },
304
+ dedupeKey: idempotencyKey,
305
+ }).catch((err) => logger.warn("crm outbound emit failed", { err }));
306
+
307
+ // (4) The money events — once per deal per canonical stage, ever.
308
+ await mintDealMoneyEvents({
309
+ db,
310
+ registry,
311
+ hatchet,
312
+ logger,
313
+ analytics,
314
+ applied,
315
+ ladder,
316
+ idempotencyPrefix: `crm-canonical:${providerId}:${event.dealId}`,
317
+ source: "crm",
318
+ userId: canonicalKey,
319
+ userEmail: event.email,
320
+ contactId,
321
+ baseProperties: {
322
+ crm: providerId,
323
+ deal_id: event.dealId,
324
+ ...(event.pipelineId ? { pipeline_id: event.pipelineId } : {}),
325
+ ...(funnelId ? { funnel_id: funnelId } : {}),
326
+ },
327
+ occurredAt: event.occurredAt,
328
+ outboundPayload,
329
+ });
330
+ } catch (err) {
331
+ logger.warn("crm stage event ingest failed", {
332
+ provider: providerId,
333
+ dealId: event.dealId,
334
+ error: err instanceof Error ? err.message : String(err),
335
+ });
336
+ skipped++;
337
+ }
338
+ }
339
+
340
+ return { ingested, skipped };
341
+ }
@@ -0,0 +1,41 @@
1
+ import type { CrmProvider } from "@hogsend/core";
2
+ import { EVENTS_DEAL_PROVIDER } from "./crm-deals.js";
3
+
4
+ /**
5
+ * Container-held registry of CRM providers, keyed by `provider.meta.id`. The
6
+ * webhook route (`POST /v1/webhooks/crm/:providerId`) resolves the verifying
7
+ * provider out of this; the reconciliation poll task walks `getAll()`.
8
+ *
9
+ * The CRM sibling of {@link SmsProviderRegistry}. Unlike email/SMS there is
10
+ * no single "active" provider — MANY CRMs sync concurrently (an agency
11
+ * deployment syncs a different CRM per client); `pushLead` callers name the
12
+ * provider explicitly.
13
+ */
14
+ export class CrmProviderRegistry {
15
+ private byId = new Map<string, CrmProvider>();
16
+
17
+ constructor(providers: CrmProvider[] = []) {
18
+ for (const provider of providers) this.register(provider);
19
+ }
20
+
21
+ register(provider: CrmProvider): void {
22
+ if (provider.meta.id === EVENTS_DEAL_PROVIDER) {
23
+ throw new Error(
24
+ `CRM provider id "${EVENTS_DEAL_PROVIDER}" is reserved for deals minted by funnel event triggers`,
25
+ );
26
+ }
27
+ this.byId.set(provider.meta.id, provider);
28
+ }
29
+
30
+ get(id: string): CrmProvider | undefined {
31
+ return this.byId.get(id);
32
+ }
33
+
34
+ getAll(): CrmProvider[] {
35
+ return [...this.byId.values()];
36
+ }
37
+
38
+ count(): number {
39
+ return this.byId.size;
40
+ }
41
+ }