@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
@@ -0,0 +1,76 @@
1
+ import { createHash } from "node:crypto";
2
+ import { existsSync, readFileSync } from "node:fs";
3
+ import { createRequire } from "node:module";
4
+ import { dirname, join, resolve } from "node:path";
5
+ import { fileURLToPath } from "node:url";
6
+
7
+ /**
8
+ * The drop-in browser snippet: `@hogsend/js` builds a single minified IIFE to
9
+ * `dist/hogsend.js`, and the engine serves it first-party at `GET /hogsend.js`
10
+ * so a site with no bundler can paste one `<script>` tag.
11
+ *
12
+ * Like the Studio SPA, `@hogsend/js` is NOT a code import of the engine — the
13
+ * asset is located on disk at boot (so consumer bundlers never inline it) and
14
+ * serving is best-effort: no file, no route (404), never a boot crash.
15
+ *
16
+ * Resolution order:
17
+ * 1. `HOGSEND_JS_PATH` env var (explicit file path; absolute or cwd-relative).
18
+ * 2. `require.resolve("@hogsend/js/package.json")` → sibling `dist/hogsend.js`
19
+ * (the package is installed alongside the engine).
20
+ * 3. Monorepo source layout: `packages/js/dist/hogsend.js` relative to here.
21
+ * 4. cwd-relative `packages/js/dist/hogsend.js`.
22
+ */
23
+ export function resolveSnippetPath(): string | null {
24
+ const candidates: string[] = [];
25
+
26
+ const envPath = process.env.HOGSEND_JS_PATH;
27
+ if (envPath && envPath.length > 0) {
28
+ candidates.push(resolve(process.cwd(), envPath));
29
+ }
30
+
31
+ const require = createRequire(import.meta.url);
32
+ try {
33
+ const pkgJson = require.resolve("@hogsend/js/package.json");
34
+ candidates.push(join(dirname(pkgJson), "dist", "hogsend.js"));
35
+ } catch {
36
+ // Not installed next to the engine — fall through to layout guesses.
37
+ }
38
+
39
+ const here = dirname(fileURLToPath(import.meta.url));
40
+ candidates.push(resolve(here, "../../../js/dist/hogsend.js"));
41
+ candidates.push(resolve(process.cwd(), "packages/js/dist/hogsend.js"));
42
+ candidates.push(resolve(process.cwd(), "../../packages/js/dist/hogsend.js"));
43
+
44
+ for (const file of candidates) {
45
+ if (existsSync(file)) return file;
46
+ }
47
+ return null;
48
+ }
49
+
50
+ export interface LoadedSnippet {
51
+ /** The JS source, served verbatim. */
52
+ body: string;
53
+ /** Strong ETag: quoted sha256 prefix of the body. */
54
+ etag: string;
55
+ /** Where it was read from (logging). */
56
+ path: string;
57
+ }
58
+
59
+ /**
60
+ * Read the snippet ONCE. The body is small (tens of KB) and immutable for the
61
+ * life of the process, so it stays in memory; the ETag is content-derived so
62
+ * clients revalidate cheaply and a new build invalidates naturally.
63
+ */
64
+ export function loadSnippet(
65
+ path: string | null = resolveSnippetPath(),
66
+ ): LoadedSnippet | null {
67
+ if (!path) return null;
68
+ let body: string;
69
+ try {
70
+ body = readFileSync(path, "utf8");
71
+ } catch {
72
+ return null;
73
+ }
74
+ const hash = createHash("sha256").update(body).digest("hex").slice(0, 32);
75
+ return { body, etag: `"${hash}"`, path };
76
+ }
@@ -118,6 +118,16 @@ export const WEBHOOK_EVENT_TYPES = [
118
118
  "account.linked",
119
119
  "account.unlinked",
120
120
  "account.link_failed",
121
+ // Referrals (`defineReferral`, PRD 05). Emitted from the referral INTENT
122
+ // layer only (`lib/referral-intent.ts`), never from the store, which never
123
+ // emits. `level` on `referral.tree_converted` is a FACT on the event, not
124
+ // program config: depth and weights stay report-time parameters.
125
+ "referral.touched",
126
+ "referral.bound",
127
+ "referral.qualified",
128
+ "referral.converted",
129
+ "referral.tree_converted",
130
+ "referral.rejected",
121
131
  // Weekly impact digest (impact experiments D5). Self-referential: the
122
132
  // cron watermarks off its own delivery rows.
123
133
  "impact.digest",
@@ -120,6 +120,11 @@ const createKeyRoute = createRoute({
120
120
  // SCOPE_HIERARCHY edit and no migration (`api_keys.scopes`
121
121
  // is a jsonb string array).
122
122
  "accounts",
123
+ // The referral data plane (`/v1/referrals` report, tree,
124
+ // touch, import). ORTHOGONAL for the same reason
125
+ // `accounts` is; `/v1/referrals/me` is NOT covered by it
126
+ // (that one is publishable + userToken).
127
+ "referrals",
123
128
  ]),
124
129
  )
125
130
  .min(1)
@@ -37,6 +37,7 @@ import { openEditorRouter } from "./open-editor.js";
37
37
  import { preferencesRouter } from "./preferences.js";
38
38
  import { providerCredentialsRouter } from "./provider-credentials.js";
39
39
  import { readinessRouter } from "./readiness.js";
40
+ import { adminReferralsRouter } from "./referrals.js";
40
41
  import { reportingRouter } from "./reporting.js";
41
42
  import { settingsRouter } from "./settings.js";
42
43
  import { suppressionsRouter } from "./suppressions.js";
@@ -67,6 +68,7 @@ adminRouter.route("/conversions", adminConversionsRouter);
67
68
  adminRouter.route("/attribution", adminAttributionRouter);
68
69
  adminRouter.route("/funnels", adminFunnelsRouter);
69
70
  adminRouter.route("/groups", groupsRouter);
71
+ adminRouter.route("/referrals", adminReferralsRouter);
70
72
  adminRouter.route("/flags", adminFlagsRouter);
71
73
  adminRouter.route("/targeting", targetingRouter);
72
74
  adminRouter.route("/events", eventsRouter);
@@ -67,7 +67,10 @@ const linkSchema = z.object({
67
67
  // link somehow has no tracked row — kept nullable to stay total.
68
68
  trackedLinkId: z.string().nullable(),
69
69
  originalUrl: z.string(),
70
- type: z.enum(["personal", "public"]),
70
+ type: z.enum(["personal", "public", "shared"]),
71
+ // The credited owner of a "shared" (referral) link; null otherwise. An
72
+ // ATTRIBUTION field, never an identity one - a shared link stitches nobody.
73
+ ownerContactId: z.string().nullable(),
71
74
  // Vanity slug (normalized lowercase, unique per instance) + its short URL
72
75
  // (`${API_PUBLIC_URL}/l/:slug`). Both null when no slug is set.
73
76
  slug: z.string().nullable(),
@@ -157,8 +160,10 @@ function serializeLink(
157
160
  id: row.id,
158
161
  trackedLinkId,
159
162
  originalUrl: row.originalUrl,
160
- // The column is a free text; mintLink only ever writes these two values.
161
- type: row.type === "personal" ? "personal" : "public",
163
+ // The column is free text; mintLink only ever writes these three values.
164
+ type:
165
+ row.type === "personal" || row.type === "shared" ? row.type : "public",
166
+ ownerContactId: row.ownerContactId,
162
167
  slug: row.slug,
163
168
  vanityUrl: row.slug ? vanityUrlFor(baseUrl, row.slug) : null,
164
169
  label: row.label,
@@ -193,7 +198,10 @@ const createLinkRoute = createRoute({
193
198
  schema: z
194
199
  .object({
195
200
  url: z.string().url(),
196
- type: z.enum(["personal", "public"]).default("public"),
201
+ type: z.enum(["personal", "public", "shared"]).default("public"),
202
+ // REQUIRED for type "shared", rejected on personal/public
203
+ // (mintLink's ownership invariant -> 400).
204
+ ownerContactId: z.string().uuid().optional(),
197
205
  // Optional vanity slug (`/l/:slug`). Normalized lowercase; 409 if
198
206
  // already taken by a different destination (same destination +
199
207
  // type recovers the existing link — see idempotencyKey).
@@ -252,7 +260,7 @@ const listLinksRoute = createRoute({
252
260
  query: z.object({
253
261
  limit: z.coerce.number().min(1).max(200).default(50),
254
262
  offset: z.coerce.number().min(0).default(0),
255
- type: z.enum(["personal", "public"]).optional(),
263
+ type: z.enum(["personal", "public", "shared"]).optional(),
256
264
  includeArchived: z.coerce.boolean().default(false),
257
265
  // true = only links whose QR scan row exists — the "QR codes" lens
258
266
  // (a QR code IS a managed link whose QR row has been minted).
@@ -448,6 +456,7 @@ export const linksRouter = new OpenAPIHono<AppEnv>()
448
456
  appendRef: body.appendRef,
449
457
  campaign: body.campaign,
450
458
  distinctId: body.distinctId,
459
+ ownerContactId: body.ownerContactId,
451
460
  createdBy: resolveActor(c) ?? undefined,
452
461
  idempotencyKey: body.idempotencyKey,
453
462
  });