@hogsend/db 0.0.1 → 0.2.0

package/src/schema/bucket-configs.ts

@@ -0,0 +1,17 @@
+import { boolean, pgTable, text, uniqueIndex, uuid } from "drizzle-orm/pg-core";
+import { timestamps } from "./_shared.js";
+
+export const bucketConfigs = pgTable(
+  "bucket_configs",
+  {
+    id: uuid("id").defaultRandom().primaryKey(),
+    bucketId: text("bucket_id").notNull(),
+    enabled: boolean("enabled").notNull().default(true),
+    // Stable hash of the normalized ConditionEval, written at boot. Diffed on the
+    // next boot to detect a CRITERIA CHANGE and enqueue the re-evaluation job
+    // (Section 6.6 B). Nullable until the first registration.
+    criteriaHash: text("criteria_hash"),
+    ...timestamps,
+  },
+  (table) => [uniqueIndex("bucket_configs_bucket_id_idx").on(table.bucketId)],
+);

package/src/schema/bucket-memberships.ts

@@ -0,0 +1,72 @@
+import { sql } from "drizzle-orm";
+import {
+  index,
+  integer,
+  jsonb,
+  pgTable,
+  text,
+  timestamp,
+  uniqueIndex,
+  uuid,
+} from "drizzle-orm/pg-core";
+import { timestamps } from "./_shared.js";
+import { bucketMembershipStatusEnum } from "./enums.js";
+
+export const bucketMemberships = pgTable(
+  "bucket_memberships",
+  {
+    id: uuid("id").defaultRandom().primaryKey(),
+    // multi-tenant insurance (nullable today, NOT in the unique key — see note)
+    organizationId: text("organization_id"),
+    // logical join to contacts.externalId — NO FK (matches userEvents /
+    // journeyStates; membership rows can predate a contacts row).
+    userId: text("user_id").notNull(),
+    userEmail: text("user_email"), // denormalized so emitted events carry it
+    bucketId: text("bucket_id").notNull(),
+    status: bucketMembershipStatusEnum("status").notNull().default("active"),
+    enteredAt: timestamp("entered_at", { withTimezone: true })
+      .defaultNow()
+      .notNull(),
+    leftAt: timestamp("left_at", { withTimezone: true }),
+    // membership epoch / armed deadline for time-based + fastExpiry buckets
+    expiresAt: timestamp("expires_at", { withTimezone: true }),
+    // unconditional membership TTL deadline (enteredAt + meta.maxDwell). Set once
+    // on join, never mutated. The reconcile cron force-leaves rows past it
+    // REGARDLESS of criteria — kept separate from expiresAt, which is the
+    // criteria-window / minDwell-defer arming epoch (overloaded meaning).
+    maxDwellAt: timestamp("max_dwell_at", { withTimezone: true }),
+    lastEvaluatedAt: timestamp("last_evaluated_at", { withTimezone: true }),
+    entryCount: integer("entry_count").notNull().default(1),
+    source: text("source"), // "event" | "reconcile" | "backfill" | "manual"
+    context: jsonb("context").$type<Record<string, unknown>>().default({}),
+    deletedAt: timestamp("deleted_at", { withTimezone: true }),
+    ...timestamps,
+  },
+  (table) => [
+    // EXACTLY ONE ACTIVE membership per (user, bucket), with any number of
+    // historical "left" rows coexisting. This is a PARTIAL unique index scoped
+    // to active, non-deleted rows — NOT a plain (userId,bucketId,status) unique
+    // index. Buckets are re-entrant: a user oscillates join → leave → join →
+    // leave forever, so a plain unique key on (userId,bucketId,status) would
+    // throw on the SECOND "left" row (two rows share (user,bucket,'left')). The
+    // journeyStates model does NOT transfer here because journey terminal states
+    // are reached once; bucket "left" is reached repeatedly. The generated SQL
+    // is `CREATE UNIQUE INDEX uq_user_bucket_active ON bucket_memberships
+    // (user_id, bucket_id) WHERE status = 'active' AND deleted_at IS NULL`.
+    // organizationId deliberately OMITTED — same NULLS-DISTINCT caveat as
+    // uq_user_journey_active (journey-states.ts:34-40). Add it to the predicate
+    // only when multi-tenancy lands and the column is non-null.
+    uniqueIndex("uq_user_bucket_active")
+      .on(table.userId, table.bucketId)
+      .where(sql`status = 'active' AND deleted_at IS NULL`),
+    index("bucket_memberships_bucket_id_status_idx").on(
+      table.bucketId,
+      table.status,
+    ), // list members / size metrics
+    index("bucket_memberships_user_id_idx").on(table.userId), // a user's buckets
+    index("bucket_memberships_last_evaluated_idx").on(table.lastEvaluatedAt),
+    index("bucket_memberships_expires_at_idx").on(table.expiresAt),
+    // the cron TTL sweep: active rows past their max_dwell_at
+    index("bucket_memberships_max_dwell_at_idx").on(table.maxDwellAt),
+  ],
+);

package/src/schema/contacts.ts

@@ -15,6 +15,13 @@ export const contacts = pgTable(
     organizationId: text("organization_id"),
     externalId: text("external_id").notNull().unique(),
     email: text("email"),
+    /**
+     * Opportunistic IANA-timezone cache (e.g. "America/New_York"). Populated
+     * best-effort when a tz is resolved from PostHog person props. PostHog and
+     * `properties` jsonb remain authoritative sources — this column sits below
+     * them in the resolution precedence, so nothing is blocked on it.
+     */
+    timezone: text("timezone"),
     properties: jsonb("properties")
       .$type<Record<string, unknown>>()
       .default({}),

package/src/schema/email-sends.ts

@@ -9,6 +9,11 @@ export const emailSends = pgTable(
     id: uuid("id").defaultRandom().primaryKey(),
     organizationId: text("organization_id"),
     journeyStateId: uuid("journey_state_id").references(() => journeyStates.id),
+    // Denormalized recipient identity, set at send time. Lets reporting attribute
+    // a send to a contact without joining journey_states, and captures journeyless
+    // (raw/batch) sends that have no journey linkage. Both nullable.
+    userId: text("user_id"),
+    userEmail: text("user_email"),
     templateKey: text("template_key"),
     resendId: text("resend_id"),
     fromEmail: text("from_email").notNull(),
@@ -22,6 +27,9 @@ export const emailSends = pgTable(
     clickedAt: timestamp("clicked_at", { withTimezone: true }),
     bouncedAt: timestamp("bounced_at", { withTimezone: true }),
     complainedAt: timestamp("complained_at", { withTimezone: true }),
+    // Bounce classification from the Resend webhook (hard/soft/transient + reason).
+    bounceType: text("bounce_type"),
+    bounceReason: text("bounce_reason"),
     ...timestamps,
   },
   (table) => [
@@ -30,5 +38,12 @@ export const emailSends = pgTable(
     index("email_sends_status_idx").on(table.status),
     index("email_sends_created_at_idx").on(table.createdAt),
     index("email_sends_journey_state_id_idx").on(table.journeyStateId),
+    index("email_sends_user_id_idx").on(table.userId),
+    // Serves the frequency-cap COUNT (recipient + recency, optionally category).
+    index("email_sends_freq_cap_idx").on(
+      table.toEmail,
+      table.createdAt,
+      table.category,
+    ),
   ],
 );

package/src/schema/enums.ts

@@ -45,3 +45,8 @@ export const dlqStatusEnum = pgEnum("dlq_status", [
   "retried",
   "discarded",
 ]);
+
+export const bucketMembershipStatusEnum = pgEnum("bucket_membership_status", [
+  "active",
+  "left",
+]);

package/src/schema/index.ts

@@ -3,6 +3,8 @@ export * from "./alert-rules.js";
 export * from "./api-keys.js";
 export * from "./audit-logs.js";
 export * from "./auth.js";
+export * from "./bucket-configs.js";
+export * from "./bucket-memberships.js";
 export * from "./contacts.js";
 export * from "./dead-letter-queue.js";
 export * from "./email-preferences.js";

package/src/schema/relations.ts

@@ -11,6 +11,8 @@ import {
   session,
   user,
 } from "./auth.js";
+import { bucketConfigs } from "./bucket-configs.js";
+import { bucketMemberships } from "./bucket-memberships.js";
 import { contacts } from "./contacts.js";
 import { deadLetterQueue } from "./dead-letter-queue.js";
 import { emailPreferences } from "./email-preferences.js";
@@ -44,12 +46,25 @@ export const importJobsRelations = relations(importJobs, () => ({}));
 
 export const journeyConfigsRelations = relations(journeyConfigs, () => ({}));
 
+export const bucketConfigsRelations = relations(bucketConfigs, () => ({}));
+
 export const contactsRelations = relations(contacts, ({ many }) => ({
   emailPreferences: many(emailPreferences),
   userEvents: many(userEvents),
   journeyStates: many(journeyStates),
+  bucketMemberships: many(bucketMemberships),
 }));
 
+export const bucketMembershipsRelations = relations(
+  bucketMemberships,
+  ({ one }) => ({
+    contact: one(contacts, {
+      fields: [bucketMemberships.userId],
+      references: [contacts.externalId],
+    }),
+  }),
+);
+
 export const emailPreferencesRelations = relations(
   emailPreferences,
   ({ one }) => ({

package/src/stamp.ts

@@ -0,0 +1,85 @@
+import { existsSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { sql } from "drizzle-orm";
+import { readMigrationFiles } from "drizzle-orm/migrator";
+import { drizzle } from "drizzle-orm/postgres-js";
+import postgres from "postgres";
+import {
+  ENGINE_MIGRATIONS_SCHEMA,
+  ENGINE_MIGRATIONS_TABLE,
+} from "./version.js";
+
+// `db:stamp` — record every bundled engine migration as applied in the ledger
+// WITHOUT running any SQL.
+//
+// Use this when the database schema is already current but the migration ledger
+// is behind — the classic case being a dev DB bootstrapped with `db:push`
+// (which syncs the schema directly and never writes the ledger). In that state
+// `db:migrate` tries to replay migrations whose objects already exist ("type
+// already exists") and the boot guard reports `migration_pending`.
+//
+// WARNING: only run this when you are sure the schema already matches HEAD
+// (e.g. it was `db:push`-ed). Stamping a DB that is genuinely missing columns
+// would mark migrations applied without creating their objects.
+
+async function run(): Promise<void> {
+  const databaseUrl = process.env.DATABASE_URL;
+  if (!databaseUrl) {
+    console.error("DATABASE_URL environment variable is required");
+    process.exit(1);
+  }
+
+  const migrationsFolder = new URL("../drizzle", import.meta.url).pathname;
+  if (!existsSync(migrationsFolder)) {
+    console.log("[stamp] No migrations folder found, nothing to stamp.");
+    return;
+  }
+
+  const migrations = readMigrationFiles({ migrationsFolder });
+  const client = postgres(databaseUrl, { max: 1, idle_timeout: 0 });
+  const db = drizzle(client);
+
+  const S = sql.identifier(ENGINE_MIGRATIONS_SCHEMA);
+  const T = sql.identifier(ENGINE_MIGRATIONS_TABLE);
+
+  try {
+    await db.execute(sql`CREATE SCHEMA IF NOT EXISTS ${S}`);
+    await db.execute(
+      sql`CREATE TABLE IF NOT EXISTS ${S}.${T} ("id" SERIAL PRIMARY KEY, "hash" text NOT NULL, "created_at" bigint)`,
+    );
+
+    const existing = (await db.execute(
+      sql`SELECT created_at FROM ${S}.${T}`,
+    )) as unknown as Array<{ created_at: number | string | null }>;
+    const have = new Set(existing.map((r) => String(r.created_at)));
+
+    let inserted = 0;
+    for (const m of migrations) {
+      if (!have.has(String(m.folderMillis))) {
+        await db.execute(
+          sql`INSERT INTO ${S}.${T} ("hash", "created_at") VALUES (${m.hash}, ${m.folderMillis})`,
+        );
+        inserted++;
+      }
+    }
+
+    console.log(
+      `[stamp] Ledger now reflects ${migrations.length} bundled migration(s); inserted ${inserted} missing row(s). No schema changes were applied.`,
+    );
+  } finally {
+    await client.end();
+  }
+}
+
+const invokedDirectly =
+  process.argv[1] !== undefined &&
+  import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (invokedDirectly) {
+  run()
+    .then(() => process.exit(0))
+    .catch((err) => {
+      console.error("Stamp failed:", err);
+      process.exit(1);
+    });
+}