From 6d80d4ca2ad9399896bf35dff1d3e4f405844525 Mon Sep 17 00:00:00 2001 From: Sabur Ali Date: Tue, 17 Nov 2026 11:33:09 +0530 Subject: [PATCH 1/8] Restore intake answers from resume links; port attribution and remint - SessionResolver adopts a `?amd_session=` resume link, restores the stored journey (intake answers included) and re-issues the cookie. - A freshly minted session now inserts its row, so its first-touch attribution and `reconciled` flag are stored, and records `session_created` with its source category. - Attribution: canonical tracking keys and vendor aliases (AttributionNormalizer), derived source/device/browser/OS (DerivedAttribution), and `_amd` payload decryption with key rotation (AmdPayload, keys from AMD_TRACKING_KEY / AMD_TRACKING_KEY_PREVIOUS). - Cookie branch reads an unreconciled journey against the EMR once and re-mints a session the EMR no longer recognises, carrying the journey. - /health reports whether the tracking keys are configured (presence only). --- src/journey/amd-payload.ts | 38 ++ src/journey/attribution-normalizer.ts | 31 ++ src/journey/attribution.ts | 48 ++- src/journey/canonical-keys.ts | 60 +++ src/journey/derived-attribution.ts | 124 ++++++ src/journey/session-options.ts | 9 +- src/journey/session-resolver.ts | 285 +++++++++++-- src/routes/health/health.controller.ts | 23 +- test/app.e2e-spec.ts | 6 +- test/journey/amd-payload.spec.ts | 38 ++ test/journey/attribution-normalizer.spec.ts | 81 ++++ test/journey/derived-attribution.spec.ts | 74 ++++ test/journey/session-resolver.spec.ts | 437 ++++++++++++++++++++ 13 files changed, 1198 insertions(+), 56 deletions(-) create mode 100644 src/journey/amd-payload.ts create mode 100644 src/journey/attribution-normalizer.ts create mode 100644 src/journey/canonical-keys.ts create mode 100644 src/journey/derived-attribution.ts create mode 100644 test/journey/amd-payload.spec.ts create mode 100644 test/journey/attribution-normalizer.spec.ts create mode 100644 test/journey/derived-attribution.spec.ts create mode 100644 test/journey/session-resolver.spec.ts diff --git a/src/journey/amd-payload.ts b/src/journey/amd-payload.ts new file mode 100644 index 0000000..5c7a00c --- /dev/null +++ b/src/journey/amd-payload.ts @@ -0,0 +1,38 @@ +import { QueryParamCipher } from '@astermd-hq/sdk'; + +/** + * Reads the `_amd` tracking payload that affiliate links carry instead of plain query parameters. + * + * The parameters are encrypted so browser extensions cannot rewrite affiliate identifiers in + * transit (`[5.1]`), and the cipher itself belongs to the SDK: `QueryParamCipher.decrypt()` owns + * the wire format and the key shape, and is already total — an absent, truncated, tampered or + * wrongly-keyed token comes back as `{}` rather than an exception, which is what lets the caller + * fall back silently to plain parameters (`[5.3]`). A payload that decrypts but carries no entries + * is indistinguishable here from one that could not be read; both return `null`, and the caller's + * response is the same either way. + * + * What this adds is the rotation overlap (`[5.2b]`): keys are tried in order, current first, so a + * deployment mid-rotation keeps reading links signed with the previous key that are already + * sitting in sent emails and bought ads. + * + * Decryption is in-process by requirement (`[5.2a]`): it runs on the first request of every + * affiliate landing. A decoded payload is still untrusted input — AES-CBC carries no authenticity — + * so `Attribution.capture()` normalises it against the canonical alias table before use. + */ +export class AmdPayload { + /** + * @param token the raw `_amd` value from the URL + * @param keysHex secret keys as the SDK expects them, current key first + * @returns decoded parameters, or null when no key could read the token + */ + static decode(token: string, keysHex: readonly string[]): Record | null { + if (token === '') return null; + + for (const keyHex of keysHex) { + const params = QueryParamCipher.decrypt(token, keyHex); + if (Object.keys(params).length > 0) return params; + } + + return null; + } +} diff --git a/src/journey/attribution-normalizer.ts b/src/journey/attribution-normalizer.ts new file mode 100644 index 0000000..040e263 --- /dev/null +++ b/src/journey/attribution-normalizer.ts @@ -0,0 +1,31 @@ +import { CanonicalKeys } from './canonical-keys'; + +/** + * Reduces a raw parameter bag to canonical tracking keys. + * + * Pure and total: unrecognised parameters are dropped rather than carried along, and a value that + * is absent, blank after trimming, or not a scalar is treated as not present at all — so a link + * carrying `?aff_id=` never shadows a real affiliate id arriving under another alias. + */ +export class AttributionNormalizer { + static normalize(params: Record): Record { + const out: Record = {}; + + for (const [canonical, aliases] of CanonicalKeys.aliases()) { + for (const alias of aliases) { + if (!Object.prototype.hasOwnProperty.call(params, alias)) continue; + + const raw = params[alias]; + if (typeof raw !== 'string' && typeof raw !== 'number' && typeof raw !== 'boolean') continue; + + const value = String(raw).trim(); + if (value === '') continue; + + out[canonical] = value; + break; + } + } + + return out; + } +} diff --git a/src/journey/attribution.ts b/src/journey/attribution.ts index ebbe8aa..9e64bc0 100644 --- a/src/journey/attribution.ts +++ b/src/journey/attribution.ts @@ -1,26 +1,15 @@ +import { AttributionNormalizer } from './attribution-normalizer'; +import { DerivedAttribution as Derive, DerivedValues } from './derived-attribution'; + /** - * The attribution - * captured for one journey: canonical parameters, the landing referrer, and (eventually) the + * The attribution captured for one journey: canonical parameters, the landing referrer, and the * values derived from them. * * Immutable by construction — attribution is captured once on first touch and never overwritten * for the life of the journey (`[5.12]`); `firstTouch()` keys off the existence of an existing * instance, not its emptiness, so an empty landing referrer still counts as a capture (`[5.13]`). - * - * Deliberately reduced for this phase: the encrypted `_amd` payload - * (`AmdPayload::decode`, tracking-key rotation) and derived device/browser/OS/source-category - * parsing (`AttributionNormalizer`, `DerivedAttribution`) are not built yet — `derived` fields are - * always null until a later pass adds real user-agent parsing. What's built now (capture from - * plain query params + referrer, first-touch precedence, the EMR session payload shape) is - * complete and correct as far as it goes. */ -export interface DerivedAttribution { - sourceCategory: string | null; - sourceDetail: string | null; - deviceType: string | null; - browser: string | null; - os: string | null; -} +export type DerivedAttribution = DerivedValues; export interface AttributionData { params: Record; @@ -43,18 +32,27 @@ export class Attribution { readonly derived: Readonly, ) {} - static capture(plainQuery: Record, referrer: string | null): Attribution { - const params: Record = {}; - for (const [key, value] of Object.entries(plainQuery)) { - if (typeof value === 'string' && value !== '') { - params[key] = value; - } - } - + /** + * @param plainQuery the request's query parameters, `_amd` already removed; anything that is not + * a canonical tracking key (or one of its aliases) is dropped + * @param encryptedParams the decoded `_amd` payload, or `{}` + * @param selfHost this storefront's own host, so a referrer naming it is not recorded as a + * traffic source referring the site to itself + */ + static capture( + plainQuery: Record, + encryptedParams: Record, + referrer: string | null, + userAgent: string | null = null, + selfHost: string | null = null, + ): Attribution { + // Precedence is decided after normalisation, so an encrypted `affiliate_id` beats a plain + // `aff_id`: encrypted wins, plain fills the gaps (`[5.11]`). + const params = { ...AttributionNormalizer.normalize(plainQuery), ...AttributionNormalizer.normalize(encryptedParams) }; const sorted = Object.fromEntries(Object.entries(params).sort(([a], [b]) => a.localeCompare(b))); const trimmedReferrer = referrer === null ? null : referrer.trim(); - return new Attribution(sorted, trimmedReferrer, EMPTY_DERIVED); + return new Attribution(sorted, trimmedReferrer, Derive.from(sorted, trimmedReferrer, userAgent, selfHost)); } /** Whatever was captured first stands (`[5.12]`, `[5.13]`). */ diff --git a/src/journey/canonical-keys.ts b/src/journey/canonical-keys.ts new file mode 100644 index 0000000..272cede --- /dev/null +++ b/src/journey/canonical-keys.ts @@ -0,0 +1,60 @@ +/** + * The canonical tracking vocabulary and the vendor aliases that map onto it. + * + * Traffic arrives in many vendor dialects; normalising once here means the rest of the system — + * session creation, the provider order payload — deals in one key set instead of each learning + * every dialect (`[5.6]`). Two properties of this table are load-bearing and easy to "tidy" into + * bugs: alias order encodes precedence (first present and non-empty wins), and a raw parameter + * appearing under two canonical keys is intentional, not duplication (`[5.9]`). + */ +export class CanonicalKeys { + private static table: ReadonlyArray | null = null; + + /** + * Canonical keys in a stable order: identifiers, the nineteen custom sub-identifiers, click + * identifiers, publisher/visitor, the offer parameter, then the five UTM parameters. + */ + static all(): string[] { + return CanonicalKeys.aliases().map(([canonical]) => canonical); + } + + /** + * Canonical key => inbound aliases, most-preferred first. The canonical spelling is always its + * own first alias so a caller sending canonical keys needs no translation. An ordered list of + * pairs rather than an object, because `c1`..`c19` must keep their place between the + * identifiers and the click ids. + */ + static aliases(): ReadonlyArray { + if (CanonicalKeys.table !== null) return CanonicalKeys.table; + + const table: Array = [ + ['network_id', ['network_id', 'nid', 'net_id']], + ['affiliate_id', ['affiliate_id', 'aff_id', 'affid', 'aff']], + ['sub_affiliate_id', ['sub_affiliate_id', 'saff_id', 'sub_id', 'sub1', 's1']], + ['source_id', ['source_id', 'src', 'source', 'utm_source']], + ]; + + // c1..c19: the canonical spelling, the vendor sub-id spellings, and the provider slot names + // other CRMs forward traffic under (`[5.10]`). + for (let i = 1; i <= 19; i += 1) { + table.push([`c${i}`, [`c${i}`, `sub${i}`, `s${i}`, `tracking${i}`, `sourceValue${i}`]]); + } + + table.push( + ['click_id', ['click_id', 'clickid', 'cid']], + ['gclid', ['gclid']], + ['network_click_id', ['network_click_id', 'transaction_id', 'tid']], + ['publisher_id', ['publisher_id', 'pub_id', 'pubid']], + ['visitor_id', ['visitor_id', 'vid']], + ['offer', ['offer', 'offer_id', 'opt']], + ['utm_source', ['utm_source']], + ['utm_medium', ['utm_medium']], + ['utm_campaign', ['utm_campaign']], + ['utm_term', ['utm_term']], + ['utm_content', ['utm_content']], + ); + + CanonicalKeys.table = table; + return table; + } +} diff --git a/src/journey/derived-attribution.ts b/src/journey/derived-attribution.ts new file mode 100644 index 0000000..1c37f67 --- /dev/null +++ b/src/journey/derived-attribution.ts @@ -0,0 +1,124 @@ +/** + * Heuristics derived from the captured parameters, the landing referrer and the user agent. + * + * Two orderings here are deliberate and must not be "simplified": source-category matching is + * first-match-wins down a fixed list (`[5.14]`), and device and browser classification test the + * impersonators before the impersonated (`[5.15]`) — tablet before mobile because an iPad's user + * agent also says `Mobile`, Edge and Opera before Chrome and Chrome before Safari because each + * carries the earlier one's token. An empty user agent yields nulls, which callers omit rather than + * sending as blanks. + */ +export interface DerivedValues { + sourceCategory: string | null; + sourceDetail: string | null; + deviceType: string | null; + browser: string | null; + os: string | null; +} + +/** Tokens that identify social traffic in a UTM source or medium. */ +const SOCIAL_TOKENS = [ + 'facebook', 'instagram', 'twitter', 'x.com', 'linkedin', 'tiktok', + 'reddit', 'pinterest', 'snapchat', 'youtube', 'threads', +]; + +const TABLET_TOKENS = ['ipad', 'tablet', 'playbook', 'silk', 'kindle']; +const MOBILE_TOKENS = ['mobi', 'iphone', 'ipod', 'android', 'phone']; + +// Order matters: each later entry's token appears in the earlier ones. +const BROWSERS: ReadonlyArray = [ + ['Edg', 'Edge'], ['OPR', 'Opera'], ['Opera', 'Opera'], ['Chrome', 'Chrome'], ['Firefox', 'Firefox'], ['Safari', 'Safari'], +]; + +// iOS before macOS: an iPhone's user agent also says "like Mac OS X". +const SYSTEMS: ReadonlyArray = [ + ['iPhone', 'iOS'], ['iPad', 'iOS'], ['iPod', 'iOS'], ['Android', 'Android'], ['Windows', 'Windows'], + ['Mac OS X', 'macOS'], ['Macintosh', 'macOS'], ['Linux', 'Linux'], +]; + +export class DerivedAttribution { + /** @param params canonical parameters (see `AttributionNormalizer`) */ + static from(params: Record, referrer: string | null, userAgent: string | null, selfHost: string | null = null): DerivedValues { + const [sourceCategory, sourceDetail] = DerivedAttribution.source(params, DerivedAttribution.externalReferrer(referrer, selfHost)); + + return { + sourceCategory, + sourceDetail, + deviceType: DerivedAttribution.device(userAgent), + browser: DerivedAttribution.browser(userAgent), + os: DerivedAttribution.os(userAgent), + }; + } + + private static source(params: Record, referrer: string | null): [string | null, string | null] { + const affiliate = params.affiliate_id ?? ''; + if (affiliate !== '') { + return ['affiliate', affiliate]; + } + + const medium = (params.utm_medium ?? '').toLowerCase(); + const utmSource = params.utm_source ?? ''; + if (medium === 'email' || medium === 'newsletter') { + const detail = (params.utm_campaign ?? '') !== '' ? params.utm_campaign : utmSource; + return ['email_campaign', detail === '' ? null : detail]; + } + + const haystack = `${utmSource} ${medium}`.toLowerCase(); + if (SOCIAL_TOKENS.some((token) => haystack.includes(token))) { + return ['social_media', utmSource === '' ? null : utmSource]; + } + + if (referrer !== null && referrer !== '') { + return ['referral', referrer]; + } + + return [null, null]; + } + + /** + * The referrer, unless it is this storefront referring to itself. + * + * A visitor moving from one page of ours to another sends a `Referer` naming our own host, and + * treating that as a traffic source records the site as its own referral. Under `[5.12]`'s + * first-touch rule that is worse than noise: one internally-referred capture can pin a journey's + * attribution to the storefront itself for its whole life. + * + * Only the derived source is affected; the raw referrer is still stored verbatim. A referrer we + * cannot parse a host out of is left alone: it is not evidence of a same-origin visit, and + * dropping it would lose a real external source to a malformed header. + */ + private static externalReferrer(referrer: string | null, selfHost: string | null): string | null { + if (referrer === null || referrer === '' || selfHost === null || selfHost === '') { + return referrer; + } + + let host: string; + try { + host = new URL(referrer).hostname; + } catch { + return referrer; + } + if (host === '') return referrer; + + return host.toLowerCase() === selfHost.toLowerCase() ? null : referrer; + } + + private static device(userAgent: string | null): string | null { + if (userAgent === null || userAgent === '') return null; + + const agent = userAgent.toLowerCase(); + if (TABLET_TOKENS.some((token) => agent.includes(token))) return 'tablet'; + if (MOBILE_TOKENS.some((token) => agent.includes(token))) return 'mobile'; + return 'desktop'; + } + + private static browser(userAgent: string | null): string | null { + if (userAgent === null || userAgent === '') return null; + return BROWSERS.find(([token]) => userAgent.includes(token))?.[1] ?? null; + } + + private static os(userAgent: string | null): string | null { + if (userAgent === null || userAgent === '') return null; + return SYSTEMS.find(([token]) => userAgent.includes(token))?.[1] ?? null; + } +} diff --git a/src/journey/session-options.ts b/src/journey/session-options.ts index e122295..4db5b8e 100644 --- a/src/journey/session-options.ts +++ b/src/journey/session-options.ts @@ -6,9 +6,8 @@ import { ConfigService } from '../support/config'; * settings, read from config once and passed as one value instead of several constructor * arguments. * - * `trackingKeys` (the `_amd` payload decryption keys) is omitted for now — Phase 2's `Attribution` - * doesn't decrypt an encrypted payload yet (see its doc comment), so there is nothing to key - * against. + * `trackingKeys` are the `_amd` payload decryption keys, current first then the previous one kept + * during a rotation (`[5.2b]`); blank values are left out, so an unset key is never tried. */ @Injectable() export class SessionOptions { @@ -17,6 +16,7 @@ export class SessionOptions { readonly payloadParam: string; readonly lifetimeDays: number; readonly excludePaths: string[]; + readonly trackingKeys: string[]; constructor(config: ConfigService) { this.cookieName = config.app.session.cookie; @@ -24,5 +24,8 @@ export class SessionOptions { this.payloadParam = config.app.attribution.payloadParam; this.lifetimeDays = config.app.session.lifetimeDays; this.excludePaths = config.app.session.excludePaths; + this.trackingKeys = [config.app.attribution.key, config.app.attribution.previousKey] + .map((key) => (key ?? '').trim()) + .filter((key) => key !== ''); } } diff --git a/src/journey/session-resolver.ts b/src/journey/session-resolver.ts index 089fe31..3a3b5f7 100644 --- a/src/journey/session-resolver.ts +++ b/src/journey/session-resolver.ts @@ -1,37 +1,51 @@ import { Inject, Injectable } from '@nestjs/common'; import type { Request } from 'express'; import { SESSION_GATEWAY } from '../core/tokens'; +import { EventRepository } from '../repository/event-repository'; +import { SessionRepository } from '../repository/session-repository'; import { OperatorLog } from '../support/operator-log'; +import { AmdPayload } from './amd-payload'; import { Attribution } from './attribution'; import { JourneyState } from './journey-state'; import { JourneyStore } from './journey-store'; -import { SessionGateway } from '../emr/session-gateway'; +import { SessionGateway, SessionViewResult } from '../emr/session-gateway'; import { SessionOptions } from './session-options'; import { SessionResolution } from './session-resolution'; +interface ResumeAdoption { + uuid: string; + snapshot: SessionViewResult | null; +} + /** - * Decides which - * analytics session this request belongs to, and captures first-touch attribution while doing it. + * Decides which analytics session this request belongs to, and captures first-touch attribution + * while doing it. * - * Not built here yet: adopting a session named by a signed resume link (`[21.3]`), - * decrypting an encrypted `_amd` attribution payload, and — the biggest piece — re-validating an - * existing cookie against the EMR on a schedule and transplanting the whole journey onto a freshly - * minted session when the EMR no longer recognises it (`remint()`, carrying roughly twenty durable - * fields across). None of that is reachable in an honest way yet: resume links and `_amd` - * decryption need the `Attribution`/`AmdPayload` machinery this phase doesn't build, and - * EMR-reconciliation-driven remint needs the full `JourneyState` field set a `remint()` would - * copy (Phases 4/6/7/8) regardless of `SESSION_GATEWAY`'s binding — `EmrSessionGateway` now - * really does mint and look up sessions against `@astermd-hq/sdk` when `config.app.session. - * analytics` is on (see `core/core.module.ts`), and under `NullSessionGateway` (analytics off, or - * `NODE_ENV=test`) `create()` still always answers null and `view()` still always answers "doesn't - * exist," so no session is ever minted or kept alive across requests in that binding. What remains - * here (cookie-present -> trust it; no cookie + may-mint -> attempt a real mint; anything else -> - * no session) is the behaviour until the remint/resume-link paths land. + * Order of precedence: + * 1. A valid resume link (`?amd_session=`) beats the cookie, because it comes from a + * message the storefront itself sent (`[21.3]`). The session is adopted, its journey restored, + * and the cookie re-issued for it. A malformed value is ignored silently (`[4.10]`); a + * well-formed one the EMR does not know is logged and recorded as `session_resume_rejected` + * (`[21.2]`), and the visitor carries on as if no link had been given. + * 2. The cookie beats minting (`[4.2]`). A cookie whose journey is not yet reconciled is read + * against the EMR once; one the EMR says it does not know is replaced (`remint()`). + * 3. Otherwise a session is minted, when the request may create one (`[4.1]`). */ @Injectable() export class SessionResolver { + /** + * Generation of the EMR read-model extractors, stamped next to `reconciled`. Bump it whenever + * the extractors change, so every journey reconciled under the old ones is re-read once. + */ + static readonly READ_MODEL_SHAPE = 1; + + /** Accepted session-identifier shape (`[4.10]`): a canonical UUID or a hex object id. */ + private static readonly UUID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9-]{15,63}$/; + constructor( @Inject(SESSION_GATEWAY) private readonly gateway: SessionGateway, + private readonly sessions: SessionRepository, + private readonly events: EventRepository, private readonly log: OperatorLog, private readonly options: SessionOptions, ) {} @@ -39,11 +53,40 @@ export class SessionResolver { async resolve(request: Request, journey: JourneyStore, mayCreate: boolean): Promise { const incoming = this.captureAttribution(request); + const candidate = SessionResolver.validUuid(SessionResolver.queryString(request, this.options.resumeParam)); + const adoption = candidate !== null ? await this.adoptFromResumeLink(candidate) : null; + if (adoption !== null) { + const state = await this.hydrate(journey, adoption.uuid, incoming, adoption.snapshot); + await this.events.append(adoption.uuid, 'session_adopted'); + await this.auditResumeAccess(adoption.uuid, state); + return new SessionResolution(adoption.uuid, true); + } + const cookies = (request as { cookies?: Record }).cookies ?? {}; const cookie = SessionResolver.validUuid(cookies[this.options.cookieName] ?? ''); if (cookie !== null) { const state = await journey.load(cookie); + const snapshot = SessionResolver.needsReconciliationRead(state) ? await this.gateway.view(cookie) : null; + + // An authoritative "the EMR does not know this session" is actionable rather than something + // to record and carry: every mirror call this journey makes from here would fail and be + // swallowed (`[7.12]`). `reconciled` is deliberately NOT stamped on this path — when the + // re-mint cannot happen on this request, the next page view has to re-read and try again + // rather than inherit the wrong answer forever. A failed read (null) is not an answer: the + // EMR being unreachable says nothing about the session, so it never triggers a re-mint. + if (snapshot !== null && snapshot.exists !== true) { + if (mayCreate) { + return this.remint(cookie, state, incoming, request, journey); + } + + state.attribution = Attribution.firstTouch(state.attribution, incoming); + return new SessionResolution(cookie); + } + + if (snapshot !== null) { + SessionResolver.applySnapshot(state, snapshot); + } state.attribution = Attribution.firstTouch(state.attribution, incoming); return new SessionResolution(cookie); } @@ -61,15 +104,214 @@ export class SessionResolver { const state = new JourneyState(); state.attribution = incoming; + // A session minted on this request has no server-side history, so the reconciliation read + // would be a round-trip for nothing. No read-model generation is stamped, because none was + // consulted: that leaves a later resume link its single confirming read (`[4.12]`). state.reconciled = true; - journey.adopt(uuid, state); + + // The row is inserted here, not left to the save-back: `flush()` only updates an existing row, + // so without it this request's journey (first-touch attribution, `reconciled`) is never stored + // and the next request's `load()` starts the session over from an empty, unreconciled row. + const updatedAt = await this.sessions.insert(uuid, state.toArray(), incoming.toArray()); + journey.adopt(uuid, state, updatedAt); + await this.events.append(uuid, 'session_created', { source_category: incoming.derived.sourceCategory }); + await this.recordRejectedResume(uuid, candidate); + + return new SessionResolution(uuid, true); + } + + /** + * Replaces a cookie the EMR no longer recognises with a fresh session, carrying the journey + * across. + * + * What moves and what does not is decided for every durable field; a field with no decision + * defaults to *not carried*, and the spec enumerates the whole state so a field added later + * cannot join either side by omission. + * + * Carried — facts about this buyer: attribution, the opportunity link, the cart, the furthest + * step, the questionnaire (answers, per-form status, any standing disqualification), the + * identity verdict, the checkout's working state (buyer details, promotion, accepted bumps, + * consents), and the whole record of a purchase that already happened (placed orders, upsell + * outcomes, the retained receipt, the fire-once completion guard and the retirement flag) + * (`[5.12]`, `[5.21]`, `[21.7]`, `[9.8]`, `[21.5]`, `[13.30]`, `[22.20]`, `[17.1]`, `[4.17]`, + * `[4.18]`). + * + * Not carried — the old session's relationship with something else: its recorded EMR events + * (carrying them would suppress "initiated" events on a session where nothing has fired yet, + * `[4.13]`), the cart-mirror flag (the new session has no remote cart), the read-model generation + * (nothing was read for the new identifier), the promotion's cart digest (re-quoting is the safe + * direction, `[14.6b]`), a payment pending on the old session's checkout attempt, and the + * post-purchase working state — credential handle, upsell queue, cursor and quotes. Without a + * handle the remaining offers are skipped silently (`[15.13]`), which costs one optional add-on; + * carrying it without its queue position would re-offer something already charged. + * + * Also not carried: `identityDocument` and `paymentSummary`. + * + * A failed mint leaves the visitor on the old identifier with the journey still unreconciled, + * so the next page view tries again rather than settling into the broken state. + */ + private async remint( + stale: string, + state: JourneyState, + incoming: Attribution, + request: Request, + journey: JourneyStore, + ): Promise { + const attribution = Attribution.firstTouch(state.attribution, incoming); + const context = SessionResolver.requestContext(request); + + // Getting the rejected identifier back is not a new session: the insert would no-op on + // conflict and the same cookie would be re-issued over the same unreconciled row, minting + // again on every page view. Treated as a failed mint for that reason. + const uuid = await this.gateway.create(attribution.emrSessionPayload(), context.userAgent, context.clientIp); + if (uuid === null || uuid === stale || SessionResolver.validUuid(uuid) === null) { + this.log.warning('session.remint_failed', { path: request.path }); + state.attribution = attribution; + return new SessionResolution(null); + } + + const fresh = new JourneyState(); + fresh.attribution = attribution; + fresh.opportunityId = state.opportunityId; + fresh.cart = state.cart; + fresh.furthestStep = state.furthestStep; + fresh.reconciled = true; + fresh.answers = state.answers; + fresh.formStatus = state.formStatus; + fresh.disqualifiedRule = state.disqualifiedRule; + fresh.disqualifiedTeleform = state.disqualifiedTeleform; + fresh.verification = state.verification; + fresh.buyer = state.buyer; + fresh.promotion = state.promotion; + fresh.acceptedBumps = state.acceptedBumps; + fresh.consents = state.consents; + fresh.placedOrders = state.placedOrders; + fresh.upsellOutcomes = state.upsellOutcomes; + fresh.receipt = state.receipt; + fresh.completedAt = state.completedAt; + fresh.sessionRetired = state.sessionRetired; + + // The opportunity is passed to the insert rather than left to the save-back: adopt() + // fingerprints the state it is handed, so nothing downstream sees the transplant as a change. + const updatedAt = await this.sessions.insert(uuid, fresh.toArray(), attribution.toArray(), fresh.opportunityId); + journey.adopt(uuid, fresh, updatedAt); + await this.events.append(uuid, 'session_reminted', { replaced: stale }); + this.log.info('session.reminted', { session: uuid, replaced: stale }); return new SessionResolution(uuid, true); } + /** + * Accepts a resume-link session if this storefront already holds a reconciled journey for it, or + * if the EMR confirms it exists. Uses a read-only lookup rather than `JourneyStore.load()`, which + * would create a row for an identifier this may be about to reject. + */ + private async adoptFromResumeLink(candidate: string): Promise { + const row = await this.sessions.find(candidate); + if (row !== null && SessionResolver.carriesCurrentReadModel(JourneyState.fromArray(row.journeyState, null, null))) { + return { uuid: candidate, snapshot: null }; + } + + const snapshot = await this.gateway.view(candidate); + if (snapshot === null || snapshot.exists !== true) { + this.log.info('session.resume_rejected', { session: candidate }); + return null; + } + + return { uuid: candidate, snapshot }; + } + + /** Loads the adopted journey, folds in the EMR snapshot (if any) and this request's attribution. */ + private async hydrate( + journey: JourneyStore, + uuid: string, + incoming: Attribution, + snapshot: SessionViewResult | null, + ): Promise { + const state = await journey.load(uuid); + + if (snapshot === null && SessionResolver.needsReconciliationRead(state)) { + snapshot = await this.gateway.view(uuid); + } + if (snapshot !== null) { + SessionResolver.applySnapshot(state, snapshot); + } + + state.attribution = Attribution.firstTouch(state.attribution, incoming); + return state; + } + + /** + * `[30.7]`/`[30.8]`: a resume link put someone's journey — possibly including intake answers — + * back in front of a browser. The link never expires, so this row is the only record that it was + * used. Records whether answers came back, never the answers themselves. + */ + private async auditResumeAccess(uuid: string, state: JourneyState): Promise { + const teleforms = Object.keys(state.answers).length; + await this.events.append(uuid, 'access.journey_resumed', { + actor: 'resume_link', + reason: 'journey_resumed', + restored_intake: teleforms > 0, + teleforms, + }); + } + + /** A well-formed resume value that adoption still rejected names a session the EMR does not know. */ + private async recordRejectedResume(uuid: string, candidate: string | null): Promise { + if (candidate !== null) { + await this.events.append(uuid, 'session_resume_rejected', { rejected: candidate }); + } + } + + /** + * Merges an EMR snapshot into the journey: the opportunity only if none is set, and events as a + * union so one recorded locally on this request isn't lost (`[4.12]`, `[4.13]`). + */ + private static applySnapshot(state: JourneyState, snapshot: SessionViewResult): void { + if (snapshot.exists) { + state.opportunityId ??= snapshot.opportunityId; + for (const name of snapshot.events) { + state.recordEmrEvent(name); + } + } + + state.reconciled = true; + state.readModelShape = SessionResolver.READ_MODEL_SHAPE; + } + + private static needsReconciliationRead(state: JourneyState): boolean { + if (!state.reconciled) return true; + return state.readModelShape !== null && state.readModelShape !== SessionResolver.READ_MODEL_SHAPE; + } + + private static carriesCurrentReadModel(state: JourneyState): boolean { + return state.reconciled && state.readModelShape === SessionResolver.READ_MODEL_SHAPE; + } + private captureAttribution(request: Request): Attribution { - const referrer = request.get('Referer') ?? null; - return Attribution.capture(request.query as Record, referrer); + const referrer = request.get('Referer') || null; + const query = { ...(request.query as Record) }; + const raw = query[this.options.payloadParam]; + const token = typeof raw === 'string' ? raw : ''; + delete query[this.options.payloadParam]; + + let encrypted: Record = {}; + if (token !== '') { + const decoded = AmdPayload.decode(token, this.options.trackingKeys); + if (decoded === null) { + this.log.warning('amd_decrypt_failed', { keys_tried: this.options.trackingKeys.length }); + } else { + encrypted = decoded; + } + } + + return Attribution.capture(query, encrypted, referrer, request.get('User-Agent') ?? null, request.hostname ?? null); + } + + /** A single string query value; anything else (absent, repeated, nested) reads as empty. */ + private static queryString(request: Request, name: string): string { + const value = (request.query as Record)[name]; + return typeof value === 'string' ? value : ''; } private static requestContext(request: Request): { userAgent: string | null; clientIp: string | null } { @@ -79,9 +321,6 @@ export class SessionResolver { }; } - /** Accepted session-identifier shape (`[4.10]`): a canonical UUID or a hex object id. */ - private static readonly UUID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9-]{15,63}$/; - private static validUuid(value: string): string | null { const trimmed = value.trim(); return SessionResolver.UUID_PATTERN.test(trimmed) ? trimmed : null; diff --git a/src/routes/health/health.controller.ts b/src/routes/health/health.controller.ts index 4948673..fe86035 100644 --- a/src/routes/health/health.controller.ts +++ b/src/routes/health/health.controller.ts @@ -1,18 +1,33 @@ import { Controller, Get, HttpCode } from '@nestjs/common'; +import { ConfigService } from '../../support/config'; /** - * The health route, reduced to its shape for Phase 1 — a cheap, dependency-free route proving the request lifecycle end to end before the - * persistence/config/storage checks it will grow (config, DB, storage, form cache -> 503 if any - * false) exist to report on. Those land alongside their owning phases (3, 6). + * The health route, still reduced: the persistence/config/storage checks it will grow (config, + * DB, storage, form cache -> 503 if any false) land alongside their owning phases. + * + * `info` carries configuration facts an operator needs but that do not make this instance + * unhealthy. The tracking keys are reported by presence only — a key never appears in a response. + * A missing `attribution_key` is otherwise visible only as `amd_decrypt_failed` in the log, once + * per affiliate landing. */ @Controller('health') export class HealthController { + constructor(private readonly config: ConfigService) {} + @Get() @HttpCode(200) check() { return { checks: {}, - info: {}, + info: { + analytics_sessions: this.config.app.session.analytics === true, + attribution_key: HealthController.presence(this.config.app.attribution.key), + attribution_previous_key: HealthController.presence(this.config.app.attribution.previousKey), + }, }; } + + private static presence(value: unknown): 'configured' | 'missing' { + return typeof value === 'string' && value.trim() !== '' ? 'configured' : 'missing'; + } } diff --git a/test/app.e2e-spec.ts b/test/app.e2e-spec.ts index 1469ffb..54ae0cf 100644 --- a/test/app.e2e-spec.ts +++ b/test/app.e2e-spec.ts @@ -49,7 +49,11 @@ describe('App bootstrap (Phase 1)', () => { it('returns 200 JSON on GET /health/', async () => { const res = await request(app.getHttpServer()).get('/health/'); expect(res.status).toBe(200); - expect(res.body).toEqual({ checks: {}, info: {} }); + expect(res.body.checks).toEqual({}); + expect(res.body.info).toMatchObject({ analytics_sessions: false }); + expect(['configured', 'missing']).toContain(res.body.info.attribution_key); + expect(['configured', 'missing']).toContain(res.body.info.attribution_previous_key); + expect(JSON.stringify(res.body)).not.toMatch(/[0-9a-f]{32}/i); }); it('renders the themed 404 page for an unmatched route, with X-Robots-Tag', async () => { diff --git a/test/journey/amd-payload.spec.ts b/test/journey/amd-payload.spec.ts new file mode 100644 index 0000000..56b8761 --- /dev/null +++ b/test/journey/amd-payload.spec.ts @@ -0,0 +1,38 @@ +import { QueryParamCipher } from '@astermd-hq/sdk'; +import { AmdPayload } from '../../src/journey/amd-payload'; + +const KEY = '00112233445566778899aabbccddeeff'; +const PREVIOUS_KEY = 'ffeeddccbbaa99887766554433221100'; + +describe('AmdPayload', () => { + it('decodes a token into a flat parameter map', () => { + const token = QueryParamCipher.encrypt({ aff_id: '4412', sub1: 'creativeA' }, KEY); + expect(AmdPayload.decode(token, [KEY])).toEqual({ aff_id: '4412', sub1: 'creativeA' }); + }); + + it('decrypts links signed before a rotation with the previous key', () => { + const token = QueryParamCipher.encrypt({ aff_id: '4412' }, PREVIOUS_KEY); + expect(AmdPayload.decode(token, [KEY])).toBeNull(); + expect(AmdPayload.decode(token, [KEY, PREVIOUS_KEY])).toEqual({ aff_id: '4412' }); + }); + + it('still decrypts a current-key token while both keys are configured', () => { + const token = QueryParamCipher.encrypt({ aff_id: 'current' }, KEY); + expect(AmdPayload.decode(token, [KEY, PREVIOUS_KEY])).toEqual({ aff_id: 'current' }); + }); + + it('returns null without throwing for every unreadable token', () => { + const valid = QueryParamCipher.encrypt({ a: 'b' }, KEY); + + expect(AmdPayload.decode('', [KEY])).toBeNull(); + expect(AmdPayload.decode('!!!not-base64!!!', [KEY])).toBeNull(); + expect(AmdPayload.decode('c2hvcnQ=', [KEY])).toBeNull(); + expect(AmdPayload.decode(valid, [])).toBeNull(); + expect(AmdPayload.decode(valid, ['not-a-key'])).toBeNull(); + }); + + it('decodes a valueless entry to an empty string', () => { + const token = QueryParamCipher.encrypt({ aff_id: '' }, KEY); + expect(AmdPayload.decode(token, [KEY])).toEqual({ aff_id: '' }); + }); +}); diff --git a/test/journey/attribution-normalizer.spec.ts b/test/journey/attribution-normalizer.spec.ts new file mode 100644 index 0000000..7932bce --- /dev/null +++ b/test/journey/attribution-normalizer.spec.ts @@ -0,0 +1,81 @@ +import { Attribution } from '../../src/journey/attribution'; +import { AttributionNormalizer } from '../../src/journey/attribution-normalizer'; +import { CanonicalKeys } from '../../src/journey/canonical-keys'; + +describe('AttributionNormalizer', () => { + it('maps vendor aliases onto canonical keys and drops unknown parameters', () => { + const normalized = AttributionNormalizer.normalize({ + aff_id: '4412', + nid: '77', + gclid: 'Cj0KEQ', + utm_medium: 'cpc', + unknown_param: 'ignored', + }); + + expect(normalized.affiliate_id).toBe('4412'); + expect(normalized.network_id).toBe('77'); + expect(normalized.gclid).toBe('Cj0KEQ'); + expect(normalized.utm_medium).toBe('cpc'); + expect(normalized).not.toHaveProperty('unknown_param'); + }); + + it('lets the first alias present win, and matches aliases case-sensitively', () => { + expect(AttributionNormalizer.normalize({ aff_id: 'second', affiliate_id: 'first' }).affiliate_id).toBe('first'); + expect(AttributionNormalizer.normalize({ AFF_ID: '4412' })).toEqual({}); + }); + + it('lets one raw parameter feed two canonical keys', () => { + const normalized = AttributionNormalizer.normalize({ utm_source: 'newsletter', sub1: 'creativeA' }); + + expect(normalized.utm_source).toBe('newsletter'); + expect(normalized.source_id).toBe('newsletter'); + expect(normalized.c1).toBe('creativeA'); + expect(normalized.sub_affiliate_id).toBe('creativeA'); + }); + + it('accepts provider slot names inbound', () => { + const normalized = AttributionNormalizer.normalize({ tracking3: 'x', sourceValue2: 'y' }); + expect(normalized.c3).toBe('x'); + expect(normalized.c2).toBe('y'); + }); + + it('drops empty, blank and non-scalar values', () => { + expect(AttributionNormalizer.normalize({ aff_id: '', nid: ' ', c1: ['array'], gclid: 'kept' })).toEqual({ gclid: 'kept' }); + }); + + it('supports custom sub-identifiers through c19', () => { + const normalized = AttributionNormalizer.normalize({ c19: 'nineteen', sub14: 'fourteen' }); + expect(normalized.c19).toBe('nineteen'); + expect(normalized.c14).toBe('fourteen'); + expect(CanonicalKeys.all()).toContain('c19'); + }); +}); + +describe('Attribution.capture', () => { + it('stores canonical params only and fills the derived values', () => { + const attribution = Attribution.capture( + { aff: '4412', amd_session: '11111111-1111-4111-8111-111111111111', _amd: 'token' }, + {}, + 'https://news.example/', + 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 Mobile/15E148', + 'shop.example', + ); + + expect(attribution.params).toEqual({ affiliate_id: '4412' }); + expect(attribution.derived).toEqual({ + sourceCategory: 'affiliate', + sourceDetail: '4412', + deviceType: 'mobile', + browser: null, + os: 'iOS', + }); + }); + + it('lets an encrypted value beat a plain one after normalisation, and drives derivation with it', () => { + const attribution = Attribution.capture({ aff_id: 'plain', utm_medium: 'cpc' }, { affiliate_id: 'encrypted' }, null); + + expect(attribution.get('affiliate_id')).toBe('encrypted'); + expect(attribution.get('utm_medium')).toBe('cpc'); + expect(attribution.derived.sourceDetail).toBe('encrypted'); + }); +}); diff --git a/test/journey/derived-attribution.spec.ts b/test/journey/derived-attribution.spec.ts new file mode 100644 index 0000000..aca539a --- /dev/null +++ b/test/journey/derived-attribution.spec.ts @@ -0,0 +1,74 @@ +import { DerivedAttribution } from '../../src/journey/derived-attribution'; + +function category(params: Record, referrer: string | null): [string | null, string | null] { + const derived = DerivedAttribution.from(params, referrer, null); + return [derived.sourceCategory, derived.sourceDetail]; +} + +describe('DerivedAttribution', () => { + it('prefers affiliate, then email, then social, then referral', () => { + expect(category({ affiliate_id: '4412', utm_medium: 'email' }, 'https://news.example/')).toEqual(['affiliate', '4412']); + expect(category({ utm_medium: 'newsletter', utm_campaign: 'spring-sale' }, 'https://news.example/')).toEqual(['email_campaign', 'spring-sale']); + expect(category({ utm_medium: 'email', utm_source: 'mailer' }, null)).toEqual(['email_campaign', 'mailer']); + expect(category({ utm_source: 'facebook' }, null)).toEqual(['social_media', 'facebook']); + expect(category({}, 'https://blog.example/post/')).toEqual(['referral', 'https://blog.example/post/']); + expect(category({}, null)).toEqual([null, null]); + expect(category({}, '')).toEqual([null, null]); + }); + + it('tests tablet before mobile', () => { + const ipad = 'Mozilla/5.0 (iPad; CPU OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148'; + expect(DerivedAttribution.from({}, null, ipad).deviceType).toBe('tablet'); + + const iphone = 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 Mobile/15E148'; + expect(DerivedAttribution.from({}, null, iphone).deviceType).toBe('mobile'); + expect(DerivedAttribution.from({}, null, iphone).os).toBe('iOS'); + + const desktop = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0 Safari/537.36'; + expect(DerivedAttribution.from({}, null, desktop).deviceType).toBe('desktop'); + }); + + it('keeps browser detection order against impersonating user agents', () => { + const edge = 'Mozilla/5.0 (Windows NT 10.0) AppleWebKit/537.36 Chrome/120.0 Safari/537.36 Edg/120.0'; + expect(DerivedAttribution.from({}, null, edge).browser).toBe('Edge'); + + const opera = 'Mozilla/5.0 (Windows NT 10.0) AppleWebKit/537.36 Chrome/120.0 Safari/537.36 OPR/106.0'; + expect(DerivedAttribution.from({}, null, opera).browser).toBe('Opera'); + + const chrome = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 Chrome/120.0 Safari/537.36'; + expect(DerivedAttribution.from({}, null, chrome).browser).toBe('Chrome'); + expect(DerivedAttribution.from({}, null, chrome).os).toBe('macOS'); + + const safari = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 Version/17.0 Safari/605.1.15'; + expect(DerivedAttribution.from({}, null, safari).browser).toBe('Safari'); + }); + + it('yields nulls for an empty user agent', () => { + const derived = DerivedAttribution.from({}, null, null); + expect(derived.deviceType).toBeNull(); + expect(derived.browser).toBeNull(); + expect(derived.os).toBeNull(); + }); + + it('does not treat a referrer from our own host as a traffic source', () => { + const derived = DerivedAttribution.from({}, 'http://127.0.0.1:8123/', null, '127.0.0.1'); + expect(derived.sourceCategory).toBeNull(); + expect(derived.sourceDetail).toBeNull(); + }); + + it('decides self-referral by host alone, ignoring case, scheme, port and path', () => { + expect(DerivedAttribution.from({}, 'https://Example.test/products/nad/', null, 'example.test').sourceCategory).toBeNull(); + }); + + it('keeps an external or unparseable referrer as a source', () => { + const external = DerivedAttribution.from({}, 'https://www.google.com/', null, 'example.test'); + expect(external.sourceCategory).toBe('referral'); + expect(external.sourceDetail).toBe('https://www.google.com/'); + + expect(DerivedAttribution.from({}, 'not-a-url', null, 'example.test').sourceCategory).toBe('referral'); + }); + + it('keeps every referrer as a source when no self host is known', () => { + expect(DerivedAttribution.from({}, 'http://127.0.0.1:8123/', null, null).sourceCategory).toBe('referral'); + }); +}); diff --git a/test/journey/session-resolver.spec.ts b/test/journey/session-resolver.spec.ts new file mode 100644 index 0000000..4dbdd17 --- /dev/null +++ b/test/journey/session-resolver.spec.ts @@ -0,0 +1,437 @@ +import { QueryParamCipher } from '@astermd-hq/sdk'; +import type { Request } from 'express'; +import { SessionGateway, SessionViewResult } from '../../src/emr/session-gateway'; +import { JourneyState } from '../../src/journey/journey-state'; +import { JourneyStore } from '../../src/journey/journey-store'; +import { SessionOptions } from '../../src/journey/session-options'; +import { SessionResolver } from '../../src/journey/session-resolver'; +import { EventRepository } from '../../src/repository/event-repository'; +import { SessionRepository, SessionRow } from '../../src/repository/session-repository'; +import { OperatorLog } from '../../src/support/operator-log'; + +/** Covers the `?amd_session=` resume link. */ + +const RESUMED = '11111111-1111-4111-8111-111111111111'; +const COOKIE = '22222222-2222-4222-8222-222222222222'; +const MINTED = '33333333-3333-4333-8333-333333333333'; +const TRACKING_KEY = '00112233445566778899aabbccddeeff'; + +class InMemorySessions { + rows = new Map(); + + async find(uuid: string): Promise { + return this.rows.get(uuid) ?? null; + } + + async insert( + uuid: string, + journeyState: SessionRow['journeyState'], + attribution: SessionRow['attribution'] = null, + opportunityId: string | null = null, + ): Promise { + const updatedAt = new Date().toISOString(); + if (!this.rows.has(uuid)) { + this.rows.set(uuid, { journeyState, attribution, opportunityId, updatedAt }); + } + return this.rows.get(uuid)!.updatedAt; + } +} + +class RecordingEvents { + appended: Array<{ uuid: string; name: string; payload: Record }> = []; + + async append(uuid: string, name: string, payload: Record = {}): Promise { + this.appended.push({ uuid, name, payload }); + } + + names(): string[] { + return this.appended.map((e) => e.name); + } +} + +class StubGateway implements SessionGateway { + views: string[] = []; + creates = 0; + + constructor( + private readonly known: Record = {}, + private readonly mintUuid: string | null = MINTED, + private readonly failingViews: string[] = [], + ) {} + + async create(): Promise { + this.creates += 1; + return this.mintUuid; + } + + async view(uuid: string): Promise { + this.views.push(uuid); + if (this.failingViews.includes(uuid)) return null; + return this.known[uuid] ?? { exists: false, opportunityId: null, events: [] }; + } +} + +function request(query: Record, cookies: Record = {}): Request { + return { query, cookies, path: '/', ip: '127.0.0.1', get: () => undefined } as unknown as Request; +} + +function setup(known: Record = {}, mintUuid: string | null = MINTED, failingViews: string[] = []) { + const sessions = new InMemorySessions(); + const events = new RecordingEvents(); + const gateway = new StubGateway(known, mintUuid, failingViews); + const log = { info: jest.fn(), warning: jest.fn(), error: jest.fn() } as unknown as OperatorLog; + const options = { + cookieName: 'amd_session', + resumeParam: 'amd_session', + payloadParam: '_amd', + trackingKeys: [TRACKING_KEY], + } as SessionOptions; + const resolver = new SessionResolver( + gateway, + sessions as unknown as SessionRepository, + events as unknown as EventRepository, + log, + options, + ); + const journey = () => new JourneyStore(sessions as unknown as SessionRepository); + + return { sessions, events, gateway, log, resolver, journey }; +} + +describe('SessionResolver resume link', () => { + it('restores a stored journey, including intake answers, and re-issues the cookie', async () => { + const { sessions, events, gateway, resolver, journey } = setup(); + sessions.rows.set(RESUMED, { + journeyState: { reconciled: true, readModelShape: SessionResolver.READ_MODEL_SHAPE, answers: { tf_1: { weight: '80' } } }, + attribution: null, + opportunityId: null, + updatedAt: '2026-01-01T00:00:00.000Z', + }); + const store = journey(); + + const resolution = await resolver.resolve(request({ amd_session: RESUMED }), store, true); + + expect(resolution.sessionUuid).toBe(RESUMED); + expect(resolution.issueCookie).toBe(true); + expect(store.currentState()?.answers).toEqual({ tf_1: { weight: '80' } }); + expect(gateway.views).toEqual([]); // already reconciled: no EMR read + expect(gateway.creates).toBe(0); + expect(events.names()).toEqual(['session_adopted', 'access.journey_resumed']); + expect(events.appended[1].payload).toEqual({ actor: 'resume_link', reason: 'journey_resumed', restored_intake: true, teleforms: 1 }); + }); + + it('beats a cookie for a different session', async () => { + const { resolver, journey } = setup({ [RESUMED]: { exists: true, opportunityId: 'opp_9', events: ['cart_initiated'] } }); + const store = journey(); + + const resolution = await resolver.resolve(request({ amd_session: RESUMED }, { amd_session: COOKIE }), store, true); + + expect(resolution.sessionUuid).toBe(RESUMED); + expect(resolution.issueCookie).toBe(true); + const state = store.currentState()!; + expect(state.opportunityId).toBe('opp_9'); + expect(state.emrEvents).toEqual(['cart_initiated']); + expect(state.reconciled).toBe(true); + expect(state.readModelShape).toBe(SessionResolver.READ_MODEL_SHAPE); + }); + + it('adopts a session this storefront has never stored when the EMR knows it', async () => { + const { sessions, resolver, journey } = setup({ [RESUMED]: { exists: true, opportunityId: null, events: [] } }); + + const resolution = await resolver.resolve(request({ amd_session: RESUMED }), journey(), false); + + expect(resolution.sessionUuid).toBe(RESUMED); + expect(sessions.rows.has(RESUMED)).toBe(true); + }); + + it('ignores a session the EMR does not know, records the rejection, and mints as usual', async () => { + const { sessions, events, resolver, journey } = setup(); + + const resolution = await resolver.resolve(request({ amd_session: RESUMED }), journey(), true); + + expect(resolution.sessionUuid).toBe(MINTED); + expect(sessions.rows.has(RESUMED)).toBe(false); + expect(events.appended).toEqual([ + { uuid: MINTED, name: 'session_created', payload: { source_category: null } }, + { uuid: MINTED, name: 'session_resume_rejected', payload: { rejected: RESUMED } }, + ]); + }); + + it('falls back to the cookie when the link is rejected', async () => { + // The EMR knows the cookie's session, so the fallback keeps it rather than re-minting. + const { events, resolver, journey } = setup({ [COOKIE]: { exists: true, opportunityId: null, events: [] } }); + + const resolution = await resolver.resolve(request({ amd_session: RESUMED }, { amd_session: COOKIE }), journey(), true); + + expect(resolution.sessionUuid).toBe(COOKIE); + expect(resolution.issueCookie).toBe(false); + expect(events.appended).toEqual([]); + }); + + it('stores a freshly minted session, so a later resume link finds its journey', async () => { + const { sessions, events, resolver, journey } = setup({ [MINTED]: { exists: true, opportunityId: null, events: [] } }); + + const resolution = await resolver.resolve(request({}), journey(), true); + + expect(resolution.sessionUuid).toBe(MINTED); + expect(sessions.rows.get(MINTED)?.journeyState).toMatchObject({ reconciled: true }); + expect(events.appended).toEqual([{ uuid: MINTED, name: 'session_created', payload: { source_category: null } }]); + + sessions.rows.get(MINTED)!.journeyState.answers = { tf_1: { weight: '80' } }; + const store = journey(); + const resumed = await resolver.resolve( + request({ amd_session: MINTED }), + store, + true, + ); + + expect(resumed.sessionUuid).toBe(MINTED); + expect(events.names()).toContain('session_adopted'); + expect(store.currentState()?.answersFor('tf_1')).toEqual({ weight: '80' }); + }); + + it('records the source category of a freshly minted session', async () => { + const { events, resolver, journey } = setup(); + + await resolver.resolve(request({ utm_source: 'facebook', utm_medium: 'paid' }), journey(), true); + + expect(events.appended).toEqual([{ uuid: MINTED, name: 'session_created', payload: { source_category: 'social_media' } }]); + }); + + it('lets an encrypted _amd payload beat plain parameters and never stores the token', async () => { + const { log, resolver, journey } = setup(); + const token = QueryParamCipher.encrypt({ aff_id: 'encrypted' }, TRACKING_KEY); + const store = journey(); + + await resolver.resolve(request({ aff_id: 'plain', _amd: token }), store, true); + + const attribution = store.currentState()?.attribution; + expect(attribution?.get('affiliate_id')).toBe('encrypted'); + expect(attribution?.derived.sourceCategory).toBe('affiliate'); + expect(JSON.stringify(attribution?.toArray())).not.toContain(token); + expect(log.warning).not.toHaveBeenCalled(); + }); + + it('falls back to plain parameters and logs when _amd cannot be decrypted', async () => { + const { log, resolver, journey } = setup(); + const store = journey(); + + await resolver.resolve(request({ aff_id: 'plain', _amd: 'tampered-garbage' }), store, true); + + expect(store.currentState()?.attribution?.get('affiliate_id')).toBe('plain'); + expect(log.warning).toHaveBeenCalledWith('amd_decrypt_failed', { keys_tried: 1 }); + }); + + it.each([['../etc/passwd'], ['short'], [[RESUMED, RESUMED]]])('silently ignores a malformed value %p', async (value) => { + const { events, gateway, resolver, journey } = setup(); + + const resolution = await resolver.resolve(request({ amd_session: value }), journey(), true); + + expect(resolution.sessionUuid).toBe(MINTED); + expect(gateway.views).toEqual([]); + expect(events.names()).toEqual(['session_created']); + }); +}); + +describe('SessionResolver remint', () => { + const STALE = '44444444-4444-4444-8444-444444444444'; + const KNOWN = '55555555-5555-4555-8555-555555555555'; + const ATTRIBUTION = { params: { affiliate_id: '4412' }, referrer: null, derived: { sourceCategory: 'affiliate', sourceDetail: '4412', deviceType: null, browser: null, os: null } }; + const CART = { lines: [{ slug: 'semaglutide', quantity: 1 }], territory: 'CA' } as never; + const ANSWERS = { 'tf-weight-loss': { weight: '80' } }; + const BUYER = { email: 'buyer@example.test', first_name: 'Ada' }; + const PROMOTION = { code: 'SPRING', discount_cents: 500 }; + const CONSENTS = [{ key: 'telehealth', granted: true, copy_version: 'v1', copy_shown: 'I agree', at: '2026-08-25T10:00:00Z' }]; + const VERDICT = { status: 'verified', at: '2026-08-25T09:59:00Z', basis: 'idology', check: 'id', reference: 'ref-1' } as never; + const RECEIPT = { order: '34788' }; + + /** + * Every durable field, each with a value distinguishable from its default — so a field that was + * dropped cannot pass for one that was carried. + */ + const EVERY_DURABLE_FIELD = { + opportunityId: 'opp-1', + attribution: ATTRIBUTION, + reconciled: false, + readModelShape: SessionResolver.READ_MODEL_SHAPE, + sessionRetired: true, + cart: CART, + cartMirrored: true, + furthestStep: 'receipt', + formStatus: { 'tf-weight-loss': 'completed' }, + disqualifiedRule: 'bmi_low_hard_stop_notice', + disqualifiedTeleform: 'tf-weight-loss', + verification: VERDICT, + placedOrders: ['34788'], + paymentSummary: { method: 'card', last4: '4242' }, + identityDocument: 'uploads/id-front.jpg', + answers: ANSWERS, + emrEvents: ['intake_initiated'], + buyer: BUYER, + promotion: PROMOTION, + promotionQuotedAgainst: 'digest-1', + acceptedBumps: ['anti-nausea-kit'], + consents: CONSENTS, + pendingPayment: { reference: 'pi_1', idempotency_key: 'key-1', claimed_at: '2026-08-25T10:00:00Z' }, + reusableCredentialData: { kind: 'stripe', handle: { customer: 'cus_1' } }, + upsellQueue: ['sleep-support'], + upsellCursor: 1, + upsellOutcomes: { 'sleep-support': 'declined' }, + upsellQuotes: { 'sleep-support': 1900 }, + receipt: RECEIPT, + completedAt: '2026-08-25T10:01:00+00:00', + }; + + function seedStale(sessions: InMemorySessions, attribution: unknown = ATTRIBUTION): void { + sessions.rows.set(STALE, { + journeyState: EVERY_DURABLE_FIELD as never, + attribution: attribution as never, + opportunityId: 'opp-1', + updatedAt: '2026-01-01T00:00:00.000Z', + }); + } + + it('discards a cookie the EMR does not recognise and re-mints, carrying the journey', async () => { + const { sessions, events, resolver, journey } = setup(); + seedStale(sessions); + const store = journey(); + + const resolution = await resolver.resolve(request({}, { amd_session: STALE }), store, true); + + expect(resolution.sessionUuid).toBe(MINTED); + expect(resolution.issueCookie).toBe(true); + expect(store.sessionUuid()).toBe(MINTED); + const row = sessions.rows.get(MINTED)!; + expect(row.opportunityId).toBe('opp-1'); + expect((row.attribution as { params: Record }).params.affiliate_id).toBe('4412'); + expect(events.appended).toContainEqual({ uuid: MINTED, name: 'session_reminted', payload: { replaced: STALE } }); + }); + + it('makes a deliberate decision for every durable field', async () => { + const { sessions, resolver, journey } = setup(); + seedStale(sessions); + + // The seed is the enumeration's other half: it must name every field. + expect(Object.keys(EVERY_DURABLE_FIELD).sort()).toEqual(Object.keys(new JourneyState().toArray()).sort()); + + await resolver.resolve(request({}, { amd_session: STALE }), journey(), true); + + expect(sessions.rows.get(MINTED)!.journeyState).toEqual({ + // Carried: facts about this buyer. + opportunityId: 'opp-1', + attribution: ATTRIBUTION, + cart: CART, + furthestStep: 'receipt', + answers: ANSWERS, + formStatus: { 'tf-weight-loss': 'completed' }, + disqualifiedRule: 'bmi_low_hard_stop_notice', + disqualifiedTeleform: 'tf-weight-loss', + verification: VERDICT, + buyer: BUYER, + promotion: PROMOTION, + acceptedBumps: ['anti-nausea-kit'], + consents: CONSENTS, + placedOrders: ['34788'], + upsellOutcomes: { 'sleep-support': 'declined' }, + receipt: RECEIPT, + completedAt: '2026-08-25T10:01:00+00:00', + sessionRetired: true, + // Set, not carried: the mint is proof the EMR knows this one. + reconciled: true, + // Not carried: the old session's relationship with something else. + readModelShape: null, + emrEvents: [], + cartMirrored: false, + promotionQuotedAgainst: null, + pendingPayment: null, + reusableCredentialData: null, + identityDocument: null, + paymentSummary: null, + upsellQueue: [], + upsellCursor: 0, + upsellQuotes: {}, + }); + }); + + it('cannot remint on a request that may not create, and leaves the journey unreconciled', async () => { + const { sessions, gateway, resolver, journey } = setup(); + seedStale(sessions); + const store = journey(); + + const resolution = await resolver.resolve(request({}, { amd_session: STALE }), store, false); + + expect(resolution.sessionUuid).toBe(STALE); + expect(gateway.creates).toBe(0); + expect(store.currentState()?.reconciled).toBe(false); + }); + + it('leaves the visitor on the old session after a failed mint, and keeps the first touch', async () => { + const { sessions, log, resolver, journey } = setup({}, null); + seedStale(sessions, null); + const store = journey(); + + const resolution = await resolver.resolve(request({ aff_id: '4412' }, { amd_session: STALE }), store, true); + + expect(resolution.sessionUuid).toBeNull(); + expect(sessions.rows.size).toBe(1); + expect(store.sessionUuid()).toBe(STALE); + expect(store.currentState()?.reconciled).toBe(false); + expect(store.currentState()?.attribution?.get('affiliate_id')).toBe('4412'); + expect(log.warning).toHaveBeenCalledWith('session.remint_failed', { path: '/' }); + }); + + it('treats a mint that returns the rejected identifier as a failure', async () => { + const { sessions, events, log, resolver, journey } = setup({}, STALE); + seedStale(sessions); + const store = journey(); + + const resolution = await resolver.resolve(request({}, { amd_session: STALE }), store, true); + + expect(resolution.sessionUuid).toBeNull(); + expect(resolution.issueCookie).toBe(false); + expect(events.names()).not.toContain('session_reminted'); + expect(store.currentState()?.reconciled).toBe(false); + expect(log.warning).toHaveBeenCalledWith('session.remint_failed', { path: '/' }); + }); + + it('leaves a session the EMR does recognise untouched, and reconciles it', async () => { + const { gateway, resolver, journey } = setup({ [KNOWN]: { exists: true, opportunityId: 'opp-5', events: ['visit_page'] } }); + const store = journey(); + + const resolution = await resolver.resolve(request({}, { amd_session: KNOWN }), store, true); + + expect(resolution.sessionUuid).toBe(KNOWN); + expect(resolution.issueCookie).toBe(false); + expect(gateway.creates).toBe(0); + expect(store.currentState()?.reconciled).toBe(true); + expect(store.currentState()?.readModelShape).toBe(SessionResolver.READ_MODEL_SHAPE); + expect(store.currentState()?.opportunityId).toBe('opp-5'); + }); + + it('does not remint on a failed read', async () => { + const { gateway, resolver, journey } = setup({}, MINTED, [KNOWN]); + const store = journey(); + + const resolution = await resolver.resolve(request({}, { amd_session: KNOWN }), store, true); + + expect(resolution.sessionUuid).toBe(KNOWN); + expect(gateway.creates).toBe(0); + expect(gateway.views).toEqual([KNOWN]); + expect(store.currentState()?.reconciled).toBe(false); + }); + + it('does not read the EMR again for a journey already reconciled under the current read model', async () => { + const { sessions, gateway, resolver, journey } = setup(); + sessions.rows.set(KNOWN, { + journeyState: { reconciled: true, readModelShape: SessionResolver.READ_MODEL_SHAPE }, + attribution: null, + opportunityId: null, + updatedAt: '2026-01-01T00:00:00.000Z', + }); + + await resolver.resolve(request({}, { amd_session: KNOWN }), journey(), true); + + expect(gateway.views).toEqual([]); + expect(gateway.creates).toBe(0); + }); +}); From 17fb0ced569d969e4ae758c0401f93747d1fcce5 Mon Sep 17 00:00:00 2001 From: Sabur Ali Date: Tue, 17 Nov 2026 11:33:45 +0530 Subject: [PATCH 2/8] Remove STATUS.md --- README.md | 1 - STATUS.md | 1254 ------------------- test/forms/intake-templates.spec.ts | 5 +- test/routes/checkout-to-receipt.e2e-spec.ts | 2 +- test/routes/intake-verify.e2e-spec.ts | 2 +- test/support/fake-teleform-gateway.ts | 4 +- test/support/no-network.ts | 4 +- 7 files changed, 8 insertions(+), 1264 deletions(-) delete mode 100644 STATUS.md diff --git a/README.md b/README.md index f14d1d2..ae8ca53 100644 --- a/README.md +++ b/README.md @@ -203,7 +203,6 @@ docs/ architecture, operations, middleware, journey notes | | | |---|---| | [`docs/STACK.md`](docs/STACK.md) | the stack, request lifecycle, container and the reasoning behind each choice | -| [`STATUS.md`](STATUS.md) | development log: build phases, what is real vs. Null-backed, known gaps | | [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | how the funnel, journey store, catalog and gateways fit together | | [`docs/MIDDLEWARE.md`](docs/MIDDLEWARE.md) | the nine-slot middleware pipeline, slot by slot | | [`docs/JOURNEY.md`](docs/JOURNEY.md) | one customer journey traced end to end | diff --git a/STATUS.md b/STATUS.md deleted file mode 100644 index 9be975d..0000000 --- a/STATUS.md +++ /dev/null @@ -1,1254 +0,0 @@ -# Build status - -Development log for the storefront: what each build phase delivered, what is real vs. Null-backed, -known gaps, and the real bugs found along the way. [`docs/STACK.md`](docs/STACK.md) describes the -stack; this file records how it got there. Entries are dated notes kept as written at the time, so -some describe intermediate states the code has since moved past. - -Last updated: 2026-09-24. - ---- - -## Phase status - -| Phase | Scope | Status | -| --- | --- | --- | -| 0 | Project init & toolchain | ✅ Done | -| 1 | Skeleton, bootstrap, CoreModule, tokens, error boundaries | ✅ Done | -| 2 | 9-slot middleware pipeline | ✅ Done | -| 3 | Persistence (Prisma + SQLite) | ✅ Done | -| 4 | Domain: Cart, CartRules, FunnelRouter, StepPreconditions | ✅ Done | -| 5 | Catalog + home/product/treatments/cart routes + templates | ✅ Done | -| — | **Real EMR integration** (Session/Cart/Verification/Teleform/Intake/Lead/Identity) | ✅ Done — not in the original 11-phase plan | -| 6 | Forms/intake engine + verify step | ✅ Done | -| 7 | Checkout (order-of-operations, idempotency, payment) | ✅ Done | -| 8 | Upsell + completion + receipt + teardown | ✅ Done | -| 9 | SEO + legal pages + error-page X-Robots-Tag correctness | ✅ **Done**, including the asset pipeline (deferred earlier in this session, now built — see note below) | -| 10 | Remaining console commands + observability | ✅ **Done** — see note below | -| — | **Real Vrio + CheckoutChamp payment adapters** | ✅ Done — not in the original 11-phase plan, user-directed reversal of the Null-payment-only decision | -| 11 | Test suite consolidation | 🟡 In progress — see note below | - -All of Phases 0–10 are covered by automated tests and were also manually smoke-tested (curl -click-through, or — for the intake templates, which the real EMR channel can't currently exercise -end-to-end — a dedicated render test driving every field type through the real view-model code; for -Phase 10, every console command run once for real via `node dist/src/console/main.js `). - ---- - -## Stack, as actually built (departs from the first stack draft) - -- **Prisma**, not Kysely — on **`7.10.0`** (the real latest *stable* release; npm's `latest` - dist-tag resolves to an unstable `8.0.0-rc.15` — see `CLAUDE.local.md` for the standing rule - this taught). Prisma 7 removed `schema.prisma`'s inline `datasource.url` entirely: the CLI reads - its connection string from `prisma.config.ts` now, and the app's own `PrismaClient` takes a - driver adapter (`@prisma/adapter-better-sqlite3`) instead of reading `DATABASE_URL` on its own — - see `prisma.config.ts` and `src/database/connection-factory.ts`'s doc comments. Re-verified with - a real runtime boot + DB write, not just `npm test`. Prisma 7+ also ships an AI-agent safety - guard on destructive CLI commands (`db push --accept-data-loss`) — see `CLAUDE.local.md`. -- **eslint/typescript-eslint/prettier bumped to latest stable** (`eslint@10.11.0`, - `typescript-eslint@8.70.1`, `prettier@3.9.8`) — no config breakage, `npm run lint` stayed clean. -- **EJS**, not Nunjucks — no template inheritance; every page includes its own head/foot partials. -- **class-validator DTOs** on every mutating route with a *static* body shape — additive to the - domain-layer validators. The intake save/submit/capture endpoints deliberately skip a DTO - class: their body shape is the teleform's own field set, which is data, not code, so no fixed - DTO can describe it — they take `@Body() body: Record` directly (Nest's - `ValidationPipe` only validates class-typed bodies, so this is a real bypass, not an oversight). -- **Node `>=22`** (not 24 — an earlier `>=24` pin in `package.json`/`.nvmrc` was a mistake, fixed). - -## Real EMR integration — what's actually live - -Reverses the original plan's "every EMR-family port stays Null-bound for the whole effort" -decision, after the real, official `@astermd-hq/sdk` npm package was found and real dev-sandbox -credentials were made available (`storefront-lamp/.env`). - -**Real, backed by `@astermd-hq/sdk`, config-gated against Null** (all on -`config.app.session.analytics`, except where noted): -- `SESSION_GATEWAY` → `EmrSessionGateway` (mints/looks up analytics sessions) -- `CART_GATEWAY` → `EmrCartGateway` (mirrors cart contents) -- `EMR_VERIFICATION_GATEWAY` → `EmrVerificationGateway` (email/address checks, each gated on its own - `config.app.features.emrVerifyEmail`/`emrVerifyAddress`; `EMR_VERIFICATION` still sets both) -- `ADDRESS_AUTOFILL` → `EmrAddressAutofill` (checkout address suggestions from the EMR when there is no - Google key; Null only under `NODE_ENV=test`) -- `INTAKE_UPLOADS` → `EmrIntakeUploads` (file-upload answers, whole or multipart; on `session.analytics`) -- `TELEFORM_GATEWAY` → `EmrTeleformGateway` (teleform metadata + definition fetch) -- `INTAKE_GATEWAY` → `EmrIntakeGateway`, wrapped in `RecordingIntakeGateway` (always writes a - local `events` audit row regardless of which gateway is inside) -- `LEAD_GATEWAY` → `EmrLeadGateway` (opportunity create/update) -- `IDENTITY_GATEWAY` → `EmrIdentityGateway` (KYC checks, gated on `config.verification.enabled` - — separately from the other six, which all key off `session.analytics`) - -`NODE_ENV=test` forces every one of these flags false, so the test suite never reaches the -network — re-verified after every addition, not assumed. - -**Still Null-only**: `PAYMENT_ADAPTER` (wired for real via `AdapterRegistry` in Phase 7, but zero -adapters are ever registered by design — see docs/STACK.md) and `CHECKOUT_EVENT_REPORTER` (Phase 7 built -its port + Null implementation only, since it's structurally unreachable while no real payment -adapter exists to place an order). - -**Proven end-to-end against the real dev-sandbox EMR** (`health.api.dev.besimplified.net`), twice: -1. A bare `curl` (no cookie) minted a real analytics session, confirmed on record via a direct - SDK call (`visit_page` event, geo-resolved IP). -2. A full cart-add → funnel-routing → intake-controller → `EmrTeleformGateway` round-trip: adding - an Rx product with a real variant selected correctly routed to `/intake/medical/`, correctly - called the real EMR for the teleform (which 404s, since this example catalog's teleform ids - don't exist in the real channel), and correctly rendered the `form-unavailable` degrade page — - the exact designed failure path, observed for real. - -**Token caching**: `@astermd-hq/sdk`'s own `FileTokenStore`, at `storage/cache/emr-token.json` — -the same path and package storefront-lamp's PHP side already uses. - ---- - -## Phase 6 — Forms/intake engine + verify step (done) - -The whole Forms domain, unit-tested (34 new tests across `Bmi`/`DateAnswer`/`RuleEvaluator`, plus -a full template-render test): `Definition`/`Field`/`Page`, `AnswerSet`/`AnswerEncoder`/ -`AnswerValidator`, `RuleEvaluator` (ported with extra care as the single highest-risk file — -inverted condition defaults, per-join combinator indexing, phone normalization, membership -semantics; every test passed on the first run), `Disqualification`/`DisqualificationOutcome`/ -`TerminationRule`, `TeleformSource`/`DefinitionCache`, the `TeleformGateway`/`IntakeGateway`/ -`LeadGateway`/`IdentityGateway` families (`Emr*`/`Null*` pairs, config-gated), `RecordMapper`, -`LeadWriter`, `IntakeSession` (the orchestrator, exact persist-before-validate ordering intact), -`VerificationStep` (identity assembly via `Prefill` read backwards through the teleform's -`db_fields` map), `IntakeController`/`NotEligibleController`/`VerifyController`, all wired into -`AppModule`. - -**Templates — all 18 field-type EJS partials built** (`field-text/boolean/choice-single/ -choice-multi/date/number/dropdown/bmi/hidden/heading/form-header/paragraph/divider/alert/image/ -form-progress/button/unsupported`) plus the `field.ejs` dispatcher, `partials/stepper.ejs`, and -both questionnaire pages (`pages/intake/form.ejs` for the server-rendered mode, `form-js-engine.ejs` -for the hosted-engine mode). Verified by a dedicated render test -(`test/forms/intake-templates.spec.ts`) that builds one definition covering every field type, -runs it through the real `FieldViewModel`/`RuleEvaluator` code (not hand-typed template locals), -and renders both page templates against the result — since this example catalog's teleform ids -don't exist in the real EMR channel, the live route can never reach a populated form to prove this -any other way. - -**Client-side multi-page stepping, wired up post-Phase 10.** `public/js/intake.js` (copied verbatim -from storefront-lamp during the asset pipeline work) expects a specific `data-intake-*` attribute -contract that the storefront's `field.ejs`/`form.ejs`/`stepper.ejs` didn't actually emit — different -attribute names entirely (`data-field-name` vs. the script's `data-intake-field`), an inverted -`cols` → `sm:col-span-*` mapping, a flex-column page layout instead of the `grid-cols-1 -sm:grid-cols-2` the script's markup expects, and a stepper using different CSS classes than the -ones `intake.js`'s own `updateStepper()` re-applies as the visitor advances. Fixed by porting -`field.twig`/`form.twig`/`stepper.twig`'s exact attribute contract from storefront-lamp field-for- -field: `field.ejs` now emits `data-intake-field`/`data-intake-type`/`data-intake-required`/ -`data-intake-hidden`/`data-intake-conditions` with the correct `cols` logic; a new shared -`field-error.ejs` partial (`data-intake-error`, always rendered so the script has a stable node to -write into) replaces the inline error markup duplicated across 7 field-type partials; -`field-bmi.ejs` gained `data-intake-bmi`/`-target`/`-result`/`-score`; `form.ejs` gained -`data-intake-form`/`data-save-url`/`data-submit-url`/`data-capture-url`/`data-intake-rules`/ -`data-intake-blocked`, the correct 2-column page grid, the eligibility interstitial, and one shared -Back/Continue nav (matching the script's own page-count-based submit-vs-advance logic, replacing -the previous per-page "Submit on the last page" markup that the script never actually drove); -`stepper.ejs` gained `data-funnel-stepper`/`data-stepper-*` and the exact done/active/upcoming class -strings `intake.js`'s `updateStepper()` hardcodes. **Verified with a real interactive test**, not -just visual inspection: a rendered two-page fixture, driven through a real browser via Playwright, -correctly advances from page 1 to page 2 on a genuine click — `data-intake-page-input`'s value -changes from `0` to `1`, the stepper re-styles step 1 as done (checkmark connector) and step 2 as -active, and the second page's own fields render. `test/forms/intake-templates.spec.ts` updated to -pass `definition` (present in the real controller's payload, missing from the test's hand-built -locals) and to match the ported copy's exact wording. - ---- - -## Known gaps - -None currently flagged. - -## Bugs found and fixed this session - -- **`cookie-parser` was never installed.** `SessionResolver`'s "cookie-present → trust it" branch - reads `request.cookies`, which no middleware populated. Completely invisible under - `NullSessionGateway` (no gateway ever returned a real UUID, so no cookie was ever set to fail to - recognize) — the instant `EmrSessionGateway` went live, **every request re-minted a brand-new - EMR session**, discovered via a real multi-request `curl` session. Fixed: installed - `cookie-parser`, registered as the first entry in `AppModule`'s pinned-middleware chain. -- **`config/app.ts`'s `session.analytics` default was wrong** (defaulted `false` via an invented - env knob; PHP has none and defaults `true` outside `APP_ENV=test`). Fixed to match exactly. -- **`AttributionMiddleware` had no route-exists guard.** The PHP original skips minting a session - for a request that doesn't match any real route (a bot scan, a stray asset request), via an - injected closure. The storefront never had an equivalent — invisible under Null-only, a real cost - once `EmrSessionGateway` went live (a GET to any unmatched path minted a real, billable EMR - session before `NotFoundController` got a say). Fixed via a new `RouteExistsChecker` - (`src/support/route-exists-checker.ts`) that introspects Express 5's own router - (`app.router.stack`, `layer.matchers`) to test-match a path against every *real* registered - route, excluding the catch-all fallback. Fails open on any structural surprise. Verified live: a - bot-scan-shaped path no longer sets `amd_session`, while static and dynamic real routes still do. -- **Prisma 6→7**: `latest` npm dist-tag is an unstable `8.0.0-rc.15`; the real latest stable is - `7.10.0`, itself a breaking major bump (inline `datasource.url` removed — see above). Migrated - cleanly; all tests + a real runtime boot re-verified afterward. - ---- - -## Phase 7 — Checkout (done) - -Full order-of-operations port of `core/Checkout/CheckoutService.php`, built from literal verbatim -source (BuyerValidator, CheckoutService, CheckoutController, the 3 repositories, Consents, -IdempotencyKey, CheckoutAttempt, PostChargeGuard, SettlementPolicy, OrderBumps, CheckoutResult/ -CheckoutViewModel, ConsentDefinition/ConsentRecord — 17 files read directly rather than from a -research-agent summary, per this project's "grep before building on a summary" rule). - -- **Domain/value objects** (`src/checkout/`): `totals`, `promotion`, `buyer-details`, `card-number`, - `consent-definition`, `consent-record`, `consents`, `idempotency-key`, `checkout-attempt`, - `post-charge-guard`, `settlement-policy`, `order-bump(s)`, `checkout-result`, - `checkout-view-model`, `buyer-validator`, `prefill`, `checkout-event-reporter` + - `null-checkout-event-reporter`, `order-recorder` + `null-order-recorder` + - `database-order-recorder`. -- **`checkout.service.ts`** — the full `submit()`/`view()`/`toggleBump()`/`applyPromotion()`/ - `removePromotion()`/`choosePlan()` orchestrator, in the spec's exact order: rate-limit before - anything costs money → re-price a stored promotion → validate buyer+consents together → - re-run the geo gate → store the buyer *before* the provider call → claim the idempotency key → - assemble one `OrderEnvelope` → mark the attempt sent → call the adapter → run - `PostChargeGuard`-wrapped writes only after that. Every constant/copy string ported verbatim. -- **Repositories** (Prisma-backed): `checkout-attempt-repository.ts` (claim/renewClaim/markSent/ - recordOutcome/release — the exact conditional-update ownership-token semantics that prevent the - PHP original's documented double-charge bug), `rate-limit-repository.ts` (fixed-window hit()), - `order-repository.ts` (transactional insert of orders/order_lines/order_consents + - findByReference). `prisma/schema.prisma`'s `Order` model gained `settlement`/`userAgent` columns - (migration `20260923093528_checkout_settlement_user_agent`). -- **`src/support/`**: `request-context.ts` (CDN IP header precedence), `database-rate-limiter.ts` - (fail-open fixed-window limiter over `RateLimitRepository`). -- **`src/upsell/`**: `upsell.ts` + `upsells.ts` — `queueFor()` (what `CheckoutService.placed()` - needs at checkout success) is fully ported; `resolve()` exists for Phase 8's page but is unused - until then. `config/upsells.ts` ships empty, matching the PHP original. -- **`PAYMENT_ADAPTER` wired for real**: `CoreModule` now binds it through `AdapterRegistry.for(config.payment.adapter)` — zero adapters ever registered, so every resolve falls through to - `NullPaymentAdapter`, exactly per plan. `ORDER_RECORDER` binds to `DatabaseOrderRecorder` - (real, DB-backed — orders must be recorded for receipt/reconciliation data to exist); - `CHECKOUT_EVENT_REPORTER` stays Null-only (structurally unreachable while `PaymentAdapter` never - places a real order — becomes real alongside a real payment adapter, not before one). -- **Routes**: `CheckoutController`/`CheckoutModule` (`GET`/`POST /checkout/`, - `POST /checkout/bump|promo|promo/remove|plan`), all 4 sub-action DTOs plus `SubmitCheckoutDto`. -- **`views/pages/checkout.ejs`** — styled per `docs/mockup/mockup/intake/checkout.html` (two-column - contact/delivery/payment form beside a sticky order summary); the mockup's shipping-method/ - express-checkout/PayPal/Afterpay/upsell-add-on sections are omitted as presentational content - with no backing service in the storefront (declared gaps), not wired to nothing. -- **`JourneyState` grew 7 fields**: `promotion`, `promotionQuotedAgainst`, `acceptedBumps`, - `consents`, `reusableCredential`, `upsellQueue`, `upsellCursor`, `upsellOutcomes` + methods - `storeBuyer()`/`storeReusableCredential()`/`wipePaymentCredential()`. - -**Bug found and fixed this session**: every `@Injectable()` class with an optional trailing -constructor parameter with no type Nest can resolve (`DatabaseRateLimiter`'s and -`CheckoutService`'s injected `clock?: () => string` test seam, `Consents`'s injected clock) failed -`AppModule` bootstrap with "Nest can't resolve dependencies… argument Function" — Nest tries to -resolve *every* constructor parameter, optional or not, unless marked `@Optional()`. Fixed by adding -`@Optional()` to all three. **A second bug, found via a real curl submit**: the checkout DTOs' -buyer-contact-detail fields (`first_name`, `email`, ...) had no `class-validator` decorators at -all — the global `ValidationPipe`'s `whitelist: true` silently deletes any property with zero -validation decorators before the controller ever sees it, which emptied every field on a real -submit. Fixed by decorating every field `@IsOptional() @IsString()` (a new shared -`BuyerContactFieldsDto` base class for the 3 sub-action DTOs that repeat the same 8 fields). - -**Proven against a real running server, not just unit-tested**: a real multi-request `curl` session -— add an OTC product to cart, submit checkout with full buyer details, a test card, and consent — -correctly failed buyer validation when fields were empty (caught the `whitelist` bug), and once -fixed, correctly reached the priced-line-unmapped decline (`[13.19]`): the port's example catalog -has no product with a real provider `offer_id`/`product_id` mapping (a documented Phase 5/6 gap), -so every priced line is honestly declined with "One of the items in your order is not available for -purchase right now" *before* ever reaching `NullPaymentAdapter` — and a resubmit of the identical -form got the same fresh decline rather than an in-flight/duplicate answer, proving -`releaseQuietly()` correctly gives the idempotency key back on this decline path. - ---- - -## Phase 8 — Upsell + completion + receipt + teardown (done) - -Full port of `core/Upsell/*` and `core/Completion/*`, built from literal verbatim source -(`Upsell`, `UpsellQueue`, `UpsellResult`, `UpsellService`, `UpsellViewModel`, `Completion`, -`Receipt`, `ReceiptViewModel`, `UpsellController`, `ReceiptController` — 10 files read directly). - -- **`JourneyState` grew 4 more fields** (`upsellQuotes`, `receipt`, `completedAt`) plus 5 - `UPSELL_*` outcome constants, and `upsellOutcomes` changed shape from Phase 7's placeholder - array to the real `Record` map the PHP original always used. The Phase 7 - `reusableCredential` field was renamed to `reusableCredentialData` with a new - `reusableCredential()` *method* added alongside it, reconstructing the real `PaymentCredential` - via `fromStorable()` — Phase 7 only ever needed to *write* the stored handle; Phase 8's - `UpsellService.accept()` is the first thing that needs to *read* it back as a real, chargeable - credential. New methods: `isComplete()`, `wipeForCompletion()`. -- **`src/upsell/`**: `upsell-queue.ts` (skip/advance/position over the durable queue — an entry - the catalog can no longer resolve is skipped and logged the moment it's read, never left for a - later render to trip over again), `upsell-result.ts`, `upsell-view-model.ts`, `upsell-service.ts` - (the full `view()`/`accept()`/`decline()` orchestrator — reuses the *checkout's own* - `checkout_attempts` idempotency guard rather than a second one, and `CheckoutAttempt.releasesKey()` - rather than re-deriving it). `[16.11]`'s central rule — a declined/skipped/unresolvable upsell - never traps the buyer, every path ends in a redirect further forward — is structural: `UpsellResult.redirectTo` is non-nullable, unlike `CheckoutResult`'s. -- **`src/completion/`**: `receipt.ts` (built from real Prisma order rows — `OrderRowForReceipt` - types `OrderRepository.findByReference()`'s actual camelCase return shape directly, no - snake_case translation layer needed), `receipt-view-model.ts`, `completion.ts` (the fire-once - orchestrator — `wipeForCompletion()` runs last, after every action that still needs the - attribution/buyer contact has already used them). -- **`CheckoutEventReporter` interface grew 5 methods** (`upsellOffered`/`upsellAccepted`/ - `upsellDeclined`/`journeyCompleted`/`treatmentsSynced`) — all no-ops on - `NullCheckoutEventReporter`, for the same structural reason Phase 7 gave: unreachable while - `PAYMENT_ADAPTER` never places a real order. -- **Routes**: `UpsellController`/`UpsellModule` (`GET /upsell/`, `POST /upsell/accept|decline`), - `ReceiptController`/`ReceiptModule` (`GET /thank-you/`) — both thin, deciding nothing themselves. -- **`views/pages/upsell.ejs`, `thank-you.ejs`** — styled per `docs/mockup/mockup/intake/ - {upsell,thankyou}.html`. Deliberately omitted, since nothing in the storefront backs them: a case id - (`ReceiptViewModel` carries none on purpose — the EMR's treatment record has a null - `provider_case_id` at creation time), the delivery map, a separate billing address (`[13.2]`: - billing = shipping), a shipping method/cost line (`config/app.ts`'s declared `shippingSelector: - false` gap), and upsell.ejs's footnote is only ever the *configured* one — never a hardcoded - "Cancel anytime", which `Upsell.php`'s own doc comment explains can only be written truthfully - per deployment/per offer. - -**Proven end-to-end against a real, fully-migrated test database** (not the suite's default -unmigrated in-memory one — this test pushes the real schema to a throwaway temp SQLite file, same -as `test/database.spec.ts`), with a stub `PaymentAdapter` that actually places (`AdapterCapabilities` -otherwise stays Null-shaped) and a `FakeSessionGateway`/`FakeCatalogProvider` swapped in for the -example catalog's real gap (no product in it carries a provider mapping — see Phase 7's own -section): a full `supertest` click-through — add to cart, submit checkout, land on `/upsell/`, -fall straight through to `/thank-you/` since no upsells are configured, see the real order and -reference on the receipt, reload the receipt and get the identical frozen snapshot (fire-once), and -then discover that `/checkout/`'s `cart_not_empty` precondition now fails (cart cleared on -placement) — which is also what triggers `[4.18]`'s delayed session-cookie teardown, confirmed by -checking order matters: visiting the receipt a second time has to happen *before* visiting any other -page, or the teardown already fired and the second receipt visit lands on a fresh, order-less -session instead. This also strengthens Phase 7's own coverage, which previously only exercised the -*decline* path (the example catalog's unmapped-line gap) — this is the first automated test of a -checkout that actually reaches `placed()`. - -Two test-only fixtures were added along the way and are reusable by later phases: -`test/support/fake-session-gateway.ts` (mints a real, stable session uuid — `NullSessionGateway` -never does, so no journey persists across requests without this) and -`test/support/fake-catalog-provider.ts` (overriding `PRODUCT_CATALOG` alone is not enough for any -test touching `/products/:slug/` — `ProductDetailController` injects the concrete `CatalogProvider` -class directly rather than through the token; this fixture overrides `CatalogProvider` itself, which -`PRODUCT_CATALOG`'s `useExisting` binding also resolves through). - ---- - -## Phase 9 — SEO + legal pages + error-page X-Robots-Tag correctness (done) - -Ported from literal verbatim source: `RobotsPolicy.php`, `MetaResolver.php`, `PageMeta.php`, -`StructuredData.php` + its 4 emitters (`Organisation`, `WebSite`, `BreadcrumbList`, `Product`), -`RobotsController.php`, `SitemapController.php`, `SeoMiddleware.php`, the 3 `pages/legal/*.twig` -placeholder templates, and `structured-data.twig`. - -- **`src/seo/`**: `robots-policy.ts` grew from Phase 1's bare `REFUSED` constant into the full - per-path directive resolver (`directiveFor`/`refusesIndexing`/`isIndexable`/ - `indexingDiscouraged`, exact-beats-prefix / longer-prefix-beats-shorter specificity ranking with - the doubled-score tie-break so object key order can never decide a match), `meta-resolver.ts` - (title/description/canonical/social resolution chain — every product this EMR syncs carries an - empty description, so a blank candidate falls *through* rather than satisfying the chain), - `page-meta.ts` (the single-writer resolved-once value object). -- **`src/seo/structured-data/`**: `emitter.ts` (the one-emitter-per-type interface), - `organisation.ts`, `web-site.ts` (conditional `SearchAction`, conditional `publisher` reference — - never a dangling `@id`), `breadcrumb-list.ts` (a 1-crumb trail emits nothing), `product.ts` - (`[24.9]`: the offer prices from the *resolved variant*, never the product-level figure, and - availability is derived from whether that variant actually carries a provider mapping; `[24.10]`: - an `rx` product publishes nothing unless the deployment explicitly permits it, and its breadcrumb - trail is withheld too, since the last crumb would restate exactly what the product omission - withheld), `structured-data.ts` (the graph assembler — every emitter independently switchable in - `config/app.ts`'s `seo.structuredData`, defaulting **off** per key). -- **`CatalogProvider` grew a `channel()` getter** — Phase 5 discarded `CatalogMerger.merge()`'s - `channel` field entirely; `StructuredData`'s offer needs the synced channel's currency (`[24.9]`: - no currency configured means no offer is published, never a guessed one). -- **`SeoMiddleware` rewritten off Phase 2's always-`noindex` stub** onto real resolution: publishes - a `res.locals.seo` object (`canonical`, the real per-path `robots` directive, `page` — a - `PageMeta` a page can `.with(title, description, type)`) and sets `X-Robots-Tag` from the same - directive on every response. -- **`partials/head.ejs` gained a canonical ``, a structured-data include, and one behavioural - change to the `` tag — additive, not a rewrite of the other ~30 templates - that already call it.** Every page that passes its own explicit `noindex` (funnel steps, error - pages) is completely unaffected. A page that passes **no opinion at all** (most of the marketing - surface, and both legal pages as of this phase) now falls through to `seo.robots` instead of - defaulting to indexable — closing a real disagreement `[24.2]` forbids: before this fallback, such - a page's `X-Robots-Tag` header said `noindex` under `discourageIndexing` (every non-production - environment) while its meta tag said nothing at all. Proven directly: `test/routes/ - legal.e2e-spec.ts` asserts the home page and all 3 legal pages agree, header vs. meta tag, under - `NODE_ENV=test`. -- **Routes**: `RobotsController`/`SitemapController`/`SeoModule` (`GET /robots.txt`, - `GET /sitemap.xml` — the sitemap's exclusions are `RobotsPolicy.isIndexable()` calls, never a - second hand-kept list, so a funnel step added later needs one robots rule, not two files kept in - sync), `LegalController`/`LegalModule` (`GET /terms|privacy|telehealth-consent/` — three thin - methods rather than porting Slim's generic template-argument `PageController`, since Nest has no - equivalent route-argument style and Nest routing wants a real method per path). -- **`views/pages/legal/{terms,privacy,telehealth-consent}.ejs`** — the placeholder copy ported - verbatim (still not real legal text; every deployment is responsible for its own, exactly as the - PHP original states). -- **Structured data wired into the 3 pages PHP's own `StructuredData::pathsToInspect()` covers**: - `HomeController`, `ProductListController` (`/treatments/`), `ProductDetailController` - (`/products/:slug/`) — each now passes `structured_data: this.structuredData.json(req.path)`. -- **Error pages needed no changes.** They already passed `noindex: true` explicitly and - `ErrorPresenter` already set `X-Robots-Tag: noindex, nofollow` unconditionally (Phase 1) — header - and meta tag already agreed; the "lands in Phase 9" note on those views was about moving them into - a shared funnel layout, which the storefront's EJS-has-no-inheritance decision (see docs/STACK.md's Templates - section) already ruled out as a real layout file — every page includes its own head/foot partials - by design, so there was no separate layout work to do here. -- **The Tailwind v4 asset-build pipeline and client JS, initially deferred, were built later this - session** (after Phase 10) — see the "Asset pipeline + design pass" section below for the full - account. - -**Proven against a real running server**: `robots.txt` correctly emits a blanket `Disallow: /` plus -a `Sitemap:` line under `discourageIndexing` (dev/test), `sitemap.xml` serves a well-formed but -empty `` so the two documents never contradict each other, all 3 legal pages render with -matching header/meta-tag `noindex`, and the home page's `