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
15 changes: 14 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,9 @@

> **Open-Source (MIT)** | Built for the Shopify Merchant & Developer Community | Open for PRs & Discussions
>
> ⚙️ **Status: Complete Engine, Admin & Storefront Modules Verified (584/584 Unit Tests Passing across 132 Suites)** | **Live PostgreSQL Integration (11 integration tests run against a live PostgreSQL instance (they skip with a notice when none is reachable))** | **Live Railway Hosting with Postgres** | **Dev Store Spikes Verified (S2, S3, S4, S5 Answered; S1 Answered on Plus Dev Store Only; S6 Answered on Dev Store)** | **Milestones M9a, M9b-1, M9b-2, M9b-3a & M9b-3b Verified Live on Dev Store**
> 🚀 **Live Interactive Demo:** [https://practitioner-protocols-production.up.railway.app/demo](https://practitioner-protocols-production.up.railway.app/demo) — Test-drive all 4 roles (Practitioner Portal, Client Storefront Page, Printable QR Handout, and Merchant Admin) live with zero setup.
>
> ⚙️ **Status: Complete Engine, Admin & Storefront Modules Verified (606/606 Unit Tests Passing across 133 Suites)** | **Live PostgreSQL Integration (11 integration tests run against a live PostgreSQL instance (they skip with a notice when none is reachable))** | **Live Railway Hosting with Postgres** | **Dev Store Spikes Verified (S2, S3, S4, S5 Answered; S1 Answered on Plus Dev Store Only; S6 Answered on Dev Store)** | **Milestones M9a, M9b-1, M9b-2, M9b-3a & M9b-3b Verified Live on Dev Store**

<p align="center">
<img src="assets/listing/feature-image-1600x900.png" alt="A curated list card of generic unbranded wellness products converging into a single coral QR code link node on deep teal background." width="720">
Expand All @@ -30,6 +32,17 @@

**Current build stage:** The pure engine logic, security controls, cryptographic primitives, Liquid renderers, catalog resolver, rate limiters, validation barriers, and PostgreSQL database queries are fully built and covered by 507 automated unit tests across 111 suites using mock database interfaces. Real PostgreSQL query execution, transaction behavior, constraints, row-level locking (`FOR UPDATE`), and migrations are verified against a live PostgreSQL instance via `npm run test:db` (11 integration tests run against a live PostgreSQL instance, skipping with a notice when none is reachable). The app is deployed live on Railway (`practitioner-protocols-production.up.railway.app`) with internal PostgreSQL and automated migration tracking. Spikes S2 (sitemap exclusion, `noindex`, and proxy header), S3 (hidden line property attribution persistence in storefront checkout and `orders/paid` webhook payload), S4 (20 lines in a single cart batch add), S5 (retail vs B2B pricing), and S6 (storefront predictive search and variant hydration contract; Option A chosen) are verified on live dev store `ai-agent-app-h9qwnwd8.myshopify.com`; Spike S1 is verified on the Plus dev store only. In production mode with `DATABASE_URL` configured, the embedded merchant admin is verified live on the dev store (Milestone M9a; `GET /`, `GET /admin`, `GET /app` served via App Bridge ID tokens and HS256 session verification), including the self-enrolment toggle and pending practitioner review table with customer admin deep links (Milestone M9b-1; verified live on dev store); for Milestone M9b-2, verified live on the dev store: enrol round trip (JSON POST through the App Proxy), pending portal state with requested name, admin pending row with customer deep link, merchant approval, approved portal display, form-encoded and `text/plain;application/json` POSTs returning 415, and unknown action returning 400 (the per-customer rate limit of 5/hr, the pending cap of 200, `customers/redact` profile deletion, and `Sec-Fetch-Site` handling are covered by automated unit tests and were not exercised live); for Milestone M9b-3a (protocol authoring and client page hydration), VERIFIED LIVE on the dev store: editor search with real products and CAD prices, protocol save, share-page hydration, Add all with _protocol_token/_protocol_id/_protocol_usage in the cart, checkout to orders/paid (webhook 200, stat row written), edit round trip (qty and note persisted, token unchanged), list card item count, handout page layout; migration adding nullable `productHandle` to `ProtocolLine`, validation and persistence, client-side predictive search (`/search/suggest.json`) and variant hydration (`/products/<handle>.js`) in the practitioner editor with `textContent` rendering, client page variant hydration from `/products/<handle>.js`, and removal of `createFakeVariantResolver` from the production App Proxy pipeline. Follow-up hotfix loaded protocol lines on portal queries (`json_agg` + `linesCount`) to eliminate edit data loss, removed fake retail total (`$0.00`) from cards to show only item count, and implemented print-friendly handout mode (`?handout=1`) in `renderProtocolLiquid`. Milestone M9b-3b (protocol lifecycle: archive, restore, duplicate-as-template for starters with CSRF, duplicate-from-starter, Rule 4 ownership isolation, in-page confirm UI, and Archived section) is VERIFIED LIVE on the dev store. Remaining NOT-verified live list: logged-out guest view, handoutText/footerDisclaimer rendering, real printing, live cross-owner/cross-shop denial, non-Latin handles (known limitation), discounted-order attribution live, and new CSP inside real admin iframe. Note: the admin attribution report page displayed zeros for live data until a contract mismatch between `getAttributionReport` and `renderAttributionTab` was resolved by unifying `{ month, summary, rows, byPractice, byProtocol }` across the data service, renderer, demo data, and RFC 4180 CSV export with `Intl.NumberFormat` currency formatting. Pre-submission hardening is complete with HMAC-signed OAuth state cookies, public `/privacy` page, `Strict-Transport-Security` on all responses, expanded embedded App Bridge CSP, admin starter catalog product search UX, individual mode settings label, and `.github/CODEOWNERS`. Milestone M11 implements shopper opt-in contact capture (server-defined canonical consent text, dedicated 5/hr rate limiter, case-insensitive email deduplication, RFC 4180 CSV export with `Verified = "no"`) and merchant contact & feedback (`ShopProfile` sync via Admin GraphQL, AES-256-GCM session token encryption at rest, "Contact & feedback" card with 1–5 rating and marketing opt-in checkbox, `scripts/contacts.mjs` and `scripts/stats.mjs`). Under Shopify Managed Installation, authentication uses App Bridge token exchange (RFC 8693) to acquire expiring offline access tokens (1-hour lifetime, `expiring: 1`) without interactive redirects, with encrypted storage at rest via AES-256-GCM, non-PII failure logging, friendly status 200 root page, and fallback legacy OAuth. The app holds a short-lived (1 hour) offline access token, re-acquired on admin load when missing or expiring within 5 minutes, and deleted on uninstallation; no refresh token is stored (fewer secrets at rest) and no separate refresh flow is built because the app makes no Admin API calls outside embedded-admin requests. Covered by 584 automated unit tests across 132 suites. Includes dedicated "How to Use" guide tab (`?tab=guide`) covering storefront navigation menu setup, 3-role workflows, and 5-minute testing walkthrough.

### Live Interactive Demo Sandbox
Test-drive the complete application live without requiring a Shopify development store, login, or credentials:

👉 **[https://practitioner-protocols-production.up.railway.app/demo](https://practitioner-protocols-production.up.railway.app/demo)** (or `/try`)

The live demo provides an interactive top showcase bar with instant role switching:
- **Practitioner Portal** (`/demo?view=portal`) — View active protocols, client roster, starter templates, and open the interactive protocol editor modal with live product search and variant hydration.
- **Client Landing Page** (`/demo?view=client`) — Experience the client-facing recommendation page with dosages, usage notes, and 1-tap "Add all to cart".
- **Printable QR Handout** (`/demo?view=handout`) — View and print self-contained US Letter and A4 clinical routines with vector QR codes.
- **Merchant Admin** (`/demo?view=admin`) — Navigate the embedded Polaris merchant dashboard across Practitioners, Starter Templates, Attribution Reports, and Settings.

---

## 2. Core Modules & Verified Features
Expand Down
137 changes: 121 additions & 16 deletions server.js
Original file line number Diff line number Diff line change
Expand Up @@ -337,9 +337,9 @@ export function renderDemoShowcaseBar(currentView = 'portal', basePath = '/demo'
return `
<style>
.demo-showcase-bar {
background: #111827;
color: #f3f4f6;
padding: 0.65rem 1.25rem;
background: #0f172a;
color: #f8fafc;
padding: 0.625rem 1.5rem;
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
font-size: 0.875rem;
display: flex;
Expand All @@ -350,20 +350,25 @@ export function renderDemoShowcaseBar(currentView = 'portal', basePath = '/demo'
border-bottom: 2px solid #008060;
position: sticky;
top: 0;
z-index: 99999;
box-shadow: 0 2px 4px rgba(0, 0, 0, 0.15);
left: 0;
right: 0;
width: 100%;
box-sizing: border-box;
z-index: 999999;
box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.06);
}
.demo-showcase-left {
display: flex;
align-items: center;
gap: 0.6rem;
gap: 0.65rem;
white-space: nowrap;
}
.demo-showcase-badge {
background: #008060;
color: #ffffff;
font-size: 0.6875rem;
font-weight: 700;
padding: 0.15rem 0.5rem;
padding: 0.2rem 0.55rem;
border-radius: 9999px;
text-transform: uppercase;
letter-spacing: 0.05em;
Expand All @@ -380,22 +385,41 @@ export function renderDemoShowcaseBar(currentView = 'portal', basePath = '/demo'
flex-wrap: wrap;
}
.demo-showcase-link {
color: #9ca3af;
color: #94a3b8;
text-decoration: none;
padding: 0.35rem 0.65rem;
border-radius: 5px;
padding: 0.4rem 0.75rem;
border-radius: 6px;
font-weight: 500;
font-size: 0.8125rem;
transition: all 0.12s ease;
white-space: nowrap;
transition: all 0.15s ease;
}
.demo-showcase-link:hover {
background: #1f2937;
background: #1e293b;
color: #ffffff;
}
.demo-showcase-link.active {
background: #008060;
color: #ffffff;
font-weight: 600;
box-shadow: 0 1px 2px rgba(0, 0, 0, 0.2);
}
@media (max-width: 768px) {
.demo-showcase-bar {
padding: 0.5rem 0.75rem;
gap: 0.5rem;
}
.demo-showcase-nav {
width: 100%;
justify-content: flex-start;
overflow-x: auto;
padding-bottom: 2px;
}
.demo-showcase-link {
font-size: 0.75rem;
padding: 0.3rem 0.55rem;
flex-shrink: 0;
}
}
@media print {
.demo-showcase-bar {
Expand All @@ -418,6 +442,39 @@ export function renderDemoShowcaseBar(currentView = 'portal', basePath = '/demo'
`;
}

/**
* Wraps HTML fragments into a complete, standards-compliant HTML5 document for public demo previews.
*/
function renderDemoHtmlShell({ title, navBar, contentHtml, extraStyles = '' }) {
return `<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="robots" content="noindex, nofollow">
<title>${title}</title>
<style>
*, *::before, *::after {
box-sizing: border-box;
}
html, body {
margin: 0;
padding: 0;
background-color: #f8fafc;
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
color: #111827;
min-height: 100vh;
}
${extraStyles}
</style>
</head>
<body>
${navBar}
${contentHtml}
</body>
</html>`;
}

/**
* Validates server configuration before startup.
* Refuses to start in production mode (DATABASE_URL set) while admin session-token
Expand Down Expand Up @@ -1203,7 +1260,11 @@ export function createRequestListener(options = {}) {
practiceName: 'Apex Integrative Wellness',
isLoggedInPractitioner: url.searchParams.get('preview') === 'practitioner',
});
content = `${navBar}\n${liquid}`;
content = renderDemoHtmlShell({
title: 'Daily Essentials Protocol — Client Storefront Demo',
navBar,
contentHtml: liquid,
});
} else if (view === 'handout') {
const shareUrl = `https://${DEMO_SHOP}/apps/protocols/${DEMO_PROTOCOL.token}`;
const qrSvg = generateQrSvg(shareUrl, { size: 180 });
Expand All @@ -1213,7 +1274,44 @@ export function createRequestListener(options = {}) {
shareUrl,
qrSvg,
});
content = rawHtml.replace('<body>', `<body>\n${navBar}`);
const demoHandoutStyle = `
<style id="demo-handout-layout">
html, body {
margin: 0 !important;
padding: 0 !important;
max-width: 100% !important;
background-color: #f1f5f9 !important;
}
.demo-handout-sheet {
max-width: 800px;
margin: 28px auto 40px auto;
padding: 32px 36px;
background: #ffffff;
border-radius: 8px;
box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.08), 0 2px 4px -2px rgba(0, 0, 0, 0.05);
}
@media print {
html, body {
background-color: #ffffff !important;
}
.demo-showcase-bar {
display: none !important;
}
.demo-handout-sheet {
box-shadow: none !important;
padding: 0 !important;
margin: 0 !important;
border-radius: 0 !important;
max-width: 100% !important;
background: transparent !important;
}
}
</style>
`;
content = rawHtml
.replace('</head>', `${demoHandoutStyle}</head>`)
.replace('<body>', `<body>\n${navBar}\n<div class="demo-handout-sheet">`)
.replace('</body>', `</div>\n</body>`);
} else if (view === 'admin') {
const activeTab = url.searchParams.get('tab') || 'practitioners';
const month = url.searchParams.get('month');
Expand All @@ -1229,7 +1327,10 @@ export function createRequestListener(options = {}) {
settings: DEMO_SETTINGS,
activeTab,
});
content = `${navBar}\n${adminHtml}`;
const adminOverrideStyle = `<style>html, body { margin: 0 !important; padding: 0 !important; }</style>`;
content = adminHtml
.replace('</head>', `${adminOverrideStyle}</head>`)
.replace('<body>', `<body>\n${navBar}`);
csp = buildAdminCsp(DEMO_SHOP);
} else {
// Default: Practitioner Portal
Expand Down Expand Up @@ -1264,7 +1365,11 @@ export function createRequestListener(options = {}) {
},
],
});
content = `${navBar}\n${portalHtml}`;
content = renderDemoHtmlShell({
title: 'Practitioner Portal — Interactive Demo',
navBar,
contentHtml: portalHtml,
});
}

res.writeHead(200, {
Expand Down
4 changes: 4 additions & 0 deletions test/server.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -979,6 +979,7 @@ describe('Server & Configuration Hardening (server.js, shopify.app.toml, README.
await prodListener(req, res);

assert.equal(res.statusCode, 200);
assert.ok(res.body.startsWith('<!DOCTYPE html>'), 'Must start with <!DOCTYPE html>');
assert.ok(res.body.includes('demo-showcase-bar'), 'Must contain demo showcase bar');
assert.ok(res.body.includes('Interactive Demo'), 'Must contain demo badge');
assert.ok(res.body.includes('Daily Essentials Protocol'), 'Must contain demo protocol');
Expand All @@ -992,6 +993,7 @@ describe('Server & Configuration Hardening (server.js, shopify.app.toml, README.
await prodListener(req, res);

assert.equal(res.statusCode, 200);
assert.ok(res.body.startsWith('<!DOCTYPE html>'), 'Must start with <!DOCTYPE html>');
assert.ok(res.body.includes('demo-showcase-bar'));
assert.ok(res.body.includes('Daily Essentials Protocol'));
assert.ok(res.body.includes('Hydrating Daily Cleanser'));
Expand All @@ -1005,6 +1007,7 @@ describe('Server & Configuration Hardening (server.js, shopify.app.toml, README.
assert.equal(res.statusCode, 200);
assert.ok(res.body.startsWith('<!DOCTYPE html>'), 'Handout must start with <!DOCTYPE html>');
assert.ok(res.body.includes('demo-showcase-bar'));
assert.ok(res.body.includes('demo-handout-sheet'));
assert.ok(res.body.includes('Print Handout'));
assert.ok(res.body.includes('<svg'));
});
Expand All @@ -1015,6 +1018,7 @@ describe('Server & Configuration Hardening (server.js, shopify.app.toml, README.
await prodListener(req, res);

assert.equal(res.statusCode, 200);
assert.ok(res.body.startsWith('<!DOCTYPE html>'), 'Must start with <!DOCTYPE html>');
assert.ok(res.body.includes('demo-showcase-bar'));
assert.ok(res.body.includes('Apex Integrative Wellness'));
assert.ok(res.body.includes('Practitioners'));
Expand Down
Loading