@hogsend/core 0.1.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/core",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -31,7 +31,7 @@
     "drizzle-orm": "^0.45.2",
     "iana-db-timezones": "^0.3.0",
     "zod": "^4.4.3",
-    "@hogsend/db": "^0.1.0"
+    "@hogsend/db": "^0.3.0"
   },
   "devDependencies": {
     "@types/node": "latest",

package/src/conditions/builder.ts

@@ -0,0 +1,163 @@
+import type { DurationObject } from "../duration.js";
+import type {
+  CompositeCondition,
+  ConditionEval,
+  EventCondition,
+  PropertyCondition,
+} from "../types/conditions.js";
+
+type CountOperator = NonNullable<EventCondition["operator"]>;
+
+/** Fluent property predicate. Each terminal returns a plain PropertyCondition. */
+export interface PropertyMatcher {
+  eq(value: string | number | boolean): PropertyCondition;
+  neq(value: string | number | boolean): PropertyCondition;
+  gt(value: number): PropertyCondition;
+  gte(value: number): PropertyCondition;
+  lt(value: number): PropertyCondition;
+  lte(value: number): PropertyCondition;
+  contains(value: string | number | boolean): PropertyCondition;
+  exists(): PropertyCondition;
+  notExists(): PropertyCondition;
+}
+
+/**
+ * Fluent event predicate. The optional `.within(window)` precedes the terminal
+ * (`b.event("x").within(days(7)).notExists()`) so every terminal still returns a
+ * clean EventCondition POJO — no wrapper objects to unwrap.
+ */
+export interface EventMatcher {
+  /** Constrain to a rolling window — this is what makes a bucket time-based. */
+  within(window: DurationObject): EventMatcher;
+  exists(): EventCondition;
+  notExists(): EventCondition;
+  count(operator: CountOperator, value: number): EventCondition;
+  atLeast(value: number): EventCondition;
+  moreThan(value: number): EventCondition;
+  atMost(value: number): EventCondition;
+  lessThan(value: number): EventCondition;
+  exactly(value: number): EventCondition;
+}
+
+/**
+ * The fluent builder passed to a `defineBucket` criteria function. Every terminal
+ * returns a plain `ConditionEval` POJO — byte-identical to the declarative form —
+ * so the registry indexes, schema validation, reconcile cron, and Studio all keep
+ * working unchanged. The function runs ONCE, at bucket-definition time; it never
+ * executes per-user, so criteria stays introspectable data.
+ */
+export interface CriteriaBuilder {
+  prop(property: string): PropertyMatcher;
+  event(eventName: string): EventMatcher;
+  /** Composite AND over the given conditions. */
+  all(...conditions: ConditionEval[]): CompositeCondition;
+  /** Composite OR over the given conditions. */
+  any(...conditions: ConditionEval[]): CompositeCondition;
+}
+
+class PropertyMatcherImpl implements PropertyMatcher {
+  private readonly property: string;
+  constructor(property: string) {
+    this.property = property;
+  }
+  private make(
+    operator: PropertyCondition["operator"],
+    value?: string | number | boolean,
+  ): PropertyCondition {
+    return {
+      type: "property",
+      property: this.property,
+      operator,
+      ...(value !== undefined ? { value } : {}),
+    };
+  }
+  eq(value: string | number | boolean): PropertyCondition {
+    return this.make("eq", value);
+  }
+  neq(value: string | number | boolean): PropertyCondition {
+    return this.make("neq", value);
+  }
+  gt(value: number): PropertyCondition {
+    return this.make("gt", value);
+  }
+  gte(value: number): PropertyCondition {
+    return this.make("gte", value);
+  }
+  lt(value: number): PropertyCondition {
+    return this.make("lt", value);
+  }
+  lte(value: number): PropertyCondition {
+    return this.make("lte", value);
+  }
+  contains(value: string | number | boolean): PropertyCondition {
+    return this.make("contains", value);
+  }
+  exists(): PropertyCondition {
+    return this.make("exists");
+  }
+  notExists(): PropertyCondition {
+    return this.make("not_exists");
+  }
+}
+
+class EventMatcherImpl implements EventMatcher {
+  private readonly eventName: string;
+  private readonly window?: DurationObject;
+  constructor(eventName: string, window?: DurationObject) {
+    this.eventName = eventName;
+    this.window = window;
+  }
+  within(window: DurationObject): EventMatcher {
+    return new EventMatcherImpl(this.eventName, window);
+  }
+  private make(
+    check: EventCondition["check"],
+    operator?: CountOperator,
+    value?: number,
+  ): EventCondition {
+    return {
+      type: "event",
+      eventName: this.eventName,
+      check,
+      ...(operator !== undefined ? { operator } : {}),
+      ...(value !== undefined ? { value } : {}),
+      ...(this.window !== undefined ? { within: this.window } : {}),
+    };
+  }
+  exists(): EventCondition {
+    return this.make("exists");
+  }
+  notExists(): EventCondition {
+    return this.make("not_exists");
+  }
+  count(operator: CountOperator, value: number): EventCondition {
+    return this.make("count", operator, value);
+  }
+  atLeast(value: number): EventCondition {
+    return this.make("count", "gte", value);
+  }
+  moreThan(value: number): EventCondition {
+    return this.make("count", "gt", value);
+  }
+  atMost(value: number): EventCondition {
+    return this.make("count", "lte", value);
+  }
+  lessThan(value: number): EventCondition {
+    return this.make("count", "lt", value);
+  }
+  exactly(value: number): EventCondition {
+    return this.make("count", "eq", value);
+  }
+}
+
+/**
+ * The default {@link CriteriaBuilder} instance. `defineBucket` passes this to a
+ * criteria function and stores the returned `ConditionEval`. Exported so it can
+ * also be used standalone (e.g. composing reusable criteria fragments in tests).
+ */
+export const criteriaBuilder: CriteriaBuilder = {
+  prop: (property) => new PropertyMatcherImpl(property),
+  event: (eventName) => new EventMatcherImpl(eventName),
+  all: (...conditions) => ({ type: "composite", operator: "and", conditions }),
+  any: (...conditions) => ({ type: "composite", operator: "or", conditions }),
+};

package/src/conditions/index.ts

@@ -1,3 +1,9 @@
+export {
+  type CriteriaBuilder,
+  criteriaBuilder,
+  type EventMatcher,
+  type PropertyMatcher,
+} from "./builder.js";
 export { type ConditionContext, evaluateCondition } from "./evaluate.js";
 export { evaluateEventCondition } from "./event.js";
 export { evaluatePropertyConditions } from "./property.js";

package/src/index.ts

@@ -1,8 +1,12 @@
 export {
   type ConditionContext,
+  type CriteriaBuilder,
+  criteriaBuilder,
+  type EventMatcher,
   evaluateCondition,
   evaluateEventCondition,
   evaluatePropertyConditions,
+  type PropertyMatcher,
 } from "./conditions/index.js";
 export {
   type DurationObject,
@@ -11,7 +15,12 @@ export {
   hours,
   minutes,
 } from "./duration.js";
-export { JourneyRegistry } from "./registry/index.js";
+export {
+  BucketRegistry,
+  collectEventNames,
+  collectPropertyNames,
+  JourneyRegistry,
+} from "./registry/index.js";
 export * from "./schedule/index.js";
-export { journeyMetaSchema } from "./schemas/index.js";
+export { bucketMetaSchema, journeyMetaSchema } from "./schemas/index.js";
 export * from "./types/index.js";

package/src/registry/bucket.ts

@@ -0,0 +1,119 @@
+import { bucketMetaSchema } from "../schemas/index.js";
+import type { BucketMeta, ConditionEval } from "../types/index.js";
+
+/**
+ * Walk a ConditionEval tree, collecting every EventCondition.eventName. Pure
+ * tree walk over the discriminated union, mirroring core/conditions/event.ts.
+ */
+export function collectEventNames(criteria: ConditionEval): string[] {
+  const names: string[] = [];
+  const visit = (condition: ConditionEval): void => {
+    switch (condition.type) {
+      case "event":
+        names.push(condition.eventName);
+        break;
+      case "composite":
+        for (const child of condition.conditions) {
+          visit(child);
+        }
+        break;
+      default:
+        break;
+    }
+  };
+  visit(criteria);
+  return names;
+}
+
+/**
+ * Walk a ConditionEval tree, collecting every PropertyCondition.property. Pure
+ * tree walk over the discriminated union.
+ */
+export function collectPropertyNames(criteria: ConditionEval): string[] {
+  const names: string[] = [];
+  const visit = (condition: ConditionEval): void => {
+    switch (condition.type) {
+      case "property":
+        names.push(condition.property);
+        break;
+      case "composite":
+        for (const child of condition.conditions) {
+          visit(child);
+        }
+        break;
+      default:
+        break;
+    }
+  };
+  visit(criteria);
+  return names;
+}
+
+export class BucketRegistry {
+  private buckets: Map<string, BucketMeta> = new Map();
+  private eventIndex: Map<string, BucketMeta[]> = new Map();
+  private propertyIndex: Map<string, BucketMeta[]> = new Map();
+  // degenerate: criteria reference neither a concrete event nor any property
+  private wildcard: BucketMeta[] = [];
+
+  register(bucket: BucketMeta): void {
+    const parsed = bucketMetaSchema.parse(bucket);
+    const validated = parsed as unknown as BucketMeta;
+
+    this.buckets.set(validated.id, validated);
+
+    // manual buckets are not criteria-driven → not indexed for real-time eval
+    if (validated.kind === "manual" || !validated.criteria) {
+      return;
+    }
+
+    const events = collectEventNames(validated.criteria);
+    const props = collectPropertyNames(validated.criteria);
+
+    for (const eventName of events) {
+      const existing = this.eventIndex.get(eventName) ?? [];
+      existing.push(validated);
+      this.eventIndex.set(eventName, existing);
+    }
+
+    for (const propName of props) {
+      const existing = this.propertyIndex.get(propName) ?? [];
+      existing.push(validated);
+      this.propertyIndex.set(propName, existing);
+    }
+
+    // "*" ONLY for criteria referencing neither a concrete event nor a property
+    // (degenerate; rare under the at-least-one-positive rule).
+    if (events.length === 0 && props.length === 0) {
+      this.wildcard.push(validated);
+    }
+  }
+
+  get(id: string): BucketMeta | undefined {
+    return this.buckets.get(id);
+  }
+
+  getByReferencedEvent(eventName: string): BucketMeta[] {
+    return [...(this.eventIndex.get(eventName) ?? []), ...this.wildcard];
+  }
+
+  getByReferencedProperty(propName: string): BucketMeta[] {
+    return this.propertyIndex.get(propName) ?? [];
+  }
+
+  getAll(): BucketMeta[] {
+    return Array.from(this.buckets.values());
+  }
+
+  getEnabled(): BucketMeta[] {
+    return this.getAll().filter((b) => b.enabled);
+  }
+
+  has(id: string): boolean {
+    return this.buckets.has(id);
+  }
+
+  count(): number {
+    return this.buckets.size;
+  }
+}

package/src/registry/index.ts

@@ -1,6 +1,12 @@
 import { journeyMetaSchema } from "../schemas/index.js";
 import type { JourneyMeta } from "../types/index.js";
 
+export {
+  BucketRegistry,
+  collectEventNames,
+  collectPropertyNames,
+} from "./bucket.js";
+
 export class JourneyRegistry {
   private journeys: Map<string, JourneyMeta> = new Map();
   private triggerIndex: Map<string, JourneyMeta[]> = new Map();

package/src/schemas/bucket.schema.ts

@@ -0,0 +1,172 @@
+import { z } from "zod";
+import { durationToMs } from "../duration.js";
+import type {
+  CompositeCondition,
+  ConditionEval,
+  EmailEngagementCondition,
+  EventCondition,
+  PropertyCondition,
+} from "../types/conditions.js";
+import { conditionEvalSchema } from "./journey.schema.js";
+
+const durationObjectSchema = z.object({
+  hours: z.number().optional(),
+  minutes: z.number().optional(),
+  seconds: z.number().optional(),
+});
+
+/**
+ * Walk a ConditionEval tree, yielding every leaf node (property / event /
+ * email_engagement). Composites recurse into their `conditions` array. Mirrors
+ * the pure discriminated-union walks in core/conditions.
+ */
+function* walkConditions(
+  condition: ConditionEval,
+): Generator<PropertyCondition | EventCondition | EmailEngagementCondition> {
+  if (condition.type === "composite") {
+    for (const child of (condition as CompositeCondition).conditions) {
+      yield* walkConditions(child);
+    }
+    return;
+  }
+  yield condition;
+}
+
+/**
+ * A leaf condition is "negative" when satisfying the bucket means the absence /
+ * inequality of data. A dynamic bucket whose every leaf is negative is
+ * degenerate/unbounded (the Customer.io rule), so at least one positive leaf is
+ * required.
+ *
+ * Exception: a TIME-BOUNDED behavioral absence — `event` `not_exists` with a
+ * `within` window ("did NOT do X in the last N") — is the canonical
+ * dormancy/churn predicate (e.g. the `went-dormant` bucket and the whole
+ * cron-reconcile leave path exist for it). It is bounded by its window, so it
+ * is NOT degenerate and counts as a legitimate anchor. Only an UNBOUNDED
+ * absence (`not_exists` with no `within`) matches nearly everyone and is
+ * treated as a pure-negation leaf.
+ */
+function isNegativeLeaf(
+  leaf: PropertyCondition | EventCondition | EmailEngagementCondition,
+): boolean {
+  switch (leaf.type) {
+    case "property":
+      return leaf.operator === "neq" || leaf.operator === "not_exists";
+    case "event":
+      return leaf.check === "not_exists" && leaf.within === undefined;
+    case "email_engagement":
+      return leaf.check === "not_opened" || leaf.check === "not_clicked";
+    default:
+      return false;
+  }
+}
+
+export const bucketMetaSchema = z
+  .object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    description: z.string().optional(),
+    enabled: z.boolean(),
+
+    kind: z.enum(["dynamic", "manual"]).optional(),
+
+    criteria: conditionEvalSchema.optional(),
+
+    entryLimit: z.enum(["once", "once_per_period", "unlimited"]).optional(),
+    entryPeriod: durationObjectSchema.optional(),
+
+    minDwell: durationObjectSchema.optional(),
+    maxDwell: durationObjectSchema.optional(),
+
+    timeBased: z.boolean().optional(),
+    reconcileEvery: durationObjectSchema.optional(),
+    reconcileJoins: z.boolean().optional(),
+    fastExpiry: z.boolean().optional(),
+
+    syncToPostHog: z.boolean().optional(),
+    postHogPropertyKey: z.string().optional(),
+  })
+  .superRefine((meta, ctx) => {
+    const kind = meta.kind ?? "dynamic";
+    const criteria = meta.criteria as ConditionEval | undefined;
+
+    // minDwell is a floor, maxDwell an unconditional ceiling. A ceiling below the
+    // floor is contradictory — the TTL leave would be permanently blocked by the
+    // minDwell guard. Applies regardless of kind.
+    if (
+      meta.minDwell &&
+      meta.maxDwell &&
+      durationToMs(meta.maxDwell) < durationToMs(meta.minDwell)
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["maxDwell"],
+        message: "maxDwell must be greater than or equal to minDwell.",
+      });
+    }
+
+    // Rule 4: kind/criteria coherence. `kind:"manual"` is declared on the
+    // discriminator for forward-compat (Phase 4) but is NOT implemented in v1 —
+    // it would register as a silent no-op (never populated by the real-time path
+    // or the reconcile cron). Reject it LOUDLY at registration time
+    // (bucketMetaSchema.parse) rather than accepting a bucket that can never
+    // gain members. This is a runtime-validation tightening, not a type break:
+    // the `kind` enum still allows declaring "manual".
+    if (kind === "manual") {
+      ctx.addIssue({
+        code: "custom",
+        path: ["kind"],
+        message:
+          'kind:"manual" buckets are not implemented in v1; use a dynamic ' +
+          'bucket (kind:"dynamic" with `criteria`) instead.',
+      });
+      return;
+    }
+
+    // kind:"dynamic" (or omitted) REQUIRES a non-empty criteria.
+    if (criteria === undefined) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["criteria"],
+        message: 'kind:"dynamic" buckets require a non-empty `criteria`.',
+      });
+      return;
+    }
+
+    const leaves = Array.from(walkConditions(criteria));
+
+    // Rule 1: at-least-one-positive-condition (dynamic buckets only).
+    if (leaves.length > 0 && leaves.every(isNegativeLeaf)) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["criteria"],
+        message:
+          "Dynamic buckets must contain at least one positive condition; " +
+          "pure-negation criteria are degenerate/unbounded.",
+      });
+    }
+
+    for (const leaf of leaves) {
+      // Rule 2: reserved-prefix rejection on EventCondition.eventName.
+      if (leaf.type === "event" && leaf.eventName.startsWith("bucket:")) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["criteria"],
+          message:
+            "criteria must not reference a reserved `bucket:*` event name " +
+            `(found "${leaf.eventName}").`,
+        });
+      }
+
+      // Rule 3: email_engagement forbidden anywhere in v1.
+      if (leaf.type === "email_engagement") {
+        ctx.addIssue({
+          code: "custom",
+          path: ["criteria"],
+          message:
+            "email_engagement conditions are not allowed in bucket criteria " +
+            "in v1.",
+        });
+      }
+    }
+  });

package/src/schemas/index.ts

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

package/src/types/bucket.ts

@@ -0,0 +1,102 @@
+import type { DurationObject } from "../duration.js";
+import type { ConditionEval } from "./conditions.js";
+
+export interface BucketMeta {
+  id: string;
+  name: string;
+  description?: string;
+  /** Static load-time flag (guard #1), mirrors JourneyMeta.enabled. */
+  enabled: boolean;
+
+  /**
+   * Discriminator, declared NOW for forward-compat even though "manual" ships in
+   * Phase 4. "dynamic" (default) = membership auto-recomputed from `criteria`;
+   * "manual" = membership mutated only by explicit API/import, NO criteria,
+   * skipped by checkBucketMembership and the reconcile cron (early-continue, the
+   * Laudspeaker pattern). Declaring it up front keeps Phase 4 genuinely additive
+   * — no breaking change to BucketMeta later. Default "dynamic".
+   *
+   * v1: kind:"manual" is REJECTED at registration time (bucketMetaSchema parse)
+   * because nothing populates a manual bucket yet — it would be a silent no-op.
+   * The value stays on the enum for forward-compat; use kind:"dynamic" with
+   * `criteria` until full manual membership ships.
+   */
+  kind?: "dynamic" | "manual";
+
+  /**
+   * Membership predicate — the existing 4-type condition engine
+   * (packages/core/src/conditions/evaluate.ts). Inclusion AND exclusion come
+   * for free via neq / not_exists / not_opened and event check:"not_exists".
+   * REQUIRED for kind:"dynamic" (omit/empty for kind:"manual"). Dynamic buckets
+   * MUST contain at least one positive condition (validated; pure-negation
+   * buckets are degenerate/unbounded — the Customer.io rule). The
+   * at-least-one-positive refine applies to dynamic buckets only.
+   * NOTE: criteria MUST NOT reference a reserved `bucket:*` event name in any
+   * EventCondition.eventName (rejected at registration — see 4.2), so transition
+   * rows can never satisfy a bucket predicate.
+   */
+  criteria?: ConditionEval;
+
+  /**
+   * Re-entry policy for EMITTED join events (maps onto checkEntryLimit
+   * semantics). "once" = emit bucket:entered once ever; "once_per_period" =
+   * re-emit only after a prior leave + period elapses; "unlimited" = always.
+   * Default "unlimited".
+   */
+  entryLimit?: "once" | "once_per_period" | "unlimited";
+  entryPeriod?: DurationObject;
+
+  /**
+   * Anti-flap: suppress bucket:left until membership has existed at least this
+   * long (debounce). Guards journeys from re-enroll spam on oscillation.
+   */
+  minDwell?: DurationObject;
+
+  /**
+   * Maximum dwell — an UNCONDITIONAL membership TTL. `maxDwell` after the user
+   * joined, the reconcile cron force-leaves them REGARDLESS of whether the
+   * criteria still match (contrast `within`, which is criteria-driven, and
+   * `minDwell`, which is a floor). Use it for time-boxed membership: "in this
+   * bucket for exactly N days, then out".
+   *
+   * Re-entry after a maxDwell exit is governed by `entryLimit` (per-bucket): pair
+   * with `entryLimit:"once"` / `"once_per_period"` for a HARD time-box (they stay
+   * out / cool off), or leave the default `"unlimited"` for a PERIODIC FLUSH
+   * (they re-join on their next qualifying event). Independent of `within` and
+   * `fastExpiry`; if `minDwell` is also set it must be <= `maxDwell` (validated).
+   * Enforced by the reconcile cron, so the exit lands within the reconcile
+   * cadence (default 5m), not to-the-second.
+   */
+  maxDwell?: DurationObject;
+
+  /**
+   * Reconciliation knobs.
+   * timeBased: criteria contain an event `within` window a clock can expire —
+   *   the ONLY kind the cron sweep touches (candidate narrowing). Inferred from
+   *   a criteria walk if omitted; an explicit value overrides.
+   * reconcileEvery: advisory cadence surfaced in Studio (the single engine-wide
+   *   cron sweeps all time-based buckets; per-bucket cadence is informational).
+   * reconcileJoins: also re-evaluate JOINS in the sweep. Tri-state:
+   *   `false` = hard OFF (cost-bounding override, even for absence buckets);
+   *   `true` = explicit ON; `undefined` = INFERRED — ON only for absence-shaped
+   *   criteria (a windowed `not_exists` leg, the sole shape a clock can JOIN, so
+   *   went-dormant works with no extra config), OFF otherwise (the real-time
+   *   path already catches positive joins on event arrival; keep the sweep
+   *   O(active members)).
+   * fastExpiry: opt-in per-user durable timer for sub-second absence-leave on
+   *   latency-critical buckets (Approach A graft). The cron remains the
+   *   authoritative backstop. Default false.
+   */
+  timeBased?: boolean;
+  reconcileEvery?: DurationObject;
+  reconcileJoins?: boolean;
+  fastExpiry?: boolean;
+
+  /**
+   * PostHog person-property sync (Section 12). Off by default. When set, on
+   * join/leave the engine $set/$unset a boolean person property keyed by
+   * `postHogPropertyKey` (default `hogsend_bucket_<id>`).
+   */
+  syncToPostHog?: boolean;
+  postHogPropertyKey?: string;
+}

package/src/types/index.ts

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