Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 48 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
name: CI

on:
pull_request:
push:
branches: [main]

permissions:
contents: read

concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: true

jobs:
checks:
name: Checks (Node ${{ matrix.node }})
runs-on: ubuntu-latest
env:
DATABASE_URL: file:${{ github.workspace }}/storage/database/ci.sqlite3
strategy:
fail-fast: false
matrix:
node: ['22', '24']
steps:
- uses: actions/checkout@v5

- uses: actions/setup-node@v5
with:
node-version: ${{ matrix.node }}
cache: npm

- run: npm ci
- run: npx prisma generate
- run: npx prisma migrate deploy

# The real file is written by `theme:sync --apply` and never committed.
- name: Use the example channel config
run: cp config/channel.generated.example.ts config/channel.generated.ts

- run: npm run typecheck
- run: npm run lint
- run: npm test
- run: npm run build
- run: npm run build:assets

# Exits 2 on error; run bare so the step fails on it.
- run: node dist/src/console/main.js config:validate
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@ never sent to the AsterMD platform and never written to this application's datab
```bash
npm install
cp .env.example .env # then edit it, see Configuration below
cp config/channel.generated.example.ts config/channel.generated.ts # until theme:sync --apply writes it
npx prisma migrate deploy # creates the SQLite file and applies migrations
npm run build:assets # compiles the Tailwind theme
npm run start:dev # dev server with watch, http://localhost:8080
Expand Down Expand Up @@ -203,7 +204,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 |
Expand Down
1,254 changes: 0 additions & 1,254 deletions STATUS.md

This file was deleted.

1 change: 0 additions & 1 deletion config/app.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,6 @@ export interface AppConfig {
url: string;
env: string;
database: {
/** PDO's driver names ('sqlite'/'mysql'/'pgsql') translated to Kysely's ('postgres' not 'pgsql'). */
driver: 'sqlite' | 'mysql' | 'postgres';
database: string;
host: string;
Expand Down
14 changes: 14 additions & 0 deletions config/channel.generated.example.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
/**
* The shape of `config/channel.generated.ts`, which `theme:sync --apply` writes from live channel
* data and which is never committed. Copy this file to `config/channel.generated.ts` on a fresh
* clone: the app builds and runs with no payment processor configured.
*/
export interface GeneratedChannelConfig {
channel: { id: string | null; name: string | null };
payment_processor: { provider_category: string | null; name: string | null; config: Record<string, unknown> };
}

export const channelGenerated: GeneratedChannelConfig = {
channel: { id: null, name: null },
payment_processor: { provider_category: null, name: null, config: {} },
};
2 changes: 1 addition & 1 deletion config/cross-sells.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
/**
* Checkout order bumps: accepted *before*
* submission, ride along on the main order (distinct from `config/upsells.ts`'s post-purchase
* upsells, charged *separately* after the first order settles — Phase 8).
* upsells, charged *separately* after the first order settles).
*
* Empty by default. Populate it when the
* catalog has something to cross-sell. A prescription offered here joins the order beside the one
Expand Down
2 changes: 1 addition & 1 deletion config/products.generated.example.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import { CatalogProduct } from '../src/domain/product-catalog';

/**
* The committed shape
* reference, preserved here once `theme:sync` became real (Phase 10) and started actually writing
* reference, preserved here once `theme:sync` became real and started actually writing
* `config/products.generated.ts` from live EMR channel data. This file is never imported by the
* application; it exists so a fresh checkout (or a reader who has never run `theme:sync --apply`)
* can see the shape `CatalogBuilder.build()` produces without needing a live channel. Not kept in
Expand Down
2 changes: 1 addition & 1 deletion config/upsells.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
* `config/cross-sells.ts`'s checkout order bumps, which ride along on the main order.
*
* **Keyed by the upsell, not by the trigger** — the opposite arrangement to cross-sells, and the
* reason is ordering: exactly one upsell is presented per step (Phase 8), so the offers have to be a
* reason is ordering: exactly one upsell is presented per step, so the offers have to be a
* single ordered list rather than assembled from several trigger buckets.
*
* Ships empty, for the same reason `cross-sells.ts` does: nothing in the current example catalog
Expand Down
2 changes: 1 addition & 1 deletion config/verification.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import { IdentityCheckConfig } from '../src/verification/identity-verification-s

/**
* Identity verification: where the step
* sits, whether it stops anybody, and (Phase 6) which identity checks run, in what order, against
* sits, whether it stops anybody, and which identity checks run, in what order, against
* which fields.
*
* Ships disabled: recorded against the live provider integration on 2026-08-25, the real check
Expand Down
3 changes: 0 additions & 3 deletions docs/STACK.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,6 @@ the funnel, journey store, catalog and gateways fit together, see
[`ARCHITECTURE.md`](ARCHITECTURE.md); for the middleware pipeline slot by slot, see
[`MIDDLEWARE.md`](MIDDLEWARE.md).

A PHP implementation of the same storefront is maintained separately in
[astermd/storefront-lamp](https://github.com/astermd/storefront-lamp).

---

## Stack at a glance
Expand Down
6 changes: 3 additions & 3 deletions prisma/schema.prisma
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ model Order {
providerCategory String? @map("provider_category")
placedAt String? @map("placed_at")
isUpsell Int @default(0) @map("is_upsell")
/// 'capture' | 'authorize' — see SettlementMode/SettlementPolicy (Phase 7). Defaulted so a row
/// 'capture' | 'authorize' — see SettlementMode/SettlementPolicy. Defaulted so a row
/// written before this column existed reads as 'capture', which is what every such row really was.
settlement String @default("capture")
userAgent String? @map("user_agent")
Expand Down Expand Up @@ -109,7 +109,7 @@ model OrderConsent {
@@map("order_consents")
}

/// The local, append-only audit trail — CartMirror (Phase 5) and RecordingIntakeGateway (Phase 6)
/// The local, append-only audit trail — CartMirror and RecordingIntakeGateway
/// are its writers so far.
model Event {
id Int @id @default(autoincrement())
Expand All @@ -128,7 +128,7 @@ model CheckoutAttempt {
/// UNIQUE — the entire double-charge defense.
idempotencyKey String @unique @map("idempotency_key")
sessionKey String @map("session_key")
/// 'claimed' | 'sent' | 'complete' — see CheckoutAttemptRepository's constants (Phase 7).
/// 'claimed' | 'sent' | 'complete' — see CheckoutAttemptRepository's constants.
state String
outcome String?
createdAt String @map("created_at")
Expand Down
3 changes: 1 addition & 2 deletions src/catalog/catalog-provider.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,7 @@ import { CatalogMerger } from './catalog-merger';

/**
* The only catalog class
* controllers/`CartRules` touch at runtime, and the real `ProductCatalog` implementation Phase 4's
* `EmptyProductCatalog` placeholder stood in for.
* controllers/`CartRules` touch at runtime — the production `ProductCatalog` implementation.
*
* The merge is computed once, at construction, rather than re-run per request:
* `products.generated.ts`/`products.overrides.ts` are static TS modules baked in at process start,
Expand Down
10 changes: 4 additions & 6 deletions src/core/core.module.ts
Original file line number Diff line number Diff line change
Expand Up @@ -145,8 +145,7 @@ class DatabaseLifecycle implements OnModuleDestroy {
* `EMR_VERIFICATION_GATEWAY` switches on `config.app.features.emrVerifyEmail`/`emrVerifyAddress`
* (each check under its own switch). `NODE_ENV=test` forces both flags false
* (see `config/app.ts`), so the test suite never reaches the network. `PRODUCT_CATALOG` is bound
* to `CatalogProvider` (Phase 5) — replacing Phase 4's `EmptyProductCatalog` placeholder now that
* there's real (example) catalog data to merge and serve.
* to `CatalogProvider`, which merges and serves the generated catalog and its overrides.
*/
@Global()
@Module({
Expand Down Expand Up @@ -296,7 +295,7 @@ class DatabaseLifecycle implements OnModuleDestroy {
useFactory: (catalog: ProductCatalog, config: ConfigService) => new FunnelRouter(catalog, config.verification),
inject: [PRODUCT_CATALOG, ConfigService],
},
// Phase 7 — checkout.
// Checkout.
CheckoutAttemptRepository,
RateLimitRepository,
OrderRepository,
Expand Down Expand Up @@ -414,7 +413,6 @@ class DatabaseLifecycle implements OnModuleDestroy {
log: OperatorLog,
journeyStoreFactory: JourneyStoreFactory,
request: Request,
nullReporter: NullCheckoutEventReporter,
instrumentation: Instrumentation,
verification: VerificationGateway,
) =>
Expand All @@ -430,15 +428,15 @@ class DatabaseLifecycle implements OnModuleDestroy {
instrumentation.checkoutEventReporter(new EmrCheckoutEventReporter(clients, events, orders, log, null, config, null, verification)),
inject: [ConfigService, EmrClientFactory, EventRepository, OrderRepository, OperatorLog, Instrumentation, EMR_VERIFICATION_GATEWAY],
},
// Phase 9 — SEO.
// SEO.
MetaResolver,
{
provide: RobotsPolicy,
useFactory: (config: ConfigService) => RobotsPolicy.fromConfig(config),
inject: [ConfigService],
},
StructuredData,
// Phase 10 — abandonment, retention, console commands.
// Abandonment, retention, console commands.
AbandonmentSweep,
{
provide: RetentionPolicy,
Expand Down
8 changes: 3 additions & 5 deletions src/core/tokens.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,14 @@
* Injection tokens for every port. A controller or service depends on the interface behind one of
* these tokens, never the concrete (Null or real) implementation directly.
*
* Two naming notes, both deliberate departures from a naive 1:1 name transcription:
* Two naming notes:
* - `EMR_VERIFICATION_GATEWAY` and `IDENTITY_GATEWAY` are two distinct ports that both involve
* the word "verification" (`VerificationGateway` — email/address aid, gated by
* `app.features.emrVerifyEmail`/`emrVerifyAddress` — vs. `IdentityGateway` — KYC checks at
* `/verify/`, gated by `verification.enabled`). Naming them identically would invite a binding
* mix-up.
* - `PAYMENT_ADAPTER` resolves through `AdapterRegistry` (a resolve-by-category-with-catch-to-Null
* factory), not a config-gated ternary like the other nine ports — see `payment/adapter-registry.ts`
* (Phase 7).
* factory), not a config-gated ternary like the other nine ports — see `payment/adapter-registry.ts`.
*/
export const SESSION_GATEWAY = Symbol('SessionGateway');
export const CART_GATEWAY = Symbol('CartGateway');
Expand Down Expand Up @@ -39,8 +38,7 @@ export const EMR_CLIENT = Symbol('EmrClient');

/**
* The `ProductCatalog` port — no Null counterpart (it's not an external
* system that degrades, it's config-derived data that's foundational). Bound to `CatalogProvider`
* (Phase 5), which merges `config/products.generated.ts` and `config/products.overrides.ts`.
* system that degrades, it's config-derived data that's foundational). Bound to `CatalogProvider`, which merges `config/products.generated.ts` and `config/products.overrides.ts`.
*/
export const PRODUCT_CATALOG = Symbol('ProductCatalog');

Expand Down
4 changes: 2 additions & 2 deletions src/database/connection-factory.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@ import { PrismaBetterSqlite3 } from '@prisma/adapter-better-sqlite3';
import { PrismaClient } from '@prisma/client';

/**
* Builds the `PrismaClient` bound behind `DATABASE_CONNECTION` in `CoreModule`. Unlike the
* Kysely-based version this replaced, there is no dialect switch here: `schema.prisma`'s
* Builds the `PrismaClient` bound behind `DATABASE_CONNECTION` in `CoreModule`. There is no
* dialect switch here: `schema.prisma`'s
* `datasource` block fixes the engine at `prisma generate` time.
*
* Prisma 7 removed the "no adapter" mode entirely — `PrismaClient` no longer reads a connection
Expand Down
8 changes: 4 additions & 4 deletions src/domain/product-catalog.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,11 @@
* The single read the cart/funnel
* rules make against the catalog — declared as a port so the domain layer stays free of I/O and
* of the config cascade: the rules are exercised against an in-memory implementation in their own
* tests, and `CatalogProvider` (Phase 5) satisfies it in production without either side knowing
* tests, and `CatalogProvider` satisfies it in production without either side knowing
* about the other.
*
* `ProductVariant`/`CatalogProduct` are typed here since TypeScript makes that free. Phase 4 only needed the fields `CartRules`/
* `FunnelRules` read; Phase 5 adds everything the catalog/product-page templates display
* `ProductVariant`/`CatalogProduct` are typed here since TypeScript makes that free: the fields `CartRules`/
* `FunnelRules` read, plus everything the catalog/product-page templates display
* (`subtitle`, `categories`, `description`, `image`, `gallery`, `badges`, `price_unit`, ...) —
* matching the shape of `CatalogBuilder.build()`'s output and `config/products.generated.example.ts`.
*/
Expand Down Expand Up @@ -65,7 +65,7 @@ export interface CatalogProduct {
geo_blocks?: string[];
requires_prequalification?: boolean;
prequalification_teleform_id?: string;
/** Checkout-time concern (Phase 7) — carried in the type now since it's part of the override shape. */
/** Checkout-time concern — carried in the type now since it's part of the override shape. */
settlement?: 'authorize' | 'capture';
}

Expand Down
2 changes: 1 addition & 1 deletion src/forms/emr-lead-gateway.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import { LeadGateway } from './lead-gateway';
* {@link LeadGateway} over the SDK's
* `opportunities()` resource.
*
* Never logs payload values — only field *names* (`array_keys($payload)`), since the payload is a
* Never logs payload values — only field *names* (`Object.keys(payload)`), since the payload is a
* mapped clinical record.
*/
@Injectable()
Expand Down
4 changes: 2 additions & 2 deletions src/funnel/funnel-rules.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@ import { JourneyState } from '../journey/journey-state';
* outstanding.
*
* Exists because three collaborators must never disagree: `FunnelRouter` decides where a visitor
* belongs, `StepPreconditions` decides whether they may enter the step they asked for, and (Phase
* 6) the intake controller decides which questionnaire a step actually collects. A shared rule is
* belongs, `StepPreconditions` decides whether they may enter the step they asked for, and the
* intake controller decides which questionnaire a step actually collects. A shared rule is
* what makes disagreement impossible rather than merely unintended.
*/
export class FunnelRules {
Expand Down
16 changes: 16 additions & 0 deletions src/journey/amd-payload.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
import { QueryParamCipher } from '@astermd-hq/sdk';

/** Decrypts the `_amd` affiliate payload, trying the current key first, then the previous one. */
export class AmdPayload {
/** Returns null when no key can read the token. */
static decode(token: string, keysHex: readonly string[]): Record<string, string> | 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;
}
}
25 changes: 25 additions & 0 deletions src/journey/attribution-normalizer.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
import { CanonicalKeys } from './canonical-keys';

/** Maps raw query params onto canonical tracking keys; unknown or blank values are dropped. */
export class AttributionNormalizer {
static normalize(params: Record<string, unknown>): Record<string, string> {
const out: Record<string, string> = {};

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;
}
}
Loading
Loading