@hogsend/engine 0.46.0 → 0.50.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 (70) hide show
  1. package/README.md +6 -0
  2. package/package.json +13 -10
  3. package/src/connectors/presets/index.ts +8 -2
  4. package/src/container.ts +149 -7
  5. package/src/destinations/presets/posthog.ts +7 -0
  6. package/src/destinations/presets/segment.ts +5 -0
  7. package/src/env.ts +38 -0
  8. package/src/flags/reconcile.ts +195 -0
  9. package/src/index.ts +79 -0
  10. package/src/journeys/authoring.ts +32 -0
  11. package/src/journeys/define-journey.ts +45 -40
  12. package/src/journeys/execute-journey-run.ts +73 -32
  13. package/src/journeys/journey-boundary.ts +76 -0
  14. package/src/journeys/journey-context.ts +128 -70
  15. package/src/journeys/journey-task-factory.ts +31 -0
  16. package/src/journeys/journey-task-runtime.ts +31 -0
  17. package/src/journeys/journey-version.test.ts +236 -0
  18. package/src/journeys/journey-version.ts +158 -0
  19. package/src/journeys/record-once.ts +28 -2
  20. package/src/lib/connector-actions.test.ts +36 -0
  21. package/src/lib/connector-actions.ts +42 -4
  22. package/src/lib/contacts.ts +49 -0
  23. package/src/lib/conversions.test.ts +33 -0
  24. package/src/lib/conversions.ts +8 -0
  25. package/src/lib/email.ts +23 -2
  26. package/src/lib/enrollment-policy.ts +51 -0
  27. package/src/lib/feed.ts +55 -3
  28. package/src/lib/flags-registry.ts +48 -0
  29. package/src/lib/flags.ts +498 -0
  30. package/src/lib/fx.ts +374 -0
  31. package/src/lib/global-control-readout.ts +166 -0
  32. package/src/lib/groups.ts +362 -0
  33. package/src/lib/ingestion.ts +38 -0
  34. package/src/lib/journey-lift.ts +142 -0
  35. package/src/lib/operator-settings.ts +71 -0
  36. package/src/lib/outbound.ts +147 -0
  37. package/src/lib/preferences.ts +6 -80
  38. package/src/lib/recipient-preferences.ts +53 -0
  39. package/src/lib/sms.ts +21 -2
  40. package/src/lib/stable-stringify.test.ts +42 -0
  41. package/src/lib/stable-stringify.ts +23 -0
  42. package/src/lib/variant.ts +99 -0
  43. package/src/lib/webhook-signing.ts +16 -1
  44. package/src/lists/registry.ts +6 -2
  45. package/src/lists/subscription.ts +13 -0
  46. package/src/routes/admin/contacts.ts +53 -4
  47. package/src/routes/admin/conversions.ts +137 -0
  48. package/src/routes/admin/flags.ts +369 -0
  49. package/src/routes/admin/groups.ts +866 -0
  50. package/src/routes/admin/impact-schemas.ts +44 -0
  51. package/src/routes/admin/impact-wire.test.ts +181 -0
  52. package/src/routes/admin/impact.ts +486 -0
  53. package/src/routes/admin/index.ts +12 -0
  54. package/src/routes/admin/journey-impact.ts +446 -0
  55. package/src/routes/admin/journeys.ts +70 -100
  56. package/src/routes/admin/readiness.ts +8 -8
  57. package/src/routes/admin/settings.ts +145 -0
  58. package/src/routes/admin/targeting.ts +256 -0
  59. package/src/routes/events/index.ts +11 -0
  60. package/src/routes/flags/index.ts +120 -0
  61. package/src/routes/groups/index.ts +417 -0
  62. package/src/routes/index.ts +23 -1
  63. package/src/testing.ts +25 -0
  64. package/src/webhook-sources/presets/index.ts +5 -1
  65. package/src/webhook-sources/presets/intercom.ts +230 -0
  66. package/src/webhook-sources/presets/segment.ts +56 -4
  67. package/src/worker.ts +3 -0
  68. package/src/workflows/bucket-backfill.ts +1 -14
  69. package/src/workflows/impact-digest.ts +761 -0
  70. package/src/workflows/journey-blueprint-interpreter.ts +18 -1
@@ -0,0 +1,230 @@
1
+ import { createHmac } from "node:crypto";
2
+ import { z } from "zod";
3
+ import type { IngestEvent } from "../../lib/ingestion.js";
4
+ import { defineWebhookSource } from "../define-webhook-source.js";
5
+ import { safeEqual } from "../verify.js";
6
+
7
+ /**
8
+ * Intercom (incl. Fin) webhook preset — support/chat as a lifecycle trigger.
9
+ *
10
+ * Auth: Intercom signs each delivery with `X-Hub-Signature: sha1=<hex>`, an
11
+ * HMAC-SHA1 of the RAW request body keyed with the app's client secret. The
12
+ * engine's built-in signature schemes are all SHA-256, so this preset uses the
13
+ * `signature` variant's custom `verify` escape hatch to recompute the SHA1 and
14
+ * constant-time compare via the shared {@link safeEqual}. Set
15
+ * `INTERCOM_CLIENT_SECRET` (your Intercom app's Client Secret) to auto-enable at
16
+ * `POST /v1/webhooks/intercom`. FAIL CLOSED when unset (the route 401s a
17
+ * `signature` source with no secret before this transform ever runs).
18
+ *
19
+ * Event mapping (Intercom notification `topic` → Hogsend `support.*`):
20
+ * - `conversation.user.created` → `support.conversation_started`
21
+ * - `conversation.admin.closed` → `support.resolved` (incl. Fin closes)
22
+ * - `conversation.admin.assigned` → `support.escalated` (handed to a human)
23
+ * - `conversation.rating.added` → `support.rated` (CSAT; carries `rating`)
24
+ * - anything else → `null` (skipped)
25
+ *
26
+ * Identity (load-bearing — folds onto the SAME Hogsend contact as the person's
27
+ * product/email activity): `userId` is the Intercom contact's `external_id`
28
+ * (the customer's OWN app user id) when present, so the resolver keys on the
29
+ * identified canonical key rather than minting a phantom twin. `userEmail` is
30
+ * always passed when Intercom has it (co-resolution key; the SOLE key when there
31
+ * is no `external_id`). Intercom's INTERNAL contact id is recorded as
32
+ * `contactProperties.intercomContactId` for reference ONLY, never as identity.
33
+ * With neither an `external_id` nor an email, the event can't be placed on a
34
+ * person and the transform returns `null`.
35
+ *
36
+ * D2 split: profile (`name`, `intercomContactId`) → `contactProperties`;
37
+ * conversation metadata (`conversationId`, `isAiResolved`, assignee/team,
38
+ * `rating`, `topic`) → `eventProperties`. `idempotencyKey = intercom:<id>`
39
+ * uses the notification envelope `id` (unique per delivery), mirroring Stripe.
40
+ */
41
+
42
+ const intercomPersonSchema = z
43
+ .object({
44
+ type: z.string().nullish(),
45
+ id: z.string().nullish(),
46
+ external_id: z.string().nullish(),
47
+ email: z.string().nullish(),
48
+ name: z.string().nullish(),
49
+ })
50
+ .catchall(z.unknown());
51
+
52
+ const intercomItemSchema = z
53
+ .object({
54
+ type: z.string().nullish(),
55
+ id: z.string().nullish(),
56
+ source: z
57
+ .object({ author: intercomPersonSchema.nullish() })
58
+ .catchall(z.unknown())
59
+ .nullish(),
60
+ // Intercom nests participating contacts under `contacts.contacts[]`.
61
+ contacts: z
62
+ .object({ contacts: z.array(intercomPersonSchema).nullish() })
63
+ .catchall(z.unknown())
64
+ .nullish(),
65
+ admin_assignee_id: z.union([z.string(), z.number()]).nullish(),
66
+ team_assignee_id: z.union([z.string(), z.number()]).nullish(),
67
+ conversation_rating: z
68
+ .object({ rating: z.number().nullish() })
69
+ .catchall(z.unknown())
70
+ .nullish(),
71
+ // Present on conversations Fin (the AI agent) participated in.
72
+ ai_agent_participated: z.boolean().nullish(),
73
+ })
74
+ .catchall(z.unknown());
75
+
76
+ const intercomWebhookSchema = z
77
+ .object({
78
+ type: z.string().nullish(),
79
+ id: z.string(),
80
+ topic: z.string(),
81
+ data: z.object({ item: intercomItemSchema }).catchall(z.unknown()),
82
+ })
83
+ .catchall(z.unknown());
84
+
85
+ type IntercomPayload = z.infer<typeof intercomWebhookSchema>;
86
+ type IntercomPerson = z.infer<typeof intercomPersonSchema>;
87
+
88
+ /** Intercom notification `topic` → Hogsend `support.*` event. */
89
+ const TOPIC_EVENT_MAP: Record<string, string> = {
90
+ "conversation.user.created": "support.conversation_started",
91
+ "conversation.admin.closed": "support.resolved",
92
+ "conversation.admin.assigned": "support.escalated",
93
+ "conversation.rating.added": "support.rated",
94
+ };
95
+
96
+ interface ResolvedIdentity {
97
+ externalId?: string;
98
+ email?: string;
99
+ name?: string;
100
+ intercomContactId?: string;
101
+ }
102
+
103
+ /**
104
+ * Resolve the human on the conversation. Only real people (the conversation
105
+ * author when it's a user/contact/lead, plus every participating contact) are
106
+ * candidates — an admin/bot author is skipped so a teammate's id never becomes
107
+ * the contact key. `external_id` (the customer's own app user id) and `email`
108
+ * are taken from the FIRST candidate that carries each; the Intercom internal
109
+ * contact id is captured for reference only.
110
+ */
111
+ function resolveIdentity(
112
+ item: IntercomPayload["data"]["item"],
113
+ ): ResolvedIdentity {
114
+ const candidates: IntercomPerson[] = [];
115
+ const author = item.source?.author;
116
+ if (
117
+ author &&
118
+ (author.type === "user" ||
119
+ author.type === "contact" ||
120
+ author.type === "lead")
121
+ ) {
122
+ candidates.push(author);
123
+ }
124
+ candidates.push(...(item.contacts?.contacts ?? []));
125
+
126
+ // Keep the first non-empty string seen for a field across the candidates.
127
+ const firstOf = (current: string | undefined, next: unknown) =>
128
+ current ?? (typeof next === "string" && next.length > 0 ? next : undefined);
129
+
130
+ const resolved: ResolvedIdentity = {};
131
+ for (const person of candidates) {
132
+ resolved.externalId = firstOf(resolved.externalId, person.external_id);
133
+ resolved.email = firstOf(resolved.email, person.email);
134
+ resolved.name = firstOf(resolved.name, person.name);
135
+ resolved.intercomContactId = firstOf(resolved.intercomContactId, person.id);
136
+ }
137
+ return resolved;
138
+ }
139
+
140
+ export const intercomSource = defineWebhookSource({
141
+ meta: {
142
+ id: "intercom",
143
+ name: "Intercom",
144
+ description:
145
+ "Receives Intercom/Fin conversation webhooks as support.* lifecycle events (X-Hub SHA1 signature-verified).",
146
+ },
147
+ auth: {
148
+ type: "signature",
149
+ // `scheme` is required by the type but ignored when `verify` is present —
150
+ // Intercom's SHA1 X-Hub scheme is not one of the built-in SHA-256 schemes.
151
+ scheme: "hmac-hex",
152
+ envKey: "INTERCOM_CLIENT_SECRET",
153
+ header: "x-hub-signature",
154
+ verify: ({ rawBody, headers, secret }) => {
155
+ const provided = headers["x-hub-signature"];
156
+ if (!provided) {
157
+ return false;
158
+ }
159
+ const expected = `sha1=${createHmac("sha1", secret)
160
+ .update(rawBody)
161
+ .digest("hex")}`;
162
+ return safeEqual(provided.trim(), expected);
163
+ },
164
+ },
165
+ schema: intercomWebhookSchema,
166
+ async transform(payload: IntercomPayload): Promise<IngestEvent | null> {
167
+ const event = TOPIC_EVENT_MAP[payload.topic];
168
+ if (!event) {
169
+ return null;
170
+ }
171
+
172
+ const item = payload.data.item;
173
+ const identity = resolveIdentity(item);
174
+
175
+ // Can't place the event on a person without an external id OR an email.
176
+ if (!identity.externalId && !identity.email) {
177
+ return null;
178
+ }
179
+
180
+ // D2 — conversation metadata → eventProperties ONLY.
181
+ const eventProperties: Record<string, unknown> = {
182
+ source: "intercom",
183
+ _intercomTopic: payload.topic,
184
+ };
185
+ if (typeof item.id === "string") {
186
+ eventProperties.conversationId = item.id;
187
+ }
188
+ if (typeof item.ai_agent_participated === "boolean") {
189
+ eventProperties.isAiResolved = item.ai_agent_participated;
190
+ }
191
+ if (
192
+ typeof item.admin_assignee_id === "string" ||
193
+ typeof item.admin_assignee_id === "number"
194
+ ) {
195
+ eventProperties.assigneeId = item.admin_assignee_id;
196
+ }
197
+ if (
198
+ typeof item.team_assignee_id === "string" ||
199
+ typeof item.team_assignee_id === "number"
200
+ ) {
201
+ eventProperties.teamId = item.team_assignee_id;
202
+ }
203
+ const rating = item.conversation_rating?.rating;
204
+ if (typeof rating === "number") {
205
+ eventProperties.rating = rating;
206
+ }
207
+
208
+ // D2 — durable profile → contactProperties ONLY. Intercom's internal id is
209
+ // a REFERENCE, never the identity key.
210
+ const contactProperties: Record<string, unknown> = {};
211
+ if (identity.name) {
212
+ contactProperties.name = identity.name;
213
+ }
214
+ if (identity.intercomContactId) {
215
+ contactProperties.intercomContactId = identity.intercomContactId;
216
+ }
217
+
218
+ return {
219
+ event,
220
+ // `userId` is the customer's own app user id (Intercom external_id) — the
221
+ // same key their product/email activity uses — so this folds onto the
222
+ // existing contact. Undefined when Intercom has no external_id (email-only).
223
+ userId: identity.externalId,
224
+ userEmail: identity.email,
225
+ eventProperties,
226
+ contactProperties,
227
+ idempotencyKey: `intercom:${payload.id}`,
228
+ };
229
+ },
230
+ });
@@ -1,6 +1,10 @@
1
1
  import { z } from "zod";
2
+ import { identifyGroup } from "../../lib/groups.js";
2
3
  import type { IngestEvent } from "../../lib/ingestion.js";
3
- import { defineWebhookSource } from "../define-webhook-source.js";
4
+ import {
5
+ defineWebhookSource,
6
+ type WebhookSourceCtx,
7
+ } from "../define-webhook-source.js";
4
8
 
5
9
  /**
6
10
  * Segment webhook preset.
@@ -12,7 +16,11 @@ import { defineWebhookSource } from "../define-webhook-source.js";
12
16
  * Event mapping (decision #16):
13
17
  * - `identify` → `contact.updated` (traits → `contactProperties` ONLY)
14
18
  * - `track` → the literal `event` name (properties → `eventProperties` ONLY)
15
- * - `page` / `screen` / `group` / `alias` → skipped (`null`)
19
+ * - `group` → `segment.group`: writes the `company` group + its traits and
20
+ * associates the contact (Segment's group model is single-type). The webhook
21
+ * is HMAC-signed (trusted server-to-server), so writing group PROPERTIES from
22
+ * it is safe — unlike a publishable browser key, which may only associate.
23
+ * - `page` / `screen` / `alias` → skipped (`null`)
16
24
  *
17
25
  * Identity: `userId = userId ?? anonymousId`; `email` lifted from
18
26
  * `traits.email`/`context.traits.email`. `idempotencyKey = messageId` so
@@ -28,6 +36,8 @@ const segmentWebhookSchema = z
28
36
  messageId: z.string().nullish(),
29
37
  userId: z.string().nullish(),
30
38
  anonymousId: z.string().nullish(),
39
+ // Segment `group` calls carry the group's external id here.
40
+ groupId: z.string().nullish(),
31
41
  traits: segmentTraitsSchema.nullish(),
32
42
  properties: z.record(z.string(), z.unknown()).nullish(),
33
43
  context: z
@@ -62,7 +72,10 @@ export const segmentSource = defineWebhookSource({
62
72
  header: "x-signature",
63
73
  },
64
74
  schema: segmentWebhookSchema,
65
- async transform(payload: SegmentPayload): Promise<IngestEvent | null> {
75
+ async transform(
76
+ payload: SegmentPayload,
77
+ ctx: WebhookSourceCtx,
78
+ ): Promise<IngestEvent | null> {
66
79
  const userId = payload.userId ?? payload.anonymousId ?? undefined;
67
80
  if (!userId) {
68
81
  return null;
@@ -114,7 +127,46 @@ export const segmentSource = defineWebhookSource({
114
127
  };
115
128
  }
116
129
 
117
- // page / screen / group / alias → skip.
130
+ if (payload.type === "group") {
131
+ // Segment's `group` call: a company/account association plus its traits.
132
+ // Single-type group model → default the groupType to "company".
133
+ const groupId = payload.groupId ?? undefined;
134
+ if (!groupId) {
135
+ return null;
136
+ }
137
+
138
+ // (1) Write the group + its traits. Safe because the Segment webhook is
139
+ // HMAC-signed (trusted server-to-server). NOTE: the outbound
140
+ // `group.identified` webhook does NOT fire from here — a webhook-source
141
+ // `ctx` has no `hatchet`; the `POST /v1/groups` HTTP route owns that
142
+ // fan-out. This path still lands the group, its traits, AND (via the
143
+ // returned IngestEvent) the membership + Events-feed observability.
144
+ await identifyGroup({
145
+ db: ctx.db,
146
+ groupType: "company",
147
+ groupKey: groupId,
148
+ properties: traits,
149
+ logger: ctx.logger,
150
+ });
151
+
152
+ // (2) Carry the association so the ingest pipeline resolves the contact
153
+ // and creates the MEMBERSHIP via the existing associateGroups path.
154
+ return {
155
+ event: "segment.group",
156
+ userId,
157
+ userEmail,
158
+ groups: { company: groupId },
159
+ eventProperties: {
160
+ source: "segment",
161
+ _segmentType: "group",
162
+ groupId,
163
+ },
164
+ contactProperties: {},
165
+ ...(idempotencyKey ? { idempotencyKey } : {}),
166
+ };
167
+ }
168
+
169
+ // page / screen / alias → skip.
118
170
  return null;
119
171
  },
120
172
  });
package/src/worker.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import type { DefinedBucket } from "./buckets/define-bucket.js";
2
+ import "./journeys/journey-task-runtime.js";
2
3
  import {
3
4
  collectBucketReactionJourneys,
4
5
  selectBucketReactionTasks,
@@ -30,6 +31,7 @@ import {
30
31
  reapDueWebhookDeliveriesTask,
31
32
  } from "./workflows/deliver-webhook.js";
32
33
  import { dispatchConversionTask } from "./workflows/dispatch-conversion.js";
34
+ import { impactDigestTask } from "./workflows/impact-digest.js";
33
35
  import { importContactsTask } from "./workflows/import-contacts.js";
34
36
  import { importSuppressionsTask } from "./workflows/import-suppressions.js";
35
37
  import { journeyBlueprintInterpreter } from "./workflows/journey-blueprint-interpreter.js";
@@ -127,6 +129,7 @@ export function createWorker(opts: CreateWorkerOptions): Worker {
127
129
  reapDueWebhookDeliveriesTask,
128
130
  confirmSemanticClickTask,
129
131
  checkAlertsTask,
132
+ impactDigestTask,
130
133
  bucketReconcileTask,
131
134
  bucketBackfillTask,
132
135
  crmReconcileTask,
@@ -28,6 +28,7 @@ import { contactKeySql, normalizeEmailOrNull } from "../lib/contacts.js";
28
28
  import { hatchet } from "../lib/hatchet.js";
29
29
  import type { Logger } from "../lib/logger.js";
30
30
  import { createLogger } from "../lib/logger.js";
31
+ import { stableStringify } from "../lib/stable-stringify.js";
31
32
 
32
33
  /** Insert chunk size, reusing the import-contacts precedent (Section 6.6). */
33
34
  const BATCH_SIZE = 500;
@@ -50,20 +51,6 @@ export function computeCriteriaHash(
50
51
  .digest("hex");
51
52
  }
52
53
 
53
- function stableStringify(value: unknown): string {
54
- if (value === null || typeof value !== "object") {
55
- return JSON.stringify(value);
56
- }
57
- if (Array.isArray(value)) {
58
- return `[${value.map(stableStringify).join(",")}]`;
59
- }
60
- const entries = Object.entries(value as Record<string, unknown>)
61
- .filter(([, v]) => v !== undefined)
62
- .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
63
- .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`);
64
- return `{${entries.join(",")}}`;
65
- }
66
-
67
54
  /**
68
55
  * Engine-owned backfill / criteria-change re-evaluation task (Section 6.6). Runs in
69
56
  * two modes: