@hogsend/engine 0.1.0 → 0.2.0

package/src/routes/admin/templates.ts

@@ -0,0 +1,298 @@
+import {
+  getTemplate,
+  getTemplateDefinition,
+  getTemplateNames,
+  renderToHtml,
+  renderToPlainText,
+  type TemplateName,
+  type TemplateRegistry,
+} from "@hogsend/email";
+import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
+import type { AppEnv } from "../../app.js";
+import { errorSchema } from "../../lib/schemas.js";
+import { requireScope } from "../../middleware/api-key.js";
+
+// ---------------------------------------------------------------------------
+// Engine-injected preview defaults
+//
+// At real send time `sendEmail()` (lib/email.ts) always injects `name`,
+// `unsubscribeUrl`, `journeyName`, `eventName`, and `body`. We mirror that here
+// so previews render the same shape a recipient would actually receive, then
+// layer the template's `examples` and any caller-supplied props on top.
+// ---------------------------------------------------------------------------
+
+function engineInjectedDefaults(key: string): Record<string, unknown> {
+  return {
+    name: "there",
+    journeyName: key,
+    eventName: key,
+    body: "This is a preview of the email body.",
+    // A no-op preview URL: never a real tracking domain, so previewing never
+    // writes tracked_links or otherwise touches the send pipeline.
+    unsubscribeUrl: "https://example.com/unsubscribe?preview=1",
+  };
+}
+
+function decodeProps(raw?: string): Record<string, unknown> {
+  if (!raw) return {};
+  const json = Buffer.from(raw, "base64").toString("utf8");
+  const parsed = JSON.parse(json);
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("props must decode to a JSON object");
+  }
+  return parsed as Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// GET /templates — catalog of all registered templates
+// ---------------------------------------------------------------------------
+
+const catalogRoute = createRoute({
+  method: "get",
+  path: "/",
+  tags: ["Admin — Templates"],
+  summary: "List all registered email templates",
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            templates: z.array(
+              z.object({
+                key: z.string(),
+                defaultSubject: z.string(),
+                category: z.string().nullable(),
+                hasPreview: z.boolean(),
+              }),
+            ),
+          }),
+        },
+      },
+      description: "Template catalog",
+    },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// GET /templates/{key}/preview — render one template
+// ---------------------------------------------------------------------------
+
+const previewRoute = createRoute({
+  method: "get",
+  path: "/{key}/preview",
+  tags: ["Admin — Templates"],
+  summary: "Render a template preview (HTML + plain text)",
+  request: {
+    params: z.object({ key: z.string() }),
+    query: z.object({
+      props: z.string().optional(),
+      format: z.enum(["html", "text"]).optional(),
+    }),
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            key: z.string(),
+            subject: z.string(),
+            category: z.string().nullable(),
+            preview: z.string().nullable(),
+            html: z.string(),
+            text: z.string(),
+          }),
+        },
+        "text/html": { schema: z.string() },
+        "text/plain": { schema: z.string() },
+      },
+      description: "Rendered preview",
+    },
+    400: {
+      content: { "application/json": { schema: errorSchema } },
+      description: "Invalid props payload",
+    },
+    404: {
+      content: { "application/json": { schema: errorSchema } },
+      description: "Template not found",
+    },
+    500: {
+      content: { "application/json": { schema: errorSchema } },
+      description: "Template failed to render",
+    },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// POST /templates/{key}/send-test — send one real email
+// ---------------------------------------------------------------------------
+
+const sendTestRoute = createRoute({
+  method: "post",
+  path: "/{key}/send-test",
+  tags: ["Admin — Templates"],
+  summary: "Send a single test email of a template",
+  middleware: [requireScope("full-admin")] as const,
+  request: {
+    params: z.object({ key: z.string() }),
+    body: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            to: z.string().email(),
+            props: z.record(z.string(), z.unknown()).optional(),
+          }),
+        },
+      },
+    },
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            status: z.string(),
+            emailSendId: z.string().optional(),
+          }),
+        },
+      },
+      description: "Test email dispatched",
+    },
+    404: {
+      content: { "application/json": { schema: errorSchema } },
+      description: "Template not found",
+    },
+    500: {
+      content: { "application/json": { schema: errorSchema } },
+      description: "Test send failed",
+    },
+  },
+});
+
+function templateExists(registry: TemplateRegistry, key: string): boolean {
+  return getTemplateNames(registry).includes(key as TemplateName);
+}
+
+export const templatesRouter = new OpenAPIHono<AppEnv>()
+  .openapi(catalogRoute, (c) => {
+    const { templates } = c.get("container");
+
+    const catalog = getTemplateNames(templates).map((key) => {
+      const def = getTemplateDefinition({
+        key: key as TemplateName,
+        registry: templates,
+      });
+      return {
+        key: key as string,
+        defaultSubject: def.defaultSubject,
+        category: def.category ?? null,
+        hasPreview: typeof def.preview === "function",
+      };
+    });
+
+    return c.json({ templates: catalog }, 200);
+  })
+  .openapi(previewRoute, async (c) => {
+    const { templates } = c.get("container");
+    const { key } = c.req.valid("param");
+    const { props: encodedProps, format } = c.req.valid("query");
+
+    if (!templateExists(templates, key)) {
+      return c.json({ error: "Template not found" }, 404);
+    }
+
+    let decoded: Record<string, unknown>;
+    try {
+      decoded = decodeProps(encodedProps);
+    } catch {
+      return c.json(
+        { error: "Invalid props: expected base64 JSON object" },
+        400,
+      );
+    }
+
+    const definition = getTemplateDefinition({
+      key: key as TemplateName,
+      registry: templates,
+    });
+
+    // Engine defaults < template examples < caller-supplied props.
+    const props = {
+      ...engineInjectedDefaults(key),
+      ...(definition.examples ?? {}),
+      ...decoded,
+    } as never;
+
+    try {
+      const { element, subject, category } = getTemplate({
+        key: key as TemplateName,
+        props,
+        registry: templates,
+      });
+
+      if (format === "html") {
+        const html = await renderToHtml(element);
+        return c.body(html, 200, {
+          "Content-Type": "text/html; charset=utf-8",
+        });
+      }
+      if (format === "text") {
+        const text = await renderToPlainText(element);
+        return c.body(text, 200, {
+          "Content-Type": "text/plain; charset=utf-8",
+        });
+      }
+
+      const [html, text] = await Promise.all([
+        renderToHtml(element),
+        renderToPlainText(element),
+      ]);
+      const preview = definition.preview?.(props) ?? null;
+
+      return c.json(
+        { key, subject, category: category ?? null, preview, html, text },
+        200,
+      );
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Render failed";
+      return c.json({ error: `Failed to render template: ${message}` }, 500);
+    }
+  })
+  .openapi(sendTestRoute, async (c) => {
+    const { emailService, templates } = c.get("container");
+    const { key } = c.req.valid("param");
+    const { to, props: bodyProps } = c.req.valid("json");
+
+    if (!templateExists(templates, key)) {
+      return c.json({ error: "Template not found" }, 404);
+    }
+
+    const definition = getTemplateDefinition({
+      key: key as TemplateName,
+      registry: templates,
+    });
+
+    const props = {
+      ...engineInjectedDefaults(key),
+      ...(definition.examples ?? {}),
+      ...(bodyProps ?? {}),
+    } as never;
+
+    try {
+      const result = await emailService.send({
+        template: key as TemplateName,
+        props,
+        to,
+        subject: definition.defaultSubject,
+        category: definition.category ?? "transactional",
+        skipPreferenceCheck: true,
+      });
+
+      return c.json(
+        { status: result.status, emailSendId: result.emailSendId },
+        200,
+      );
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Send failed";
+      return c.json({ error: `Test send failed: ${message}` }, 500);
+    }
+  });

package/src/worker.ts

@@ -1,9 +1,16 @@
+import type { DefinedBucket } from "./buckets/define-bucket.js";
+import { selectBucketTasks } from "./buckets/registry.js";
 import type { HogsendClient } from "./container.js";
 import type { DefinedJourney } from "./journeys/define-journey.js";
 import { selectJourneyTasks } from "./journeys/registry.js";
 import { hatchet } from "./lib/hatchet.js";
 import { getPostHog } from "./lib/posthog.js";
 import { getRedisIfConnected } from "./lib/redis.js";
+import {
+  bucketBackfillTask,
+  enqueueBucketBackfills,
+} from "./workflows/bucket-backfill.js";
+import { bucketReconcileTask } from "./workflows/bucket-reconcile.js";
 import { checkAlertsTask } from "./workflows/check-alerts.js";
 import { importContactsTask } from "./workflows/import-contacts.js";
 import { sendEmailTask } from "./workflows/send-email.js";
@@ -11,8 +18,12 @@ import { sendEmailTask } from "./workflows/send-email.js";
 export interface CreateWorkerOptions {
   container: HogsendClient;
   journeys: DefinedJourney[];
+  /** Buckets whose fast-expiry timer tasks are registered. Defaults to none. */
+  buckets?: DefinedBucket[];
   /** Defaults to `container.env.ENABLED_JOURNEYS`. */
   enabledJourneys?: string;
+  /** Defaults to `container.env.ENABLED_BUCKETS`. */
+  enabledBuckets?: string;
   /** Extra client tasks registered alongside the built-in workflows. */
   extraWorkflows?: unknown[];
 }
@@ -27,11 +38,22 @@ export function createWorker(opts: CreateWorkerOptions): Worker {
   const enabled = opts.enabledJourneys ?? container.env.ENABLED_JOURNEYS;
   const journeyTasks = selectJourneyTasks(journeys, enabled);
 
+  const enabledBuckets = opts.enabledBuckets ?? container.env.ENABLED_BUCKETS;
+  // The single place a bucket's per-user fast-expiry timer task is constructed
+  // (Section 9.4): the shared `bucket:arm-expiry` durableTask, registered once iff
+  // any enabled bucket opts into fastExpiry. The engine-wide time-based-leave
+  // reconcile cron (bucketReconcileTask) is ALWAYS registered in baseWorkflows
+  // below (Section 10), regardless of fastExpiry.
+  const bucketTasks = selectBucketTasks(opts.buckets ?? [], enabledBuckets);
+
   const baseWorkflows = [
     sendEmailTask,
     importContactsTask,
     checkAlertsTask,
+    bucketReconcileTask,
+    bucketBackfillTask,
     ...journeyTasks,
+    ...bucketTasks,
   ];
   const workflows = [
     ...baseWorkflows,
@@ -58,6 +80,19 @@ export function createWorker(opts: CreateWorkerOptions): Worker {
     );
 
     await _worker.start();
+
+    // Boot-time backfill / criteria-change re-eval (Section 6.6 B): diff each
+    // enabled bucket's criteriaHash against bucket_configs and enqueue a
+    // backfill/re-eval job where it differs. Best-effort — never block worker
+    // start; the cron is the backstop for time-based leaves regardless.
+    enqueueBucketBackfills({
+      db: container.db,
+      logger: container.logger,
+    }).catch((err) => {
+      container.logger.warn("Bucket backfill enqueue (boot) failed", {
+        error: err instanceof Error ? err.message : String(err),
+      });
+    });
   }
 
   return { start, stop };