@hogsend/db 0.6.0 → 0.7.0

package/drizzle/meta/_journal.json

@@ -99,6 +99,34 @@
       "when": 1780734148043,
       "tag": "0013_illegal_firedrake",
       "breakpoints": true
+    },
+    {
+      "idx": 14,
+      "version": "7",
+      "when": 1780829225830,
+      "tag": "0014_front_door_identity",
+      "breakpoints": true
+    },
+    {
+      "idx": 15,
+      "version": "7",
+      "when": 1780833852463,
+      "tag": "0015_crazy_kronos",
+      "breakpoints": true
+    },
+    {
+      "idx": 16,
+      "version": "7",
+      "when": 1780840132281,
+      "tag": "0016_campaigns",
+      "breakpoints": true
+    },
+    {
+      "idx": 17,
+      "version": "7",
+      "when": 1780841637175,
+      "tag": "0017_long_spacker_dave",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/db",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "license": "MIT",
   "repository": {

package/src/schema/campaigns.ts

@@ -0,0 +1,71 @@
+import { sql } from "drizzle-orm";
+import {
+  index,
+  integer,
+  jsonb,
+  pgTable,
+  text,
+  timestamp,
+  uniqueIndex,
+  uuid,
+} from "drizzle-orm/pg-core";
+import { timestamps } from "./_shared.js";
+
+/**
+ * One-shot campaign / broadcast (Loops "campaign" parity): a single email
+ * template sent to every subscribed member of a LIST (or every active member of
+ * a BUCKET). A row is created in `queued` by `POST /v1/campaigns`, then the
+ * durable `send-campaign` Hatchet task transitions it `sending → sent`/`failed`
+ * and tallies the final counts.
+ *
+ * `status` is a plain text column (not an enum) so adding a future state needs
+ * no migration; the app constrains it to `queued|sending|sent|failed`.
+ *
+ * `audienceKind` + `audienceId` reference a code-defined list (ListRegistry) or
+ * bucket (BucketRegistry) by string id — NOT a contacts FK, so there is no
+ * relation to wire.
+ */
+export const campaigns = pgTable(
+  "campaigns",
+  {
+    id: uuid("id").defaultRandom().primaryKey(),
+    organizationId: text("organization_id"),
+    name: text("name").notNull(),
+    // queued | sending | sent | failed
+    status: text("status").notNull().default("queued"),
+    // "list" | "bucket"
+    audienceKind: text("audience_kind").notNull(),
+    // the list id (ListRegistry) or bucket id (BucketRegistry)
+    audienceId: text("audience_id").notNull(),
+    templateKey: text("template_key").notNull(),
+    props: jsonb("props").$type<Record<string, unknown>>().default({}),
+    fromEmail: text("from_email"),
+    subject: text("subject"),
+    /**
+     * Optional client-supplied idempotency key (POST /v1/campaigns
+     * `Idempotency-Key` header / body field). A retried create with the same key
+     * resolves to the EXISTING campaign instead of spawning a second broadcast
+     * (a distinct campaignId would give the same recipient a different per-send
+     * idempotency key, double-sending the blast). Uniqueness is enforced by the
+     * partial-unique index below (NULL keys are unconstrained).
+     */
+    idempotencyKey: text("idempotency_key"),
+    totalRecipients: integer("total_recipients").notNull().default(0),
+    sentCount: integer("sent_count").notNull().default(0),
+    skippedCount: integer("skipped_count").notNull().default(0),
+    failedCount: integer("failed_count").notNull().default(0),
+    startedAt: timestamp("started_at", { withTimezone: true }),
+    completedAt: timestamp("completed_at", { withTimezone: true }),
+    ...timestamps,
+  },
+  (table) => [
+    index("campaigns_status_idx").on(table.status),
+    index("campaigns_created_at_idx").on(table.createdAt),
+    // Partial-unique on the client idempotency key (scoped to non-NULL keys so
+    // the common keyless create is unconstrained). A retried create with the
+    // same key collides here and resolves to the existing campaign.
+    uniqueIndex("campaigns_idempotency_key_idx")
+      .on(table.idempotencyKey)
+      .where(sql`idempotency_key IS NOT NULL`),
+  ],
+);

package/src/schema/contact-aliases.ts

@@ -0,0 +1,41 @@
+import { index, pgTable, text, uniqueIndex, uuid } from "drizzle-orm/pg-core";
+import { timestamps } from "./_shared.js";
+import { contacts } from "./contacts.js";
+
+/**
+ * Alias table for identity resolution. After a merge (or a fill-in-link
+ * "promote"), a stale identity key — the loser's old external_id / email /
+ * anonymous_id — sits on a soft-deleted row, so the `deleted_at IS NULL`
+ * lookups in `findByExternalId`/`findByEmail` miss it. This table lets a stale
+ * key resolve to the SURVIVOR contact instead of minting a fresh row and
+ * re-splitting history (risk 5). Each `findByX` falls back to it on a miss.
+ */
+export const contactAliases = pgTable(
+  "contact_aliases",
+  {
+    id: uuid("id").defaultRandom().primaryKey(),
+    // The SURVIVOR a stale key resolves TO.
+    contactId: uuid("contact_id")
+      .notNull()
+      .references(() => contacts.id, { onDelete: "cascade" }),
+    // 'email' | 'external' | 'anonymous'
+    aliasKind: text("alias_kind").notNull(),
+    // The stale key value (the loser's old external_id / normalized email /
+    // anonymous_id).
+    aliasValue: text("alias_value").notNull(),
+    // Provenance: the loser contact id this alias came from (nullable — a
+    // 'promote' alias may have no distinct loser row).
+    fromContactId: uuid("from_contact_id"),
+    // 'merge' | 'promote'
+    reason: text("reason").notNull(),
+    ...timestamps,
+  },
+  (table) => [
+    // One alias per (kind, value): a stale key resolves to exactly one survivor.
+    uniqueIndex("contact_aliases_kind_value_idx").on(
+      table.aliasKind,
+      table.aliasValue,
+    ),
+    index("contact_aliases_contact_id_idx").on(table.contactId),
+  ],
+);

package/src/schema/contacts.ts

@@ -1,9 +1,11 @@
+import { sql } from "drizzle-orm";
 import {
   index,
   jsonb,
   pgTable,
   text,
   timestamp,
+  uniqueIndex,
   uuid,
 } from "drizzle-orm/pg-core";
 import { timestamps } from "./_shared.js";
@@ -13,8 +15,22 @@ export const contacts = pgTable(
   {
     id: uuid("id").defaultRandom().primaryKey(),
     organizationId: text("organization_id"),
-    externalId: text("external_id").notNull().unique(),
+    /**
+     * Stable external/distinct id (= the `user_id` text key joined by every
+     * contact-referencing table). NULLABLE since D1: contacts can be email-only
+     * or anonymous-only. Uniqueness is enforced by the partial-unique index
+     * below (scoped to live, non-deleted rows) rather than an inline `.unique()`
+     * — a soft-deleted loser row must be able to keep its stale external_id
+     * until a merge re-points it.
+     */
+    externalId: text("external_id"),
     email: text("email"),
+    /**
+     * Stable anonymous/distinct id for the future anonymous→identified path.
+     * NULLABLE. Like external_id, uniqueness is enforced by a partial-unique
+     * index scoped to live, non-deleted rows.
+     */
+    anonymousId: text("anonymous_id"),
     /**
      * Opportunistic IANA-timezone cache (e.g. "America/New_York"). Populated
      * best-effort when a tz is resolved from PostHog person props. PostHog and
@@ -34,5 +50,24 @@ export const contacts = pgTable(
     deletedAt: timestamp("deleted_at", { withTimezone: true }),
     ...timestamps,
   },
-  (table) => [index("contacts_email_idx").on(table.email)],
+  (table) => [
+    // Plain (non-unique) lookup index on email — kept for the email-search path.
+    index("contacts_email_idx").on(table.email),
+    // D1 partial-unique identity indexes. Each is scoped to live rows
+    // (`WHERE col IS NOT NULL AND deleted_at IS NULL`) so a soft-deleted loser
+    // row can retain its stale key until a merge re-points it (merge soft-
+    // deletes the loser FIRST, then copies keys onto the survivor — risk 4).
+    uniqueIndex("contacts_external_id_unique_idx")
+      .on(table.externalId)
+      .where(sql`external_id IS NOT NULL AND deleted_at IS NULL`),
+    // Functional partial-unique on lower(email) — email is a case-insensitive
+    // resolvable identity key. Emails are stored already-normalized (trim +
+    // toLowerCase), so lower() here is belt-and-suspenders.
+    uniqueIndex("contacts_email_unique_idx")
+      .on(sql`lower(email)`)
+      .where(sql`email IS NOT NULL AND deleted_at IS NULL`),
+    uniqueIndex("contacts_anonymous_id_unique_idx")
+      .on(table.anonymousId)
+      .where(sql`anonymous_id IS NOT NULL AND deleted_at IS NULL`),
+  ],
 );

package/src/schema/email-sends.ts

@@ -1,4 +1,11 @@
-import { index, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+import {
+  index,
+  pgTable,
+  text,
+  timestamp,
+  uniqueIndex,
+  uuid,
+} from "drizzle-orm/pg-core";
 import { timestamps } from "./_shared.js";
 import { emailSendStatusEnum } from "./enums.js";
 import { journeyStates } from "./journey-states.js";
@@ -30,6 +37,11 @@ export const emailSends = pgTable(
     // Bounce classification from the Resend webhook (hard/soft/transient + reason).
     bounceType: text("bounce_type"),
     bounceReason: text("bounce_reason"),
+    // Caller-supplied idempotency key (POST /v1/emails). A retry with the same
+    // key short-circuits to the prior send instead of dispatching a duplicate —
+    // mirrors the user_events idempotency pattern. Nullable: journey/system sends
+    // don't set it.
+    idempotencyKey: text("idempotency_key"),
     ...timestamps,
   },
   (table) => [
@@ -45,5 +57,8 @@ export const emailSends = pgTable(
       table.createdAt,
       table.category,
     ),
+    // Idempotency dedup for POST /v1/emails (NULLs are distinct in Postgres, so
+    // unkeyed journey/system sends never collide).
+    uniqueIndex("email_sends_idempotency_key_idx").on(table.idempotencyKey),
   ],
 );

package/src/schema/index.ts

@@ -5,6 +5,8 @@ export * from "./audit-logs.js";
 export * from "./auth.js";
 export * from "./bucket-configs.js";
 export * from "./bucket-memberships.js";
+export * from "./campaigns.js";
+export * from "./contact-aliases.js";
 export * from "./contacts.js";
 export * from "./dead-letter-queue.js";
 export * from "./email-preferences.js";

package/src/schema/relations.ts

@@ -13,6 +13,7 @@ import {
 } from "./auth.js";
 import { bucketConfigs } from "./bucket-configs.js";
 import { bucketMemberships } from "./bucket-memberships.js";
+import { contactAliases } from "./contact-aliases.js";
 import { contacts } from "./contacts.js";
 import { deadLetterQueue } from "./dead-letter-queue.js";
 import { emailPreferences } from "./email-preferences.js";
@@ -49,10 +50,24 @@ export const journeyConfigsRelations = relations(journeyConfigs, () => ({}));
 export const bucketConfigsRelations = relations(bucketConfigs, () => ({}));
 
 export const contactsRelations = relations(contacts, ({ many }) => ({
+  // NOTE: the logical joins below (emailPreferences/userEvents/journeyStates/
+  // bucketMemberships) reference contacts.externalId — anonymous-only contacts
+  // (external_id NULL) won't resolve through Drizzle relational queries until
+  // identified. Acceptable (anon contacts have no prefs/journeys yet); see
+  // risk 22. contacts.id is NOT the relational key for those tables.
   emailPreferences: many(emailPreferences),
   userEvents: many(userEvents),
   journeyStates: many(journeyStates),
   bucketMemberships: many(bucketMemberships),
+  // contact_aliases joins on the contacts.id UUID (real FK).
+  aliases: many(contactAliases),
+}));
+
+export const contactAliasesRelations = relations(contactAliases, ({ one }) => ({
+  contact: one(contacts, {
+    fields: [contactAliases.contactId],
+    references: [contacts.id],
+  }),
 }));
 
 export const bucketMembershipsRelations = relations(