@hogsend/engine 0.43.0 → 0.44.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.
- package/package.json +10 -9
- package/src/container.ts +229 -2
- package/src/destinations/define-destination.ts +7 -3
- package/src/destinations/presets/posthog.ts +31 -0
- package/src/index.ts +99 -0
- package/src/journeys/execute-journey-run.ts +93 -0
- package/src/journeys/journey-context.ts +4 -0
- package/src/lib/attribution-backfill.ts +285 -0
- package/src/lib/attribution.ts +239 -0
- package/src/lib/contacts.ts +71 -0
- package/src/lib/conversion-dispatch.ts +326 -0
- package/src/lib/conversions.ts +197 -0
- package/src/lib/crm-deals.ts +320 -0
- package/src/lib/crm-ingest.ts +341 -0
- package/src/lib/crm-provider-registry.ts +41 -0
- package/src/lib/crm-registry-singleton.ts +22 -0
- package/src/lib/deal-money-events.ts +85 -0
- package/src/lib/email-service-types.ts +16 -1
- package/src/lib/event-names.ts +1 -1
- package/src/lib/funnel-progress.ts +76 -0
- package/src/lib/funnel-registry.ts +108 -0
- package/src/lib/funnel-transitions.ts +280 -0
- package/src/lib/holdout.ts +62 -0
- package/src/lib/ingestion.ts +218 -9
- package/src/lib/lift-stats.ts +125 -0
- package/src/lib/mailer.ts +1 -0
- package/src/lib/operator.ts +31 -0
- package/src/lib/outbound.ts +51 -0
- package/src/lib/revenue.ts +116 -0
- package/src/lib/sms-service-types.ts +7 -1
- package/src/lib/sms-tracked.ts +35 -0
- package/src/lib/tracked.ts +40 -0
- package/src/lib/tracking-events.ts +26 -0
- package/src/lib/webhook-signing.ts +7 -0
- package/src/routes/admin/attribution.ts +414 -0
- package/src/routes/admin/contacts.ts +71 -11
- package/src/routes/admin/conversions.ts +247 -0
- package/src/routes/admin/deals.ts +472 -0
- package/src/routes/admin/funnels.ts +228 -0
- package/src/routes/admin/index.ts +8 -0
- package/src/routes/admin/journeys.ts +158 -1
- package/src/routes/admin/readiness.ts +97 -2
- package/src/routes/admin/templates.ts +28 -1
- package/src/routes/events/index.ts +12 -0
- package/src/routes/tracking/click-pipeline.ts +26 -18
- package/src/routes/webhooks/crm-provider.ts +117 -0
- package/src/routes/webhooks/index.ts +5 -1
- package/src/sources/define-contact-source.ts +159 -0
- package/src/sources/registry.ts +71 -0
- package/src/sources/webhook-source.ts +109 -0
- package/src/worker.ts +4 -0
- package/src/workflows/crm-reconcile.ts +129 -0
- package/src/workflows/dispatch-conversion.ts +31 -0
- 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
|
+
}
|