@hogsend/engine 0.5.0 → 0.7.0

package/src/lists/registry-singleton.ts

@@ -0,0 +1,39 @@
+import { ListRegistry } from "./registry.js";
+
+/**
+ * Process-singleton for the {@link ListRegistry}, installed by
+ * `createHogsendClient` / `buildListRegistry` at startup.
+ *
+ * Unlike the journey/bucket singletons (which `throw` if read before set), this
+ * one is EMPTY-DEFAULT and NEVER throws: `tracked.ts`'s `checkSuppression` runs
+ * in BOTH the API and the worker, and a send issued before
+ * `createHogsendClient` installs the registry — or a test that constructs no
+ * client at all — must still resolve. An empty registry yields legacy behaviour
+ * (every unknown id → opt-in default → blocked only on explicit `false`), so the
+ * pre-init / no-client path degrades safely instead of crashing (open risk #12).
+ */
+// Lazily constructed: `registry.ts` ↔ `registry-singleton.ts` form an ESM
+// import cycle (registry.ts imports `setListRegistry`; this file imports the
+// `ListRegistry` class). A top-level `new ListRegistry()` here would touch the
+// class while it is still in its temporal dead zone if `registry.ts` is the
+// module that loads first. Deferring construction to first read (after both
+// modules finish evaluating) sidesteps the cycle.
+let registry: ListRegistry | undefined;
+
+/** Read the installed registry, or an empty (legacy-behaviour) default. */
+export function getListRegistry(): ListRegistry {
+  if (registry === undefined) {
+    registry = new ListRegistry();
+  }
+  return registry;
+}
+
+/** Install the process registry (called by `buildListRegistry`). */
+export function setListRegistry(next: ListRegistry): void {
+  registry = next;
+}
+
+/** Reset to an empty registry — for test cleanup. */
+export function resetListRegistry(): void {
+  registry = new ListRegistry();
+}

package/src/lists/registry.ts

@@ -0,0 +1,95 @@
+import { parseEnabledFilter } from "../journeys/registry.js";
+import type { DefinedList, ListMeta } from "./define-list.js";
+import { setListRegistry } from "./registry-singleton.js";
+
+/**
+ * In-process index of the defined email lists (D3). Mirrors `BucketRegistry` /
+ * `JourneyRegistry`: a plain id-keyed map plus the polarity helpers that are the
+ * SINGLE SOURCE OF TRUTH for "is this category subscribed", consumed by the
+ * mailer's suppression check AND the preference-center render so the two never
+ * drift.
+ *
+ * A list shares the `email_preferences.categories` JSONB key namespace with the
+ * built-in `transactional`/`journey` categories. The registry only knows about
+ * defined lists — an UNKNOWN id resolves to legacy opt-in behaviour via
+ * {@link ListRegistry.isSubscribedByDefault} (`?? true`).
+ */
+export class ListRegistry {
+  private lists: Map<string, ListMeta> = new Map();
+
+  register(list: ListMeta): void {
+    this.lists.set(list.id, list);
+  }
+
+  get(id: string): ListMeta | undefined {
+    return this.lists.get(id);
+  }
+
+  getAll(): ListMeta[] {
+    return Array.from(this.lists.values());
+  }
+
+  getEnabled(): ListMeta[] {
+    return this.getAll().filter((l) => l.enabled);
+  }
+
+  has(id: string): boolean {
+    return this.lists.has(id);
+  }
+
+  count(): number {
+    return this.lists.size;
+  }
+
+  /**
+   * The list's default polarity. An unknown id (not a defined list — e.g. a
+   * built-in `transactional`/`journey` category, or a stale list) defaults to
+   * `true` (opt-in), preserving legacy behaviour: blocked only on explicit
+   * `false`.
+   */
+  isSubscribedByDefault(id: string): boolean {
+    return this.get(id)?.defaultOptIn ?? true;
+  }
+
+  /**
+   * The LOCKED polarity rule (§2.6). Given the stored `categories` map and a
+   * category id, decide whether the recipient is subscribed:
+   *  - opt-in default (`defaultOptIn true`): subscribed unless explicitly `false`
+   *  - opt-out default (`defaultOptIn false`): subscribed only when explicitly `true`
+   *
+   * Unknown ids fall through to opt-in default (via
+   * {@link ListRegistry.isSubscribedByDefault}), matching legacy semantics.
+   */
+  isSubscribed(categories: Record<string, boolean>, id: string): boolean {
+    const defaultOptIn = this.isSubscribedByDefault(id);
+    return defaultOptIn ? categories[id] !== false : categories[id] === true;
+  }
+}
+
+/**
+ * Build a {@link ListRegistry} from an injected array of lists, applying the
+ * enabled filter, and install it as the process singleton (so the mailer's
+ * suppression check and the preference center can resolve it). Returns the
+ * registry.
+ *
+ * `parseEnabledFilter` (journeys/registry.ts) is reused as-is — `ENABLED_LISTS`
+ * honours the same `"*"`-or-csv contract as `ENABLED_JOURNEYS` /
+ * `ENABLED_BUCKETS`. Disabled lists (filtered out OR `enabled: false`) are NOT
+ * registered, so an unknown id resolves to legacy opt-in.
+ */
+export function buildListRegistry(
+  lists: DefinedList[],
+  enabledFilter?: string,
+): ListRegistry {
+  const registry = new ListRegistry();
+  const enabled = parseEnabledFilter(enabledFilter);
+
+  for (const list of lists) {
+    if (enabled === "*" || enabled.has(list.meta.id)) {
+      registry.register(list.meta);
+    }
+  }
+
+  setListRegistry(registry);
+  return registry;
+}

package/src/middleware/api-key.ts

@@ -16,6 +16,38 @@ const SCOPE_HIERARCHY: Record<string, number> = {
   "full-admin": 2,
 };
 
+/**
+ * Single source of truth for scope checks.
+ *
+ * - Hierarchical scopes (`read` < `journey-admin` < `full-admin`): the key
+ *   passes when the MAX hierarchical rank it holds is >= the required rank.
+ * - Orthogonal scopes (e.g. `ingest`): NOT part of the hierarchy. A key must
+ *   either be granted the scope explicitly OR hold `full-admin` (which implies
+ *   every orthogonal data-plane scope).
+ *
+ * This fixes the latent bug where an orthogonal required scope was looked up in
+ * SCOPE_HIERARCHY (`?? 0`), letting ANY authenticated key satisfy it.
+ */
+export function hasScope(keyScopes: string[], required: string): boolean {
+  const requiredRank = SCOPE_HIERARCHY[required];
+
+  if (requiredRank === undefined) {
+    // Orthogonal scope (e.g. "ingest"): explicit grant or full-admin implies it.
+    return keyScopes.includes(required) || keyScopes.includes("full-admin");
+  }
+
+  // Hierarchical scope: highest rank held must clear the required rank.
+  let maxRank = Number.NEGATIVE_INFINITY;
+  for (const scope of keyScopes) {
+    const rank = SCOPE_HIERARCHY[scope];
+    if (rank !== undefined && rank > maxRank) {
+      maxRank = rank;
+    }
+  }
+
+  return maxRank >= requiredRank;
+}
+
 const KEY_CACHE = new Map<
   string,
   {
@@ -108,19 +140,13 @@ export const requireApiKey = createMiddleware<AppEnv>(async (c, next) => {
 });
 
 export function requireScope(scope: string) {
-  const required = SCOPE_HIERARCHY[scope] ?? 0;
-
   return createMiddleware<AppEnv>(async (c, next) => {
     const apiKey = c.get("apiKey");
     if (!apiKey) {
       return c.json({ error: "Unauthorized" }, 401);
     }
 
-    const maxScope = Math.max(
-      ...apiKey.scopes.map((s: string) => SCOPE_HIERARCHY[s] ?? 0),
-    );
-
-    if (maxScope < required) {
+    if (!hasScope(apiKey.scopes, scope)) {
       return c.json({ error: "Forbidden: insufficient scope" }, 403);
     }
 

package/src/middleware/rate-limit.ts

@@ -2,64 +2,88 @@ import { createMiddleware } from "hono/factory";
 import type { AppEnv } from "../app.js";
 import { getRedis } from "../lib/redis.js";
 
-const WINDOW_MS = 60_000;
-const MAX_REQUESTS = 100;
-
-const memoryStore = new Map<string, number[]>();
-let cleanupCounter = 0;
+const DEFAULT_WINDOW_MS = 60_000;
+const DEFAULT_MAX_REQUESTS = 100;
+const DEFAULT_PREFIX = "ratelimit";
 const MAX_KEYS = 10_000;
 
-export const rateLimit = createMiddleware<AppEnv>(async (c, next) => {
-  if (process.env.NODE_ENV === "test") return next();
+export interface RateLimitOptions {
+  windowMs?: number;
+  max?: number;
+  prefix?: string;
+}
 
-  const apiKey = c.get("apiKey");
-  const keyId = apiKey?.id ?? c.get("user")?.id ?? "anonymous";
-  const now = Date.now();
+/**
+ * Build a sliding-window rate-limit middleware.
+ *
+ * Each instance owns an isolated in-memory fallback store (keyed by `prefix`)
+ * and a distinct Redis key namespace, so two middlewares with different
+ * prefixes (e.g. "ratelimit" vs "ratelimit:emails") never share a budget —
+ * an email send must not consume the contact-upsert sliding window.
+ */
+export function createRateLimit(opts: RateLimitOptions = {}) {
+  const windowMs = opts.windowMs ?? DEFAULT_WINDOW_MS;
+  const max = opts.max ?? DEFAULT_MAX_REQUESTS;
+  const prefix = opts.prefix ?? DEFAULT_PREFIX;
 
-  let count: number;
+  // Per-instance memory store so prefixes stay budget-isolated in the
+  // Redis-less fallback path too.
+  const memoryStore = new Map<string, number[]>();
+  let cleanupCounter = 0;
 
-  try {
-    const redis = getRedis();
-    if (redis) {
-      const windowKey = `ratelimit:${keyId}`;
-      const pipeline = redis.pipeline();
-      pipeline.zremrangebyscore(windowKey, 0, now - WINDOW_MS);
-      pipeline.zcard(windowKey);
-      pipeline.zadd(windowKey, now, `${now}:${Math.random()}`);
-      pipeline.expire(windowKey, Math.ceil(WINDOW_MS / 1000));
+  return createMiddleware<AppEnv>(async (c, next) => {
+    if (process.env.NODE_ENV === "test") return next();
 
-      const results = await pipeline.exec();
-      count = (results?.[1]?.[1] as number) ?? 0;
-    } else {
-      throw new Error("No Redis");
-    }
-  } catch {
-    const entries = memoryStore.get(keyId) ?? [];
-    const cutoff = now - WINDOW_MS;
-    const valid = entries.filter((t) => t > cutoff);
-    valid.push(now);
-    memoryStore.set(keyId, valid);
-    count = valid.length - 1;
+    const apiKey = c.get("apiKey");
+    const keyId = apiKey?.id ?? c.get("user")?.id ?? "anonymous";
+    const now = Date.now();
+
+    let count: number;
+
+    try {
+      const redis = getRedis();
+      if (redis) {
+        const windowKey = `${prefix}:${keyId}`;
+        const pipeline = redis.pipeline();
+        pipeline.zremrangebyscore(windowKey, 0, now - windowMs);
+        pipeline.zcard(windowKey);
+        pipeline.zadd(windowKey, now, `${now}:${Math.random()}`);
+        pipeline.expire(windowKey, Math.ceil(windowMs / 1000));
 
-    if (++cleanupCounter % 100 === 0 && memoryStore.size > MAX_KEYS) {
-      const sweepCutoff = now - WINDOW_MS;
-      for (const [key, entries] of memoryStore) {
-        const active = entries.filter((t) => t > sweepCutoff);
-        if (active.length === 0) memoryStore.delete(key);
-        else memoryStore.set(key, active);
+        const results = await pipeline.exec();
+        count = (results?.[1]?.[1] as number) ?? 0;
+      } else {
+        throw new Error("No Redis");
+      }
+    } catch {
+      const entries = memoryStore.get(keyId) ?? [];
+      const cutoff = now - windowMs;
+      const valid = entries.filter((t) => t > cutoff);
+      valid.push(now);
+      memoryStore.set(keyId, valid);
+      count = valid.length - 1;
+
+      if (++cleanupCounter % 100 === 0 && memoryStore.size > MAX_KEYS) {
+        const sweepCutoff = now - windowMs;
+        for (const [key, ts] of memoryStore) {
+          const active = ts.filter((t) => t > sweepCutoff);
+          if (active.length === 0) memoryStore.delete(key);
+          else memoryStore.set(key, active);
+        }
       }
     }
-  }
 
-  c.header("X-RateLimit-Limit", String(MAX_REQUESTS));
-  c.header(
-    "X-RateLimit-Remaining",
-    String(Math.max(0, MAX_REQUESTS - count - 1)),
-  );
+    c.header("X-RateLimit-Limit", String(max));
+    c.header("X-RateLimit-Remaining", String(Math.max(0, max - count - 1)));
+
+    if (count >= max) {
+      // SDKs map Retry-After to RateLimitError.retryAfter (seconds).
+      c.header("Retry-After", String(Math.ceil(windowMs / 1000)));
+      return c.json({ error: "Rate limit exceeded" }, 429);
+    }
 
-  if (count >= MAX_REQUESTS) {
-    return c.json({ error: "Rate limit exceeded" }, 429);
-  }
+    return next();
+  });
+}
 
-  return next();
-});
+export const rateLimit = createRateLimit();

package/src/routes/_shared.ts

@@ -0,0 +1,30 @@
+import type { Context } from "hono";
+
+/**
+ * The data-plane identity guard shared by `/v1/contacts`, `/v1/events`,
+ * `/v1/emails`, and `/v1/lists`: a request must carry at least one resolvable
+ * identity key. Returns the 400 JSON response when BOTH keys are absent (so the
+ * caller can `return guard;`), or `null` to proceed.
+ *
+ * `/v1/emails` names its recipient field `to` rather than `email`; pass
+ * `{ field: "to" }` so the 400 message matches that route's wording exactly.
+ */
+export function requireIdentity(
+  c: Context,
+  identity: { email?: string; userId?: string },
+  opts?: { field?: "email" | "to" },
+) {
+  if (!identity.email && !identity.userId) {
+    const field = opts?.field ?? "email";
+    return c.json({ error: `${field} or userId is required` }, 400);
+  }
+  return null;
+}
+
+/**
+ * Extract a human-readable message from an `applyListMembership` failure,
+ * matching the wording every data-plane route used inline.
+ */
+export function listMembershipError(err: unknown): string {
+  return err instanceof Error ? err.message : "Failed to apply list membership";
+}

package/src/routes/admin/api-keys.ts

@@ -58,7 +58,7 @@ const createKeyRoute = createRoute({
           schema: z.object({
             name: z.string().min(1).max(100),
             scopes: z
-              .array(z.enum(["read", "journey-admin", "full-admin"]))
+              .array(z.enum(["read", "journey-admin", "full-admin", "ingest"]))
               .min(1)
               .default(["read"]),
             expiresAt: z.string().datetime().optional(),

package/src/routes/admin/buckets.ts

@@ -123,6 +123,8 @@ const getRoute = createRoute({
                   id: z.string(),
                   name: z.string(),
                   trigger: z.string(),
+                  sourceBucketId: z.string().nullable(),
+                  owned: z.boolean(),
                 }),
               ),
               recentMembers: z.array(memberSchema),
@@ -332,27 +334,55 @@ export const bucketsRouter = new OpenAPIHono<AppEnv>()
       counts[row.status as keyof typeof emptyCounts] = row.count;
     }
 
-    // Which journeys this bucket feeds — cross-reference the bucket's emitted
-    // transition events against the journey registry's trigger index. A journey
-    // bound to the per-bucket alias `bucket:entered:<id>` (the recommended,
-    // narrowly-routed binding) or the generic `bucket:entered` is woken by this
-    // bucket's joins.
+    // Which journeys this bucket feeds. Two sources, owned-first:
+    //  1. Owned reactions — journeys generated by `bucket.on()`, tagged with
+    //     `sourceBucketId === id`. Discovered by scanning the registry; surfaced
+    //     with `owned: true`.
+    //  2. External bindings — hand-written journeys bound to the bucket's emitted
+    //     transition events via the per-bucket alias `bucket:entered:<id>` (the
+    //     recommended, narrowly-routed binding) or the generic `bucket:entered`.
+    //     Surfaced with `owned: false`. Owned wins on collision.
+    const feedsMap = new Map<
+      string,
+      {
+        id: string;
+        name: string;
+        trigger: string;
+        sourceBucketId: string | null;
+        owned: boolean;
+      }
+    >();
+
+    // Owned reactions: scan the journey registry for sourceBucketId === id.
+    for (const journey of registry
+      .getAll()
+      .filter((j) => j.sourceBucketId === id)) {
+      feedsMap.set(journey.id, {
+        id: journey.id,
+        name: journey.name,
+        trigger: journey.trigger.event,
+        sourceBucketId: id,
+        owned: true,
+      });
+    }
+
+    // External bindings: the existing alias + generic cross-reference. Skip any
+    // journey already surfaced as owned (owned wins).
     const feedEvents = [
       `bucket:entered:${id}`,
       `bucket:left:${id}`,
       "bucket:entered",
       "bucket:left",
     ];
-    const feedsMap = new Map<
-      string,
-      { id: string; name: string; trigger: string }
-    >();
     for (const evt of feedEvents) {
       for (const journey of registry.getByTriggerEvent(evt)) {
+        if (feedsMap.has(journey.id)) continue;
         feedsMap.set(journey.id, {
           id: journey.id,
           name: journey.name,
           trigger: evt,
+          sourceBucketId: journey.sourceBucketId ?? null,
+          owned: false,
         });
       }
     }

package/src/routes/admin/bulk.ts

@@ -308,7 +308,7 @@ export const bulkRouter = new OpenAPIHono<AppEnv>()
       const header = "externalId,email,properties,firstSeenAt,lastSeenAt";
       const csvRows = rows.map(
         (r) =>
-          `${r.externalId},${r.email ?? ""},${JSON.stringify(r.properties ?? {}).replace(/,/g, ";")},${r.firstSeenAt.toISOString()},${r.lastSeenAt.toISOString()}`,
+          `${r.externalId ?? ""},${r.email ?? ""},${JSON.stringify(r.properties ?? {}).replace(/,/g, ";")},${r.firstSeenAt.toISOString()},${r.lastSeenAt.toISOString()}`,
       );
       const csv = [header, ...csvRows].join("\n");
 
@@ -389,7 +389,9 @@ export const bulkRouter = new OpenAPIHono<AppEnv>()
               event: event.event,
               userId: event.userId,
               userEmail: "",
-              properties: (event.properties as Record<string, unknown>) ?? {},
+              // Stored `user_events.properties` is the event-property bag (D2).
+              eventProperties:
+                (event.properties as Record<string, unknown>) ?? {},
             },
           }),
         ),
@@ -481,7 +483,9 @@ export const bulkRouter = new OpenAPIHono<AppEnv>()
               event: journey.trigger.event,
               userId: user.userId,
               userEmail: user.userEmail,
-              properties: user.properties ?? {},
+              // Public batch-enroll request field stays `properties`
+              // (decision #14); maps to the event-property bag (D2).
+              eventProperties: user.properties ?? {},
             },
           }),
         ),

package/src/routes/admin/contacts.ts

@@ -5,12 +5,15 @@ import type { AppEnv } from "../../app.js";
 import {
   contactSearchFilter,
   resolveContact,
+  resolveOrCreateContact,
+  serializeContact as serializeContactRow,
   serializePrefs,
 } from "../../lib/contacts.js";
 
 const contactSchema = z.object({
   id: z.string(),
-  externalId: z.string(),
+  externalId: z.string().nullable(),
+  anonymousId: z.string().nullable(),
   email: z.string().nullable(),
   properties: z.record(z.string(), z.unknown()),
   firstSeenAt: z.string(),
@@ -95,16 +98,20 @@ const createRoute_ = createRoute({
   method: "post",
   path: "/",
   tags: ["Admin"],
-  summary: "Create a contact",
+  summary: "Create or upsert a contact",
   request: {
     body: {
       content: {
         "application/json": {
-          schema: z.object({
-            externalId: z.string().min(1),
-            email: z.string().email().optional(),
-            properties: z.record(z.string(), z.unknown()).optional(),
-          }),
+          schema: z
+            .object({
+              externalId: z.string().min(1).optional(),
+              email: z.string().email().optional(),
+              properties: z.record(z.string(), z.unknown()).optional(),
+            })
+            .refine((b) => Boolean(b.externalId || b.email), {
+              message: "Provide at least one of externalId or email",
+            }),
         },
       },
     },
@@ -116,15 +123,15 @@ const createRoute_ = createRoute({
           schema: z.object({ contact: contactSchema }),
         },
       },
-      description: "Contact created",
+      description: "Contact created or upserted",
     },
-    409: {
+    400: {
       content: {
         "application/json": {
           schema: z.object({ error: z.string() }),
         },
       },
-      description: "Contact with this externalId already exists",
+      description: "Missing identity (externalId or email required)",
     },
   },
 });
@@ -195,18 +202,8 @@ const deleteRoute = createRoute({
   },
 });
 
-function serializeContact(row: typeof contacts.$inferSelect) {
-  return {
-    id: row.id,
-    externalId: row.externalId,
-    email: row.email,
-    properties: (row.properties ?? {}) as Record<string, unknown>,
-    firstSeenAt: row.firstSeenAt.toISOString(),
-    lastSeenAt: row.lastSeenAt.toISOString(),
-    createdAt: row.createdAt.toISOString(),
-    updatedAt: row.updatedAt.toISOString(),
-  };
-}
+const serializeContact = (row: typeof contacts.$inferSelect) =>
+  serializeContactRow(row, { includeAnonymousId: true });
 
 export const contactsRouter = new OpenAPIHono<AppEnv>()
   .openapi(listRoute, async (c) => {
@@ -249,10 +246,12 @@ export const contactsRouter = new OpenAPIHono<AppEnv>()
       return c.json({ error: "Contact not found" }, 404);
     }
 
+    // email_preferences.user_id uses external_id when present, else the contact
+    // uuid as the deterministic fallback (risk 10 — email-only contacts).
     const prefRows = await db
       .select()
       .from(emailPreferences)
-      .where(eq(emailPreferences.userId, contact.externalId))
+      .where(eq(emailPreferences.userId, contact.externalId ?? contact.id))
       .limit(1);
 
     const prefs = prefRows[0] ? serializePrefs(prefRows[0]) : null;
@@ -266,28 +265,17 @@ export const contactsRouter = new OpenAPIHono<AppEnv>()
     const { db } = c.get("container");
     const body = c.req.valid("json");
 
-    const existing = await db
-      .select({ id: contacts.id })
-      .from(contacts)
-      .where(eq(contacts.externalId, body.externalId))
-      .limit(1);
-
-    if (existing.length > 0) {
-      return c.json(
-        { error: "Contact with this externalId already exists" },
-        409,
-      );
-    }
-
-    const [created] = await db
-      .insert(contacts)
-      .values({
-        externalId: body.externalId,
-        email: body.email ?? null,
-        properties: body.properties ?? {},
-      })
-      .returning();
+    // Delegate to the identity resolver (D1): it upserts/merges on the provided
+    // identity keys (externalId and/or email), so the hand-rolled existence
+    // check + raw insert + 409 are gone (§5). Read the row back to serialize.
+    const { id } = await resolveOrCreateContact({
+      db,
+      userId: body.externalId,
+      email: body.email,
+      contactProperties: body.properties,
+    });
 
+    const created = await resolveContact({ db, id });
     if (!created) {
       throw new Error("Failed to create contact");
     }
@@ -304,20 +292,41 @@ export const contactsRouter = new OpenAPIHono<AppEnv>()
       return c.json({ error: "Contact not found" }, 404);
     }
 
-    const [updated] = await db
-      .update(contacts)
-      .set({
-        ...(body.email !== undefined ? { email: body.email } : {}),
-        ...(body.properties
-          ? {
-              properties: sql`COALESCE(${contacts.properties}, '{}'::jsonb) || ${JSON.stringify(body.properties)}::jsonb`,
-            }
-          : {}),
-        updatedAt: new Date(),
-      })
-      .where(eq(contacts.id, current.id))
-      .returning();
+    const hasIdentityKey = Boolean(
+      current.externalId || current.anonymousId || body.email || current.email,
+    );
+
+    if (hasIdentityKey) {
+      // Delegate the email-fill + property merge to the resolver, keyed on the
+      // contact's canonical identity so the COALESCE||patch merge lives in one
+      // place (§5). Passing the existing externalId/anonymousId/email keeps the
+      // resolver on the fill-in-link path; a NEW email that already belongs to
+      // another contact correctly merges (the partial-unique index would have
+      // rejected a blind set anyway).
+      await resolveOrCreateContact({
+        db,
+        userId: current.externalId ?? undefined,
+        email: body.email ?? current.email ?? undefined,
+        anonymousId: current.anonymousId ?? undefined,
+        contactProperties: body.properties,
+      });
+    } else {
+      // Degenerate contact with no identity keys (resolver requires >=1 key):
+      // update it directly by uuid.
+      await db
+        .update(contacts)
+        .set({
+          ...(body.properties
+            ? {
+                properties: sql`COALESCE(${contacts.properties}, '{}'::jsonb) || ${JSON.stringify(body.properties)}::jsonb`,
+              }
+            : {}),
+          updatedAt: new Date(),
+        })
+        .where(eq(contacts.id, current.id));
+    }
 
+    const updated = await resolveContact({ db, id });
     if (!updated) {
       throw new Error("Failed to update contact");
     }