@shware/workflow 0.0.0-stage → 0.0.0

package/dist/store/index.d.mts

@@ -0,0 +1,291 @@
+import { BundleIR, ConditionIR, ScalarIR, WorkflowIR } from "../ir.mjs";
+import { PushDevice } from "../engine/ports.mjs";
+import { D1JourneyStore } from "./d1.mjs";
+import { JourneyFactSource } from "./facts.mjs";
+import { SqlClientLike } from "./sql.mjs";
+import { DEFAULT_SCHEMA, TABLES, TableSpec, renderDrizzleSchema, renderPostgresDdl } from "./tables.mjs";
+import { PostgresJourneyStore, PostgresJourneyStoreOptions } from "./postgres.mjs";
+import { PostgresReporting } from "./postgres-reporting.mjs";
+//#region src/store/index.d.ts
+/**
+ * The journey engine's data plane as a port. Everything the ingest router, the
+ * runner and the fact source persist or look up goes through this interface,
+ * so the storage engine is a deployment choice: D1 + KV (`D1JourneyStore`,
+ * the original), Postgres (`PostgresJourneyStore`), or anything else that can
+ * satisfy the contract below. Execution (durable steps, sleeps, wake-ups) is
+ * the workflow runtime's job and stays out of here.
+ *
+ * Timestamps are epoch milliseconds throughout; a store may persist them in
+ * its native type as long as `sinceMs` comparisons behave.
+ */
+/**
+ * A profile patch or a stored profile. On the way in, `null` means "remove
+ * this property" (RFC 7386 merge-patch, the only way the API has to unset
+ * one); a stored profile never contains null.
+ */
+export type ProfileProps = Record<string, ScalarIR | null | undefined>;
+export interface EventInput {
+  /** The occurrence's identity, chosen by the sender; a second insert with the same id is a no-op. */
+  id: string;
+  userId: string;
+  event: string;
+  ts: number;
+  payload: Record<string, unknown>;
+}
+export interface TriggerRoute {
+  workflow: string;
+  hash: string;
+  /** Payload gate (payload-only condition tree), or null when the trigger has none. */
+  where: ConditionIR | null;
+  /** Profile gate, or null. */
+  filter: ConditionIR | null;
+}
+export interface SegmentTriggerRoute {
+  workflow: string;
+  hash: string;
+  segment: string;
+}
+export interface EntryInput {
+  workflow: string;
+  userId: string;
+  instanceId: string;
+  hash: string;
+  ts: number;
+}
+/**
+ * How an entry attempt ended: a fresh row, a 'failed' row of a dead instance
+ * taken over (the once policy does not bar a user over one outage), or
+ * refused because the pair already entered and is still alive.
+ */
+export type EntryOutcome = 'entered' | 'reclaimed' | null;
+/** A device registered for pushes: its provider token belongs to the user who registered it last. */
+export interface DeviceInput {
+  userId: string;
+  token: string;
+  /** `ios` (APNs) or `android` (FCM): which provider the token belongs to. */
+  platform: string;
+  ts: number;
+}
+/** A store plus how to release what opening it acquired (a connection, say). */
+export interface StoreLease {
+  store: JourneyStore;
+  close?: () => Promise<void>;
+}
+/**
+ * The live database lacks tables or columns the engine reads (an SDK upgrade added them, or the
+ * host never ran the migration). Raised before a deploy writes anything.
+ */
+export declare class SchemaMismatchError extends Error {
+  readonly problems: readonly string[];
+  readonly name = "SchemaMismatchError";
+  constructor(problems: readonly string[]);
+}
+/** A message copy as reporting records it, before it goes out. */
+export interface MessageRecord {
+  idempotencyKey: string;
+  workflow: string;
+  instanceId: string;
+  nodeId: string;
+  template: string;
+  /** Where the copy lands: `email`, `push_ios`, `push_android`. */
+  channel: string;
+  userId: string;
+  sentAt: number;
+}
+/** What a click is judged by. */
+export interface ClickContext {
+  url: string;
+  deliveredAt: number;
+  linkCount: number;
+  /** The copy's clicks in the window before this one. */
+  recent: {
+    position: number;
+    at: number;
+  }[];
+}
+/** An open or a click, with the verdict on who made it and where it came from. */
+export interface Engagement {
+  at: number;
+  machine: boolean;
+  /** The rule that called it a machine; null for a person. */
+  reason: string | null;
+  userAgent: string | null;
+  /** The network the request came from (Cloudflare's `cf.asn`, `cf.asOrganization`, `cf.country`), never the address. */
+  asn: number | null;
+  organization: string | null;
+  country: string | null;
+}
+/**
+ * Journey reporting: where each instance stands, every copy and how it was engaged with, segment
+ * sizes. A store that keeps it (Postgres) exposes it as `reporting`; the Worker then records it
+ * and serves email tracking. Every write is idempotent — a retried step reports again.
+ */
+/** Bounds on when an event happened, both inclusive (epoch ms); an absent side is open. */
+export interface EventWindow {
+  sinceMs?: number;
+  untilMs?: number;
+}
+export interface JourneyReporting {
+  /** The instance entered: its row exists from here, so one a guard ends at once still counts. */
+  instanceStarted(input: {
+    workflow: string;
+    instanceId: string;
+    userId: string;
+    at: number;
+  }): Promise<void>;
+  nodeReached(input: {
+    workflow: string;
+    instanceId: string;
+    userId: string;
+    nodeId: string;
+    at: number;
+  }): Promise<void>;
+  instanceFinished(input: {
+    workflow: string;
+    instanceId: string;
+    userId: string;
+    status: string;
+    at: number;
+    convertedAt?: number;
+  }): Promise<void>;
+  /** The copy's row id; the row a retry already wrote, when there is one. */
+  recordMessage(message: MessageRecord): Promise<string>;
+  settleMessage(idempotencyKey: string, result: {
+    delivered: true;
+  } | {
+    delivered: false;
+    reason: string;
+  }, at: number): Promise<void>;
+  /** An email's tracked links, in document order. */
+  recordLinks(messageId: string, urls: readonly string[]): Promise<void>;
+  /**
+   * Record an open of the copy, judged by `judge` against the copy (its recipient and when it was
+   * delivered — when it was sent, before the transport answered); `undefined` from the judge
+   * records nothing. Read and written in one transaction. False for an unknown copy.
+   */
+  recordOpen(messageId: string, judge: (message: {
+    userId: string;
+    deliveredAt: number;
+  }) => Engagement | undefined): Promise<boolean>;
+  /**
+   * Record a click on the copy's link at `position`, judged by `judge` against the link, how
+   * many links the copy has and its clicks of the last `windowMs`. The copy is locked for the
+   * transaction, so clicks arriving together (a scanner following every link at once) are
+   * judged one after another, each seeing the ones before. When the judge asks to `backdate`,
+   * the window's earlier clicks are reclassified with this one's verdict. A click implies an
+   * open. Undefined for an unknown link.
+   */
+  recordClick(messageId: string, position: number, at: number, windowMs: number, judge: (link: ClickContext) => {
+    engagement: Engagement;
+    backdate: boolean;
+  }): Promise<{
+    url: string;
+    engagement: Engagement;
+  } | undefined>;
+  /** The email copy's recipient opted out of email: recorded on the copy and as a suppression. False for an unknown copy. */
+  recordUnsubscribe(messageId: string, at: number): Promise<boolean>;
+  /** A push copy the device reported it received. False for an unknown copy. */
+  recordDeviceDelivered(messageId: string, at: number): Promise<boolean>;
+  /** Drop members of segments no longer deployed, then record every deployed segment's size. */
+  snapshotSegments(at: number): Promise<{
+    segment: string;
+    size: number;
+  }[]>;
+}
+export interface JourneyStore {
+  /** Reporting, when the store keeps it (Postgres); D1 stores none. */
+  readonly reporting?: JourneyReporting;
+  /**
+   * Record that the user's data must go (a deleted account), before anything is erased: the
+   * request outlives a failure to stop their instances, and the sweep retries it.
+   */
+  requestErasure(userId: string, at: number): Promise<void>;
+  /** Users whose erasure was requested and not finished yet. */
+  pendingErasures(): Promise<string[]>;
+  /** The user's journey instances still running, by the entry ledger. */
+  runningInstances(userId: string): Promise<string[]>;
+  /**
+   * Erase everything kept about the user — profile, devices, events, wake subscriptions, segment
+   * memberships, suppressions, entries and reporting — and the erasure request last. Run only
+   * once no instance of theirs runs any more, or one could write some of it back.
+   */
+  forgetUser(userId: string): Promise<void>;
+  /** The user opted out of the channel (recorded by an unsubscribe); stores without reporting omit it. */
+  isSuppressed?(userId: string, channel: string): Promise<boolean>;
+  /**
+   * What the live database lacks against the engine's tables (read-only); a deploy refuses to
+   * run while it lists anything. Stores whose schema the engine owns (D1) omit it.
+   */
+  checkSchema?(): Promise<string[]>;
+  /** Append the occurrence; false when its id was already in the log (nothing written). */
+  insertEvent(input: EventInput): Promise<boolean>;
+  /** Occurrences of `event` for the user, optionally only those within the window. */
+  countEvents(userId: string, event: string, window?: EventWindow): Promise<number>;
+  /** The payloads of those occurrences — the caller filters them with the shared evaluator. */
+  listEventPayloads(userId: string, event: string, window?: EventWindow): Promise<Record<string, unknown>[]>;
+  getProfile(userId: string): Promise<ProfileProps | undefined>;
+  /**
+   * Merge-patch `props` into the stored profile in one statement (a null
+   * removes the property) and return the result. One statement, because a
+   * read-modify-write loses one of two concurrent identifies.
+   */
+  mergeProfile(userId: string, props: ProfileProps): Promise<ProfileProps>;
+  /** Every user the engine knows (a profile or an event): who the segment sweep evaluates. */
+  listUserIds(): Promise<string[]>;
+  /** The user's push devices, most recently registered first. */
+  listDevices(userId: string): Promise<PushDevice[]>;
+  /**
+   * Register a device: one row per token, so a token registered again moves to the user who
+   * registered it last (a phone signed into another account) and to the front of their list.
+   */
+  upsertDevice(device: DeviceInput): Promise<void>;
+  /** Forget a token (reported dead by APNs / FCM); the user it belonged to, if any. */
+  removeDevice(token: string): Promise<string | undefined>;
+  /**
+   * The user signed out on the device: the token is kept, bound to nobody, until the next sign-in
+   * binds it again. The user it belonged to, if any.
+   */
+  unbindDevice(token: string): Promise<string | undefined>;
+  getSegmentCondition(id: string): Promise<ConditionIR | undefined>;
+  /** Every deployed segment with its definition: what the segment sweep evaluates. */
+  listSegments(): Promise<{
+    id: string;
+    condition: ConditionIR;
+  }[]>;
+  findTriggers(event: string): Promise<TriggerRoute[]>;
+  listSegmentTriggers(): Promise<SegmentTriggerRoute[]>;
+  putWorkflowIR(workflow: WorkflowIR): Promise<void>;
+  getWorkflowIR(contentHash: string): Promise<WorkflowIR | undefined>;
+  /**
+   * Swap the routing tables (segments, event triggers, segment triggers) for
+   * the bundle's — atomically, so a concurrent ingest never sees them half
+   * empty. Workflow bodies are stored separately (`putWorkflowIR`) because they
+   * are content-addressed and outlive the routes that point at them.
+   */
+  replaceRoutes(bundle: BundleIR): Promise<void>;
+  isSegmentMember(segment: string, userId: string): Promise<boolean>;
+  /** Record the membership, with the workflows its entry has to start (see segment_start). */
+  addSegmentMember(segment: string, userId: string, ts: number, workflows: readonly string[]): Promise<void>;
+  /** The workflows the member's entry has not started yet. */
+  pendingSegmentStarts(segment: string, userId: string): Promise<string[]>;
+  completeSegmentStart(segment: string, userId: string, workflow: string): Promise<void>;
+  /** Drop the membership and any start it still owed. */
+  removeSegmentMember(segment: string, userId: string): Promise<void>;
+  /**
+   * Record the entry (the once policy). Atomic under concurrent ingests: of
+   * two racing attempts exactly one is 'entered' (or 'reclaimed', when the
+   * pair's previous instance is recorded as 'failed') and the other null.
+   */
+  enterJourney(entry: EntryInput): Promise<EntryOutcome>;
+  removeEntry(instanceId: string): Promise<void>;
+  setEntryStatus(instanceId: string, status: string): Promise<void>;
+  /** Distinct wake handles registered for (user, event). */
+  findWakeHandles(userId: string, event: string): Promise<string[]>;
+  /** Register the handle for each event; repeated registrations are idempotent. */
+  subscribe(handle: string, userId: string, events: readonly string[], ts: number): Promise<void>;
+  /** Drop every registration the handle holds. */
+  unsubscribe(handle: string): Promise<void>;
+}
+//#endregion
+export { D1JourneyStore, DEFAULT_SCHEMA, JourneyFactSource, PostgresJourneyStore, type PostgresJourneyStoreOptions, PostgresReporting, type SqlClientLike, TABLES, type TableSpec, renderDrizzleSchema, renderPostgresDdl };
+//# sourceMappingURL=index.d.mts.map

package/dist/store/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/store/index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;YAoBY,eAAe,eAAe;iBAEzB;;EAEf;EACA;EACA;EACA;EACA,SAAS;;iBAGM;EACf;EACA;;EAEA,OAAO;;EAEP,QAAQ;;iBAGO;EACf;EACA;EACA;;iBAGe;EACf;EACA;EACA;EACA;EACA;;;;;;;YAQU;;iBAGK;EACf;EACA;;EAEA;EACA;;;iBAIe;EACf,OAAO;EACP,cAAc;;;;;;qBAOH,4BAA4B;WAGlB;WAFH;EAElB,YAAqB;;;iBAQN;EACf;EACA;EACA;EACA;EACA;;EAEA;EACA;EACA;;;iBAIe;EACf;EACA;EACA;;EAEA;IAAU;IAAkB;;;;iBAIb;EACf;EACA;;EAEA;EACA;;EAEA;EACA;EACA;;;;;;;;iBASe;EACf;EACA;;iBAGe;;EAEf,gBAAgB;IACd;IACA;IACA;IACA;MACE;EACJ,YAAY;IACV;IACA;IACA;IACA;IACA;MACE;EACJ,iBAAiB;IACf;IACA;IACA;IACA;IACA;IACA;MACE;;EAEJ,cAAc,SAAS,gBAAgB;EACvC,cACE,wBACA;IAAU;;IAAsB;IAAkB;KAClD,aACC;;EAEH,YAAY,mBAAmB,0BAA0B;;;;;;EAMzD,WACE,mBACA,QAAQ;IAAW;IAAgB;QAA0B,yBAC5D;;;;;;;;;EASH,YACE,mBACA,kBACA,YACA,kBACA,QAAQ,MAAM;IAAmB,YAAY;IAAY;MACxD;IAAU;IAAa,YAAY;;;EAEtC,kBAAkB,mBAAmB,aAAa;;EAElD,sBAAsB,mBAAmB,aAAa;;EAEtD,iBAAiB,aAAa;IAAU;IAAiB;;;iBAG1C;;WAEN,YAAY;;;;;EAMrB,eAAe,gBAAgB,aAAa;;EAE5C,mBAAmB;;EAEnB,iBAAiB,iBAAiB;;;;;;EAMlC,WAAW,iBAAiB;;EAG5B,cAAc,gBAAgB,kBAAkB;;;;;EAMhD,gBAAgB;;EAIhB,YAAY,OAAO,aAAa;;EAEhC,YAAY,gBAAgB,eAAe,SAAS,cAAc;;EAElE,kBACE,gBACA,eACA,SAAS,cACR,QAAQ;EAGX,WAAW,iBAAiB,QAAQ;;;;;;EAMpC,aAAa,gBAAgB,OAAO,eAAe,QAAQ;;EAG3D,eAAe;;EAIf,YAAY,iBAAiB,QAAQ;;;;;EAKrC,aAAa,QAAQ,cAAc;;EAEnC,aAAa,gBAAgB;;;;;EAK7B,aAAa,gBAAgB;EAG7B,oBAAoB,aAAa,QAAQ;;EAEzC,gBAAgB;IAAU;IAAY,WAAW;;EACjD,aAAa,gBAAgB,QAAQ;EACrC,uBAAuB,QAAQ;EAC/B,cAAc,UAAU,aAAa;EACrC,cAAc,sBAAsB,QAAQ;;;;;;;EAO5C,cAAc,QAAQ,WAAW;EAGjC,gBAAgB,iBAAiB,iBAAiB;;EAElD,iBACE,iBACA,gBACA,YACA,+BACC;;EAEH,qBAAqB,iBAAiB,iBAAiB;EACvD,qBAAqB,iBAAiB,gBAAgB,mBAAmB;;EAEzE,oBAAoB,iBAAiB,iBAAiB;;;;;;EAQtD,aAAa,OAAO,aAAa,QAAQ;EACzC,YAAY,qBAAqB;EACjC,eAAe,oBAAoB,iBAAiB;;EAIpD,gBAAgB,gBAAgB,gBAAgB;;EAEhD,UAAU,gBAAgB,gBAAgB,2BAA2B,aAAa;;EAElF,YAAY,iBAAiB"}

package/dist/store/index.mjs

@@ -0,0 +1,22 @@
+import { PostgresReporting } from "./postgres-reporting.mjs";
+import { DEFAULT_SCHEMA, TABLES, renderDrizzleSchema, renderPostgresDdl } from "./tables.mjs";
+import { PostgresJourneyStore } from "./postgres.mjs";
+import { JourneyFactSource } from "./facts.mjs";
+import { D1JourneyStore } from "./d1.mjs";
+//#region src/store/index.ts
+/**
+* The live database lacks tables or columns the engine reads (an SDK upgrade added them, or the
+* host never ran the migration). Raised before a deploy writes anything.
+*/
+var SchemaMismatchError = class extends Error {
+	problems;
+	name = "SchemaMismatchError";
+	constructor(problems) {
+		super(`the database does not match @shware/workflow's tables — regenerate the drizzle schema (workflow-ui generate) and run your migrations:\n  ${problems.join("\n  ")}`);
+		this.problems = problems;
+	}
+};
+//#endregion
+export { D1JourneyStore, DEFAULT_SCHEMA, JourneyFactSource, PostgresJourneyStore, PostgresReporting, SchemaMismatchError, TABLES, renderDrizzleSchema, renderPostgresDdl };
+
+//# sourceMappingURL=index.mjs.map

package/dist/store/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/store/index.ts"],"sourcesContent":["import type { PushDevice } from '../engine/ports';\nimport type { BundleIR, ConditionIR, ScalarIR, WorkflowIR } from '../ir';\n\n/**\n * The journey engine's data plane as a port. Everything the ingest router, the\n * runner and the fact source persist or look up goes through this interface,\n * so the storage engine is a deployment choice: D1 + KV (`D1JourneyStore`,\n * the original), Postgres (`PostgresJourneyStore`), or anything else that can\n * satisfy the contract below. Execution (durable steps, sleeps, wake-ups) is\n * the workflow runtime's job and stays out of here.\n *\n * Timestamps are epoch milliseconds throughout; a store may persist them in\n * its native type as long as `sinceMs` comparisons behave.\n */\n\n/**\n * A profile patch or a stored profile. On the way in, `null` means \"remove\n * this property\" (RFC 7386 merge-patch, the only way the API has to unset\n * one); a stored profile never contains null.\n */\nexport type ProfileProps = Record<string, ScalarIR | null | undefined>;\n\nexport interface EventInput {\n  /** The occurrence's identity, chosen by the sender; a second insert with the same id is a no-op. */\n  id: string;\n  userId: string;\n  event: string;\n  ts: number;\n  payload: Record<string, unknown>;\n}\n\nexport interface TriggerRoute {\n  workflow: string;\n  hash: string;\n  /** Payload gate (payload-only condition tree), or null when the trigger has none. */\n  where: ConditionIR | null;\n  /** Profile gate, or null. */\n  filter: ConditionIR | null;\n}\n\nexport interface SegmentTriggerRoute {\n  workflow: string;\n  hash: string;\n  segment: string;\n}\n\nexport interface EntryInput {\n  workflow: string;\n  userId: string;\n  instanceId: string;\n  hash: string;\n  ts: number;\n}\n\n/**\n * How an entry attempt ended: a fresh row, a 'failed' row of a dead instance\n * taken over (the once policy does not bar a user over one outage), or\n * refused because the pair already entered and is still alive.\n */\nexport type EntryOutcome = 'entered' | 'reclaimed' | null;\n\n/** A device registered for pushes: its provider token belongs to the user who registered it last. */\nexport interface DeviceInput {\n  userId: string;\n  token: string;\n  /** `ios` (APNs) or `android` (FCM): which provider the token belongs to. */\n  platform: string;\n  ts: number;\n}\n\n/** A store plus how to release what opening it acquired (a connection, say). */\nexport interface StoreLease {\n  store: JourneyStore;\n  close?: () => Promise<void>;\n}\n\n/**\n * The live database lacks tables or columns the engine reads (an SDK upgrade added them, or the\n * host never ran the migration). Raised before a deploy writes anything.\n */\nexport class SchemaMismatchError extends Error {\n  override readonly name = 'SchemaMismatchError';\n\n  constructor(readonly problems: readonly string[]) {\n    super(\n      `the database does not match @shware/workflow's tables — regenerate the drizzle schema (workflow-ui generate) and run your migrations:\\n  ${problems.join('\\n  ')}`\n    );\n  }\n}\n\n/** A message copy as reporting records it, before it goes out. */\nexport interface MessageRecord {\n  idempotencyKey: string;\n  workflow: string;\n  instanceId: string;\n  nodeId: string;\n  template: string;\n  /** Where the copy lands: `email`, `push_ios`, `push_android`. */\n  channel: string;\n  userId: string;\n  sentAt: number;\n}\n\n/** What a click is judged by. */\nexport interface ClickContext {\n  url: string;\n  deliveredAt: number;\n  linkCount: number;\n  /** The copy's clicks in the window before this one. */\n  recent: { position: number; at: number }[];\n}\n\n/** An open or a click, with the verdict on who made it and where it came from. */\nexport interface Engagement {\n  at: number;\n  machine: boolean;\n  /** The rule that called it a machine; null for a person. */\n  reason: string | null;\n  userAgent: string | null;\n  /** The network the request came from (Cloudflare's `cf.asn`, `cf.asOrganization`, `cf.country`), never the address. */\n  asn: number | null;\n  organization: string | null;\n  country: string | null;\n}\n\n/**\n * Journey reporting: where each instance stands, every copy and how it was engaged with, segment\n * sizes. A store that keeps it (Postgres) exposes it as `reporting`; the Worker then records it\n * and serves email tracking. Every write is idempotent — a retried step reports again.\n */\n/** Bounds on when an event happened, both inclusive (epoch ms); an absent side is open. */\nexport interface EventWindow {\n  sinceMs?: number;\n  untilMs?: number;\n}\n\nexport interface JourneyReporting {\n  /** The instance entered: its row exists from here, so one a guard ends at once still counts. */\n  instanceStarted(input: {\n    workflow: string;\n    instanceId: string;\n    userId: string;\n    at: number;\n  }): Promise<void>;\n  nodeReached(input: {\n    workflow: string;\n    instanceId: string;\n    userId: string;\n    nodeId: string;\n    at: number;\n  }): Promise<void>;\n  instanceFinished(input: {\n    workflow: string;\n    instanceId: string;\n    userId: string;\n    status: string;\n    at: number;\n    convertedAt?: number;\n  }): Promise<void>;\n  /** The copy's row id; the row a retry already wrote, when there is one. */\n  recordMessage(message: MessageRecord): Promise<string>;\n  settleMessage(\n    idempotencyKey: string,\n    result: { delivered: true } | { delivered: false; reason: string },\n    at: number\n  ): Promise<void>;\n  /** An email's tracked links, in document order. */\n  recordLinks(messageId: string, urls: readonly string[]): Promise<void>;\n  /**\n   * Record an open of the copy, judged by `judge` against the copy (its recipient and when it was\n   * delivered — when it was sent, before the transport answered); `undefined` from the judge\n   * records nothing. Read and written in one transaction. False for an unknown copy.\n   */\n  recordOpen(\n    messageId: string,\n    judge: (message: { userId: string; deliveredAt: number }) => Engagement | undefined\n  ): Promise<boolean>;\n  /**\n   * Record a click on the copy's link at `position`, judged by `judge` against the link, how\n   * many links the copy has and its clicks of the last `windowMs`. The copy is locked for the\n   * transaction, so clicks arriving together (a scanner following every link at once) are\n   * judged one after another, each seeing the ones before. When the judge asks to `backdate`,\n   * the window's earlier clicks are reclassified with this one's verdict. A click implies an\n   * open. Undefined for an unknown link.\n   */\n  recordClick(\n    messageId: string,\n    position: number,\n    at: number,\n    windowMs: number,\n    judge: (link: ClickContext) => { engagement: Engagement; backdate: boolean }\n  ): Promise<{ url: string; engagement: Engagement } | undefined>;\n  /** The email copy's recipient opted out of email: recorded on the copy and as a suppression. False for an unknown copy. */\n  recordUnsubscribe(messageId: string, at: number): Promise<boolean>;\n  /** A push copy the device reported it received. False for an unknown copy. */\n  recordDeviceDelivered(messageId: string, at: number): Promise<boolean>;\n  /** Drop members of segments no longer deployed, then record every deployed segment's size. */\n  snapshotSegments(at: number): Promise<{ segment: string; size: number }[]>;\n}\n\nexport interface JourneyStore {\n  /** Reporting, when the store keeps it (Postgres); D1 stores none. */\n  readonly reporting?: JourneyReporting;\n\n  /**\n   * Record that the user's data must go (a deleted account), before anything is erased: the\n   * request outlives a failure to stop their instances, and the sweep retries it.\n   */\n  requestErasure(userId: string, at: number): Promise<void>;\n  /** Users whose erasure was requested and not finished yet. */\n  pendingErasures(): Promise<string[]>;\n  /** The user's journey instances still running, by the entry ledger. */\n  runningInstances(userId: string): Promise<string[]>;\n  /**\n   * Erase everything kept about the user — profile, devices, events, wake subscriptions, segment\n   * memberships, suppressions, entries and reporting — and the erasure request last. Run only\n   * once no instance of theirs runs any more, or one could write some of it back.\n   */\n  forgetUser(userId: string): Promise<void>;\n\n  /** The user opted out of the channel (recorded by an unsubscribe); stores without reporting omit it. */\n  isSuppressed?(userId: string, channel: string): Promise<boolean>;\n\n  /**\n   * What the live database lacks against the engine's tables (read-only); a deploy refuses to\n   * run while it lists anything. Stores whose schema the engine owns (D1) omit it.\n   */\n  checkSchema?(): Promise<string[]>;\n\n  /* ---------------------------------- events --------------------------------- */\n  /** Append the occurrence; false when its id was already in the log (nothing written). */\n  insertEvent(input: EventInput): Promise<boolean>;\n  /** Occurrences of `event` for the user, optionally only those within the window. */\n  countEvents(userId: string, event: string, window?: EventWindow): Promise<number>;\n  /** The payloads of those occurrences — the caller filters them with the shared evaluator. */\n  listEventPayloads(\n    userId: string,\n    event: string,\n    window?: EventWindow\n  ): Promise<Record<string, unknown>[]>;\n\n  /* --------------------------------- profiles -------------------------------- */\n  getProfile(userId: string): Promise<ProfileProps | undefined>;\n  /**\n   * Merge-patch `props` into the stored profile in one statement (a null\n   * removes the property) and return the result. One statement, because a\n   * read-modify-write loses one of two concurrent identifies.\n   */\n  mergeProfile(userId: string, props: ProfileProps): Promise<ProfileProps>;\n\n  /** Every user the engine knows (a profile or an event): who the segment sweep evaluates. */\n  listUserIds(): Promise<string[]>;\n\n  /* ---------------------------------- devices --------------------------------- */\n  /** The user's push devices, most recently registered first. */\n  listDevices(userId: string): Promise<PushDevice[]>;\n  /**\n   * Register a device: one row per token, so a token registered again moves to the user who\n   * registered it last (a phone signed into another account) and to the front of their list.\n   */\n  upsertDevice(device: DeviceInput): Promise<void>;\n  /** Forget a token (reported dead by APNs / FCM); the user it belonged to, if any. */\n  removeDevice(token: string): Promise<string | undefined>;\n  /**\n   * The user signed out on the device: the token is kept, bound to nobody, until the next sign-in\n   * binds it again. The user it belonged to, if any.\n   */\n  unbindDevice(token: string): Promise<string | undefined>;\n\n  /* ---------------------------- deployed definitions -------------------------- */\n  getSegmentCondition(id: string): Promise<ConditionIR | undefined>;\n  /** Every deployed segment with its definition: what the segment sweep evaluates. */\n  listSegments(): Promise<{ id: string; condition: ConditionIR }[]>;\n  findTriggers(event: string): Promise<TriggerRoute[]>;\n  listSegmentTriggers(): Promise<SegmentTriggerRoute[]>;\n  putWorkflowIR(workflow: WorkflowIR): Promise<void>;\n  getWorkflowIR(contentHash: string): Promise<WorkflowIR | undefined>;\n  /**\n   * Swap the routing tables (segments, event triggers, segment triggers) for\n   * the bundle's — atomically, so a concurrent ingest never sees them half\n   * empty. Workflow bodies are stored separately (`putWorkflowIR`) because they\n   * are content-addressed and outlive the routes that point at them.\n   */\n  replaceRoutes(bundle: BundleIR): Promise<void>;\n\n  /* ----------------------------- segment membership --------------------------- */\n  isSegmentMember(segment: string, userId: string): Promise<boolean>;\n  /** Record the membership, with the workflows its entry has to start (see segment_start). */\n  addSegmentMember(\n    segment: string,\n    userId: string,\n    ts: number,\n    workflows: readonly string[]\n  ): Promise<void>;\n  /** The workflows the member's entry has not started yet. */\n  pendingSegmentStarts(segment: string, userId: string): Promise<string[]>;\n  completeSegmentStart(segment: string, userId: string, workflow: string): Promise<void>;\n  /** Drop the membership and any start it still owed. */\n  removeSegmentMember(segment: string, userId: string): Promise<void>;\n\n  /* ------------------------------- entry ledger ------------------------------- */\n  /**\n   * Record the entry (the once policy). Atomic under concurrent ingests: of\n   * two racing attempts exactly one is 'entered' (or 'reclaimed', when the\n   * pair's previous instance is recorded as 'failed') and the other null.\n   */\n  enterJourney(entry: EntryInput): Promise<EntryOutcome>;\n  removeEntry(instanceId: string): Promise<void>;\n  setEntryStatus(instanceId: string, status: string): Promise<void>;\n\n  /* ------------------------------ wake subscriptions --------------------------- */\n  /** Distinct wake handles registered for (user, event). */\n  findWakeHandles(userId: string, event: string): Promise<string[]>;\n  /** Register the handle for each event; repeated registrations are idempotent. */\n  subscribe(handle: string, userId: string, events: readonly string[], ts: number): Promise<void>;\n  /** Drop every registration the handle holds. */\n  unsubscribe(handle: string): Promise<void>;\n}\n\nexport { D1JourneyStore } from './d1';\nexport { JourneyFactSource } from './facts';\nexport { PostgresJourneyStore } from './postgres';\nexport { PostgresReporting } from './postgres-reporting';\nexport {\n  DEFAULT_SCHEMA,\n  TABLES,\n  renderDrizzleSchema,\n  renderPostgresDdl,\n  type TableSpec,\n} from './tables';\nexport type { PostgresJourneyStoreOptions, SqlClientLike } from './postgres';\n"],"mappings":";;;;;;;;;;AAgFA,IAAa,sBAAb,cAAyC,MAAM;CAGxB;CAFrB,OAAyB;CAEzB,YAAY,UAAsC;EAChD,MACE,4IAA4I,SAAS,KAAK,MAAM,GAClK;EAHmB,KAAA,WAAA;CAIrB;AACF"}

package/dist/store/postgres-reporting.cjs

@@ -0,0 +1,213 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_store_sql = require("./sql.cjs");
+//#region src/store/postgres-reporting.ts
+/**
+* Epoch milliseconds → timestamptz, and back: numbers in and out, whatever the driver maps (a
+* driver may hand a double or a bigint count back as a string).
+*/
+const TS = (param) => `to_timestamp(${param}::double precision / 1000)`;
+const MS = (column) => `(extract(epoch from ${column}) * 1000)::double precision`;
+/**
+* Journey reporting on the engine's Postgres schema (tables.ts: instance, message,
+* message_link, message_open, message_click, segment_member, segment_snapshot). Every timestamp
+* is written here, never defaulted, and every write is idempotent: the engine reports again when
+* a step is retried.
+*/
+var PostgresReporting = class {
+	sql;
+	t;
+	constructor(sql, t) {
+		this.sql = sql;
+		this.t = t;
+	}
+	async instanceStarted(input) {
+		await this.sql.query(`INSERT INTO ${this.t.instance} (instance_id, workflow, user_id, entered_at, status)
+       VALUES ($1, $2, $3, ${TS("$4")}, 'running')
+       ON CONFLICT (instance_id) DO NOTHING`, [
+			input.instanceId,
+			input.workflow,
+			input.userId,
+			input.at
+		]);
+	}
+	async nodeReached(input) {
+		await this.sql.query(`INSERT INTO ${this.t.instance} (instance_id, workflow, user_id, entered_at, node_id, node_at, status)
+       VALUES ($1, $2, $3, ${TS("$4")}, $5, ${TS("$4")}, 'running')
+       ON CONFLICT (instance_id) DO UPDATE SET node_id = EXCLUDED.node_id, node_at = EXCLUDED.node_at`, [
+			input.instanceId,
+			input.workflow,
+			input.userId,
+			input.at,
+			input.nodeId
+		]);
+	}
+	async instanceFinished(input) {
+		await this.sql.query(`INSERT INTO ${this.t.instance}
+         (instance_id, workflow, user_id, entered_at, status, finished_at, converted_at)
+       VALUES ($1, $2, $3, ${TS("$5")}, $4, ${TS("$5")}, ${TS("$6")})
+       ON CONFLICT (instance_id) DO UPDATE SET status = EXCLUDED.status,
+         finished_at = EXCLUDED.finished_at, converted_at = EXCLUDED.converted_at`, [
+			input.instanceId,
+			input.workflow,
+			input.userId,
+			input.status,
+			input.at,
+			input.convertedAt ?? null
+		]);
+	}
+	async recordMessage(message) {
+		const id = (await this.sql.query(`INSERT INTO ${this.t.message}
+         (id, idempotency_key, workflow, instance_id, node_id, template, channel, user_id, sent_at)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, ${TS("$9")})
+       ON CONFLICT (idempotency_key) DO UPDATE SET idempotency_key = EXCLUDED.idempotency_key
+       RETURNING id`, [
+			require_store_sql.uuidv7(message.sentAt),
+			message.idempotencyKey,
+			message.workflow,
+			message.instanceId,
+			message.nodeId,
+			message.template,
+			message.channel,
+			message.userId,
+			message.sentAt
+		]))[0]?.id;
+		if (id === void 0) throw new Error(`message ${message.idempotencyKey} was not recorded`);
+		return id;
+	}
+	async settleMessage(idempotencyKey, result, at) {
+		if (result.delivered) await this.sql.query(`UPDATE ${this.t.message} SET delivered_at = coalesce(delivered_at, ${TS("$2")}) WHERE idempotency_key = $1`, [idempotencyKey, at]);
+		else await this.sql.query(`UPDATE ${this.t.message} SET undelivered_reason = $2 WHERE idempotency_key = $1`, [idempotencyKey, result.reason]);
+	}
+	async recordLinks(messageId, urls) {
+		if (urls.length === 0) return;
+		const values = urls.map((_, i) => `($1, ${i}, $${i + 2})`).join(", ");
+		await this.sql.query(`INSERT INTO ${this.t.messageLink} (message_id, position, url) VALUES ${values} ON CONFLICT DO NOTHING`, [messageId, ...urls]);
+	}
+	async recordOpen(messageId, judge) {
+		return this.sql.transaction(async (tx) => {
+			const row = (await tx.query(`SELECT user_id, ${MS("coalesce(delivered_at, sent_at)")} AS delivered_at
+         FROM ${this.t.message} WHERE id = $1`, [messageId]))[0];
+			if (row === void 0) return false;
+			const open = judge({
+				userId: row.user_id,
+				deliveredAt: Number(row.delivered_at)
+			});
+			if (open === void 0) return true;
+			await tx.query(`INSERT INTO ${this.t.messageOpen}
+           (id, message_id, opened_at, machine, reason, user_agent, asn, as_organization, country)
+         VALUES ($1, $2, ${TS("$3")}, $4, $5, $6, $7, $8, $9)`, [
+				require_store_sql.uuidv7(open.at),
+				messageId,
+				open.at,
+				open.machine,
+				open.reason,
+				open.userAgent,
+				open.asn,
+				open.organization,
+				open.country
+			]);
+			await tx.query(`UPDATE ${this.t.message} SET
+           opened_at = coalesce(opened_at, ${TS("$2")}),
+           human_opened_at = CASE WHEN $3 THEN human_opened_at ELSE coalesce(human_opened_at, ${TS("$2")}) END
+         WHERE id = $1`, [
+				messageId,
+				open.at,
+				open.machine
+			]);
+			return true;
+		});
+	}
+	async recordClick(messageId, position, at, windowMs, judge) {
+		return this.sql.transaction(async (tx) => {
+			const message = (await tx.query(`SELECT ${MS("coalesce(delivered_at, sent_at)")} AS delivered_at
+         FROM ${this.t.message} WHERE id = $1 FOR UPDATE`, [messageId]))[0];
+			if (message === void 0) return void 0;
+			const link = (await tx.query(`SELECT l.url,
+           (SELECT count(*) FROM ${this.t.messageLink} a WHERE a.message_id = l.message_id) AS link_count
+         FROM ${this.t.messageLink} l WHERE l.message_id = $1 AND l.position = $2`, [messageId, position]))[0];
+			if (link === void 0) return void 0;
+			const since = at - windowMs;
+			const recent = await tx.query(`SELECT position, ${MS("clicked_at")} AS at FROM ${this.t.messageClick}
+         WHERE message_id = $1 AND clicked_at >= ${TS("$2")} ORDER BY clicked_at`, [messageId, since]);
+			const { engagement: click, backdate } = judge({
+				url: link.url,
+				deliveredAt: Number(message.delivered_at),
+				linkCount: Number(link.link_count),
+				recent: recent.map((row) => ({
+					position: row.position,
+					at: Number(row.at)
+				}))
+			});
+			await tx.query(`INSERT INTO ${this.t.messageClick}
+           (id, message_id, position, url, clicked_at, machine, reason, user_agent, asn, as_organization, country)
+         VALUES ($1, $2, $3, $4, ${TS("$5")}, $6, $7, $8, $9, $10, $11)`, [
+				require_store_sql.uuidv7(click.at),
+				messageId,
+				position,
+				link.url,
+				click.at,
+				click.machine,
+				click.reason,
+				click.userAgent,
+				click.asn,
+				click.organization,
+				click.country
+			]);
+			if (backdate) await tx.query(`UPDATE ${this.t.messageClick} SET machine = true, reason = $4
+           WHERE message_id = $1 AND NOT machine
+             AND clicked_at BETWEEN ${TS("$2")} AND ${TS("$3")}`, [
+				messageId,
+				since,
+				at,
+				click.reason
+			]);
+			await tx.query(`UPDATE ${this.t.message} m SET
+           clicked_at = coalesce(m.clicked_at, ${TS("$2")}),
+           opened_at = coalesce(m.opened_at, ${TS("$2")}),
+           human_clicked_at = (SELECT min(c.clicked_at) FROM ${this.t.messageClick} c
+             WHERE c.message_id = m.id AND NOT c.machine),
+           human_opened_at = (SELECT min(t) FROM (
+             SELECT o.opened_at AS t FROM ${this.t.messageOpen} o WHERE o.message_id = m.id AND NOT o.machine
+             UNION ALL
+             SELECT c.clicked_at FROM ${this.t.messageClick} c WHERE c.message_id = m.id AND NOT c.machine
+           ) human)
+         WHERE m.id = $1`, [messageId, at]);
+			return {
+				url: link.url,
+				engagement: click
+			};
+		});
+	}
+	async recordDeviceDelivered(messageId, at) {
+		return (await this.sql.query(`UPDATE ${this.t.message} SET device_delivered_at = coalesce(device_delivered_at, ${TS("$2")})
+       WHERE id = $1 RETURNING id`, [messageId, at])).length > 0;
+	}
+	async recordUnsubscribe(messageId, at) {
+		return this.sql.transaction(async (tx) => {
+			const userId = (await tx.query(`UPDATE ${this.t.message} SET unsubscribed_at = coalesce(unsubscribed_at, ${TS("$2")})
+         WHERE id = $1 AND channel = 'email' RETURNING user_id`, [messageId, at]))[0]?.user_id;
+			if (userId === void 0) return false;
+			await tx.query(`INSERT INTO ${this.t.suppression} (user_id, channel, ts) VALUES ($1, 'email', ${TS("$2")})
+         ON CONFLICT DO NOTHING`, [userId, at]);
+			return true;
+		});
+	}
+	async snapshotSegments(at) {
+		return this.sql.transaction(async (tx) => {
+			await tx.query(`DELETE FROM ${this.t.segmentMember} m
+         WHERE NOT EXISTS (SELECT 1 FROM ${this.t.segment} s WHERE s.id = m.segment)`);
+			return (await tx.query(`INSERT INTO ${this.t.segmentSnapshot} (segment, taken_at, size)
+         SELECT s.id, ${TS("$1")}, (SELECT count(*) FROM ${this.t.segmentMember} m WHERE m.segment = s.id)
+         FROM ${this.t.segment} s
+         ON CONFLICT DO NOTHING
+         RETURNING segment, size`, [at])).map((row) => ({
+				segment: row.segment,
+				size: Number(row.size)
+			})).sort((a, b) => a.segment.localeCompare(b.segment));
+		});
+	}
+};
+//#endregion
+exports.PostgresReporting = PostgresReporting;
+
+//# sourceMappingURL=postgres-reporting.cjs.map

package/dist/store/postgres-reporting.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-reporting.cjs","names":["uuidv7"],"sources":["../../src/store/postgres-reporting.ts"],"sourcesContent":["import type { ClickContext, Engagement, JourneyReporting, MessageRecord } from './index';\nimport { type SqlClientLike, uuidv7 } from './sql';\nimport type { TableKey } from './tables';\n\n/**\n * Epoch milliseconds → timestamptz, and back: numbers in and out, whatever the driver maps (a\n * driver may hand a double or a bigint count back as a string).\n */\nconst TS = (param: string) => `to_timestamp(${param}::double precision / 1000)`;\nconst MS = (column: string) => `(extract(epoch from ${column}) * 1000)::double precision`;\n\n/**\n * Journey reporting on the engine's Postgres schema (tables.ts: instance, message,\n * message_link, message_open, message_click, segment_member, segment_snapshot). Every timestamp\n * is written here, never defaulted, and every write is idempotent: the engine reports again when\n * a step is retried.\n */\nexport class PostgresReporting implements JourneyReporting {\n  constructor(\n    private readonly sql: SqlClientLike,\n    private readonly t: Record<TableKey, string>\n  ) {}\n\n  async instanceStarted(input: {\n    workflow: string;\n    instanceId: string;\n    userId: string;\n    at: number;\n  }): Promise<void> {\n    await this.sql.query(\n      `INSERT INTO ${this.t.instance} (instance_id, workflow, user_id, entered_at, status)\n       VALUES ($1, $2, $3, ${TS('$4')}, 'running')\n       ON CONFLICT (instance_id) DO NOTHING`,\n      [input.instanceId, input.workflow, input.userId, input.at]\n    );\n  }\n\n  async nodeReached(input: {\n    workflow: string;\n    instanceId: string;\n    userId: string;\n    nodeId: string;\n    at: number;\n  }): Promise<void> {\n    await this.sql.query(\n      `INSERT INTO ${this.t.instance} (instance_id, workflow, user_id, entered_at, node_id, node_at, status)\n       VALUES ($1, $2, $3, ${TS('$4')}, $5, ${TS('$4')}, 'running')\n       ON CONFLICT (instance_id) DO UPDATE SET node_id = EXCLUDED.node_id, node_at = EXCLUDED.node_at`,\n      [input.instanceId, input.workflow, input.userId, input.at, input.nodeId]\n    );\n  }\n\n  async instanceFinished(input: {\n    workflow: string;\n    instanceId: string;\n    userId: string;\n    status: string;\n    at: number;\n    convertedAt?: number;\n  }): Promise<void> {\n    // An upsert: an instance that started before its start was reported still gets its row\n    await this.sql.query(\n      `INSERT INTO ${this.t.instance}\n         (instance_id, workflow, user_id, entered_at, status, finished_at, converted_at)\n       VALUES ($1, $2, $3, ${TS('$5')}, $4, ${TS('$5')}, ${TS('$6')})\n       ON CONFLICT (instance_id) DO UPDATE SET status = EXCLUDED.status,\n         finished_at = EXCLUDED.finished_at, converted_at = EXCLUDED.converted_at`,\n      [\n        input.instanceId,\n        input.workflow,\n        input.userId,\n        input.status,\n        input.at,\n        input.convertedAt ?? null,\n      ]\n    );\n  }\n\n  async recordMessage(message: MessageRecord): Promise<string> {\n    // A retried step records the same copy again: the row it already wrote is the one\n    const rows = await this.sql.query<{ id: string }>(\n      `INSERT INTO ${this.t.message}\n         (id, idempotency_key, workflow, instance_id, node_id, template, channel, user_id, sent_at)\n       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, ${TS('$9')})\n       ON CONFLICT (idempotency_key) DO UPDATE SET idempotency_key = EXCLUDED.idempotency_key\n       RETURNING id`,\n      [\n        uuidv7(message.sentAt),\n        message.idempotencyKey,\n        message.workflow,\n        message.instanceId,\n        message.nodeId,\n        message.template,\n        message.channel,\n        message.userId,\n        message.sentAt,\n      ]\n    );\n    const id = rows[0]?.id;\n    if (id === undefined) throw new Error(`message ${message.idempotencyKey} was not recorded`);\n    return id;\n  }\n\n  async settleMessage(\n    idempotencyKey: string,\n    result: { delivered: true } | { delivered: false; reason: string },\n    at: number\n  ): Promise<void> {\n    if (result.delivered) {\n      await this.sql.query(\n        `UPDATE ${this.t.message} SET delivered_at = coalesce(delivered_at, ${TS('$2')}) WHERE idempotency_key = $1`,\n        [idempotencyKey, at]\n      );\n    } else {\n      await this.sql.query(\n        `UPDATE ${this.t.message} SET undelivered_reason = $2 WHERE idempotency_key = $1`,\n        [idempotencyKey, result.reason]\n      );\n    }\n  }\n\n  async recordLinks(messageId: string, urls: readonly string[]): Promise<void> {\n    if (urls.length === 0) return;\n    const values = urls.map((_, i) => `($1, ${i}, $${i + 2})`).join(', ');\n    await this.sql.query(\n      `INSERT INTO ${this.t.messageLink} (message_id, position, url) VALUES ${values} ON CONFLICT DO NOTHING`,\n      [messageId, ...urls]\n    );\n  }\n\n  async recordOpen(\n    messageId: string,\n    judge: (message: { userId: string; deliveredAt: number }) => Engagement | undefined\n  ): Promise<boolean> {\n    // In a transaction: read through Hyperdrive, a bare read may come from its cache, from before\n    // the copy existed\n    return this.sql.transaction(async (tx) => {\n      const rows = await tx.query<{ user_id: string; delivered_at: number | string }>(\n        `SELECT user_id, ${MS('coalesce(delivered_at, sent_at)')} AS delivered_at\n         FROM ${this.t.message} WHERE id = $1`,\n        [messageId]\n      );\n      const row = rows[0];\n      if (row === undefined) return false;\n      const open = judge({ userId: row.user_id, deliveredAt: Number(row.delivered_at) });\n      if (open === undefined) return true;\n      await tx.query(\n        `INSERT INTO ${this.t.messageOpen}\n           (id, message_id, opened_at, machine, reason, user_agent, asn, as_organization, country)\n         VALUES ($1, $2, ${TS('$3')}, $4, $5, $6, $7, $8, $9)`,\n        [\n          uuidv7(open.at),\n          messageId,\n          open.at,\n          open.machine,\n          open.reason,\n          open.userAgent,\n          open.asn,\n          open.organization,\n          open.country,\n        ]\n      );\n      await tx.query(\n        `UPDATE ${this.t.message} SET\n           opened_at = coalesce(opened_at, ${TS('$2')}),\n           human_opened_at = CASE WHEN $3 THEN human_opened_at ELSE coalesce(human_opened_at, ${TS('$2')}) END\n         WHERE id = $1`,\n        [messageId, open.at, open.machine]\n      );\n      return true;\n    });\n  }\n\n  async recordClick(\n    messageId: string,\n    position: number,\n    at: number,\n    windowMs: number,\n    judge: (link: ClickContext) => { engagement: Engagement; backdate: boolean }\n  ): Promise<{ url: string; engagement: Engagement } | undefined> {\n    return this.sql.transaction(async (tx) => {\n      // The copy's row is the lock: concurrent clicks on it are judged one at a time\n      const messages = await tx.query<{ delivered_at: number | string }>(\n        `SELECT ${MS('coalesce(delivered_at, sent_at)')} AS delivered_at\n         FROM ${this.t.message} WHERE id = $1 FOR UPDATE`,\n        [messageId]\n      );\n      const message = messages[0];\n      if (message === undefined) return undefined;\n      const links = await tx.query<{ url: string; link_count: number | string }>(\n        `SELECT l.url,\n           (SELECT count(*) FROM ${this.t.messageLink} a WHERE a.message_id = l.message_id) AS link_count\n         FROM ${this.t.messageLink} l WHERE l.message_id = $1 AND l.position = $2`,\n        [messageId, position]\n      );\n      const link = links[0];\n      if (link === undefined) return undefined;\n      const since = at - windowMs;\n      const recent = await tx.query<{ position: number; at: number | string }>(\n        `SELECT position, ${MS('clicked_at')} AS at FROM ${this.t.messageClick}\n         WHERE message_id = $1 AND clicked_at >= ${TS('$2')} ORDER BY clicked_at`,\n        [messageId, since]\n      );\n      const { engagement: click, backdate } = judge({\n        url: link.url,\n        deliveredAt: Number(message.delivered_at),\n        linkCount: Number(link.link_count),\n        recent: recent.map((row) => ({ position: row.position, at: Number(row.at) })),\n      });\n      await tx.query(\n        `INSERT INTO ${this.t.messageClick}\n           (id, message_id, position, url, clicked_at, machine, reason, user_agent, asn, as_organization, country)\n         VALUES ($1, $2, $3, $4, ${TS('$5')}, $6, $7, $8, $9, $10, $11)`,\n        [\n          uuidv7(click.at),\n          messageId,\n          position,\n          link.url,\n          click.at,\n          click.machine,\n          click.reason,\n          click.userAgent,\n          click.asn,\n          click.organization,\n          click.country,\n        ]\n      );\n      if (backdate) {\n        // A walk across the copy is found on its later clicks: the earlier ones were part of it\n        await tx.query(\n          `UPDATE ${this.t.messageClick} SET machine = true, reason = $4\n           WHERE message_id = $1 AND NOT machine\n             AND clicked_at BETWEEN ${TS('$2')} AND ${TS('$3')}`,\n          [messageId, since, at, click.reason]\n        );\n      }\n      // First opens and clicks, from the classified rows (a click implies an open)\n      await tx.query(\n        `UPDATE ${this.t.message} m SET\n           clicked_at = coalesce(m.clicked_at, ${TS('$2')}),\n           opened_at = coalesce(m.opened_at, ${TS('$2')}),\n           human_clicked_at = (SELECT min(c.clicked_at) FROM ${this.t.messageClick} c\n             WHERE c.message_id = m.id AND NOT c.machine),\n           human_opened_at = (SELECT min(t) FROM (\n             SELECT o.opened_at AS t FROM ${this.t.messageOpen} o WHERE o.message_id = m.id AND NOT o.machine\n             UNION ALL\n             SELECT c.clicked_at FROM ${this.t.messageClick} c WHERE c.message_id = m.id AND NOT c.machine\n           ) human)\n         WHERE m.id = $1`,\n        [messageId, at]\n      );\n      return { url: link.url, engagement: click };\n    });\n  }\n\n  async recordDeviceDelivered(messageId: string, at: number): Promise<boolean> {\n    const rows = await this.sql.query<{ id: string }>(\n      `UPDATE ${this.t.message} SET device_delivered_at = coalesce(device_delivered_at, ${TS('$2')})\n       WHERE id = $1 RETURNING id`,\n      [messageId, at]\n    );\n    return rows.length > 0;\n  }\n\n  async recordUnsubscribe(messageId: string, at: number): Promise<boolean> {\n    return this.sql.transaction(async (tx) => {\n      const rows = await tx.query<{ user_id: string }>(\n        `UPDATE ${this.t.message} SET unsubscribed_at = coalesce(unsubscribed_at, ${TS('$2')})\n         WHERE id = $1 AND channel = 'email' RETURNING user_id`,\n        [messageId, at]\n      );\n      const userId = rows[0]?.user_id;\n      if (userId === undefined) return false;\n      // The opt-out itself: the engine sends this user no more email\n      await tx.query(\n        `INSERT INTO ${this.t.suppression} (user_id, channel, ts) VALUES ($1, 'email', ${TS('$2')})\n         ON CONFLICT DO NOTHING`,\n        [userId, at]\n      );\n      return true;\n    });\n  }\n\n  async snapshotSegments(at: number): Promise<{ segment: string; size: number }[]> {\n    return this.sql.transaction(async (tx) => {\n      // Segments no longer deployed take their members with them\n      await tx.query(\n        `DELETE FROM ${this.t.segmentMember} m\n         WHERE NOT EXISTS (SELECT 1 FROM ${this.t.segment} s WHERE s.id = m.segment)`\n      );\n      const rows = await tx.query<{ segment: string; size: number | string }>(\n        `INSERT INTO ${this.t.segmentSnapshot} (segment, taken_at, size)\n         SELECT s.id, ${TS('$1')}, (SELECT count(*) FROM ${this.t.segmentMember} m WHERE m.segment = s.id)\n         FROM ${this.t.segment} s\n         ON CONFLICT DO NOTHING\n         RETURNING segment, size`,\n        [at]\n      );\n      return rows\n        .map((row) => ({ segment: row.segment, size: Number(row.size) }))\n        .sort((a, b) => a.segment.localeCompare(b.segment));\n    });\n  }\n}\n"],"mappings":"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"}