@medfunnels/next 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 medFunnels
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,65 @@
-# Temporary Holding Version
+# @medfunnels/next
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Run [medFunnels](https://www.medfunnels.app) patient questionnaires in your Next.js app (App Router).
+
+Your team builds questionnaires in medFunnels. This package downloads each published version at build time,
+verifies its signature and every file, serves it from your own domain in a locked-down sandbox, and validates
+patients' answers on your server before your code sees them. **Patient data never goes to medFunnels.**
+
+## Setup
+
+```bash
+npm install @medfunnels/next
+```
+
+Add your credential (medFunnels → Integrations → New credential) to `.env.local` and your host:
+
+```bash
+MEDFUNNELS_CLIENT_ID=mfc_…
+MEDFUNNELS_CLIENT_SECRET=mfs_…
+```
+
+```bash
+npx medfunnels init
+```
+
+`init` creates `medfunnels.config.json` (no secrets; commit it), `medfunnels.server.ts`, and two routes under
+`app/medfunnels/[slug]/`. Then run the sync before every dev server and build:
+
+```json
+"scripts": { "predev": "medfunnels pull", "prebuild": "medfunnels pull" }
+```
+
+Show a questionnaire on any page:
+
+```tsx
+import { MedFunnelsQuestionnaire } from "@medfunnels/next/client";
+import { medfunnels } from "../../medfunnels.server";
+
+export default function IntakePage() {
+    return <MedFunnelsQuestionnaire questionnaire={medfunnels.questionnaire("glp1-intake")} redirectTo="/next-step" />;
+}
+```
+
+And save the answers in the submit route `init` created:
+
+```ts
+export const POST = medfunnels.submitRoute(async (answers, { request, questionnaire }) => {
+    // Identify the patient with your own session, then save `answers`.
+    // Return { ok: false, message } to show the patient a message instead.
+});
+```
+
+## How it works
+
+- **Build time:** `medfunnels pull` verifies each release (Ed25519 signature against the key pinned in your config,
+  your workspace, your website, file digests) and writes it to `.medfunnels/`. A failed check fails the build.
+- **Frame route:** serves the verified script with a Content-Security-Policy that allows only those exact bytes and
+  blocks all network access. The page embeds it in an opaque-origin sandbox with no access to your cookies or APIs.
+- **Submit route:** validates every answer against the verified questionnaire, then calls your handler. It never logs answers.
+- **Versions:** each deploy ships the latest published version. Pin one with `"versions": { "slug": 3 }` in the config.
+- **Staging:** set `MEDFUNNELS_SITE_ORIGIN` to your Staging website on staging deployments.
+
+The complete guide, with your workspace's values filled in, is in medFunnels under **Integrations → Developer guide**.
+
+Using another Node framework? See [`@medfunnels/sdk`](https://www.npmjs.com/package/@medfunnels/sdk).

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+// medfunnels init | pull
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { MedFunnelsClient } from "@medfunnels/sdk";
+import { CONFIG_FILE, DEFAULT_API, DEFAULT_OUTPUT } from "./config.js";
+import { pull } from "./pull.js";
+const HELP = `medFunnels for Next.js
+
+  npx medfunnels init    Scaffold medfunnels.config.json, medfunnels.server.ts and the frame and submit routes.
+  npx medfunnels pull    Download and verify the questionnaires this build serves (run before next dev / next build).
+
+Environment: MEDFUNNELS_CLIENT_ID, MEDFUNNELS_CLIENT_SECRET (server-side only),
+             MEDFUNNELS_SITE_ORIGIN (optional: the website this deployment serves, e.g. your Staging site).
+Guide: medFunnels → Integrations → Developer guide.`;
+function write(cwd, path, content) {
+    const target = join(cwd, path);
+    if (existsSync(target)) {
+        console.log(`  kept     ${path} (already exists)`);
+        return;
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, content);
+    console.log(`  created  ${path}`);
+}
+const importPath = (from, to) => {
+    const path = relative(dirname(from), to).replace(/\\/g, "/");
+    return path.startsWith("./") || path.startsWith("../") ? path : `./${path}`;
+};
+async function init(cwd) {
+    const appDir = existsSync(join(cwd, "src", "app")) ? "src/app" : "app";
+    const serverFile = appDir === "src/app" ? "src/medfunnels.server.ts" : "medfunnels.server.ts";
+    let config = { api: DEFAULT_API, organizationId: "org_…", signingKeys: { "key-id": "public-key" }, siteOrigin: "https://intake.yourclinic.com" };
+    const { MEDFUNNELS_CLIENT_ID: clientId, MEDFUNNELS_CLIENT_SECRET: clientSecret, MEDFUNNELS_API: api } = process.env;
+    if (clientId && clientSecret) {
+        // One-time setup convenience. Compare the key with the developer guide before you commit it.
+        const connection = await new MedFunnelsClient({ baseUrl: api || DEFAULT_API, clientId, clientSecret }).testConnection();
+        config = {
+            ...config,
+            api: api || DEFAULT_API,
+            organizationId: connection.organization.id,
+            ...(connection.websites?.live ? { siteOrigin: connection.websites.live } : {}),
+            signingKeys: Object.fromEntries(connection.signingKeys.map((key) => [key.keyId, key.publicKey])),
+        };
+        console.log(`  connected to ${connection.organization.name}`);
+    }
+    write(cwd, CONFIG_FILE, `${JSON.stringify(config, null, 2)}\n`);
+    write(cwd, serverFile, `import { createMedFunnels } from "@medfunnels/next/server";
+
+import releases from "${importPath(serverFile, `${DEFAULT_OUTPUT}/releases.json`)}";
+import config from "${importPath(serverFile, CONFIG_FILE)}";
+
+// Server-only. Releases come from \`medfunnels pull\` and are re-verified before they're served.
+export const medfunnels = createMedFunnels({ config, releases });
+`);
+    const frame = `${appDir}/medfunnels/[slug]/frame/route.ts`;
+    write(cwd, frame, `import { medfunnels } from "${importPath(frame, serverFile.replace(/\.ts$/, ""))}";
+
+export const runtime = "nodejs";
+export const GET = medfunnels.frameRoute;
+`);
+    const submit = `${appDir}/medfunnels/[slug]/submit/route.ts`;
+    write(cwd, submit, `import { medfunnels } from "${importPath(submit, serverFile.replace(/\.ts$/, ""))}";
+
+export const runtime = "nodejs";
+
+export const POST = medfunnels.submitRoute(async (answers, { request, questionnaire }) => {
+    // 1. Identify the patient with your own session (cookies on \`request\`).
+    // 2. Save \`answers\` with their record. Each has questionKey, kind, value and displayValue.
+    // Return { ok: false, message } to show the patient an error instead.
+});
+`);
+    console.log(`
+Next steps:
+  1. Fill in ${CONFIG_FILE} (values are in medFunnels → Integrations → Developer guide).
+  2. Add to package.json scripts:  "predev": "medfunnels pull",  "prebuild": "medfunnels pull"
+  3. Set MEDFUNNELS_CLIENT_ID and MEDFUNNELS_CLIENT_SECRET in .env.local and your hosting provider.
+  4. Render it on a page:
+       <MedFunnelsQuestionnaire questionnaire={medfunnels.questionnaire("your-slug")} redirectTo="/thanks" />`);
+}
+async function main() {
+    const [command] = process.argv.slice(2);
+    const cwd = process.cwd();
+    if (command === "pull") {
+        console.log("medfunnels pull");
+        const result = await pull({ cwd });
+        console.log(`  wrote ${relative(cwd, result.file)} (${result.questionnaires.length} questionnaire${result.questionnaires.length === 1 ? "" : "s"})`);
+    }
+    else if (command === "init") {
+        console.log("medfunnels init");
+        await init(cwd);
+    }
+    else {
+        console.log(HELP);
+        if (command && command !== "help" && command !== "--help" && command !== "-h")
+            process.exitCode = 1;
+    }
+}
+main().catch((error) => {
+    const detail = error;
+    console.error(`medfunnels: ${detail.message ?? String(error)}${detail.code ? ` [${detail.code}]` : ""}${detail.requestId ? ` (request ${detail.requestId})` : ""}`);
+    process.exitCode = 1;
+});

package/dist/client.d.ts

@@ -0,0 +1,44 @@
+export interface QuestionnaireInfo {
+    slug: string;
+    questionnaireId: string;
+    releaseId: string;
+    version: number;
+    title: string;
+    basePath: string;
+}
+export interface StopScreen {
+    questionKey: string;
+    clinicalTag: string;
+}
+export interface MedFunnelsQuestionnaireProps {
+    /** From `medfunnels.questionnaire("slug")` in a server component. */
+    questionnaire: QuestionnaireInfo;
+    /** Go here after answers are accepted (works from server components). */
+    redirectTo?: string;
+    /** Go here when a stop screen is reached. */
+    stopRedirectTo?: string;
+    /** Override colors and shape: accent, text, muted, background, surface, border, error (hex), radius (0–32), font (system | serif | rounded). */
+    theme?: Record<string, string | number>;
+    labels?: Record<string, string>;
+    /** Restore a patient's in-progress answers (pair with onState). */
+    initialAnswers?: Record<string, unknown>;
+    className?: string;
+    onSubmitted?: () => void;
+    onEnd?: (stop: StopScreen) => void;
+    onReady?: () => void;
+    onBack?: () => void;
+    onProgress?: (progress: {
+        page: number;
+        pages: number;
+        answered: number;
+        total: number;
+    }) => void;
+    /** Passing it turns on a live copy of in-progress answers, for restoring a session. */
+    onState?: (state: {
+        answers: Record<string, unknown>;
+        screen: unknown;
+    }) => void;
+    /** frame_timeout | frame_navigated | release_mismatch | submit_failed */
+    onError?: (code: string, detail?: string) => void;
+}
+export declare function MedFunnelsQuestionnaire(props: MedFunnelsQuestionnaireProps): import("react").JSX.Element;

package/dist/client.js

@@ -0,0 +1,55 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+// <MedFunnelsQuestionnaire>: mounts a verified questionnaire from your own routes inside an opaque-origin
+// sandbox (no access to your cookies, storage or APIs) and posts answers to your submit route.
+import { useEffect, useRef } from "react";
+import { mountQuestionnaire } from "./vendor/embed.js";
+export function MedFunnelsQuestionnaire(props) {
+    const container = useRef(null);
+    const latest = useRef(props);
+    latest.current = props;
+    const { slug, releaseId, basePath, title } = props.questionnaire;
+    const observe = Boolean(props.onState);
+    useEffect(() => {
+        const element = container.current;
+        if (!element)
+            return;
+        const base = `${basePath.replace(/\/+$/, "")}/${encodeURIComponent(slug)}`;
+        const mounted = mountQuestionnaire({
+            container: element,
+            frameUrl: `${base}/frame`,
+            releaseId,
+            title,
+            theme: latest.current.theme,
+            labels: latest.current.labels,
+            initialAnswers: latest.current.initialAnswers,
+            onSubmit: async (response) => {
+                const reply = await fetch(`${base}/submit`, {
+                    method: "POST",
+                    credentials: "same-origin",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify(response),
+                });
+                const result = await reply.json().catch(() => ({ ok: false, errors: {} }));
+                if (result.ok) {
+                    latest.current.onSubmitted?.();
+                    if (latest.current.redirectTo)
+                        window.location.assign(latest.current.redirectTo);
+                }
+                return result;
+            },
+            onEnd: (stop) => {
+                latest.current.onEnd?.(stop);
+                if (latest.current.stopRedirectTo)
+                    window.location.assign(latest.current.stopRedirectTo);
+            },
+            onReady: () => latest.current.onReady?.(),
+            onBack: () => latest.current.onBack?.(),
+            onProgress: (progress) => latest.current.onProgress?.(progress),
+            onState: observe ? (state) => latest.current.onState?.(state) : undefined,
+            onError: (code, detail) => latest.current.onError?.(code, detail),
+        });
+        return () => mounted.destroy();
+    }, [slug, releaseId, basePath, title, observe]);
+    return _jsx("div", { ref: container, className: props.className, "data-medfunnels": slug });
+}

package/dist/config.d.ts

@@ -0,0 +1,28 @@
+/** medfunnels.config.json, committed to your repository. Contains no secrets. */
+export interface MedFunnelsConfig {
+    /** API base URL. Defaults to https://www.medfunnels.app; MEDFUNNELS_API overrides it. */
+    api?: string;
+    /** Your workspace's organization ID: releases from any other workspace are rejected. */
+    organizationId: string;
+    /** Pinned signing keys (key id → public key) from the developer guide. Never fetched at runtime. */
+    signingKeys: Record<string, string>;
+    /** The website this build serves, e.g. https://intake.example.com. MEDFUNNELS_SITE_ORIGIN overrides it (use it for Staging). */
+    siteOrigin?: string;
+    /** Only sync these questionnaires (by slug). Default: every questionnaire the credential can read. */
+    questionnaires?: string[];
+    /** Pin versions (slug → version). Unpinned questionnaires use their latest published version. */
+    versions?: Record<string, number>;
+    /** Question kinds your backend accepts. Default: every kind this package can validate. */
+    supportedKinds?: string[];
+    /** Where your frame and submit routes live. Default "/medfunnels". */
+    basePath?: string;
+    /** Where `medfunnels pull` writes verified releases. Default ".medfunnels". */
+    output?: string;
+}
+export declare const CONFIG_FILE = "medfunnels.config.json";
+export declare const DEFAULT_API = "https://www.medfunnels.app";
+export declare const DEFAULT_BASE_PATH = "/medfunnels";
+export declare const DEFAULT_OUTPUT = ".medfunnels";
+export declare const ALL_KINDS: string[];
+export declare function loadConfig(cwd: string): MedFunnelsConfig;
+export declare function siteOrigin(config: MedFunnelsConfig, env?: Record<string, string | undefined>): string | undefined;

package/dist/config.js

@@ -0,0 +1,24 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+export const CONFIG_FILE = "medfunnels.config.json";
+export const DEFAULT_API = "https://www.medfunnels.app";
+export const DEFAULT_BASE_PATH = "/medfunnels";
+export const DEFAULT_OUTPUT = ".medfunnels";
+export const ALL_KINDS = ["boolean", "date", "end", "multi_choice", "number", "single_choice", "statement", "text", "textarea"];
+export function loadConfig(cwd) {
+    let raw;
+    try {
+        raw = readFileSync(join(cwd, CONFIG_FILE), "utf8");
+    }
+    catch {
+        throw new Error(`No ${CONFIG_FILE} in ${cwd}. Run \`npx medfunnels init\` first.`);
+    }
+    const config = JSON.parse(raw);
+    if (!config.organizationId || !config.signingKeys || !Object.keys(config.signingKeys).length) {
+        throw new Error(`${CONFIG_FILE} needs organizationId and signingKeys. Copy them from the developer guide in medFunnels (Integrations → Developer guide).`);
+    }
+    return config;
+}
+export function siteOrigin(config, env = process.env) {
+    return env.MEDFUNNELS_SITE_ORIGIN || config.siteOrigin || undefined;
+}

package/dist/pull.d.ts

@@ -0,0 +1,26 @@
+import { type Envelope } from "@medfunnels/sdk";
+import { type MedFunnelsConfig } from "./config.js";
+export interface ReleaseFile {
+    generatedAt: string;
+    questionnaires: Record<string, {
+        envelope: Envelope;
+        artifacts: {
+            "questionnaire.js": string;
+            "definition.json": string;
+        };
+    }>;
+}
+export interface PullOptions {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    config?: MedFunnelsConfig;
+    log?: (message: string) => void;
+}
+export declare function pull(options?: PullOptions): Promise<{
+    file: string;
+    questionnaires: Array<{
+        slug: string;
+        version: number;
+        releaseId: string;
+    }>;
+}>;

package/dist/pull.js

@@ -0,0 +1,73 @@
+// `medfunnels pull`: download, verify and store the releases this build will serve. Run it before `next build`
+// (and `next dev`). Any release that fails verification fails the build: nothing unverified reaches patients.
+import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { MedFunnelsClient, verifyRelease } from "@medfunnels/sdk";
+import { ALL_KINDS, DEFAULT_API, DEFAULT_OUTPUT, loadConfig, siteOrigin } from "./config.js";
+const decoder = new TextDecoder("utf-8", { fatal: true });
+export async function pull(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const env = options.env ?? process.env;
+    const log = options.log ?? ((message) => console.log(message));
+    const config = options.config ?? loadConfig(cwd);
+    const clientId = env.MEDFUNNELS_CLIENT_ID;
+    const clientSecret = env.MEDFUNNELS_CLIENT_SECRET;
+    if (!clientId || !clientSecret) {
+        throw new Error("Set MEDFUNNELS_CLIENT_ID and MEDFUNNELS_CLIENT_SECRET (from medFunnels → Integrations → Credentials) in this environment.");
+    }
+    const client = new MedFunnelsClient({ baseUrl: env.MEDFUNNELS_API || config.api || DEFAULT_API, clientId, clientSecret });
+    const available = [];
+    let cursor;
+    do {
+        const page = await client.listQuestionnaires({ cursor, limit: 100 });
+        available.push(...page.questionnaires);
+        cursor = page.nextCursor ?? undefined;
+    } while (cursor);
+    const wanted = config.questionnaires ?? available.map((item) => item.slug);
+    const missing = wanted.filter((slug) => !available.some((item) => item.slug === slug));
+    if (missing.length)
+        throw new Error(`Not found or not published for this credential: ${missing.join(", ")}.`);
+    const output = { generatedAt: new Date().toISOString(), questionnaires: {} };
+    const summary = [];
+    for (const slug of [...wanted].sort()) {
+        const questionnaire = available.find((item) => item.slug === slug);
+        const pinned = config.versions?.[slug];
+        let release = questionnaire.latestRelease;
+        if (pinned !== undefined) {
+            const releases = (await client.listReleases(questionnaire.id)).releases;
+            release = releases.find((item) => item.version === pinned);
+            if (!release)
+                throw new Error(`${slug}: version ${pinned} (pinned in config) doesn't exist.`);
+            if (release.status !== "published")
+                throw new Error(`${slug}: version ${pinned} (pinned in config) was withdrawn. Pin another version.`);
+        }
+        if (!release) {
+            log(`  skipped ${slug}: nothing published yet`);
+            continue;
+        }
+        const envelope = (await client.getManifest(release.id));
+        const artifacts = {
+            "questionnaire.js": await client.downloadArtifact(release.id, "questionnaire.js"),
+            "definition.json": await client.downloadArtifact(release.id, "definition.json"),
+        };
+        const verified = verifyRelease(envelope, artifacts, {
+            trustedKeys: config.signingKeys,
+            supportedKinds: config.supportedKinds ?? ALL_KINDS,
+            expectedOrganizationId: config.organizationId,
+            expectedOrigin: siteOrigin(config, env),
+        });
+        output.questionnaires[slug] = {
+            envelope,
+            artifacts: { "questionnaire.js": decoder.decode(artifacts["questionnaire.js"]), "definition.json": decoder.decode(artifacts["definition.json"]) },
+        };
+        summary.push({ slug, version: verified.version, releaseId: verified.releaseId });
+        log(`  verified ${slug} v${verified.version}${pinned !== undefined ? " (pinned)" : ""}`);
+    }
+    const directory = join(cwd, config.output ?? DEFAULT_OUTPUT);
+    mkdirSync(directory, { recursive: true });
+    writeFileSync(join(directory, ".gitignore"), "# Generated by `medfunnels pull` on every build.\n*\n");
+    const file = join(directory, "releases.json");
+    writeFileSync(`${file}.tmp`, JSON.stringify(output));
+    renameSync(`${file}.tmp`, file);
+    return { file, questionnaires: summary };
+}

package/dist/server.d.ts

@@ -0,0 +1,44 @@
+import { type NormalizedAnswer, type VerifiedRelease } from "@medfunnels/sdk";
+import { type MedFunnelsConfig } from "./config.js";
+import type { ReleaseFile } from "./pull.js";
+export type { MedFunnelsConfig } from "./config.js";
+export type { NormalizedAnswer } from "@medfunnels/sdk";
+/** What a page passes to <MedFunnelsQuestionnaire>. Contains no bundle or answers, so it's safe to send to the browser. */
+export interface QuestionnaireInfo {
+    slug: string;
+    questionnaireId: string;
+    releaseId: string;
+    version: number;
+    title: string;
+    basePath: string;
+}
+export interface SubmitContext {
+    request: Request;
+    questionnaire: QuestionnaireInfo;
+    release: VerifiedRelease;
+}
+/** Return nothing to accept, or { ok: false, message } to show the patient an error (e.g. their session expired). */
+export type SubmitHandler = (answers: NormalizedAnswer[], context: SubmitContext) => void | {
+    ok: false;
+    message?: string;
+} | Promise<void | {
+    ok: false;
+    message?: string;
+}>;
+type RouteContext = {
+    params: Promise<{
+        slug: string;
+    }> | {
+        slug: string;
+    };
+};
+export declare function createMedFunnels(options: {
+    config: MedFunnelsConfig;
+    releases: ReleaseFile | Record<string, unknown>;
+}): {
+    questionnaire: (slug: string) => QuestionnaireInfo;
+    release: (slug: string) => VerifiedRelease | null;
+    frameRoute: (_request: Request, context: RouteContext) => Promise<Response>;
+    submitRoute: (handler: SubmitHandler) => (request: Request, context: RouteContext) => Promise<Response>;
+    basePath: string;
+};

package/dist/server.js

@@ -0,0 +1,84 @@
+// Route handlers for the Next.js App Router (web-standard Request/Response, Node.js runtime).
+// Releases are re-verified once per server process before anything is served. Answers are validated against
+// the verified definition and handed to your callback; this module never logs or stores them.
+import { ContractError, buildFrame, validateResponse, verifyRelease } from "@medfunnels/sdk";
+import { ALL_KINDS, DEFAULT_BASE_PATH, siteOrigin } from "./config.js";
+const MAX_BODY_BYTES = 256 * 1024;
+const encoder = new TextEncoder();
+const json = (body, status = 200) => new Response(JSON.stringify(body), { status, headers: { "Content-Type": "application/json", "Cache-Control": "no-store" } });
+export function createMedFunnels(options) {
+    const { config } = options;
+    const file = options.releases;
+    const basePath = (config.basePath ?? DEFAULT_BASE_PATH).replace(/\/+$/, "");
+    const verified = new Map();
+    function release(slug) {
+        const cached = verified.get(slug);
+        if (cached)
+            return cached;
+        const entry = file?.questionnaires?.[slug];
+        if (!entry)
+            return null;
+        const result = verifyRelease(entry.envelope, { "questionnaire.js": encoder.encode(entry.artifacts["questionnaire.js"]), "definition.json": encoder.encode(entry.artifacts["definition.json"]) }, { trustedKeys: config.signingKeys, supportedKinds: config.supportedKinds ?? ALL_KINDS, expectedOrganizationId: config.organizationId, expectedOrigin: siteOrigin(config) });
+        verified.set(slug, result);
+        return result;
+    }
+    function info(slug, verifiedRelease) {
+        return { slug, questionnaireId: verifiedRelease.questionnaireId, releaseId: verifiedRelease.releaseId, version: verifiedRelease.version, title: verifiedRelease.manifest.questionnaire.name, basePath };
+    }
+    /** For a page: the props <MedFunnelsQuestionnaire questionnaire={…}> needs. */
+    function questionnaire(slug) {
+        const found = release(slug);
+        if (!found) {
+            const known = Object.keys(file?.questionnaires ?? {});
+            throw new Error(`No synced questionnaire "${slug}". Run \`medfunnels pull\`. Available: ${known.join(", ") || "none"}.`);
+        }
+        return info(slug, found);
+    }
+    async function slugFrom(context) {
+        return (await context.params).slug;
+    }
+    /** GET {basePath}/[slug]/frame: the sandboxed questionnaire page, with its exact security headers. */
+    async function frameRoute(_request, context) {
+        const found = release(await slugFrom(context));
+        if (!found)
+            return new Response("Not found", { status: 404 });
+        const { html, headers } = buildFrame(found.bundle, { title: found.manifest.questionnaire.name });
+        // The page is UTF-8; a string body is encoded back to exactly these bytes.
+        return new Response(new TextDecoder().decode(html), { status: 200, headers });
+    }
+    /** POST {basePath}/[slug]/submit: validate the answers, then call your handler with them. */
+    function submitRoute(handler) {
+        return async function POST(request, context) {
+            const slug = await slugFrom(context);
+            const found = release(slug);
+            if (!found)
+                return json({ ok: false, errors: { _: "This questionnaire isn't available." } }, 404);
+            if (!(request.headers.get("content-type") ?? "").includes("application/json"))
+                return json({ ok: false, errors: { _: "Expected JSON." } }, 415);
+            const body = await request.text();
+            if (encoder.encode(body).length > MAX_BODY_BYTES)
+                return json({ ok: false, errors: { _: "Too large." } }, 413);
+            let answers;
+            try {
+                answers = validateResponse(found.definition, JSON.parse(body), { questionnaireId: found.questionnaireId, releaseId: found.releaseId });
+            }
+            catch (error) {
+                if (error instanceof ContractError)
+                    return json({ ok: false, errors: error.errors }, 422);
+                return json({ ok: false, errors: { _: "Answers couldn't be read." } }, 400);
+            }
+            try {
+                const result = await handler(answers, { request, questionnaire: info(slug, found), release: found });
+                if (result && result.ok === false)
+                    return json({ ok: false, errors: { _: result.message ?? "Your answers couldn't be saved." } }, 409);
+            }
+            catch (error) {
+                // Never log the answers or request body: they're patient data.
+                console.error(`[medfunnels] submit handler failed for ${slug}: ${error instanceof Error ? error.name : "error"}`);
+                return json({ ok: false, errors: { _: "Your answers couldn't be saved. Please try again." } }, 500);
+            }
+            return json({ ok: true });
+        };
+    }
+    return { questionnaire, release, frameRoute, submitRoute, basePath };
+}

package/dist/vendor/embed.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @typedef {{ contract: string, questionnaireId: string, releaseId: string, version: number, answers: Array<{ questionKey: string, kind: string, value: unknown }> }} QuestionnaireResponse
+ * @typedef {{ ok: true } | { ok: false, errors?: Record<string, string>, message?: string }} SubmitResult
+ * @typedef {{
+ *   container: HTMLElement,
+ *   frameUrl: string,
+ *   releaseId: string,
+ *   title: string,
+ *   theme?: Record<string, string | number>,
+ *   labels?: Record<string, string>,
+ *   initialAnswers?: Record<string, unknown>,
+ *   onSubmit: (response: QuestionnaireResponse) => Promise<SubmitResult>,
+ *   onBack?: () => void,
+ *   onEnd?: (stop: { questionKey: string, clinicalTag: string }) => void,
+ *   onProgress?: (progress: { page: number, pages: number, answered: number, total: number }) => void,
+ *   onReady?: () => void,
+ *   onError?: (code: string, detail?: string) => void,
+ *   onState?: (state: { answers: Record<string, unknown>, screen: { id: string, type: string, questionKeys: string[] } | null }) => void,
+ *   readyTimeoutMs?: number,
+ *   documentRef?: Document,
+ *   windowRef?: Window,
+ * }} MountOptions
+ */
+/**
+ * @param {MountOptions} options
+ */
+export function mountQuestionnaire(options: MountOptions): {
+    destroy: () => void;
+    iframe: HTMLIFrameElement;
+    goto: (questionKey: string) => void;
+};
+export const EMBED_PROTOCOL: 1;
+export const FRAME_SANDBOX: "allow-scripts allow-forms";
+export type QuestionnaireResponse = {
+    contract: string;
+    questionnaireId: string;
+    releaseId: string;
+    version: number;
+    answers: Array<{
+        questionKey: string;
+        kind: string;
+        value: unknown;
+    }>;
+};
+export type SubmitResult = {
+    ok: true;
+} | {
+    ok: false;
+    errors?: Record<string, string>;
+    message?: string;
+};
+export type MountOptions = {
+    container: HTMLElement;
+    frameUrl: string;
+    releaseId: string;
+    title: string;
+    theme?: Record<string, string | number>;
+    labels?: Record<string, string>;
+    initialAnswers?: Record<string, unknown>;
+    onSubmit: (response: QuestionnaireResponse) => Promise<SubmitResult>;
+    onBack?: () => void;
+    onEnd?: (stop: {
+        questionKey: string;
+        clinicalTag: string;
+    }) => void;
+    onProgress?: (progress: {
+        page: number;
+        pages: number;
+        answered: number;
+        total: number;
+    }) => void;
+    onReady?: () => void;
+    onError?: (code: string, detail?: string) => void;
+    onState?: (state: {
+        answers: Record<string, unknown>;
+        screen: {
+            id: string;
+            type: string;
+            questionKeys: string[];
+        } | null;
+    }) => void;
+    readyTimeoutMs?: number;
+    documentRef?: Document;
+    windowRef?: Window;
+};

package/dist/vendor/embed.js

@@ -0,0 +1,157 @@
+// @ts-check
+// medicalforms.ai embed controller — runs in the CUSTOMER's page (the host).
+//
+// Mounts a verified questionnaire frame served by the customer's own backend inside an
+// opaque-origin sandbox, and relays messages. It never contacts medicalforms.ai and never
+// sends data anywhere itself: submission is delegated to the host's `onSubmit` callback.
+export const EMBED_PROTOCOL = 1;
+export const FRAME_SANDBOX = "allow-scripts allow-forms";
+const MIN_HEIGHT = 240;
+const MAX_HEIGHT = 20000;
+function randomNonce() {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+ * @typedef {{ contract: string, questionnaireId: string, releaseId: string, version: number, answers: Array<{ questionKey: string, kind: string, value: unknown }> }} QuestionnaireResponse
+ * @typedef {{ ok: true } | { ok: false, errors?: Record<string, string>, message?: string }} SubmitResult
+ * @typedef {{
+ *   container: HTMLElement,
+ *   frameUrl: string,
+ *   releaseId: string,
+ *   title: string,
+ *   theme?: Record<string, string | number>,
+ *   labels?: Record<string, string>,
+ *   initialAnswers?: Record<string, unknown>,
+ *   onSubmit: (response: QuestionnaireResponse) => Promise<SubmitResult>,
+ *   onBack?: () => void,
+ *   onEnd?: (stop: { questionKey: string, clinicalTag: string }) => void,
+ *   onProgress?: (progress: { page: number, pages: number, answered: number, total: number }) => void,
+ *   onReady?: () => void,
+ *   onError?: (code: string, detail?: string) => void,
+ *   onState?: (state: { answers: Record<string, unknown>, screen: { id: string, type: string, questionKeys: string[] } | null }) => void,
+ *   readyTimeoutMs?: number,
+ *   documentRef?: Document,
+ *   windowRef?: Window,
+ * }} MountOptions
+ */
+/**
+ * @param {MountOptions} options
+ */
+export function mountQuestionnaire(options) {
+    const doc = options.documentRef || document;
+    const win = options.windowRef || window;
+    if (!options.frameUrl.startsWith("/"))
+        throw new Error("frameUrl must be a same-origin path served by your backend.");
+    const nonce = randomNonce();
+    const iframe = /** @type {HTMLIFrameElement} */ (doc.createElement("iframe"));
+    // Never add allow-same-origin: the frame must not reach the host's cookies, storage, or APIs.
+    iframe.setAttribute("sandbox", FRAME_SANDBOX);
+    iframe.setAttribute("referrerpolicy", "no-referrer");
+    iframe.setAttribute("allow", "");
+    iframe.setAttribute("title", options.title);
+    iframe.setAttribute("loading", "eager");
+    iframe.className = "medicalforms-frame";
+    iframe.style.width = "100%";
+    iframe.style.border = "0";
+    iframe.style.display = "block";
+    iframe.style.height = `${MIN_HEIGHT}px`;
+    let loads = 0;
+    let ready = false;
+    let destroyed = false;
+    let submitting = false;
+    const fail = (/** @type {string} */ code, /** @type {string} */ detail = "") => {
+        if (destroyed)
+            return;
+        destroy();
+        options.onError?.(code, detail);
+    };
+    const post = (/** @type {Record<string, unknown>} */ message) => {
+        // "*" is required for an opaque-origin frame; the recipient is pinned by window reference
+        // and we stop talking to it if it ever navigates (see the load counter).
+        iframe.contentWindow?.postMessage({ ...message, protocol: EMBED_PROTOCOL, nonce }, "*");
+    };
+    const timer = win.setTimeout(() => { if (!ready)
+        fail("frame_timeout", "Questionnaire did not start."); }, options.readyTimeoutMs ?? 15000);
+    iframe.addEventListener("load", () => {
+        loads += 1;
+        if (loads > 1)
+            fail("frame_navigated", "Questionnaire frame navigated unexpectedly.");
+    });
+    /** @param {MessageEvent} event */
+    const onMessage = async (event) => {
+        if (destroyed || event.source !== iframe.contentWindow || event.origin !== "null")
+            return;
+        const data = event.data;
+        if (!data || typeof data !== "object" || data.protocol !== EMBED_PROTOCOL || typeof data.type !== "string")
+            return;
+        if (data.type === "mf:ready") {
+            if (ready)
+                return;
+            if (data.releaseId !== options.releaseId)
+                return fail("release_mismatch", "Frame is running a different release.");
+            ready = true;
+            win.clearTimeout(timer);
+            post({ type: "mf:init", theme: options.theme || {}, labels: options.labels || {}, initialAnswers: options.initialAnswers || null, observe: Boolean(options.onState) });
+            options.onReady?.();
+            return;
+        }
+        if (!ready || data.nonce !== nonce)
+            return;
+        if (data.type === "mf:resize" && typeof data.height === "number") {
+            iframe.style.height = `${Math.min(MAX_HEIGHT, Math.max(MIN_HEIGHT, Math.ceil(data.height)))}px`;
+        }
+        else if (data.type === "mf:progress") {
+            options.onProgress?.({ page: Number(data.page) || 1, pages: Number(data.pages) || 1, answered: Number(data.answered) || 0, total: Number(data.total) || 0 });
+        }
+        else if (data.type === "mf:state" && options.onState) {
+            options.onState({ answers: data.answers && typeof data.answers === "object" ? data.answers : {}, screen: data.screen || null });
+        }
+        else if (data.type === "mf:end") {
+            // The patient reached a stop screen. No answers are attached; your server decides next steps.
+            options.onEnd?.({ questionKey: String(data.questionKey || ""), clinicalTag: String(data.clinicalTag || "") });
+        }
+        else if (data.type === "mf:back") {
+            options.onBack?.();
+        }
+        else if (data.type === "mf:submit" && !submitting) {
+            const response = data.response;
+            if (!response || response.releaseId !== options.releaseId || !Array.isArray(response.answers)) {
+                post({ type: "mf:submit-result", ok: false, errors: {} });
+                return;
+            }
+            submitting = true;
+            try {
+                const result = await options.onSubmit(response);
+                if (!destroyed)
+                    post({ type: "mf:submit-result", ...result });
+            }
+            catch (error) {
+                if (!destroyed)
+                    post({ type: "mf:submit-result", ok: false, errors: {} });
+                options.onError?.("submit_failed", error instanceof Error ? error.message : "");
+            }
+            finally {
+                submitting = false;
+            }
+        }
+    };
+    function destroy() {
+        destroyed = true;
+        win.clearTimeout(timer);
+        win.removeEventListener("message", onMessage);
+        iframe.remove();
+    }
+    win.addEventListener("message", onMessage);
+    // Set src before insertion so the browser never loads an initial about:blank document,
+    // which would otherwise count as a navigation.
+    iframe.setAttribute("src", options.frameUrl);
+    options.container.replaceChildren(iframe);
+    /** Jump the questionnaire to the screen containing a question (used by authoring tools). */
+    function goto(/** @type {string} */ questionKey) {
+        if (ready && !destroyed)
+            post({ type: "mf:goto", questionKey });
+    }
+    return { destroy, iframe, goto };
+}

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@medfunnels/next",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Run medFunnels questionnaires in your Next.js app: build-time sync, route handlers and a React component.",
+  "license": "MIT",
+  "homepage": "https://www.medfunnels.app",
+  "keywords": [
+    "medfunnels",
+    "nextjs",
+    "react",
+    "telehealth",
+    "questionnaire",
+    "intake"
+  ],
+  "type": "module",
+  "bin": {
+    "medfunnels": "./dist/cli.js"
+  },
+  "exports": {
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./pull": {
+      "types": "./dist/pull.d.ts",
+      "import": "./dist/pull.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "scripts": {
+    "build": "rm -rf dist && node scripts/copy-embed.mjs && tsc -p tsconfig.json && chmod +x dist/cli.js",
+    "test": "node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "@medfunnels/sdk": "^1.0.0"
+  },
+  "peerDependencies": {
+    "next": ">=14",
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  }
+}