@hogsend/engine 0.66.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.
- package/package.json +12 -12
- package/src/container.ts +77 -0
- package/src/index.ts +78 -0
- package/src/lib/contacts.ts +70 -0
- package/src/lib/ingestion.ts +61 -0
- package/src/lib/links.ts +94 -11
- package/src/lib/outbound.ts +94 -0
- package/src/lib/referral-intent.ts +723 -0
- package/src/lib/referral-link.ts +200 -0
- package/src/lib/referral-registry.ts +83 -0
- package/src/lib/referral-report.ts +739 -0
- package/src/lib/referral-runtime.ts +49 -0
- package/src/lib/referrals-no-emit.test.ts +109 -0
- package/src/lib/referrals.ts +712 -0
- package/src/lib/webhook-signing.ts +10 -0
- package/src/routes/admin/api-keys.ts +5 -0
- package/src/routes/admin/index.ts +2 -0
- package/src/routes/admin/links.ts +14 -5
- package/src/routes/admin/referrals.ts +565 -0
- package/src/routes/contacts/index.ts +78 -0
- package/src/routes/index.ts +39 -0
- package/src/routes/referrals/index.ts +41 -0
- package/src/routes/referrals/me.ts +123 -0
- package/src/routes/referrals/report.ts +285 -0
- package/src/routes/referrals/shared.ts +34 -0
- package/src/routes/referrals/touch.ts +313 -0
- package/src/routes/tracking/arrive.ts +90 -0
- package/src/routes/tracking/click-pipeline.ts +8 -0
package/src/lib/outbound.ts
CHANGED
|
@@ -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;
|