@hogsend/engine 0.42.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.
Files changed (75) hide show
  1. package/package.json +10 -7
  2. package/src/container.ts +419 -4
  3. package/src/destinations/define-destination.ts +7 -3
  4. package/src/destinations/presets/posthog.ts +31 -0
  5. package/src/env.ts +28 -0
  6. package/src/index.ts +138 -0
  7. package/src/journeys/execute-journey-run.ts +93 -0
  8. package/src/journeys/journey-boundary.ts +5 -1
  9. package/src/journeys/journey-context.ts +30 -0
  10. package/src/lib/attribution-backfill.ts +285 -0
  11. package/src/lib/attribution.ts +239 -0
  12. package/src/lib/contacts.ts +71 -0
  13. package/src/lib/conversion-dispatch.ts +326 -0
  14. package/src/lib/conversions.ts +197 -0
  15. package/src/lib/crm-deals.ts +320 -0
  16. package/src/lib/crm-ingest.ts +341 -0
  17. package/src/lib/crm-provider-registry.ts +41 -0
  18. package/src/lib/crm-registry-singleton.ts +22 -0
  19. package/src/lib/deal-money-events.ts +85 -0
  20. package/src/lib/email-service-types.ts +16 -1
  21. package/src/lib/event-names.ts +1 -1
  22. package/src/lib/funnel-progress.ts +76 -0
  23. package/src/lib/funnel-registry.ts +108 -0
  24. package/src/lib/funnel-transitions.ts +280 -0
  25. package/src/lib/holdout.ts +62 -0
  26. package/src/lib/ingestion.ts +218 -9
  27. package/src/lib/journey-suppress.ts +33 -2
  28. package/src/lib/lift-stats.ts +125 -0
  29. package/src/lib/mailer.ts +1 -0
  30. package/src/lib/operator.ts +31 -0
  31. package/src/lib/outbound.ts +109 -0
  32. package/src/lib/phone.ts +19 -0
  33. package/src/lib/preferences.ts +32 -0
  34. package/src/lib/revenue.ts +116 -0
  35. package/src/lib/sms-frequency-cap.ts +47 -0
  36. package/src/lib/sms-inbound.ts +200 -0
  37. package/src/lib/sms-link-tracking.ts +160 -0
  38. package/src/lib/sms-mailer.ts +338 -0
  39. package/src/lib/sms-provider-registry.ts +35 -0
  40. package/src/lib/sms-providers-from-env.ts +100 -0
  41. package/src/lib/sms-service-types.ts +175 -0
  42. package/src/lib/sms-tracked.ts +625 -0
  43. package/src/lib/sms.ts +117 -0
  44. package/src/lib/tracked.ts +40 -0
  45. package/src/lib/tracking-event-names.ts +6 -0
  46. package/src/lib/tracking-events.ts +133 -1
  47. package/src/lib/tracking.ts +2 -1
  48. package/src/lib/webhook-signing.ts +24 -1
  49. package/src/lists/channels.ts +21 -0
  50. package/src/routes/admin/attribution.ts +414 -0
  51. package/src/routes/admin/contacts.ts +71 -11
  52. package/src/routes/admin/conversions.ts +247 -0
  53. package/src/routes/admin/deals.ts +472 -0
  54. package/src/routes/admin/funnels.ts +228 -0
  55. package/src/routes/admin/index.ts +8 -0
  56. package/src/routes/admin/journeys.ts +158 -1
  57. package/src/routes/admin/readiness.ts +97 -2
  58. package/src/routes/admin/templates.ts +28 -1
  59. package/src/routes/email/unsubscribe.ts +1 -0
  60. package/src/routes/events/index.ts +12 -0
  61. package/src/routes/index.ts +6 -0
  62. package/src/routes/lists/index.ts +54 -7
  63. package/src/routes/tracking/click-pipeline.ts +105 -16
  64. package/src/routes/tracking/short.ts +61 -0
  65. package/src/routes/webhooks/crm-provider.ts +117 -0
  66. package/src/routes/webhooks/index.ts +9 -1
  67. package/src/routes/webhooks/sms-provider.ts +110 -0
  68. package/src/sources/define-contact-source.ts +159 -0
  69. package/src/sources/registry.ts +71 -0
  70. package/src/sources/webhook-source.ts +109 -0
  71. package/src/worker.ts +4 -0
  72. package/src/workflows/crm-reconcile.ts +129 -0
  73. package/src/workflows/dispatch-conversion.ts +31 -0
  74. package/src/workflows/import-contacts.ts +61 -4
  75. package/src/workflows/send-campaign.ts +5 -0
@@ -0,0 +1,247 @@
1
+ import { contacts, conversionDispatches, conversions } from "@hogsend/db";
2
+ import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
3
+ import { and, asc, count, desc, eq, sql } from "drizzle-orm";
4
+ import type { AppEnv } from "../../app.js";
5
+
6
+ /**
7
+ * Admin conversions API (docs/revenue-attribution-plan.md §5b.2) — fired
8
+ * conversion points and their per-destination delivery state. Answers the
9
+ * operator question "did the ad platform actually receive the sale?".
10
+ */
11
+
12
+ const dispatchSchema = z.object({
13
+ destinationId: z.string(),
14
+ status: z.string(),
15
+ attempts: z.number(),
16
+ lastError: z.string().nullable(),
17
+ deliveredAt: z.string().nullable(),
18
+ });
19
+
20
+ const conversionSchema = z.object({
21
+ id: z.string(),
22
+ definitionId: z.string(),
23
+ contactId: z.string(),
24
+ contactEmail: z.string().nullable(),
25
+ value: z.number().nullable(),
26
+ currency: z.string().nullable(),
27
+ /** The definition's declared scope (ConversionMeta.scope), if any. */
28
+ scopeJourneyId: z.string().nullable(),
29
+ scopeCampaignId: z.string().nullable(),
30
+ occurredAt: z.string(),
31
+ dispatches: z.array(dispatchSchema),
32
+ });
33
+
34
+ const listRoute = createRoute({
35
+ method: "get",
36
+ path: "/",
37
+ tags: ["Admin"],
38
+ summary: "List fired conversions with delivery state",
39
+ request: {
40
+ query: z.object({
41
+ definitionId: z.string().optional(),
42
+ /** Filter by the definition's declared scope (ConversionMeta.scope). */
43
+ journeyId: z.string().optional(),
44
+ campaignId: z.string().optional(),
45
+ /** Only conversions with at least one dispatch in this status. */
46
+ dispatchStatus: z.enum(["pending", "delivered", "failed"]).optional(),
47
+ sort: z
48
+ .enum(["occurredAt", "value", "definitionId"])
49
+ .default("occurredAt"),
50
+ dir: z.enum(["asc", "desc"]).default("desc"),
51
+ limit: z.coerce.number().min(1).max(200).default(50),
52
+ offset: z.coerce.number().min(0).default(0),
53
+ }),
54
+ },
55
+ responses: {
56
+ 200: {
57
+ content: {
58
+ "application/json": {
59
+ schema: z.object({
60
+ conversions: z.array(conversionSchema),
61
+ total: z.number(),
62
+ limit: z.number(),
63
+ offset: z.number(),
64
+ }),
65
+ },
66
+ },
67
+ description: "Paginated fired conversions, newest first",
68
+ },
69
+ },
70
+ });
71
+
72
+ const statsSchema = z.object({
73
+ /** Per-definition firing counts (30d window + lifetime). */
74
+ definitions: z.array(
75
+ z.object({
76
+ definitionId: z.string(),
77
+ count30d: z.number(),
78
+ countLifetime: z.number(),
79
+ lastFiredAt: z.string().nullable(),
80
+ }),
81
+ ),
82
+ /** Per-destination delivery health across all dispatches. */
83
+ destinations: z.array(
84
+ z.object({
85
+ destinationId: z.string(),
86
+ pending: z.number(),
87
+ delivered: z.number(),
88
+ failed: z.number(),
89
+ }),
90
+ ),
91
+ });
92
+
93
+ const statsRoute = createRoute({
94
+ method: "get",
95
+ path: "/stats",
96
+ tags: ["Admin"],
97
+ summary: "Conversion firing counts + destination delivery health",
98
+ responses: {
99
+ 200: {
100
+ content: { "application/json": { schema: statsSchema } },
101
+ description: "Definition and destination summaries",
102
+ },
103
+ },
104
+ });
105
+
106
+ export const adminConversionsRouter = new OpenAPIHono<AppEnv>()
107
+ .openapi(listRoute, async (c) => {
108
+ const { db } = c.get("container");
109
+ const query = c.req.valid("query");
110
+
111
+ const filters = [
112
+ ...(query.definitionId
113
+ ? [eq(conversions.definitionId, query.definitionId)]
114
+ : []),
115
+ ...(query.journeyId
116
+ ? [eq(conversions.scopeJourneyId, query.journeyId)]
117
+ : []),
118
+ ...(query.campaignId
119
+ ? [eq(conversions.scopeCampaignId, query.campaignId)]
120
+ : []),
121
+ ...(query.dispatchStatus
122
+ ? [
123
+ sql`exists (select 1 from conversion_dispatches d where d.conversion_id = ${conversions.id} and d.status = ${query.dispatchStatus})`,
124
+ ]
125
+ : []),
126
+ ];
127
+ const where = filters.length > 0 ? and(...filters) : undefined;
128
+
129
+ const sortColumns = {
130
+ occurredAt: conversions.occurredAt,
131
+ value: conversions.value,
132
+ definitionId: conversions.definitionId,
133
+ } as const;
134
+ const sortCol = sortColumns[query.sort];
135
+
136
+ const [rows, totalRows] = await Promise.all([
137
+ db
138
+ .select({ conversion: conversions, contactEmail: contacts.email })
139
+ .from(conversions)
140
+ .leftJoin(contacts, eq(conversions.contactId, contacts.id))
141
+ .where(where)
142
+ .orderBy(
143
+ query.dir === "asc" ? asc(sortCol) : desc(sortCol),
144
+ desc(conversions.occurredAt),
145
+ )
146
+ .limit(query.limit)
147
+ .offset(query.offset),
148
+ db.select({ total: count() }).from(conversions).where(where),
149
+ ]);
150
+
151
+ // One IN query for the page's dispatches beats a per-row join explosion.
152
+ const ids = rows.map((r) => r.conversion.id);
153
+ const dispatchRows =
154
+ ids.length > 0
155
+ ? await db
156
+ .select()
157
+ .from(conversionDispatches)
158
+ .where(
159
+ sql`${conversionDispatches.conversionId} in (${sql.join(
160
+ ids.map((id) => sql`${id}`),
161
+ sql`, `,
162
+ )})`,
163
+ )
164
+ : [];
165
+ const dispatchesByConversion = new Map<
166
+ string,
167
+ (typeof dispatchRows)[number][]
168
+ >();
169
+ for (const d of dispatchRows) {
170
+ const list = dispatchesByConversion.get(d.conversionId) ?? [];
171
+ list.push(d);
172
+ dispatchesByConversion.set(d.conversionId, list);
173
+ }
174
+
175
+ return c.json(
176
+ {
177
+ conversions: rows.map(({ conversion, contactEmail }) => ({
178
+ id: conversion.id,
179
+ definitionId: conversion.definitionId,
180
+ contactId: conversion.contactId,
181
+ contactEmail,
182
+ value: conversion.value,
183
+ currency: conversion.currency,
184
+ scopeJourneyId: conversion.scopeJourneyId,
185
+ scopeCampaignId: conversion.scopeCampaignId,
186
+ occurredAt: conversion.occurredAt.toISOString(),
187
+ dispatches: (dispatchesByConversion.get(conversion.id) ?? []).map(
188
+ (d) => ({
189
+ destinationId: d.destinationId,
190
+ status: d.status,
191
+ attempts: d.attempts,
192
+ lastError: d.lastError,
193
+ deliveredAt: d.deliveredAt?.toISOString() ?? null,
194
+ }),
195
+ ),
196
+ })),
197
+ total: totalRows[0]?.total ?? 0,
198
+ limit: query.limit,
199
+ offset: query.offset,
200
+ },
201
+ 200,
202
+ );
203
+ })
204
+ .openapi(statsRoute, async (c) => {
205
+ const { db } = c.get("container");
206
+ const thirtyDaysAgo = new Date(
207
+ Date.now() - 30 * 24 * 60 * 60 * 1000,
208
+ ).toISOString();
209
+
210
+ const [definitionRows, destinationRows] = await Promise.all([
211
+ db
212
+ .select({
213
+ definitionId: conversions.definitionId,
214
+ count30d: sql<number>`count(*) filter (where ${conversions.occurredAt} >= ${thirtyDaysAgo}::timestamptz)::int`,
215
+ countLifetime: count(),
216
+ lastFiredAt: sql<string | null>`max(${conversions.occurredAt})`,
217
+ })
218
+ .from(conversions)
219
+ .groupBy(conversions.definitionId),
220
+ db
221
+ .select({
222
+ destinationId: conversionDispatches.destinationId,
223
+ pending: sql<number>`count(*) filter (where ${conversionDispatches.status} = 'pending')::int`,
224
+ delivered: sql<number>`count(*) filter (where ${conversionDispatches.status} = 'delivered')::int`,
225
+ failed: sql<number>`count(*) filter (where ${conversionDispatches.status} = 'failed')::int`,
226
+ })
227
+ .from(conversionDispatches)
228
+ .groupBy(conversionDispatches.destinationId),
229
+ ]);
230
+
231
+ return c.json(
232
+ {
233
+ definitions: definitionRows
234
+ .map((row) => ({
235
+ definitionId: row.definitionId,
236
+ count30d: row.count30d,
237
+ countLifetime: Number(row.countLifetime),
238
+ lastFiredAt: row.lastFiredAt
239
+ ? new Date(row.lastFiredAt).toISOString()
240
+ : null,
241
+ }))
242
+ .sort((a, b) => b.count30d - a.count30d),
243
+ destinations: destinationRows,
244
+ },
245
+ 200,
246
+ );
247
+ });