@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
@@ -7,6 +7,7 @@ import { agentRouter } from "./agent.js";
7
7
  import { alertsRouter } from "./alerts.js";
8
8
  import { analyticsAdminRouter } from "./analytics.js";
9
9
  import { apiKeysRouter } from "./api-keys.js";
10
+ import { adminAttributionRouter } from "./attribution.js";
10
11
  import { auditLogsRouter } from "./audit-logs.js";
11
12
  import { blueprintsRouter } from "./blueprints.js";
12
13
  import { bucketsRouter } from "./buckets.js";
@@ -14,10 +15,13 @@ import { bulkRouter } from "./bulk.js";
14
15
  import { adminCampaignsRouter } from "./campaigns.js";
15
16
  import { adminConnectorsRouter } from "./connectors.js";
16
17
  import { contactsRouter } from "./contacts.js";
18
+ import { adminConversionsRouter } from "./conversions.js";
19
+ import { adminDealsRouter } from "./deals.js";
17
20
  import { dlqRouter } from "./dlq.js";
18
21
  import { domainRouter } from "./domain.js";
19
22
  import { emailsRouter } from "./emails.js";
20
23
  import { eventsRouter } from "./events.js";
24
+ import { adminFunnelsRouter } from "./funnels.js";
21
25
  import { journeyLogsRouter } from "./journey-logs.js";
22
26
  import { journeysRouter } from "./journeys.js";
23
27
  import { linksRouter } from "./links.js";
@@ -47,6 +51,10 @@ adminRouter.route("/open-in-editor", openEditorRouter);
47
51
  adminRouter.route("/buckets", bucketsRouter);
48
52
  adminRouter.route("/lists", adminListsRouter);
49
53
  adminRouter.route("/campaigns", adminCampaignsRouter);
54
+ adminRouter.route("/deals", adminDealsRouter);
55
+ adminRouter.route("/conversions", adminConversionsRouter);
56
+ adminRouter.route("/attribution", adminAttributionRouter);
57
+ adminRouter.route("/funnels", adminFunnelsRouter);
50
58
  adminRouter.route("/events", eventsRouter);
51
59
  adminRouter.route("/emails", emailsRouter);
52
60
  adminRouter.route("/links", linksRouter);
@@ -21,6 +21,7 @@ import {
21
21
  import type { AppEnv } from "../../app.js";
22
22
  import { buildJourneyGraph } from "../../journeys/graph/build-graph.js";
23
23
  import { ingestEvent } from "../../lib/ingestion.js";
24
+ import { computeLift } from "../../lib/lift-stats.js";
24
25
 
25
26
  /**
26
27
  * Per-process cache of the built {@link JourneyGraph}. A journey's `runSource`
@@ -44,6 +45,8 @@ const journeySchema = z.object({
44
45
  completed: z.number(),
45
46
  failed: z.number(),
46
47
  exited: z.number(),
48
+ /** Holdout controls (impact plan §4.1) — would-have-entered contacts. */
49
+ held_out: z.number(),
47
50
  }),
48
51
  });
49
52
 
@@ -111,6 +114,7 @@ const emptyCounts = {
111
114
  completed: 0,
112
115
  failed: 0,
113
116
  exited: 0,
117
+ held_out: 0,
114
118
  };
115
119
 
116
120
  // --- Route definitions ---
@@ -236,7 +240,14 @@ const listStatesRoute = createRoute({
236
240
  limit: z.coerce.number().min(1).max(100).default(50),
237
241
  offset: z.coerce.number().min(0).default(0),
238
242
  status: z
239
- .enum(["active", "waiting", "completed", "failed", "exited"])
243
+ .enum([
244
+ "active",
245
+ "waiting",
246
+ "completed",
247
+ "failed",
248
+ "exited",
249
+ "held_out",
250
+ ])
240
251
  .optional(),
241
252
  userId: z.string().optional(),
242
253
  }),
@@ -466,6 +477,60 @@ const graphRoute = createRoute({
466
477
  },
467
478
  });
468
479
 
480
+ /**
481
+ * Holdout lift (impact plan §4.2) — the ONLY surface allowed causal
482
+ * language. Treatment = entered enrollments in the window; control =
483
+ * held_out diversions (§4.1). Outcome = the contact fired ≥1 conversion
484
+ * AFTER their state row was created. Beta-binomial win probability with a
485
+ * suppression floor and a loud small-sample flag (lib/lift-stats.ts).
486
+ */
487
+ const liftCohortSchema = z.object({
488
+ contacts: z.number(),
489
+ converters: z.number(),
490
+ rate: z.number(),
491
+ /** Qualifying conversion value per currency (full, not fractional). */
492
+ value: z.array(
493
+ z.object({ currency: z.string().nullable(), value: z.number() }),
494
+ ),
495
+ });
496
+
497
+ const liftRoute = createRoute({
498
+ method: "get",
499
+ path: "/{id}/lift",
500
+ tags: ["Admin — Journeys"],
501
+ summary: "Holdout lift: entered vs held-out conversion rates",
502
+ request: {
503
+ params: z.object({ id: z.string() }),
504
+ query: z.object({
505
+ days: z.coerce.number().min(1).max(365).default(90),
506
+ /** Scope the outcome to one conversion point; default any. */
507
+ definitionId: z.string().optional(),
508
+ }),
509
+ },
510
+ responses: {
511
+ 200: {
512
+ content: {
513
+ "application/json": {
514
+ schema: z.object({
515
+ journeyId: z.string(),
516
+ days: z.number(),
517
+ definitionId: z.string().nullable(),
518
+ treatment: liftCohortSchema,
519
+ control: liftCohortSchema,
520
+ liftPercent: z.number().nullable(),
521
+ /** Null when suppressed (combined conversions < 10). */
522
+ winProbability: z.number().nullable(),
523
+ suppressed: z.boolean(),
524
+ smallSample: z.boolean(),
525
+ }),
526
+ },
527
+ },
528
+ description:
529
+ "Intent-to-treat lift between entered and held-out cohorts, with honest small-sample presentation",
530
+ },
531
+ },
532
+ });
533
+
469
534
  export const journeysRouter = new OpenAPIHono<AppEnv>()
470
535
  .openapi(listRoute, async (c) => {
471
536
  const { db, registry } = c.get("container");
@@ -1050,4 +1115,96 @@ export const journeysRouter = new OpenAPIHono<AppEnv>()
1050
1115
  },
1051
1116
  200,
1052
1117
  );
1118
+ })
1119
+ .openapi(liftRoute, async (c) => {
1120
+ const { db } = c.get("container");
1121
+ const { id } = c.req.valid("param");
1122
+ const { days, definitionId } = c.req.valid("query");
1123
+ const since = new Date(
1124
+ Date.now() - days * 24 * 60 * 60 * 1000,
1125
+ ).toISOString();
1126
+ const sinceTs = sql`${since}::timestamptz`;
1127
+
1128
+ // Outcome: the contact fired ≥1 qualifying conversion AFTER their state
1129
+ // row was created (post-assignment — the intent-to-treat clock).
1130
+ const definitionSql = definitionId
1131
+ ? sql` and c.definition_id = ${definitionId}`
1132
+ : sql``;
1133
+ const convertedSql = sql`exists (
1134
+ select 1 from conversions c
1135
+ where c.user_key = ${journeyStates.userId}
1136
+ and c.occurred_at >= ${journeyStates.createdAt}${definitionSql}
1137
+ )`;
1138
+
1139
+ const cohort = async (control: boolean) => {
1140
+ const statusFilter = control
1141
+ ? eq(journeyStates.status, "held_out")
1142
+ : sql`${journeyStates.status} != 'held_out'`;
1143
+ const [row] = await db
1144
+ .select({
1145
+ contacts: sql<number>`count(distinct ${journeyStates.userId})::int`,
1146
+ converters: sql<number>`(count(distinct ${journeyStates.userId}) filter (where ${convertedSql}))::int`,
1147
+ })
1148
+ .from(journeyStates)
1149
+ .where(
1150
+ and(
1151
+ eq(journeyStates.journeyId, id),
1152
+ gteCreated(sinceTs),
1153
+ statusFilter,
1154
+ ),
1155
+ );
1156
+ // Full qualifying conversion value per currency (secondary read-out —
1157
+ // the rate is the primary lift instrument).
1158
+ const valueRows = await db.execute<{
1159
+ currency: string | null;
1160
+ value: number;
1161
+ }>(sql`
1162
+ select c.currency, coalesce(sum(c.value), 0)::float8 as value
1163
+ from conversions c
1164
+ where c.value is not null
1165
+ and exists (
1166
+ select 1 from journey_states js
1167
+ where js.journey_id = ${id}
1168
+ and js.created_at >= ${sinceTs}
1169
+ and ${control ? sql`js.status = 'held_out'` : sql`js.status != 'held_out'`}
1170
+ and js.user_id = c.user_key
1171
+ and c.occurred_at >= js.created_at
1172
+ )${definitionId ? sql` and c.definition_id = ${definitionId}` : sql``}
1173
+ group by c.currency
1174
+ `);
1175
+ const contacts = Number(row?.contacts ?? 0);
1176
+ const converters = row?.converters ?? 0;
1177
+ return {
1178
+ contacts,
1179
+ converters,
1180
+ rate: contacts > 0 ? converters / contacts : 0,
1181
+ value: [...valueRows].map((r) => ({
1182
+ currency: r.currency,
1183
+ value: Number(r.value),
1184
+ })),
1185
+ };
1186
+ };
1187
+
1188
+ const [treatment, control] = await Promise.all([
1189
+ cohort(false),
1190
+ cohort(true),
1191
+ ]);
1192
+ const verdict = computeLift({ treatment, control });
1193
+
1194
+ return c.json(
1195
+ {
1196
+ journeyId: id,
1197
+ days,
1198
+ definitionId: definitionId ?? null,
1199
+ treatment,
1200
+ control,
1201
+ ...verdict,
1202
+ },
1203
+ 200,
1204
+ );
1053
1205
  });
1206
+
1207
+ /** `created_at >= since` as a reusable fragment (lift cohort windows). */
1208
+ function gteCreated(sinceTs: ReturnType<typeof sql>) {
1209
+ return sql`${journeyStates.createdAt} >= ${sinceTs}`;
1210
+ }
@@ -1,7 +1,13 @@
1
- import { apiKeys } from "@hogsend/db";
1
+ import {
2
+ apiKeys,
3
+ attributionCredits,
4
+ conversions,
5
+ userEvents,
6
+ } from "@hogsend/db";
2
7
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
3
- import { count, isNull } from "drizzle-orm";
8
+ import { count, inArray, isNull } from "drizzle-orm";
4
9
  import type { AppEnv } from "../../app.js";
10
+ import { trustedValuedEventFilter } from "../../lib/revenue.js";
5
11
 
6
12
  /**
7
13
  * First-time setup readiness — a NON-BLOCKING checklist for Studio's Setup view.
@@ -172,6 +178,95 @@ export const readinessRouter = new OpenAPIHono<AppEnv>().openapi(
172
178
  docsUrl: DOCS,
173
179
  });
174
180
 
181
+ // 7–10. Attribution readiness (impact plan §5.4) — the "how's it doing"
182
+ // wires, in causal order: arrivals → valued events → conversions →
183
+ // credits. ALL optional-tier: attribution never blocks setup-`ready`;
184
+ // the detail text names the exact missing wire. Cheap existence probes,
185
+ // each degrading alone on a DB hiccup.
186
+ const exists = async (probe: () => Promise<unknown[]>) => {
187
+ try {
188
+ return (await probe()).length > 0;
189
+ } catch {
190
+ return null;
191
+ }
192
+ };
193
+ const [hasArrivals, hasValued, hasConversions, hasCredits] =
194
+ await Promise.all([
195
+ exists(() =>
196
+ db
197
+ .select({ id: userEvents.id })
198
+ .from(userEvents)
199
+ .where(
200
+ inArray(userEvents.event, ["campaign.arrived", "link.arrived"]),
201
+ )
202
+ .limit(1),
203
+ ),
204
+ exists(() =>
205
+ db
206
+ .select({ id: userEvents.id })
207
+ .from(userEvents)
208
+ .where(trustedValuedEventFilter())
209
+ .limit(1),
210
+ ),
211
+ exists(() =>
212
+ db.select({ id: conversions.id }).from(conversions).limit(1),
213
+ ),
214
+ exists(() =>
215
+ db
216
+ .select({ id: attributionCredits.id })
217
+ .from(attributionCredits)
218
+ .limit(1),
219
+ ),
220
+ ]);
221
+ const probeCheck = (
222
+ id: string,
223
+ label: string,
224
+ seen: boolean | null,
225
+ okDetail: string,
226
+ missingDetail: string,
227
+ ): Check => ({
228
+ id,
229
+ label,
230
+ status: seen === true ? "ok" : "optional",
231
+ detail:
232
+ seen === null
233
+ ? "Couldn't probe — check the database connection."
234
+ : seen
235
+ ? okDetail
236
+ : missingDetail,
237
+ docsUrl: `${DOCS}/conversions/impact`,
238
+ });
239
+ checks.push(
240
+ probeCheck(
241
+ "attribution_arrivals",
242
+ "Arrival capture",
243
+ hasArrivals,
244
+ "Landing arrivals are being captured.",
245
+ "No arrivals yet — add @hogsend/js to your landing pages (2 minutes) so ad/UTM touches earn credit.",
246
+ ),
247
+ probeCheck(
248
+ "attribution_valued_events",
249
+ "Valued events",
250
+ hasValued,
251
+ "Trusted valued events are flowing.",
252
+ "No valued events yet — point one revenue webhook (Stripe, orders) at a source with value + currency.",
253
+ ),
254
+ probeCheck(
255
+ "attribution_conversions",
256
+ "Conversions firing",
257
+ hasConversions,
258
+ "Conversion points are firing.",
259
+ "No conversions yet — the built-in revenue definition fires on any trusted valued event; or author defineConversion.",
260
+ ),
261
+ probeCheck(
262
+ "attribution_credits",
263
+ "Attribution credits",
264
+ hasCredits,
265
+ "The credit ledger is accruing.",
266
+ "No credits yet — credits appear once a converting contact has touchpoints; run `hogsend attribution backfill` to credit existing history.",
267
+ ),
268
+ );
269
+
175
270
  const doneCount = checks.filter((ch) => ch.status === "ok").length;
176
271
  // "ready" ignores optional rows — only outstanding "action" items block it.
177
272
  const ready = checks.every((ch) => ch.status !== "action");
@@ -9,6 +9,7 @@ import {
9
9
  } from "@hogsend/email";
10
10
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
11
11
  import type { AppEnv } from "../../app.js";
12
+ import { isOperatorAddress } from "../../lib/operator.js";
12
13
  import { errorSchema } from "../../lib/schemas.js";
13
14
  import { requireScope } from "../../middleware/api-key.js";
14
15
 
@@ -157,6 +158,10 @@ const sendTestRoute = createRoute({
157
158
  },
158
159
  description: "Test email dispatched",
159
160
  },
161
+ 403: {
162
+ content: { "application/json": { schema: errorSchema } },
163
+ description: "Recipient is not a verified operator/team address",
164
+ },
160
165
  404: {
161
166
  content: { "application/json": { schema: errorSchema } },
162
167
  description: "Template not found",
@@ -258,7 +263,7 @@ export const templatesRouter = new OpenAPIHono<AppEnv>()
258
263
  }
259
264
  })
260
265
  .openapi(sendTestRoute, async (c) => {
261
- const { emailService, templates } = c.get("container");
266
+ const { emailService, templates, db, env, logger } = c.get("container");
262
267
  const { key } = c.req.valid("param");
263
268
  const { to, props: bodyProps } = c.req.valid("json");
264
269
 
@@ -266,6 +271,28 @@ export const templatesRouter = new OpenAPIHono<AppEnv>()
266
271
  return c.json({ error: "Template not found" }, 404);
267
272
  }
268
273
 
274
+ // Restrict test sends to a verified operator/team address. This route is
275
+ // full-admin-key-only (its `requireScope`), which is exactly how the MCP
276
+ // server / an external agent authenticates — and the send below skips
277
+ // preference checks. Bounding the recipient to the admin team removes the
278
+ // "reach an unintended recipient" capability from a prompt-injected agent.
279
+ if (!(await isOperatorAddress({ db, env, email: to }))) {
280
+ return c.json(
281
+ {
282
+ error:
283
+ "Test sends are restricted to your team's verified addresses (an admin user, HOGSEND_TEST_EMAIL, or STUDIO_ADMIN_EMAIL).",
284
+ },
285
+ 403,
286
+ );
287
+ }
288
+
289
+ const apiKey = c.get("apiKey");
290
+ logger.info("[templates] test send", {
291
+ template: key,
292
+ to,
293
+ actor: apiKey?.id ?? "session",
294
+ });
295
+
269
296
  const definition = getTemplateDefinition({
270
297
  key: key as TemplateName,
271
298
  registry: templates,
@@ -20,6 +20,16 @@ const eventRequestSchema = z.object({
20
20
  anonymousId: z.string().min(1).max(200).optional(),
21
21
  eventProperties: z.record(z.string(), z.unknown()).optional(),
22
22
  contactProperties: z.record(z.string(), z.unknown()).optional(),
23
+ // The event's monetary worth (order total, deal value). First-class — lands
24
+ // on `user_events.value`, the column revenue rollups, conversion definitions,
25
+ // and attribution credits read. Negative = refunds/adjustments.
26
+ value: z.number().finite().optional(),
27
+ // ISO-4217 alpha code for `value` (uppercased at ingest). Ignored without
28
+ // `value`.
29
+ currency: z
30
+ .string()
31
+ .regex(/^[A-Za-z]{3}$/)
32
+ .optional(),
23
33
  lists: z.record(z.string(), z.boolean()).optional(),
24
34
  idempotencyKey: z.string().optional(),
25
35
  timestamp: z.string().datetime().optional(),
@@ -121,6 +131,8 @@ export const eventsRouter = new OpenAPIHono<AppEnv>().openapi(
121
131
  anonymousId: body.anonymousId,
122
132
  eventProperties: body.eventProperties ?? {},
123
133
  contactProperties: body.contactProperties,
134
+ value: body.value,
135
+ currency: body.currency,
124
136
  idempotencyKey,
125
137
  // §2.5: caller-supplied event time (backfill/replay). The validated
126
138
  // ISO string is coerced to a Date inside ingestEvent.
@@ -265,21 +265,31 @@ export async function handleTrackedClick(
265
265
  : resolveEmailSendContext(db, emailSendId)
266
266
  )
267
267
  .then(async (ctx) => {
268
- await pushTrackingEvent({
269
- db,
270
- hatchet,
271
- registry,
272
- logger,
273
- event: EMAIL_LINK_CLICKED,
274
- emailSendId,
275
- properties: { linkUrl: link.originalUrl, linkId: link.id },
276
- resolvedContext: ctx,
277
- }).catch((err) => {
278
- logger.warn("Failed to push click tracking event", {
279
- linkId: link.id,
280
- error: err instanceof Error ? err.message : String(err),
268
+ // Bus re-ingest GATED on `!isBot` (impact plan §2.4 touch hygiene):
269
+ // `email.link_clicked` is a credit-bearing attribution touch AND a
270
+ // journey trigger, and inbox security scanners (Outlook SafeLinks,
271
+ // Barracuda, …) fetch email links with bot UAs — without the gate a
272
+ // scanner sweep mints touches and phantom journey triggers. The
273
+ // linkClicks row, clickCount, clickedAt, and the per-hit outbound
274
+ // emit below stay UNCONDITIONAL — stats record every hit; only the
275
+ // credit/journey spine is protected.
276
+ if (!isBot) {
277
+ await pushTrackingEvent({
278
+ db,
279
+ hatchet,
280
+ registry,
281
+ logger,
282
+ event: EMAIL_LINK_CLICKED,
283
+ emailSendId,
284
+ properties: { linkUrl: link.originalUrl, linkId: link.id },
285
+ resolvedContext: ctx,
286
+ }).catch((err) => {
287
+ logger.warn("Failed to push click tracking event", {
288
+ linkId: link.id,
289
+ error: err instanceof Error ? err.message : String(err),
290
+ });
281
291
  });
282
- });
292
+ }
283
293
 
284
294
  // Only emit when the send-context resolved. A missing emailSends row
285
295
  // (orphaned tracked link / deleted send) has no userId or recipient to
@@ -310,10 +320,8 @@ export async function handleTrackedClick(
310
320
  // `sms.link_clicked` bus event and emit the per-hit `sms.clicked`
311
321
  // outbound — the SMS sibling of the email branch above. The bus
312
322
  // re-ingest is GATED on `!isBot` (iMessage/WhatsApp/RCS link-preview
313
- // bots prefetch texted URLs — a phantom-enrollment risk the email
314
- // branch doesn't share because inbox clicks aren't unfurl-prefetched
315
- // the same way) AND on a resolved contact key (phone is NOT a contact
316
- // `Kind`; a userless raw send has no subject to ingest).
323
+ // bots prefetch texted URLs) AND on a resolved contact key (phone is
324
+ // NOT a contact `Kind`; a userless raw send has no subject to ingest).
317
325
  const smsSendId = link.smsSendId;
318
326
  void resolveSmsSendContext(db, smsSendId)
319
327
  .then(async (ctx) => {
@@ -0,0 +1,117 @@
1
+ import { WebhookHandshakeSignal } from "@hogsend/core";
2
+ import { createRoute, type OpenAPIHono, z } from "@hono/zod-openapi";
3
+ import type { Context } from "hono";
4
+ import type { AppEnv } from "../../app.js";
5
+ import { env } from "../../env.js";
6
+ import { ingestCrmStageEvents } from "../../lib/crm-ingest.js";
7
+ import { headersToRecord } from "../../lib/headers.js";
8
+
9
+ /**
10
+ * CRM-provider webhook dispatch for `POST /v1/webhooks/crm/:providerId` — the
11
+ * CRM sibling of the email/SMS provider routes. Resolves the provider from
12
+ * the container's {@link CrmProviderRegistry} (404 on unknown id), verifies
13
+ * with the EXACT received bytes + canonical public URL, and lands the
14
+ * normalized {@link CrmStageEvent}s on the spine via
15
+ * {@link ingestCrmStageEvents} (idempotent against the reconciliation poll).
16
+ */
17
+ export async function dispatchCrmProviderWebhook(
18
+ c: Context<AppEnv>,
19
+ providerId: string,
20
+ ) {
21
+ const { crmProviders, funnels, db, registry, hatchet, logger, analytics } =
22
+ c.get("container");
23
+
24
+ const provider = crmProviders.get(providerId);
25
+ if (!provider) {
26
+ return c.json({ error: "Unknown CRM provider" }, 404);
27
+ }
28
+
29
+ const payload = await c.req.text();
30
+ const headers = headersToRecord(c.req.raw.headers);
31
+
32
+ const requestUrl = new URL(c.req.url);
33
+ const base = env.API_PUBLIC_URL.replace(/\/+$/, "");
34
+ const url = `${base}${requestUrl.pathname}${requestUrl.search}`;
35
+
36
+ try {
37
+ const events = await provider.verifyWebhook({ payload, headers, url });
38
+ const result = await ingestCrmStageEvents({
39
+ db,
40
+ registry,
41
+ hatchet,
42
+ logger,
43
+ analytics,
44
+ providerId,
45
+ events,
46
+ funnels,
47
+ });
48
+ logger.info("CRM provider webhook processed", {
49
+ providerId,
50
+ events: events.length,
51
+ ...result,
52
+ });
53
+ return c.json({ received: events.length, ...result }, 200);
54
+ } catch (err) {
55
+ if (err instanceof WebhookHandshakeSignal) {
56
+ logger.info("CRM webhook handshake", { providerId, action: err.action });
57
+ return c.json({ ok: true }, 200);
58
+ }
59
+ logger.warn("CRM provider webhook failed", {
60
+ providerId,
61
+ error: err instanceof Error ? err.message : String(err),
62
+ });
63
+ return c.json({ error: "Webhook verification failed" }, 401);
64
+ }
65
+ }
66
+
67
+ const crmProviderWebhookRoute = createRoute({
68
+ method: "post",
69
+ path: "/v1/webhooks/crm/{providerId}",
70
+ tags: ["Webhooks"],
71
+ summary:
72
+ "CRM provider webhook receiver (pipeline stage changes + deal values)",
73
+ request: {
74
+ params: z.object({ providerId: z.string() }),
75
+ body: {
76
+ content: {
77
+ // Providers post arbitrary JSON (object OR array); verification reads
78
+ // the raw bytes, so the schema is deliberately permissive.
79
+ "application/json": { schema: z.unknown() },
80
+ },
81
+ },
82
+ },
83
+ responses: {
84
+ 200: {
85
+ content: {
86
+ "application/json": {
87
+ schema: z.object({
88
+ received: z.number().optional(),
89
+ ingested: z.number().optional(),
90
+ skipped: z.number().optional(),
91
+ ok: z.boolean().optional(),
92
+ }),
93
+ },
94
+ },
95
+ description: "Webhook processed",
96
+ },
97
+ 401: {
98
+ content: {
99
+ "application/json": { schema: z.object({ error: z.string() }) },
100
+ },
101
+ description: "Missing or invalid webhook signature",
102
+ },
103
+ 404: {
104
+ content: {
105
+ "application/json": { schema: z.object({ error: z.string() }) },
106
+ },
107
+ description: "Unknown CRM provider",
108
+ },
109
+ },
110
+ });
111
+
112
+ export function registerCrmProviderRoutes(app: OpenAPIHono<AppEnv>) {
113
+ app.openapi(crmProviderWebhookRoute, (c) => {
114
+ const { providerId } = c.req.valid("param");
115
+ return dispatchCrmProviderWebhook(c, providerId);
116
+ });
117
+ }
@@ -1,6 +1,7 @@
1
1
  import type { OpenAPIHono } from "@hono/zod-openapi";
2
2
  import type { AppEnv } from "../../app.js";
3
3
  import type { DefinedConnector } from "../../connectors/define-connector.js";
4
+ import { registerCrmProviderRoutes } from "./crm-provider.js";
4
5
  import { registerEmailProviderRoutes } from "./email-provider.js";
5
6
  import { resendWebhookRouter } from "./resend.js";
6
7
  import { registerSmsProviderRoutes } from "./sms-provider.js";
@@ -20,9 +21,12 @@ export function registerWebhookRoutes(
20
21
  // `email/` prefix — MUST come before the catch-all),
21
22
  // 3. the `/v1/webhooks/sms/:providerId` id-dispatched route (static `sms/`
22
23
  // prefix — MUST come before the catch-all),
23
- // 4. the `/v1/webhooks/:sourceId` consumer-source catch-all (LAST).
24
+ // 4. the `/v1/webhooks/crm/:providerId` id-dispatched route (static `crm/`
25
+ // prefix — MUST come before the catch-all),
26
+ // 5. the `/v1/webhooks/:sourceId` consumer-source catch-all (LAST).
24
27
  app.route("/v1/webhooks", resendWebhookRouter);
25
28
  registerEmailProviderRoutes(app);
26
29
  registerSmsProviderRoutes(app);
30
+ registerCrmProviderRoutes(app);
27
31
  registerWebhookSourceRoutes(app, opts.webhookConnectors);
28
32
  }