@hogsend/core 0.0.1

package/LICENSE

@@ -0,0 +1,93 @@
+Elastic License 2.0 (ELv2)
+
+Copyright 2025 Doug Silkstone and Hogsend contributors
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor's trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising out
+of these terms or the use or nature of the software, under any kind of legal
+claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+**control** means ownership of substantially all the assets of an entity, or the
+power to direct its management and policies by vote, contract, or otherwise.
+Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,9 @@
+# @hogsend/core
+
+Core types, Zod schemas, the condition-evaluation engine, duration helpers, and
+the `JourneyRegistry` for [Hogsend](https://github.com/dougwithseismic/hogsend) —
+a code-first lifecycle orchestration engine for teams on PostHog + Resend.
+
+This package ships raw TypeScript source; consumers bundle it via their own build
+(tsup `noExternal`). See the repo docs for the full architecture and the
+[release model](https://github.com/dougwithseismic/hogsend/blob/main/docs/RELEASING.md).

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@hogsend/core",
+  "version": "0.0.1",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dougwithseismic/hogsend.git",
+    "directory": "packages/core"
+  },
+  "sideEffects": false,
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./types": "./src/types/index.ts",
+    "./registry": "./src/registry/index.ts",
+    "./conditions": "./src/conditions/index.ts",
+    "./schemas": "./src/schemas/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "drizzle-orm": "^0.45.2",
+    "zod": "^4.4.3",
+    "@hogsend/db": "^0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "latest",
+    "@repo/typescript-config": "0.0.0"
+  },
+  "scripts": {
+    "check-types": "tsc --noEmit"
+  }
+}

package/src/conditions/composite.ts

@@ -0,0 +1,26 @@
+import type { CompositeCondition } from "../types/index.js";
+import type { ConditionContext } from "./evaluate.js";
+import { evaluateCondition } from "./evaluate.js";
+
+export async function evaluateCompositeCondition(opts: {
+  condition: CompositeCondition;
+  ctx: ConditionContext;
+}): Promise<boolean> {
+  const { condition, ctx } = opts;
+
+  if (condition.operator === "and") {
+    for (const sub of condition.conditions) {
+      if (!(await evaluateCondition({ condition: sub, ctx }))) return false;
+    }
+    return true;
+  }
+
+  if (condition.operator === "or") {
+    for (const sub of condition.conditions) {
+      if (await evaluateCondition({ condition: sub, ctx })) return true;
+    }
+    return false;
+  }
+
+  return false;
+}

package/src/conditions/email-engagement.ts

@@ -0,0 +1,33 @@
+import { emailSends } from "@hogsend/db/schema";
+import { and, eq } from "drizzle-orm";
+import type { EmailEngagementCondition } from "../types/index.js";
+import type { ConditionContext } from "./evaluate.js";
+
+export async function evaluateEmailEngagementCondition(opts: {
+  condition: EmailEngagementCondition;
+  ctx: ConditionContext;
+}): Promise<boolean> {
+  const { condition, ctx } = opts;
+  const send = await ctx.db.query.emailSends.findFirst({
+    where: and(
+      eq(emailSends.toEmail, ctx.userId),
+      eq(emailSends.templateKey, condition.templateKey),
+    ),
+    orderBy: (sends, { desc }) => [desc(sends.createdAt)],
+  });
+
+  if (!send) return false;
+
+  switch (condition.check) {
+    case "opened":
+      return send.openedAt !== null;
+    case "clicked":
+      return send.clickedAt !== null;
+    case "not_opened":
+      return send.openedAt === null;
+    case "not_clicked":
+      return send.clickedAt === null;
+    default:
+      return false;
+  }
+}

package/src/conditions/evaluate.ts

@@ -0,0 +1,34 @@
+import type { Database } from "@hogsend/db";
+import type { ConditionEval } from "../types/index.js";
+import { evaluateCompositeCondition } from "./composite.js";
+import { evaluateEmailEngagementCondition } from "./email-engagement.js";
+import { evaluateEventCondition } from "./event.js";
+import { evaluatePropertyCondition } from "./property.js";
+
+export interface ConditionContext {
+  db: Database;
+  userId: string;
+  journeyContext: Record<string, unknown>;
+}
+
+export async function evaluateCondition(opts: {
+  condition: ConditionEval;
+  ctx: ConditionContext;
+}): Promise<boolean> {
+  const { condition, ctx } = opts;
+
+  switch (condition.type) {
+    case "property":
+      return evaluatePropertyCondition({ condition, ctx });
+    case "event": {
+      const result = await evaluateEventCondition({ condition, ctx });
+      return result.matched;
+    }
+    case "email_engagement":
+      return evaluateEmailEngagementCondition({ condition, ctx });
+    case "composite":
+      return evaluateCompositeCondition({ condition, ctx });
+    default:
+      return false;
+  }
+}

package/src/conditions/event.ts

@@ -0,0 +1,69 @@
+import { userEvents } from "@hogsend/db/schema";
+import { and, eq, gte, sql } from "drizzle-orm";
+import { durationToMs } from "../duration.js";
+import type { EventCondition } from "../types/index.js";
+import type { ConditionContext } from "./evaluate.js";
+
+export async function evaluateEventCondition(opts: {
+  condition: EventCondition;
+  ctx: ConditionContext;
+}): Promise<{ matched: boolean; count: number }> {
+  const { condition, ctx } = opts;
+  const [result] = await ctx.db
+    .select({ count: sql<number>`count(*)` })
+    .from(userEvents)
+    .where(
+      and(
+        eq(userEvents.userId, ctx.userId),
+        eq(userEvents.event, condition.eventName),
+        condition.within
+          ? gte(
+              userEvents.occurredAt,
+              new Date(Date.now() - durationToMs(condition.within)),
+            )
+          : undefined,
+      ),
+    );
+
+  const count = Number(result?.count ?? 0);
+
+  let matched: boolean;
+  switch (condition.check) {
+    case "exists":
+      matched = count > 0;
+      break;
+    case "not_exists":
+      matched = count === 0;
+      break;
+    case "count": {
+      if (!condition.operator || condition.value === undefined) {
+        matched = count > 0;
+      } else {
+        switch (condition.operator) {
+          case "gt":
+            matched = count > condition.value;
+            break;
+          case "gte":
+            matched = count >= condition.value;
+            break;
+          case "lt":
+            matched = count < condition.value;
+            break;
+          case "lte":
+            matched = count <= condition.value;
+            break;
+          case "eq":
+            matched = count === condition.value;
+            break;
+          default:
+            matched = false;
+        }
+      }
+      break;
+    }
+    default:
+      matched = false;
+  }
+
+  return { matched, count };
+}

package/src/conditions/index.ts

@@ -0,0 +1,3 @@
+export { type ConditionContext, evaluateCondition } from "./evaluate.js";
+export { evaluateEventCondition } from "./event.js";
+export { evaluatePropertyConditions } from "./property.js";

package/src/conditions/property.ts

@@ -0,0 +1,71 @@
+import type { PropertyCondition } from "../types/index.js";
+import type { ConditionContext } from "./evaluate.js";
+
+export function evaluatePropertyCondition(opts: {
+  condition: PropertyCondition;
+  ctx: ConditionContext;
+}): boolean {
+  const { condition, ctx } = opts;
+  const value = ctx.journeyContext[condition.property];
+  return compareValue(value, condition.operator, condition.value);
+}
+
+export function evaluatePropertyConditions(opts: {
+  conditions: PropertyCondition[];
+  properties: Record<string, unknown>;
+}): boolean {
+  const { conditions, properties } = opts;
+  return conditions.every((condition) => {
+    const value = properties[condition.property];
+    return compareValue(value, condition.operator, condition.value);
+  });
+}
+
+function compareValue(
+  actual: unknown,
+  operator: PropertyCondition["operator"],
+  expected: PropertyCondition["value"],
+): boolean {
+  switch (operator) {
+    case "eq":
+      return actual === expected;
+    case "neq":
+      return actual !== expected;
+    case "gt":
+      return (
+        typeof actual === "number" &&
+        typeof expected === "number" &&
+        actual > expected
+      );
+    case "gte":
+      return (
+        typeof actual === "number" &&
+        typeof expected === "number" &&
+        actual >= expected
+      );
+    case "lt":
+      return (
+        typeof actual === "number" &&
+        typeof expected === "number" &&
+        actual < expected
+      );
+    case "lte":
+      return (
+        typeof actual === "number" &&
+        typeof expected === "number" &&
+        actual <= expected
+      );
+    case "exists":
+      return actual !== undefined && actual !== null;
+    case "not_exists":
+      return actual === undefined || actual === null;
+    case "contains":
+      return (
+        typeof actual === "string" &&
+        typeof expected === "string" &&
+        actual.includes(expected)
+      );
+    default:
+      return false;
+  }
+}

package/src/duration.ts

@@ -0,0 +1,25 @@
+export interface DurationObject {
+  readonly hours?: number;
+  readonly minutes?: number;
+  readonly seconds?: number;
+}
+
+export function days(n: number): DurationObject {
+  return { hours: n * 24 };
+}
+
+export function hours(n: number): DurationObject {
+  return { hours: n };
+}
+
+export function minutes(n: number): DurationObject {
+  return { minutes: n };
+}
+
+export function durationToMs(d: DurationObject): number {
+  return (
+    (d.hours ?? 0) * 3_600_000 +
+    (d.minutes ?? 0) * 60_000 +
+    (d.seconds ?? 0) * 1_000
+  );
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export {
+  type ConditionContext,
+  evaluateCondition,
+  evaluateEventCondition,
+  evaluatePropertyConditions,
+} from "./conditions/index.js";
+export {
+  type DurationObject,
+  days,
+  durationToMs,
+  hours,
+  minutes,
+} from "./duration.js";
+export { JourneyRegistry } from "./registry/index.js";
+export { journeyMetaSchema } from "./schemas/index.js";
+export * from "./types/index.js";

package/src/registry/index.ts

@@ -0,0 +1,43 @@
+import { journeyMetaSchema } from "../schemas/index.js";
+import type { JourneyMeta } from "../types/index.js";
+
+export class JourneyRegistry {
+  private journeys: Map<string, JourneyMeta> = new Map();
+  private triggerIndex: Map<string, JourneyMeta[]> = new Map();
+
+  register(journey: JourneyMeta): void {
+    const parsed = journeyMetaSchema.parse(journey);
+    const validated = parsed as unknown as JourneyMeta;
+
+    this.journeys.set(validated.id, validated);
+
+    const event = validated.trigger.event;
+    const existing = this.triggerIndex.get(event) ?? [];
+    existing.push(validated);
+    this.triggerIndex.set(event, existing);
+  }
+
+  get(id: string): JourneyMeta | undefined {
+    return this.journeys.get(id);
+  }
+
+  getByTriggerEvent(eventName: string): JourneyMeta[] {
+    return this.triggerIndex.get(eventName) ?? [];
+  }
+
+  getAll(): JourneyMeta[] {
+    return Array.from(this.journeys.values());
+  }
+
+  getEnabled(): JourneyMeta[] {
+    return this.getAll().filter((j) => j.enabled);
+  }
+
+  has(id: string): boolean {
+    return this.journeys.has(id);
+  }
+
+  count(): number {
+    return this.journeys.size;
+  }
+}

package/src/schemas/index.ts

@@ -0,0 +1 @@
+export { journeyMetaSchema } from "./journey.schema.js";

package/src/schemas/journey.schema.ts

@@ -0,0 +1,88 @@
+import { z } from "zod";
+
+export const propertyConditionSchema = z.object({
+  type: z.literal("property"),
+  property: z.string(),
+  operator: z.enum([
+    "eq",
+    "neq",
+    "gt",
+    "gte",
+    "lt",
+    "lte",
+    "exists",
+    "not_exists",
+    "contains",
+  ]),
+  value: z.union([z.string(), z.number(), z.boolean()]).optional(),
+});
+
+export const eventConditionSchema = z.object({
+  type: z.literal("event"),
+  eventName: z.string(),
+  check: z.enum(["exists", "not_exists", "count"]),
+  operator: z.enum(["gt", "gte", "lt", "lte", "eq"]).optional(),
+  value: z.number().optional(),
+  within: z
+    .object({
+      hours: z.number().optional(),
+      minutes: z.number().optional(),
+      seconds: z.number().optional(),
+    })
+    .optional(),
+});
+
+export const emailEngagementConditionSchema = z.object({
+  type: z.literal("email_engagement"),
+  templateKey: z.string(),
+  check: z.enum(["opened", "clicked", "not_opened", "not_clicked"]),
+});
+
+export const conditionEvalSchema: z.ZodType<unknown> = z.lazy(() =>
+  z.discriminatedUnion("type", [
+    propertyConditionSchema,
+    eventConditionSchema,
+    emailEngagementConditionSchema,
+    z.object({
+      type: z.literal("composite"),
+      operator: z.enum(["and", "or"]),
+      conditions: z.array(conditionEvalSchema),
+    }),
+  ]),
+);
+
+export const journeyMetaSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  description: z.string().optional(),
+  enabled: z.boolean(),
+
+  trigger: z.object({
+    event: z.string().min(1),
+    where: z.array(propertyConditionSchema).optional(),
+  }),
+
+  entryLimit: z.enum(["once", "once_per_period", "unlimited"]),
+  entryPeriod: z
+    .object({
+      hours: z.number().optional(),
+      minutes: z.number().optional(),
+      seconds: z.number().optional(),
+    })
+    .optional(),
+
+  exitOn: z
+    .array(
+      z.object({
+        event: z.string().min(1),
+        where: z.array(propertyConditionSchema).optional(),
+      }),
+    )
+    .optional(),
+
+  suppress: z.object({
+    hours: z.number().optional(),
+    minutes: z.number().optional(),
+    seconds: z.number().optional(),
+  }),
+});

package/src/types/conditions.ts

@@ -0,0 +1,44 @@
+export interface PropertyCondition {
+  type: "property";
+  property: string;
+  operator:
+    | "eq"
+    | "neq"
+    | "gt"
+    | "gte"
+    | "lt"
+    | "lte"
+    | "exists"
+    | "not_exists"
+    | "contains";
+  value?: string | number | boolean;
+}
+
+import type { DurationObject } from "../duration.js";
+
+export interface EventCondition {
+  type: "event";
+  eventName: string;
+  check: "exists" | "not_exists" | "count";
+  operator?: "gt" | "gte" | "lt" | "lte" | "eq";
+  value?: number;
+  within?: DurationObject;
+}
+
+export interface EmailEngagementCondition {
+  type: "email_engagement";
+  templateKey: string;
+  check: "opened" | "clicked" | "not_opened" | "not_clicked";
+}
+
+export interface CompositeCondition {
+  type: "composite";
+  operator: "and" | "or";
+  conditions: ConditionEval[];
+}
+
+export type ConditionEval =
+  | PropertyCondition
+  | EventCondition
+  | EmailEngagementCondition
+  | CompositeCondition;

package/src/types/index.ts

@@ -0,0 +1,3 @@
+export * from "./conditions.js";
+export * from "./journey.js";
+export * from "./journey-context.js";

package/src/types/journey-context.ts

@@ -0,0 +1,80 @@
+import type { DurationObject } from "../duration.js";
+
+export interface SleepOptions {
+  duration: DurationObject;
+  label?: string;
+}
+
+export interface SleepResult {
+  sleptAt: string;
+  resumedAt: string;
+}
+
+export interface TriggerOptions {
+  event: string;
+  userId: string;
+  userEmail?: string;
+  properties?: Record<string, unknown>;
+}
+
+export interface HasEventOptions {
+  userId: string;
+  event: string;
+  within?: DurationObject;
+}
+
+export interface HasEventResult {
+  found: boolean;
+  count: number;
+}
+
+export interface JourneyHistoryOptions {
+  userId: string;
+  journeyId: string;
+}
+
+export interface JourneyHistoryResult {
+  completed: boolean;
+  lastCompletedAt: string | null;
+  entryCount: number;
+}
+
+export interface EmailHistoryOptions {
+  email: string;
+  template: string;
+}
+
+export interface EmailHistoryResult {
+  sent: boolean;
+  lastSentAt: string | null;
+  count: number;
+}
+
+export interface JourneyContext {
+  sleep(opts: SleepOptions): Promise<SleepResult>;
+  checkpoint(label: string): Promise<void>;
+  trigger(opts: TriggerOptions): Promise<void>;
+  identify(properties: Record<string, unknown>): void;
+
+  guard: {
+    isSubscribed(): Promise<boolean>;
+  };
+
+  history: {
+    hasEvent(opts: HasEventOptions): Promise<HasEventResult>;
+    journey(opts: JourneyHistoryOptions): Promise<JourneyHistoryResult>;
+    email(opts: EmailHistoryOptions): Promise<EmailHistoryResult>;
+  };
+
+  posthog: {
+    capture(opts: {
+      event: string;
+      properties?: Record<string, unknown>;
+    }): void;
+  };
+}
+
+export type JourneyRunFn = (
+  user: import("./journey.js").JourneyUser,
+  ctx: JourneyContext,
+) => Promise<void>;

package/src/types/journey.ts

@@ -0,0 +1,33 @@
+import type { DurationObject } from "../duration.js";
+import type { PropertyCondition } from "./conditions.js";
+
+export interface JourneyMeta {
+  id: string;
+  name: string;
+  description?: string;
+  enabled: boolean;
+
+  trigger: {
+    event: string;
+    where?: PropertyCondition[];
+  };
+
+  entryLimit: "once" | "once_per_period" | "unlimited";
+  entryPeriod?: DurationObject;
+
+  exitOn?: Array<{
+    event: string;
+    where?: PropertyCondition[];
+  }>;
+
+  suppress: DurationObject;
+}
+
+export interface JourneyUser {
+  id: string;
+  email: string;
+  properties: Record<string, string | number | boolean | null>;
+  stateId: string;
+  journeyId: string;
+  journeyName: string;
+}