@hogsend/engine 0.65.0 → 0.67.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 (40) hide show
  1. package/package.json +12 -12
  2. package/src/account-links/battlenet.ts +84 -0
  3. package/src/account-links/epic.ts +87 -0
  4. package/src/account-links/index.ts +12 -5
  5. package/src/account-links/riot.ts +82 -0
  6. package/src/account-links/xbox.ts +92 -0
  7. package/src/app.ts +9 -1
  8. package/src/container.ts +77 -0
  9. package/src/env.ts +18 -2
  10. package/src/index.ts +84 -0
  11. package/src/lib/account-links-from-env.ts +94 -30
  12. package/src/lib/contacts.ts +94 -2
  13. package/src/lib/ingestion.ts +61 -0
  14. package/src/lib/links.ts +94 -11
  15. package/src/lib/outbound.ts +94 -0
  16. package/src/lib/referral-intent.ts +723 -0
  17. package/src/lib/referral-link.ts +200 -0
  18. package/src/lib/referral-registry.ts +83 -0
  19. package/src/lib/referral-report.ts +739 -0
  20. package/src/lib/referral-runtime.ts +49 -0
  21. package/src/lib/referrals-no-emit.test.ts +109 -0
  22. package/src/lib/referrals.ts +712 -0
  23. package/src/lib/snippet.ts +76 -0
  24. package/src/lib/webhook-signing.ts +10 -0
  25. package/src/routes/admin/api-keys.ts +5 -0
  26. package/src/routes/admin/index.ts +2 -0
  27. package/src/routes/admin/links.ts +14 -5
  28. package/src/routes/admin/referrals.ts +565 -0
  29. package/src/routes/contacts/index.ts +78 -0
  30. package/src/routes/index.ts +45 -0
  31. package/src/routes/referrals/index.ts +41 -0
  32. package/src/routes/referrals/me.ts +123 -0
  33. package/src/routes/referrals/report.ts +285 -0
  34. package/src/routes/referrals/shared.ts +34 -0
  35. package/src/routes/referrals/touch.ts +313 -0
  36. package/src/routes/snippet.test.ts +70 -0
  37. package/src/routes/snippet.ts +58 -0
  38. package/src/routes/tracking/arrive.ts +90 -0
  39. package/src/routes/tracking/click-pipeline.ts +8 -0
  40. package/src/workflows/import-contacts.ts +6 -0
@@ -318,6 +318,51 @@ export interface OutboundPayloads {
318
318
  userEmail: string;
319
319
  heldOutAt: string;
320
320
  };
321
+ /**
322
+ * A referral EDGE reached its first end: someone clicked a `shared` link and
323
+ * landed. `refereeContactId` is NULL on the (normal) cold path — the referee
324
+ * is a browser id, not yet a person — which is exactly why this event names
325
+ * only the REFERRER as its subject and mints no contact.
326
+ */
327
+ "referral.touched": ReferralTouchPayload;
328
+ /**
329
+ * The edge gained its second end: the referee identified and
330
+ * `adoptOrphanHistory` stamped the touch. Delivered ONCE per touch (one
331
+ * dedupe key), and re-ingested onto the journey bus for BOTH ends.
332
+ */
333
+ "referral.bound": ReferralTouchPayload & { boundAt: string; side: string };
334
+ /**
335
+ * A bound referee did the thing the program asked for (`qualify.event`, with
336
+ * optional `where`). Exactly once per touch — the store's
337
+ * `qualified_at IS NULL` predicate is the guard.
338
+ */
339
+ "referral.qualified": ReferralTouchPayload & {
340
+ event: string | null;
341
+ conversionId: string | null;
342
+ qualifiedAt: string;
343
+ side: string;
344
+ };
345
+ /** A referee converted; the DIRECT referrer is told (`level` is always 1). */
346
+ "referral.converted": ReferralConversionPayload;
347
+ /**
348
+ * An ANCESTOR above the direct referrer is told about the same conversion,
349
+ * one delivery per hop to depth 5. `level` is a FACT on the event: a reward
350
+ * journey filters with `trigger.where: (b) => b.prop("level").eq(1)`, and
351
+ * that is the only place levels appear in code. Depth and weights stay
352
+ * report-time parameters.
353
+ */
354
+ "referral.tree_converted": ReferralConversionPayload;
355
+ /**
356
+ * An edge was refused — `self` (the referee turned out to BE the referrer,
357
+ * which falls out of the identity merge rather than a fraud heuristic),
358
+ * `window` (the touch was older than `bindWindow` at identify),
359
+ * `duplicate`, or `veto` (a `before*` hook said no; its free text rides
360
+ * `detail`).
361
+ */
362
+ "referral.rejected": ReferralTouchPayload & {
363
+ reason: string | null;
364
+ detail?: string | null;
365
+ };
321
366
  /**
322
367
  * Weekly impact digest (impact experiments D5) — facts-only rollup of
323
368
  * shipped journey changes and holdout-lift threshold crossings, emitted
@@ -569,6 +614,55 @@ export interface ImpactDigestLiftEntry {
569
614
  smallSample: boolean;
570
615
  }
571
616
 
617
+ /**
618
+ * The shared shape of every touch-scoped referral event. Scalars only: these
619
+ * payloads double as the journey-bus `eventProperties`, and `ingestEvent`
620
+ * filters the Hatchet push down to `string | number | boolean | null`, so a
621
+ * nested field would be silently dropped between `user_events` and the journey
622
+ * (and a `where` clause naming it would never match).
623
+ */
624
+ export type ReferralTouchPayload = {
625
+ referralId: string;
626
+ touchId: string;
627
+ referrerContactId: string;
628
+ /** NULL until the edge binds. */
629
+ refereeContactId: string | null;
630
+ /** The canonical key at touch time — an ANONYMOUS id on a cold touch. */
631
+ refereeKey: string;
632
+ source: string;
633
+ linkId: string | null;
634
+ clickId: string | null;
635
+ status: string;
636
+ /** ISO 8601. */
637
+ touchedAt: string;
638
+ };
639
+
640
+ /** `referral.converted` / `referral.tree_converted`. */
641
+ export type ReferralConversionPayload = {
642
+ referralId: string;
643
+ touchId: string;
644
+ /** 1 = the direct referrer; 2+ = an ancestor. Capped at 5. */
645
+ level: number;
646
+ /** The contact being TOLD (who earns at this level). */
647
+ beneficiaryContactId: string;
648
+ /** The contact who actually converted. */
649
+ refereeContactId: string;
650
+ /** The next hop toward the referee — "your friend's friend". */
651
+ viaContactId: string;
652
+ conversionId: string;
653
+ /**
654
+ * The converted amount. NOT named `value`: this payload doubles verbatim as
655
+ * the journey-bus `eventProperties`, and a `value` there would fire the
656
+ * built-in wildcard `revenue` conversion (trigger `*` + `value > 0`) FOR THE
657
+ * BENEFICIARY - minting a phantom conversion on every ancestor and
658
+ * re-entering `convertReferral` up the whole chain.
659
+ */
660
+ conversionValue: number | null;
661
+ currency: string | null;
662
+ /** ISO 8601. */
663
+ at: string;
664
+ };
665
+
572
666
  export type ImpactDigestEntry =
573
667
  | ImpactDigestShippedEntry
574
668
  | ImpactDigestLiftEntry;