@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.
- package/package.json +12 -9
- package/src/container.ts +289 -13
- 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/analytics-providers-from-env.ts +106 -43
- 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/posthog-scopes.ts +30 -6
- 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/unconfigured-email-provider.ts +45 -0
- package/src/lib/webhook-signing.ts +7 -0
- package/src/routes/admin/analytics.ts +14 -5
- 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
|
@@ -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([
|
|
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 {
|
|
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
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
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
|
|
314
|
-
//
|
|
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/:
|
|
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
|
}
|