@hogsend/engine 0.0.1 → 0.1.1

package/src/lib/frequency-cap.ts

@@ -0,0 +1,54 @@
+import { durationToMs } from "@hogsend/core";
+import type { Database } from "@hogsend/db";
+import { emailSends } from "@hogsend/db";
+import { and, count, eq, gte, ne } from "drizzle-orm";
+import type { FrequencyCapConfig } from "./email-service-types.js";
+
+const DEFAULT_EXEMPT = ["transactional"];
+
+/**
+ * True if this recipient has hit the configured send cap within the window.
+ *
+ * - `config` undefined → false (feature is opt-in; safe default = no cap).
+ * - An exempt `category` (default "transactional") → false.
+ * - A `byCategory[category]` override uses its own count/window AND filters the
+ *   COUNT by that category; otherwise the global rule counts ALL of the
+ *   recipient's non-failed sends in the window (NULL-category rows included).
+ *
+ * The COUNT is served by `email_sends_freq_cap_idx (to_email, created_at,
+ * category)`. Never-dispatched / failed rows (`status = 'failed'`) are excluded.
+ */
+export async function isFrequencyCapped(opts: {
+  db: Database;
+  to: string;
+  category?: string;
+  config?: FrequencyCapConfig;
+}): Promise<boolean> {
+  const { db, to, category, config } = opts;
+  if (!config) return false;
+
+  const exempt = config.exemptCategories ?? DEFAULT_EXEMPT;
+  if (category && exempt.includes(category)) return false;
+
+  const override = category ? config.byCategory?.[category] : undefined;
+  const rule = override ?? { count: config.count, window: config.window };
+
+  const since = new Date(Date.now() - durationToMs(rule.window));
+
+  const conditions = [
+    eq(emailSends.toEmail, to),
+    gte(emailSends.createdAt, since),
+    ne(emailSends.status, "failed"),
+  ];
+  // The byCategory branch counts only sends in that category.
+  if (override && category) {
+    conditions.push(eq(emailSends.category, category));
+  }
+
+  const [row] = await db
+    .select({ n: count() })
+    .from(emailSends)
+    .where(and(...conditions));
+
+  return (row?.n ?? 0) >= rule.count;
+}

package/src/lib/mailer.ts

@@ -82,6 +82,8 @@ export function createTrackedMailer(
           registry,
           retryOptions: retryDefaults,
           prepareTrackedHtml: deps.prepareTrackedHtml,
+          frequencyCap: config.frequencyCap,
+          logger: config.logger,
           options: {
             templateKey: options.template,
             props: options.props,
@@ -89,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,
@@ -188,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":
@@ -245,6 +252,7 @@ export function createTrackedMailer(
   async function updateEmailStatus(
     eventType: WebhookEventType,
     resendId: string,
+    extra?: { bounceType?: string; bounceReason?: string },
   ): Promise<void> {
     if (!db) return;
 
@@ -257,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/timezone.ts

@@ -0,0 +1,126 @@
+import { isValidTimeZone, type TimeZone } from "@hogsend/core/schedule";
+import { contacts, type Database } from "@hogsend/db";
+import { eq } from "drizzle-orm";
+
+export interface ResolveTimezoneInput {
+  /** Explicit per-call override, e.g. from `ctx.when.tz("Area/City")`. */
+  explicit?: string;
+  /** PostHog person properties ($timezone, $geoip_time_zone). */
+  posthogProperties?: Record<string, unknown>;
+  /** The `contacts.timezone` cache column. */
+  contactTimezone?: string | null;
+  /** The `contacts.properties` jsonb. */
+  contactProperties?: Record<string, unknown> | null;
+  /** The client `defaults.timezone`. */
+  defaultTimezone?: string;
+  logger?: { warn(msg: string): void };
+}
+
+/**
+ * Source of a resolved timezone, surfaced so callers (e.g. `define-journey`)
+ * can decide whether to opportunistically cache it back to `contacts.timezone`.
+ */
+export type TimezoneSource =
+  | "explicit"
+  | "posthog_timezone"
+  | "posthog_geoip"
+  | "contact_column"
+  | "contact_properties"
+  | "default"
+  | "fallback";
+
+export interface ResolveTimezoneResult {
+  timezone: string;
+  source: TimezoneSource;
+}
+
+function candidate(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+/**
+ * Resolve a user's IANA timezone via the precedence chain. The first *valid*
+ * candidate wins; invalid candidates are skipped and warned. Never throws —
+ * the terminal fallback is `"UTC"`.
+ *
+ * Precedence: explicit → PostHog `$timezone` → PostHog `$geoip_time_zone` →
+ * `contacts.timezone` → `contacts.properties.timezone` → client default → UTC.
+ */
+export function resolveTimezoneWithSource(
+  input: ResolveTimezoneInput,
+): ResolveTimezoneResult {
+  const { logger } = input;
+
+  // An explicit (author-supplied) timezone is a hard contract: if it is present
+  // but invalid, throw rather than silently falling through to UTC. Data-sourced
+  // candidates below stay lenient (warn + skip) — they are not author input.
+  const explicit = candidate(input.explicit);
+  if (explicit !== undefined && !isValidTimeZone(explicit)) {
+    throw new TypeError(
+      `resolveTimezone: invalid explicit timezone "${explicit}"`,
+    );
+  }
+
+  const chain: Array<{ value: string | undefined; source: TimezoneSource }> = [
+    { value: candidate(input.explicit), source: "explicit" },
+    {
+      value: candidate(input.posthogProperties?.$timezone),
+      source: "posthog_timezone",
+    },
+    {
+      value: candidate(input.posthogProperties?.$geoip_time_zone),
+      source: "posthog_geoip",
+    },
+    { value: candidate(input.contactTimezone), source: "contact_column" },
+    {
+      value: candidate(input.contactProperties?.timezone),
+      source: "contact_properties",
+    },
+    { value: candidate(input.defaultTimezone), source: "default" },
+  ];
+
+  for (const { value, source } of chain) {
+    if (value === undefined) continue;
+    if (isValidTimeZone(value)) {
+      return { timezone: value, source };
+    }
+    logger?.warn(`resolveTimezone: ignoring invalid tz '${value}'`);
+  }
+
+  return { timezone: "UTC", source: "fallback" };
+}
+
+/** Convenience wrapper returning just the resolved IANA timezone string. */
+export function resolveTimezone(input: ResolveTimezoneInput): string {
+  return resolveTimezoneWithSource(input).timezone;
+}
+
+/**
+ * Persist a known timezone for a contact (e.g. one the user picked in your
+ * app's settings) into the canonical `contacts.timezone` column, so the
+ * resolution chain prefers it over PostHog/geoip on the next journey run.
+ *
+ * Validates the zone and throws `TypeError` on an invalid one — this is an
+ * explicit, author-driven write, not best-effort data ingestion. Returns
+ * `{ updated: false }` if no contact exists yet for `userId` (it is created on
+ * first event ingestion); call again once the contact exists.
+ */
+export async function setContactTimezone(opts: {
+  db: Database;
+  userId: string;
+  timezone: TimeZone;
+}): Promise<{ updated: boolean }> {
+  const { db, userId, timezone } = opts;
+
+  if (!isValidTimeZone(timezone)) {
+    throw new TypeError(`setContactTimezone: invalid timezone "${timezone}"`);
+  }
+
+  const rows = await db
+    .update(contacts)
+    .set({ timezone, updatedAt: new Date() })
+    .where(eq(contacts.externalId, userId))
+    .returning({ id: contacts.id });
+
+  return { updated: rows.length > 0 };
+}

package/src/lib/tracked.ts

@@ -10,9 +10,12 @@ import { getTemplate, renderToHtml } from "@hogsend/email";
 import type { EmailProvider } from "@hogsend/plugin-resend";
 import { eq } from "drizzle-orm";
 import type {
+  FrequencyCapConfig,
   SendTrackedEmailOptions,
   TrackedSendResult,
 } from "./email-service-types.js";
+import { isFrequencyCapped } from "./frequency-cap.js";
+import type { Logger } from "./logger.js";
 
 export type PrepareTrackedHtmlFn = (opts: {
   html: string;
@@ -28,12 +31,24 @@ interface TrackedEmailDeps {
   registry: TemplateRegistry;
   retryOptions?: RetryOptions;
   prepareTrackedHtml?: PrepareTrackedHtmlFn;
+  /** Optional per-client frequency cap; undefined disables capping. */
+  frequencyCap?: FrequencyCapConfig;
+  /** Optional structured logger for operational events (e.g. cap skips). */
+  logger?: Logger;
 }
 
 export async function sendTrackedEmail<K extends TemplateName>(
   opts: TrackedEmailDeps & { options: SendTrackedEmailOptions<K> },
 ): Promise<TrackedSendResult> {
-  const { db, provider, registry, prepareTrackedHtml, options } = opts;
+  const {
+    db,
+    provider,
+    registry,
+    prepareTrackedHtml,
+    frequencyCap,
+    logger,
+    options,
+  } = opts;
 
   if (!options.skipPreferenceCheck) {
     const suppression = await checkSuppression(
@@ -51,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 });
@@ -68,6 +85,30 @@ export async function sendTrackedEmail<K extends TemplateName>(
             : "suppressed",
       };
     }
+
+    // Frequency cap — consulted only for non-system sends (system mail sets
+    // skipPreferenceCheck and bypasses both suppression and the cap). On a cap
+    // hit: no provider call, no row inserted, no throw — the journey continues.
+    if (frequencyCap) {
+      const capped = await isFrequencyCapped({
+        db,
+        to: options.to,
+        category: options.category,
+        config: frequencyCap,
+      });
+      if (capped) {
+        logger?.info("send skipped: frequency_capped", {
+          to: options.to,
+          category: options.category,
+        });
+        return {
+          emailSendId: "",
+          resendId: "",
+          status: "skipped",
+          reason: "frequency_capped",
+        };
+      }
+    }
   }
 
   const {
@@ -87,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;

package/src/middleware/require-admin.ts

@@ -0,0 +1,26 @@
+import { createMiddleware } from "hono/factory";
+import type { AppEnv } from "../app.js";
+import { requireApiKey } from "./api-key.js";
+
+// Authorizes admin routes via EITHER an API key (Bearer header, the
+// programmatic/CLI path) OR a Better-Auth session (cookie, the Studio path).
+// A Bearer header is always treated as an API key; otherwise we resolve the
+// session. Role-based gating is deferred — the security control for the session
+// path is closed signup (only the first user can register; see app.ts), so any
+// authenticated session is an intended admin in this single-tenant model.
+export const requireAdmin = createMiddleware<AppEnv>(async (c, next) => {
+  const header = c.req.header("authorization");
+  if (header?.startsWith("Bearer ")) {
+    return requireApiKey(c, next);
+  }
+
+  const { auth } = c.get("container");
+  const session = await auth.api.getSession({ headers: c.req.raw.headers });
+  if (!session?.user) {
+    return c.json({ error: "Unauthorized" }, 401);
+  }
+
+  c.set("user", session.user);
+  c.set("session", session.session);
+  return next();
+});