@hogsend/engine 0.1.0 → 0.2.0

package/src/container.ts

@@ -1,6 +1,6 @@
 import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
 import type { TimeZone } from "@hogsend/core";
-import type { JourneyRegistry } from "@hogsend/core/registry";
+import type { BucketRegistry, JourneyRegistry } from "@hogsend/core/registry";
 import type { SendWindow } from "@hogsend/core/schedule";
 import {
   createDatabase,
@@ -16,6 +16,8 @@ import {
   type EmailProvider,
 } from "@hogsend/plugin-resend";
 import type { Resend } from "resend";
+import type { DefinedBucket } from "./buckets/define-bucket.js";
+import { buildBucketRegistry } from "./buckets/registry.js";
 import { env } from "./env.js";
 import { setClientScheduleDefaults } from "./journeys/client-defaults-singleton.js";
 import type { DefinedJourney } from "./journeys/define-journey.js";
@@ -49,8 +51,22 @@ export interface HogsendClient {
   auth: Auth;
   email: Resend;
   emailService: EmailService;
+  /**
+   * The app's template registry (key → component + subject + category +
+   * optional preview/examples). Same object threaded into the engine mailer;
+   * exposed here so admin preview/catalog routes can enumerate keys and render
+   * templates without going through a send. Empty when no templates are wired.
+   */
+  templates: TemplateRegistry;
   analytics?: PostHogService;
   registry: JourneyRegistry;
+  /**
+   * The bucket registry (id map + event/property inverted indexes for candidate
+   * narrowing). Built and installed as the process singleton at client build;
+   * the real-time ingest path reads it via `getBucketRegistrySingleton()`.
+   * Empty when no buckets are wired.
+   */
+  bucketRegistry: BucketRegistry;
   hatchet: HatchetClient;
   /**
    * The client repo's migration journal (`migrations/meta/_journal.json`),
@@ -70,6 +86,8 @@ export interface HogsendClient {
 export interface HogsendClientOptions {
   /** Journeys to register in the {@link JourneyRegistry}. Defaults to none. */
   journeys?: DefinedJourney[];
+  /** Buckets to register in the {@link BucketRegistry}. Defaults to none. */
+  buckets?: DefinedBucket[];
   /**
    * Email is a first-class channel. Its config is grouped here rather than
    * spread across top-level args — the engine owns the cohesive email pipeline
@@ -105,6 +123,11 @@ export interface HogsendClientOptions {
    * `env.ENABLED_JOURNEYS`.
    */
   enabledJourneys?: string;
+  /**
+   * Comma-separated ids (or `*`) controlling which buckets load. Defaults to
+   * `env.ENABLED_BUCKETS`.
+   */
+  enabledBuckets?: string;
   /**
    * The client repo's migration journal for the `schema.client` health block.
    * Defaults to `{ entries: [] }` (empty client track ⇒ trivially in sync).
@@ -154,6 +177,18 @@ export function createHogsendClient(
       db,
       secret: env.BETTER_AUTH_SECRET,
       baseURL: env.BETTER_AUTH_URL,
+      // Always trust the public API origin; add any explicitly configured ones
+      // (e.g. a remote Studio origin) on top. baseURL is trusted automatically.
+      trustedOrigins: Array.from(
+        new Set(
+          [
+            env.API_PUBLIC_URL,
+            ...(env.BETTER_AUTH_TRUSTED_ORIGINS?.split(",") ?? []),
+          ]
+            .map((o) => o.trim())
+            .filter(Boolean),
+        ),
+      ),
     });
 
   const email = createResendClient({ apiKey: env.RESEND_API_KEY });
@@ -163,6 +198,14 @@ export function createHogsendClient(
     opts.enabledJourneys ?? env.ENABLED_JOURNEYS,
   );
 
+  // Installs the bucket registry singleton in BOTH the API and worker processes
+  // (both call createHogsendClient); the real-time ingest path reads it via
+  // getBucketRegistrySingleton().
+  const bucketRegistry = buildBucketRegistry(
+    opts.buckets ?? [],
+    opts.enabledBuckets ?? env.ENABLED_BUCKETS,
+  );
+
   const provider =
     opts.email?.provider ??
     createResendProvider({
@@ -183,12 +226,14 @@ export function createHogsendClient(
     sendWindow: defaults.sendWindow,
   });
 
+  const templates = opts.email?.templates ?? ({} as TemplateRegistry);
+
   const emailService =
     opts.overrides?.mailer ??
     createTrackedMailer(
       {
         defaultFrom: env.RESEND_FROM_EMAIL,
-        templates: opts.email?.templates ?? ({} as TemplateRegistry),
+        templates,
         db,
         webhookSecret: env.RESEND_WEBHOOK_SECRET,
         bounceThreshold: 3,
@@ -207,6 +252,7 @@ export function createHogsendClient(
   const analytics = opts.analytics ?? getPostHog();
 
   logger.info(`Journey registry loaded: ${registry.count()} journeys`);
+  logger.info(`Bucket registry loaded: ${bucketRegistry.count()} buckets`);
 
   return {
     env,
@@ -216,8 +262,10 @@ export function createHogsendClient(
     auth,
     email,
     emailService,
+    templates,
     analytics,
     registry,
+    bucketRegistry,
     hatchet: opts.overrides?.hatchet ?? hatchet,
     clientJournal: opts.clientJournal ?? { entries: [] },
     defaults,

package/src/env.ts

@@ -16,6 +16,10 @@ export const env = createEnv({
     REDIS_URL: z.string().min(1).default("redis://localhost:6379"),
     BETTER_AUTH_SECRET: z.string().min(1),
     BETTER_AUTH_URL: z.string().url().default("http://localhost:3002"),
+    // Extra origins allowed to call the auth endpoints (beyond BETTER_AUTH_URL),
+    // comma-separated. Needed when the Studio is served from a different origin
+    // than the API — e.g. the `hogsend studio` CLI pointing at a remote instance.
+    BETTER_AUTH_TRUSTED_ORIGINS: z.string().optional(),
     RESEND_API_KEY: z.string().min(1),
     RESEND_FROM_EMAIL: z.string().email().default("noreply@hogsend.com"),
     // Hatchet connection contract. The @hatchet-dev SDK also reads these straight
@@ -50,6 +54,12 @@ export const env = createEnv({
     ADMIN_API_KEY: z.string().min(1).optional(),
     API_PUBLIC_URL: z.string().url().default("http://localhost:3002"),
     ENABLED_JOURNEYS: z.string().default("*"),
+    // Buckets: same `"*"`-or-csv contract as ENABLED_JOURNEYS (Section 9.3).
+    // Evaluated at worker boot — a toggle requires a worker restart; only the
+    // bucket_configs DB override is hot.
+    ENABLED_BUCKETS: z.string().default("*"),
+    // Cadence for the engine-owned bucket reconcile cron (time-based leaves).
+    BUCKET_RECONCILE_CRON: z.string().default("*/5 * * * *"),
   },
   runtimeEnv: process.env,
   emptyStringAsUndefined: true,

package/src/index.ts

@@ -6,7 +6,10 @@
 // Core helpers used by content journeys (days/hours/minutes, condition + journey
 // types) so content can import everything from `@hogsend/engine`.
 export * from "@hogsend/core";
-export { JourneyRegistry } from "@hogsend/core/registry";
+export {
+  BucketRegistry,
+  JourneyRegistry,
+} from "@hogsend/core/registry";
 // --- Re-exports for content ---
 // Schema/version helpers used by the boot guard and the /v1/health route.
 export {
@@ -19,6 +22,25 @@ export {
 } from "@hogsend/db";
 // --- App / container / worker factories ---
 export { type AppEnv, type CreateAppOptions, createApp } from "./app.js";
+// --- Buckets ---
+export {
+  type BucketTransition,
+  type BucketTransitionKind,
+  checkBucketMembership,
+} from "./buckets/check-membership.js";
+export {
+  type DefinedBucket,
+  defineBucket,
+} from "./buckets/define-bucket.js";
+export {
+  buildBucketRegistry,
+  selectBucketTasks,
+} from "./buckets/registry.js";
+export {
+  getBucketRegistrySingleton,
+  resetBucketRegistry,
+  setBucketRegistry,
+} from "./buckets/registry-singleton.js";
 export {
   createHogsendClient,
   type HogsendClient,
@@ -50,6 +72,11 @@ export {
   type BatchedBackfillResult,
   runBatchedBackfill,
 } from "./lib/backfill.js";
+// --- Bucket transition emission (shared by real-time / cron / fast-expiry) ---
+export {
+  type BucketTransitionSource,
+  emitBucketTransition,
+} from "./lib/bucket-emit.js";
 // --- Infrastructure singletons ---
 export { getDb } from "./lib/db.js";
 // --- Email ---
@@ -86,6 +113,7 @@ export { createLogger, type Logger } from "./lib/logger.js";
 export { createTrackedMailer } from "./lib/mailer.js";
 export { getPostHog } from "./lib/posthog.js";
 export { getRedisIfConnected } from "./lib/redis.js";
+export { type MountStudioResult, mountStudio } from "./lib/studio.js";
 export {
   type ResolveTimezoneInput,
   type ResolveTimezoneResult,
@@ -120,6 +148,17 @@ export {
   createWorker,
   type Worker,
 } from "./worker.js";
+export {
+  type BucketBackfillInput,
+  bucketBackfillTask,
+  computeCriteriaHash,
+  enqueueBucketBackfills,
+} from "./workflows/bucket-backfill.js";
+export {
+  type BucketArmExpiryInput,
+  bucketExpiryTask,
+  bucketReconcileTask,
+} from "./workflows/bucket-reconcile.js";
 export { checkAlertsTask } from "./workflows/check-alerts.js";
 export { importContactsTask } from "./workflows/import-contacts.js";
 // --- Built-in Hatchet workflow tasks ---

package/src/lib/auth.ts

@@ -8,12 +8,19 @@ export function createAuth(opts: {
   db: Database;
   secret: string;
   baseURL: string;
+  /**
+   * Extra origins allowed to call auth endpoints, beyond `baseURL` (which is
+   * always trusted). Needed when the Studio is served from a different origin
+   * than the API (e.g. the `hogsend studio` CLI against a remote instance).
+   */
+  trustedOrigins?: string[];
 }) {
-  const { db, secret, baseURL } = opts;
+  const { db, secret, baseURL, trustedOrigins } = opts;
   return betterAuth({
     basePath: "/api/auth",
     secret,
     baseURL,
+    ...(trustedOrigins && trustedOrigins.length > 0 ? { trustedOrigins } : {}),
     database: drizzleAdapter(db, {
       provider: "pg",
       schema,

package/src/lib/bucket-emit.ts

@@ -0,0 +1,107 @@
+import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
+import type { BucketMeta } from "@hogsend/core";
+import type { JourneyRegistry } from "@hogsend/core/registry";
+import type { Database } from "@hogsend/db";
+import { syncBucketToPostHog } from "./bucket-posthog-sync.js";
+import { ingestEvent } from "./ingestion.js";
+import type { Logger } from "./logger.js";
+
+export type BucketTransitionKind = "entered" | "left";
+
+/** Where a transition originated — carried on the emitted event properties. */
+export type BucketTransitionSource =
+  | "event"
+  | "reconcile"
+  | "backfill"
+  | "manual";
+
+/**
+ * Emit a bucket transition back through `ingestEvent` (the `ctx.trigger`
+ * precedent) — shared by ALL three producers (real-time `checkBucketMembership`,
+ * the reconcile cron, and the fast-expiry timer) so they compute byte-identical
+ * `idempotencyKey`s for the same transition and converge to ONE emission
+ * (Section 6.3 worked example).
+ *
+ * Persists to `userEvents`, pushes to Hatchet (routing to journeys), and runs
+ * `checkExits`. Emits the per-bucket ALIAS (`bucket:<kind>:<id>`) by default; the
+ * generic `bucket:<kind>` is emitted ONLY when a generic-bound journey actually
+ * exists (aliased-only default — Section 8.5). `epoch` is the winning membership
+ * row's `entryCount`, read off the single winning mutation by the caller.
+ */
+export async function emitBucketTransition(opts: {
+  db: Database;
+  /** The JOURNEY registry — forwarded into the recursive emit ingestEvent. */
+  registry: JourneyRegistry;
+  hatchet: HatchetClient;
+  logger: Logger;
+  kind: BucketTransitionKind;
+  bucket: BucketMeta;
+  userId: string;
+  userEmail: string | null;
+  epoch: number;
+  source?: BucketTransitionSource;
+}): Promise<void> {
+  const {
+    db,
+    registry,
+    hatchet,
+    logger,
+    kind,
+    bucket,
+    userId,
+    userEmail,
+    epoch,
+    source = "event",
+  } = opts;
+
+  const properties: Record<string, unknown> = {
+    bucketId: bucket.id,
+    bucketName: bucket.name,
+    userId,
+    transition: kind,
+    source,
+  };
+
+  // Optional PostHog person-property mirror (Section 12). Off by default; a
+  // no-op without POSTHOG_API_KEY. Wired here, the single transition path shared
+  // by all three producers (real-time / reconcile / fast-expiry), so the sync
+  // fires exactly once per emitted transition. Best-effort — it never blocks the
+  // event emit below.
+  syncBucketToPostHog({ logger, kind, bucket, userId });
+
+  // Per-bucket alias — the recommended, narrowly-routed binding. The
+  // deterministic idempotencyKey rides the userEvents dedup short-circuit as
+  // defense-in-depth (Section 6.3).
+  await ingestEvent({
+    db,
+    registry,
+    hatchet,
+    logger,
+    event: {
+      event: `bucket:${kind}:${bucket.id}`,
+      userId,
+      userEmail: userEmail ?? "",
+      properties,
+      idempotencyKey: `bucket:${bucket.id}:${userId}:${kind}:${epoch}`,
+    },
+  });
+
+  // Generic form — emitted ONLY if a journey actually binds to it, so the
+  // recursion-guarded generic event is not written for nothing (Section 8.5).
+  const genericEvent = `bucket:${kind}`;
+  if (registry.getByTriggerEvent(genericEvent).length > 0) {
+    await ingestEvent({
+      db,
+      registry,
+      hatchet,
+      logger,
+      event: {
+        event: genericEvent,
+        userId,
+        userEmail: userEmail ?? "",
+        properties,
+        idempotencyKey: `bucket:${bucket.id}:${userId}:${kind}:${epoch}:generic`,
+      },
+    });
+  }
+}

package/src/lib/bucket-posthog-sync.ts

@@ -0,0 +1,63 @@
+import type { BucketMeta } from "@hogsend/core";
+import type { Logger } from "./logger.js";
+import { getPostHog } from "./posthog.js";
+
+/**
+ * Optional PostHog person-property mirror for a bucket transition (Section 12).
+ *
+ * OFF BY DEFAULT — a no-op unless `meta.syncToPostHog === true`. Also a no-op
+ * without `POSTHOG_API_KEY` (`getPostHog()` returns undefined), so self-host
+ * setups that omit PostHog silently do nothing — documented, not broken.
+ *
+ * On JOIN it `$set`s a boolean person property `true`; on LEAVE it `$unset`s the
+ * same key. `$unset` (NOT `$set false`) is the recommended default: a cohort
+ * `key = true` excludes a false value, but a cohort `key is set` STILL matches a
+ * false value, so `$unset` is the only form where both cohort idioms behave
+ * correctly. The property key defaults to `hogsend_bucket_<id>`, overridable via
+ * `meta.postHogPropertyKey`.
+ *
+ * This reuses the existing `plugin-posthog` capture path (the same one
+ * `identify()` uses at journey-context.ts) — it adds no new integration surface
+ * and never pushes to any non-PostHog destination (the Section 2.4 anti-CDP
+ * invariant). Best-effort: a capture failure is logged and swallowed so a sync
+ * error never blocks a transition emit.
+ */
+export function syncBucketToPostHog(opts: {
+  logger: Logger;
+  kind: "entered" | "left";
+  bucket: BucketMeta;
+  userId: string;
+}): void {
+  const { logger, kind, bucket, userId } = opts;
+
+  if (!bucket.syncToPostHog) return;
+
+  const posthog = getPostHog();
+  if (!posthog) return; // no POSTHOG_API_KEY → silent no-op
+
+  const propertyKey =
+    bucket.postHogPropertyKey ?? `hogsend_bucket_${bucket.id}`;
+
+  try {
+    if (kind === "entered") {
+      // $set { key: true } — mirrors plugin-posthog identify() ($set path).
+      posthog.identify(userId, { [propertyKey]: true });
+    } else {
+      // $unset [key] — RECOMMENDED on leave (Section 12). The property is absent
+      // unless the user is currently a member, so both `key = true` and
+      // `key is set` cohorts behave correctly.
+      posthog.captureEvent({
+        distinctId: userId,
+        event: "$set",
+        properties: { $unset: [propertyKey] },
+      });
+    }
+  } catch (err) {
+    logger.warn("Bucket PostHog sync failed (best-effort)", {
+      bucketId: bucket.id,
+      userId,
+      kind,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+}

package/src/lib/email-service-types.ts

@@ -35,6 +35,9 @@ export interface SendTrackedEmailOptions<
   to: string;
   subject?: string;
   journeyStateId?: string;
+  /** Denormalized recipient identity, persisted on the email_sends row for reporting. */
+  userId?: string;
+  userEmail?: string;
   category?: string;
   tags?: Array<{ name: string; value: string }>;
   headers?: Record<string, string>;
@@ -108,6 +111,9 @@ export interface EmailServiceSendOptions<
   from?: string;
   subject?: string;
   journeyStateId?: string;
+  /** Denormalized recipient identity, persisted on the email_sends row for reporting. */
+  userId?: string;
+  userEmail?: string;
   category?: string;
   tags?: Array<{ name: string; value: string }>;
   headers?: Record<string, string>;

package/src/lib/email.ts

@@ -76,6 +76,8 @@ export async function sendEmail(
     to: opts.to,
     subject: opts.subject,
     journeyStateId: opts.journeyStateId,
+    userId: opts.userId,
+    userEmail: opts.to,
     category: "journey",
     tags: [
       { name: "journeyId", value: opts.journeyName ?? opts.template },

package/src/lib/ingestion.ts

@@ -3,6 +3,7 @@ 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 { upsertContact } from "./contacts.js";
 import type { Logger } from "./logger.js";
 
@@ -93,6 +94,30 @@ export async function ingestEvent(opts: {
     }),
   ]);
 
+  // Real-time bucket membership re-evaluation (Section 6.1). NOT part of the
+  // Promise.all above: its property eval reads MERGED contact state, and its
+  // bucket:entered/left emissions recurse back into ingestEvent (the recursion
+  // guard in checkBucketMembership bounds them). Best-effort: a bucket failure
+  // must not fail the ingest of the originating event.
+  try {
+    await checkBucketMembership({
+      db,
+      registry,
+      hatchet,
+      logger,
+      userId: event.userId,
+      userEmail: event.userEmail || null,
+      event: event.event,
+      properties: event.properties,
+    });
+  } catch (err) {
+    logger.warn("Bucket membership check failed", {
+      event: event.event,
+      userId: event.userId,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+
   logger.info("Event ingested", {
     event: event.event,
     userId: event.userId,

package/src/lib/mailer.ts

@@ -91,6 +91,8 @@ export function createTrackedMailer(
             to: options.to,
             subject: options.subject,
             journeyStateId: options.journeyStateId,
+            userId: options.userId,
+            userEmail: options.userEmail,
             category: options.category,
             tags: options.tags,
             headers: options.headers,
@@ -190,7 +192,10 @@ export function createTrackedMailer(
         await updateEmailStatus(event.type, event.data.email_id);
         break;
       case "email.bounced":
-        await updateEmailStatus(event.type, event.data.email_id);
+        await updateEmailStatus(event.type, event.data.email_id, {
+          bounceType: event.data.bounce?.type,
+          bounceReason: event.data.bounce?.message,
+        });
         await handleBounce(event.data.to);
         break;
       case "email.complained":
@@ -247,6 +252,7 @@ export function createTrackedMailer(
   async function updateEmailStatus(
     eventType: WebhookEventType,
     resendId: string,
+    extra?: { bounceType?: string; bounceReason?: string },
   ): Promise<void> {
     if (!db) return;
 
@@ -259,6 +265,8 @@ export function createTrackedMailer(
       .set({
         status: status as typeof emailSends.$inferSelect.status,
         [timestampField]: new Date(),
+        ...(extra?.bounceType ? { bounceType: extra.bounceType } : {}),
+        ...(extra?.bounceReason ? { bounceReason: extra.bounceReason } : {}),
         updatedAt: new Date(),
       })
       .where(eq(emailSends.resendId, resendId));

package/src/lib/metrics-sql.ts

@@ -0,0 +1,17 @@
+import { sql } from "drizzle-orm";
+
+// Shared SQL building blocks for the admin metrics + reporting routers.
+
+/** Guarded divide, rounded to 4 decimal places. Returns 0 when denom <= 0. */
+export const rate = (num: number, denom: number) =>
+  denom > 0 ? Math.round((num / denom) * 10000) / 10000 : 0;
+
+/** `date_trunc` granularity literals, keyed by the API's period/granularity enum. */
+export const TRUNC_SQL = {
+  hour: sql`'hour'`,
+  day: sql`'day'`,
+  week: sql`'week'`,
+  month: sql`'month'`,
+} as const;
+
+export type TruncPeriod = keyof typeof TRUNC_SQL;

package/src/lib/studio.ts

@@ -0,0 +1,105 @@
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { serveStatic } from "@hono/node-server/serve-static";
+import type { OpenAPIHono } from "@hono/zod-openapi";
+import type { AppEnv } from "../app.js";
+
+/**
+ * Where the built Studio SPA lives. The Studio (`@hogsend/studio`) is a separate
+ * Vite package that builds to a static `dist/` under base `/studio/`. The engine
+ * serves that `dist/` as static files at `/studio/*` with an SPA fallback.
+ *
+ * The Studio is NOT a runtime dependency of the engine — it ships as a built
+ * artifact and is optional. Mounting is best-effort: if no `dist/` is found, the
+ * mount is silently skipped so an unbuilt / studio-less deploy never crashes.
+ *
+ * Resolution order:
+ *  1. `STUDIO_DIST_PATH` env var (explicit override; absolute or cwd-relative).
+ *  2. `require.resolve("@hogsend/studio/package.json")` → sibling `dist/`
+ *     (works when the studio package is installed/linked alongside the engine).
+ *  3. Monorepo source layout: walk up from this file to `packages/studio/dist`.
+ *  4. cwd-relative `packages/studio/dist` (dogfood app run from repo root).
+ */
+function resolveStudioDist(): string | null {
+  const candidates: string[] = [];
+
+  const envPath = process.env.STUDIO_DIST_PATH;
+  if (envPath && envPath.length > 0) {
+    candidates.push(resolve(process.cwd(), envPath));
+  }
+
+  const require = createRequire(import.meta.url);
+  try {
+    const pkgJson = require.resolve("@hogsend/studio/package.json");
+    candidates.push(join(dirname(pkgJson), "dist"));
+  } catch {
+    // Not resolvable as a module — fall through to layout-based guesses.
+  }
+
+  // Monorepo source layout: this file is packages/engine/src/lib/studio.ts, so
+  // the studio dist is ../../../studio/dist relative to here.
+  const here = dirname(fileURLToPath(import.meta.url));
+  candidates.push(resolve(here, "../../../studio/dist"));
+
+  // cwd fallbacks for a repo-root process (apps/api dogfood, tests).
+  candidates.push(resolve(process.cwd(), "packages/studio/dist"));
+  candidates.push(resolve(process.cwd(), "../../packages/studio/dist"));
+
+  for (const dir of candidates) {
+    if (existsSync(join(dir, "index.html"))) {
+      return dir;
+    }
+  }
+  return null;
+}
+
+export interface MountStudioResult {
+  /** True when the SPA was mounted, false when no built dist was found. */
+  mounted: boolean;
+  /** Absolute path to the served dist directory, when mounted. */
+  distPath?: string;
+}
+
+/**
+ * Mount the Studio SPA at `/studio/*` as static files, with an SPA fallback to
+ * `index.html` for client-side routes.
+ *
+ * IMPORTANT: this is intentionally OUTSIDE the `/v1/admin` auth guard at the
+ * static layer. The SPA itself gates access via `/v1/auth/status` + login; the
+ * actual data endpoints under `/v1/admin/*` stay protected by `requireAdmin`.
+ *
+ * No-op (returns `{ mounted: false }`) when no built `dist/` is found, so an
+ * unbuilt studio never crashes the server.
+ */
+export function mountStudio(app: OpenAPIHono<AppEnv>): MountStudioResult {
+  const distPath = resolveStudioDist();
+  if (!distPath) {
+    return { mounted: false };
+  }
+
+  // serveStatic resolves `path` relative to `root` (which is relative to cwd by
+  // default). We pass an absolute `root` and strip the `/studio` URL prefix so a
+  // request for `/studio/assets/x.js` maps to `<dist>/assets/x.js`.
+  const staticHandler = serveStatic({
+    root: distPath,
+    rewriteRequestPath: (path) => path.replace(/^\/studio/, "") || "/",
+  });
+
+  // Redirect the bare `/studio` to `/studio/` so relative/base assets resolve.
+  app.get("/studio", (c) => c.redirect("/studio/"));
+
+  // Static assets (js/css/images) under /studio/*.
+  app.use("/studio/*", staticHandler);
+
+  // SPA fallback: any /studio/* path that didn't resolve to a file serves
+  // index.html so client-side (TanStack Router) routes work on hard refresh.
+  const indexHandler = serveStatic({
+    root: distPath,
+    rewriteRequestPath: () => "/index.html",
+  });
+  app.get("/studio/*", indexHandler);
+
+  return { mounted: true, distPath };
+}

package/src/lib/tracked.ts

@@ -66,6 +66,8 @@ export async function sendTrackedEmail<K extends TemplateName>(
           subject: options.subject ?? "",
           category: options.category,
           journeyStateId: options.journeyStateId,
+          userId: options.userId,
+          userEmail: options.userEmail ?? options.to,
           status: "failed",
         })
         .returning({ id: emailSends.id });
@@ -126,6 +128,8 @@ export async function sendTrackedEmail<K extends TemplateName>(
       subject,
       category: options.category ?? category,
       journeyStateId: options.journeyStateId,
+      userId: options.userId,
+      userEmail: options.userEmail ?? options.to,
       status: "queued",
     })
     .returning({ id: emailSends.id });

package/src/middleware/rate-limit.ts

@@ -13,7 +13,7 @@ export const rateLimit = createMiddleware<AppEnv>(async (c, next) => {
   if (process.env.NODE_ENV === "test") return next();
 
   const apiKey = c.get("apiKey");
-  const keyId = apiKey?.id ?? "anonymous";
+  const keyId = apiKey?.id ?? c.get("user")?.id ?? "anonymous";
   const now = Date.now();
 
   let count: number;