@hogsend/engine 0.21.1 → 0.23.0

package/src/lib/identity-service.ts

@@ -0,0 +1,107 @@
+import type { AnalyticsProvider } from "@hogsend/core";
+import type { Database } from "@hogsend/db";
+import {
+  logResidualTwins,
+  mergeAnalyticsIdentities,
+} from "./analytics-identity.js";
+import { resolveOrCreateContact } from "./contacts.js";
+import type { Logger } from "./logger.js";
+
+/**
+ * Args for {@link IdentityService.linkContact} — the same identity-attach inputs
+ * `resolveOrCreateContact` accepts (at least one of `userId`/`email`/
+ * `anonymousId`/`discordId` is required by the resolver), minus the `db` (the
+ * service closes over the container's db).
+ */
+export interface LinkContactArgs {
+  userId?: string;
+  email?: string;
+  anonymousId?: string;
+  discordId?: string;
+  contactProperties?: Record<string, unknown>;
+}
+
+/**
+ * The container-held identity helper (`client.identity`). It exists so any
+ * identity-attach OUTSIDE the `/v1/events` ingest path — most notably Discord
+ * `/link` (§7), but also any consumer wiring — folds two keys into one analytics
+ * person through the SAME engine emission used by `ingestEvent` (§5.3), rather
+ * than each consumer hand-rolling its own `resolveOrCreateContact` +
+ * `mergeIdentities` plumbing (the bespoke path the spec calls out as the bug).
+ */
+export interface IdentityService {
+  /**
+   * Resolve / merge a contact AND propagate the analytics merge in one call.
+   *
+   * Wraps `resolveOrCreateContact` (the resolver stays analytics-free — it takes
+   * only `db`) then, on a collide-MERGE or canonical-key flip that absorbed an
+   * anonymous/uuid key, fans out the provider-neutral `mergeIdentities` primitive
+   * via {@link mergeAnalyticsIdentities} with `reason: "discord_link"`. MF-2:
+   * `mergedKeys` already excludes identified `external_id`s (the resolver split
+   * them out) — only the safe anon/uuid keys are aliased; the excluded
+   * identified twins surface as `identity.merge.residual_twin` for observability.
+   *
+   * The SURVIVOR RULE makes `resolvedKey` the survivor (`distinctId`) and each
+   * loser its absorbed `alias` — e.g. on a Discord `/link` that merges the
+   * discord-keyed contact into the email contact, `distinctId = resolvedKey`
+   * (survivor, email/external) and `alias = <discord-contact uuid>` (the
+   * loser's anon/uuid key the Discord-platform events were captured under).
+   *
+   * Best-effort and analytics-non-load-bearing: the merge emission never throws
+   * (the helper swallows provider errors), so a missing/incapable provider
+   * no-ops cleanly — the contact resolve still happened and is returned.
+   */
+  linkContact(args: LinkContactArgs): ReturnType<typeof resolveOrCreateContact>;
+}
+
+/**
+ * Build the {@link IdentityService} bound to a container's db + active analytics
+ * provider. `analytics` is undefined when nothing is configured (the merge
+ * emission no-ops); the resolver itself is unaffected.
+ */
+export function createIdentityService(deps: {
+  db: Database;
+  analytics?: AnalyticsProvider;
+  logger?: Logger;
+}): IdentityService {
+  const { db, analytics, logger } = deps;
+
+  return {
+    async linkContact(args) {
+      const result = await resolveOrCreateContact({ db, ...args });
+
+      const {
+        id: contactId,
+        resolvedKey,
+        mergedKeys,
+        mergedIdentifiedKeys,
+      } = result;
+
+      // §5.3 emission point 1, reused (§7): fire the analytics merge ONLY when
+      // the resolver actually folded keys this call. MF-2: `mergedKeys` carries
+      // the safe anon/uuid losers (the discord-contact uuid on a `/link` merge);
+      // identified `external_id`s are excluded by the resolver and surfaced as
+      // residual twins below — never aliased (the merge PostHog refuses, R2/R4).
+      if (mergedKeys?.length) {
+        mergeAnalyticsIdentities({
+          analytics,
+          survivorKey: resolvedKey,
+          loserKeys: mergedKeys,
+          reason: "discord_link",
+          contactId,
+          logger,
+        });
+      }
+      if (mergedIdentifiedKeys?.length) {
+        logResidualTwins({
+          survivorKey: resolvedKey,
+          identifiedLoserKeys: mergedIdentifiedKeys,
+          contactId,
+          logger,
+        });
+      }
+
+      return result;
+    },
+  };
+}

package/src/lib/identity-token.ts

@@ -8,8 +8,12 @@ import {
 /**
  * Short-lived identity token appended to tracked-link redirects as `hs_t`
  * (opt-in via TRACKING_IDENTITY_TOKEN). The landing site exchanges it at
- * `POST /v1/t/identify` for the distinct id and calls `posthog.identify` —
- * stitching the email click to the web session.
+ * `POST /v1/t/identify`, where the engine fires a SERVER-SIDE `alias` folding
+ * the caller's own anon session into the token's canonical id — stitching the
+ * click to the web session. Minted for EMAIL links by default; non-email
+ * (Discord/referral) links carry a token only when explicitly stitch-bearing
+ * (`tracked_links.distinct_id` set) — referral links are token-less by default
+ * (MF-4 anti-hijack).
  *
  * ENCRYPTED (AES-256-GCM keyed off BETTER_AUTH_SECRET), not merely signed:
  * the distinct id can fall back to an email address, and a signed-but-
@@ -18,11 +22,38 @@ import {
  * auth tag also covers integrity, so tampering fails decryption.
  */
 
+/**
+ * The only merge mode a token may authorize: fold the CALLER's own anonymous
+ * session INTO the token's canonical `distinctId`. There is deliberately no
+ * "become the subject" / overwrite mode — that is the anti-hijack invariant.
+ */
+export type IdentityTokenScope = "anon-absorb";
+
 export interface IdentityTokenPayload {
-  /** The distinct id the landing site should identify as. */
+  /**
+   * The canonical contact key the landing site should fold INTO — the ONLY
+   * ever-identified id. NEVER a per-link or anonymous id.
+   */
   distinctId: string;
-  emailSendId: string;
+  /**
+   * Where the token was minted: `"email:<sendId>"` | `"link:<linkId>"`.
+   * Referral links are excluded by default (they carry no identity token).
+   */
+  src: string;
+  /**
+   * The authorized merge mode. Only `"anon-absorb"` is ever minted. OPTIONAL on
+   * the wire for the rolling-deploy window (MF-7): a token minted by the still-old
+   * click route carries no `scope`, so `validateIdentityToken` treats a MISSING
+   * scope as `"anon-absorb"` (allow) and rejects only a PRESENT-and-wrong value.
+   */
+  scope?: IdentityTokenScope;
   exp: number;
+  /**
+   * @deprecated Alias of `src` for ONE minor (mirrors the `resendId` → `messageId`
+   * deprecation window). Old tokens carry only `emailSendId`; new email tokens
+   * carry both. Reads should prefer `src`.
+   */
+  emailSendId?: string;
 }
 
 export class InvalidIdentityTokenError extends Error {
@@ -43,11 +74,27 @@ function deriveKey(secret: string): Buffer {
 export function generateIdentityToken(opts: {
   secret: string;
   distinctId: string;
-  emailSendId: string;
+  /**
+   * Mint provenance: `"email:<sendId>"` | `"link:<linkId>"`. When omitted, falls
+   * back to `email:<emailSendId>` for the legacy email-link caller.
+   */
+  src?: string;
+  /** Defaults to `"anon-absorb"` — the only mode a token may authorize. */
+  scope?: IdentityTokenScope;
+  /**
+   * @deprecated Pass `src` instead. Kept for the one-minor deprecation window so
+   * existing email-link callers compile unchanged; mirrored into the payload's
+   * deprecated `emailSendId` field and used to synthesize `src` when `src` is
+   * absent.
+   */
+  emailSendId?: string;
   expiresInSeconds?: number;
 }): string {
+  const src = opts.src ?? (opts.emailSendId ? `email:${opts.emailSendId}` : "");
   const payload: IdentityTokenPayload = {
     distinctId: opts.distinctId,
+    src,
+    scope: opts.scope ?? "anon-absorb",
     emailSendId: opts.emailSendId,
     exp:
       Math.floor(Date.now() / 1000) +
@@ -108,5 +155,18 @@ export function validateIdentityToken(opts: {
   if (payload.exp < Math.floor(Date.now() / 1000)) {
     throw new InvalidIdentityTokenError("Token expired");
   }
+  // MF-7 — missing-scope-ALLOW. The API and worker deploy independently from
+  // the same image, so a token minted by the still-old click route carries no
+  // `scope`. Treat a MISSING scope as the only legal mode (`"anon-absorb"`);
+  // reject ONLY a present-and-wrong value. Old tokens (no `scope`, no `src`)
+  // still validate — this check never widened the required-shape gate above.
+  if (payload.scope !== undefined && payload.scope !== "anon-absorb") {
+    throw new InvalidIdentityTokenError("Unsupported token scope");
+  }
+  // Backfill `src` from the deprecated `emailSendId` for old tokens, so the one
+  // response schema (`{ distinctId, src, emailSendId? }`) is always populated.
+  if (typeof payload.src !== "string" || payload.src.length === 0) {
+    payload.src = payload.emailSendId ? `email:${payload.emailSendId}` : "";
+  }
   return payload;
 }

package/src/lib/ingestion.ts

@@ -1,9 +1,14 @@
 import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
+import type { AnalyticsProvider } from "@hogsend/core";
 import { evaluatePropertyConditions } from "@hogsend/core";
 import type { JourneyRegistry } from "@hogsend/core/registry";
 import { type Database, journeyStates, userEvents } from "@hogsend/db";
 import { and, eq, inArray, isNull } from "drizzle-orm";
 import { checkBucketMembership } from "../buckets/check-membership.js";
+import {
+  logResidualTwins,
+  mergeAnalyticsIdentities,
+} from "./analytics-identity.js";
 import { resolveOrCreateContact } from "./contacts.js";
 import type { Logger } from "./logger.js";
 
@@ -14,6 +19,11 @@ export interface IngestEvent {
   userEmail?: string;
   /** D1: future anonymous→identified path. Threaded into the resolver. */
   anonymousId?: string;
+  /**
+   * Discord user id (snowflake). Resolves a `discord`-keyed contact (a later
+   * per-member link merges it into the email contact).
+   */
+  discordId?: string;
   /** D2: → `user_events` + Hatchet `trigger.where`/`exitOn` ONLY. */
   eventProperties: Record<string, unknown>;
   /** D2: → `contacts.properties` merge ONLY. */
@@ -53,8 +63,17 @@ export async function ingestEvent(opts: {
   hatchet: HatchetClient;
   logger: Logger;
   event: IngestEvent;
+  /**
+   * The active analytics provider (`c.get("container").analytics`). When the
+   * identity resolve folds two keys into one (collide-MERGE or canonical-key
+   * flip), the engine fires the provider-neutral `mergeIdentities` primitive so
+   * the analytics person store stitches the same way the contact store did
+   * (§5.3). Optional: absent ⇒ DB-only resolve (no stitch), exactly as before; a
+   * provider without `identityMerge` no-ops cleanly.
+   */
+  analytics?: AnalyticsProvider;
 }): Promise<IngestResult> {
-  const { db, registry, hatchet, logger, event } = opts;
+  const { db, registry, hatchet, logger, event, analytics } = opts;
 
   // (1) Resolve identity FIRST (awaited — no longer fire-and-forget). The
   // contact-referencing tables join on a NOT NULL text key, so an email-only /
@@ -63,11 +82,18 @@ export async function ingestEvent(opts: {
   // `contacts.properties` (D2 split) and returns BOTH the canonical contact id
   // AND its resolved string key (external_id ?? anonymous_id ?? contact.id —
   // risk 1/6), so no second read-back of the contact row is needed.
-  const { resolvedKey } = await resolveOrCreateContact({
+  const {
+    id: contactId,
+    resolvedKey,
+    mergedKeys,
+    mergedIdentifiedKeys,
+    merged,
+  } = await resolveOrCreateContact({
     db,
     userId: event.userId,
     email: event.userEmail || undefined,
     anonymousId: event.anonymousId,
+    discordId: event.discordId,
     contactProperties: event.contactProperties,
   });
 
@@ -106,6 +132,36 @@ export async function ingestEvent(opts: {
     });
   }
 
+  // (2b) §5.3 — fire the provider-neutral identity merge at the two resolver
+  // outcomes where two keys fold into one (collide-MERGE or canonical-key flip).
+  // Placed INSIDE the idempotency-guarded block (after a FRESH insert; the
+  // duplicate path returned early above) so a Hatchet/client retry with the same
+  // idempotencyKey does NOT re-fire `alias` — honoring the "only at the moment
+  // two keys first become one" contract (PostHog `alias` is harmless on replay
+  // but firing per-retry adds queue noise). MF-2: `mergedKeys` already excludes
+  // identified `external_id`s (the resolver split them out); fire only the safe
+  // anon/uuid keys, and surface the excluded identified twins for observability.
+  if (mergedKeys?.length || mergedIdentifiedKeys?.length) {
+    if (mergedKeys?.length) {
+      mergeAnalyticsIdentities({
+        analytics,
+        survivorKey: resolvedKey,
+        loserKeys: mergedKeys,
+        reason: merged ? "collide_merge" : "key_flip",
+        contactId,
+        logger,
+      });
+    }
+    if (mergedIdentifiedKeys?.length) {
+      logResidualTwins({
+        survivorKey: resolvedKey,
+        identifiedLoserKeys: mergedIdentifiedKeys,
+        contactId,
+        logger,
+      });
+    }
+  }
+
   // (3) Build the JSON-serializable subset of eventProperties for the Hatchet
   // push payload (scalars only — the SDK serializes the envelope).
   const serializableProperties = Object.fromEntries(

package/src/lib/outbound.ts

@@ -90,6 +90,23 @@ export interface OutboundPayloads {
   "email.delivered": EmailEventPayload;
   "email.opened": EmailEventPayload;
   "email.clicked": EmailEventPayload & { linkUrl?: string; linkId?: string };
+  /**
+   * A NON-email tracked link was clicked (Discord/referral/ad-hoc
+   * `createTrackedLink`). The deliberate counterpart to `email.clicked` — a
+   * non-email click has no `email_sends` row, so it carries `emailSendId: null`
+   * and `messageId: null` and never masquerades as an email click
+   * (MF-missing #3). `userId` is the link's stitch subject (`distinct_id`) when
+   * the link is identity-bearing, else null for a broadcast link.
+   */
+  "link.clicked": {
+    linkId: string;
+    source: string | null;
+    userId: string | null;
+    emailSendId: null;
+    messageId: null;
+    linkUrl: string;
+    at: string;
+  };
   /**
    * A SEMANTIC link answered — the in-email action event (consumer-named, e.g.
    * "nps.submitted"). Emitted at most once per (send, event name): first

package/src/lib/provider-credentials.ts

@@ -54,6 +54,17 @@ export interface DerivedCredentialPayload {
   projectApiKey?: string;
   projectId?: string;
   privateHost?: string;
+  // --- Discord (kind="derived", providerId="discord") ---
+  // Server-derived during `hogsend connect discord`: the app id + public key
+  // are read by the admin connect-info / interactions routes; the guild id is
+  // captured from the bot-install OAuth grant; the bot token + client secret
+  // (when stored here rather than env) feed the gateway worker / code exchange.
+  // All optional — the store is provider-neutral and additive.
+  discordAppId?: string;
+  discordPublicKey?: string;
+  discordClientSecret?: string;
+  discordBotToken?: string;
+  discordGuildId?: string;
 }
 
 /** Row metadata — everything EXCEPT token material. Safe to surface. */

package/src/lib/semantic-click.ts

@@ -90,6 +90,15 @@ export async function confirmSemanticClick(
   if (!link?.event) {
     return { status: "skipped", reason: "not_semantic" };
   }
+  // The confirm path is EMAIL-semantic end to end (it claims a send's answer
+  // slot keyed on `emailSendId` and emits `email.action`). The click route only
+  // enqueues this task for links with a non-null `emailSendId`, but `emailSendId`
+  // is nullable since the identity-stitching minor — guard defensively and
+  // narrow the type for the rest of the function.
+  if (!link.emailSendId) {
+    return { status: "skipped", reason: "non_email_link" };
+  }
+  const emailSendId = link.emailSendId;
   const semanticEvent = link.event;
 
   // (1) Let the burst window close before judging the click.
@@ -109,7 +118,7 @@ export async function confirmSemanticClick(
     .innerJoin(trackedLinks, eq(linkClicks.trackedLinkId, trackedLinks.id))
     .where(
       and(
-        eq(trackedLinks.emailSendId, link.emailSendId),
+        eq(trackedLinks.emailSendId, emailSendId),
         gte(linkClicks.clickedAt, windowStart),
         lte(linkClicks.clickedAt, windowEnd),
       ),
@@ -117,7 +126,7 @@ export async function confirmSemanticClick(
   const distinctLinks = burst[0]?.n ?? 0;
   if (distinctLinks >= SEMANTIC_BURST_DISTINCT_LINKS) {
     logger.warn("Semantic answer suppressed: scanner-like click burst", {
-      emailSendId: link.emailSendId,
+      emailSendId,
       linkId: link.id,
       event: semanticEvent,
       distinctLinks,
@@ -125,21 +134,21 @@ export async function confirmSemanticClick(
     return { status: "suppressed", distinctLinks };
   }
 
-  const ctx = await resolveEmailSendContext(db, link.emailSendId);
+  const ctx = await resolveEmailSendContext(db, emailSendId);
   if (!ctx) {
     return { status: "skipped", reason: "no_send_context" };
   }
 
   // (3) Claim the answer slot. Duplicate key → stored=false BEFORE the Hatchet
   // push, so journeys/destinations see at most one answer per (send, event).
-  const semKey = `sem:${link.emailSendId}:${semanticEvent}`;
+  const semKey = `sem:${emailSendId}:${semanticEvent}`;
   const result = await pushTrackingEvent({
     db,
     hatchet,
     registry,
     logger,
     event: semanticEvent,
-    emailSendId: link.emailSendId,
+    emailSendId,
     properties: {
       ...(link.eventProperties ?? {}),
       linkId: link.id,
@@ -180,7 +189,7 @@ export async function confirmSemanticClick(
     payload: {
       event: semanticEvent,
       properties: link.eventProperties ?? null,
-      emailSendId: link.emailSendId,
+      emailSendId,
       templateKey: ctx.templateKey ?? null,
       userId: ctx.userId ?? null,
       to: ctx.to ?? ctx.userEmail ?? "",

package/src/lib/tracking-events.ts

@@ -15,8 +15,12 @@ interface EmailSendContext {
 
 export async function resolveEmailSendContext(
   db: Database,
-  emailSendId: string,
+  emailSendId: string | null,
 ): Promise<EmailSendContext | null> {
+  // A non-email tracked link (Discord/referral/ad-hoc `createTrackedLink`) has
+  // a NULL `email_send_id` — there is no send row to resolve, so short-circuit
+  // to null rather than issue a `WHERE id = NULL` query that matches nothing.
+  if (!emailSendId) return null;
   const rows = await db
     .select({
       toEmail: emailSends.toEmail,

package/src/lib/tracking.ts

@@ -240,3 +240,40 @@ export async function prepareTrackedHtml(opts: {
   });
   return result;
 }
+
+/**
+ * The mint surface for a NON-email tracked link (Discord, referral, ad-hoc).
+ * Inserts a `tracked_links` row with a NULL `emailSendId` and returns the
+ * `/v1/t/c/:id` redirect URL to use in place of the raw destination.
+ *
+ * This is the SINGLE chokepoint enforcing "broadcast links carry no subject":
+ * a link only becomes identity-bearing when the caller EXPLICITLY passes
+ * `distinctId` (the canonical contact key the click should stitch into). Per
+ * MF-4, the referral path does NOT pass `distinctId` by default (referral
+ * pages are shareable → broadcast), and the Discord destination passes
+ * `distinctId: undefined`. The `hs_t` mint at click time is still gated by
+ * `TRACKING_IDENTITY_TOKEN` (default false); a row with a NULL `distinctId`
+ * never mints a token regardless.
+ */
+export async function createTrackedLink(opts: {
+  db: Database;
+  url: string;
+  /**
+   * The canonical contact key a click should fold the visitor's anon session
+   * into. OMIT for a broadcast link (the safe default) — only an explicit,
+   * single-subject, non-shareable link should pass this.
+   */
+  distinctId?: string;
+  source: "discord" | "referral" | "link";
+  baseUrl: string;
+}): Promise<string> {
+  const id = randomUUID();
+  await opts.db.insert(trackedLinks).values({
+    id,
+    emailSendId: null,
+    distinctId: opts.distinctId ?? null,
+    source: opts.source,
+    originalUrl: opts.url,
+  });
+  return `${opts.baseUrl}/v1/t/c/${id}`;
+}

package/src/lib/webhook-signing.ts

@@ -25,9 +25,14 @@ import { Webhook } from "svix";
  */
 
 /**
- * The 14-event catalog — the SINGLE source of truth (schema, routes, client,
+ * The 15-event catalog — the SINGLE source of truth (schema, routes, client,
  * CLI all derive from this). The `webhook.test` sentinel is intentionally NOT a
  * member (it is delivered out-of-band regardless of an endpoint's `eventTypes`).
+ *
+ * `link.clicked` is the NON-email click event: a click on a tracked link that
+ * has no email send (Discord/referral/ad-hoc `createTrackedLink`). It is the
+ * deliberate counterpart to `email.clicked` so a non-email click never fires a
+ * malformed `email.clicked` (MF-missing #3).
  */
 export const WEBHOOK_EVENT_TYPES = [
   "contact.created",
@@ -44,6 +49,7 @@ export const WEBHOOK_EVENT_TYPES = [
   "journey.completed",
   "bucket.entered",
   "bucket.left",
+  "link.clicked",
 ] as const;
 
 export type WebhookEventType = (typeof WEBHOOK_EVENT_TYPES)[number];