@medfunnels/sdk 0.0.0-stage → 1.0.0

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,34 @@
-# Temporary Holding Version
+# @medfunnels/sdk
 
-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.
+Server-side building blocks for running [medFunnels](https://www.medfunnels.app) questionnaires on your own
+platform from Node.js: an Integration API client, release verification, the sandboxed frame, and authoritative
+answer validation. **Using Next.js? Install [`@medfunnels/next`](https://www.npmjs.com/package/@medfunnels/next) instead.**
+
+```bash
+npm install @medfunnels/sdk
+```
+
+```ts
+import { MedFunnelsClient, buildFrame, validateResponse, verifyRelease } from "@medfunnels/sdk";
+
+const client = new MedFunnelsClient({ baseUrl: "https://www.medfunnels.app", clientId, clientSecret });
+const { updates } = await client.releaseUpdates({ cursor });
+const envelope = await client.getManifest(updates[0].id);
+const artifacts = {
+    "questionnaire.js": await client.downloadArtifact(updates[0].id, "questionnaire.js"),
+    "definition.json": await client.downloadArtifact(updates[0].id, "definition.json"),
+};
+const release = verifyRelease(envelope, artifacts, {
+    trustedKeys: PINNED_KEYS,          // from your developer guide; never fetched at runtime
+    supportedKinds: SUPPORTED_KINDS,
+    expectedOrganizationId: ORGANIZATION_ID,
+    expectedOrigin: "https://intake.example.com",
+});
+
+const { html, headers } = buildFrame(release.bundle, { title: release.manifest.questionnaire.name });  // serve both unchanged
+const answers = validateResponse(release.definition, submitted, { questionnaireId: release.questionnaireId, releaseId: release.releaseId });
+```
+
+The client is read-only: there is no method that sends patient data. It mirrors the Python SDK
+([`medfunnels`](https://pypi.org/project/medfunnels/)) function for function, and both pass the same conformance
+cases. Requires Node.js 18.17 or later. The full guide is in medFunnels under **Integrations → Developer guide**.

package/dist/canonical.d.ts

@@ -0,0 +1,5 @@
+export declare function canonicalJson(value: unknown): Uint8Array;
+export declare function sha256Hex(data: Uint8Array): string;
+/** Value for a CSP `script-src 'sha256-…'` source matching an inline script with exactly these bytes. */
+export declare function cspHash(script: Uint8Array): string;
+export declare function b64urlDecode(value: string): Uint8Array;

package/dist/canonical.js

@@ -0,0 +1,53 @@
+// Canonical JSON used for manifest signatures. Byte-identical to the Python SDK's
+// json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+// for the values manifests contain. Signed manifests never contain decimal numbers (JavaScript can't
+// tell 1.0 from 1), so non-integers are rejected rather than silently encoded differently.
+import { createHash } from "node:crypto";
+const encoder = new TextEncoder();
+/** Python sorts dict keys by code point; JavaScript's default sort compares UTF-16 units. */
+function compareCodePoints(a, b) {
+    const left = Array.from(a);
+    const right = Array.from(b);
+    for (let i = 0; i < Math.min(left.length, right.length); i += 1) {
+        const diff = (left[i].codePointAt(0) ?? 0) - (right[i].codePointAt(0) ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return left.length - right.length;
+}
+function serialize(value) {
+    if (value === null)
+        return "null";
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "number") {
+        if (!Number.isSafeInteger(value))
+            throw new TypeError("Canonical JSON supports integers only.");
+        return String(value === 0 ? 0 : value);
+    }
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(serialize).join(",")}]`;
+    if (typeof value === "object") {
+        const entries = Object.keys(value)
+            .filter((key) => value[key] !== undefined)
+            .sort(compareCodePoints)
+            .map((key) => `${JSON.stringify(key)}:${serialize(value[key])}`);
+        return `{${entries.join(",")}}`;
+    }
+    throw new TypeError(`Canonical JSON can't encode ${typeof value}.`);
+}
+export function canonicalJson(value) {
+    return encoder.encode(serialize(value));
+}
+export function sha256Hex(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+/** Value for a CSP `script-src 'sha256-…'` source matching an inline script with exactly these bytes. */
+export function cspHash(script) {
+    return `sha256-${createHash("sha256").update(script).digest("base64")}`;
+}
+export function b64urlDecode(value) {
+    return new Uint8Array(Buffer.from(value, "base64url"));
+}

package/dist/client.d.ts

@@ -0,0 +1,42 @@
+export type IntegrationErrorCode = "network" | "auth" | "forbidden" | "not_found" | "rate_limited" | "server" | "protocol" | "plan_required";
+export declare class IntegrationError extends Error {
+    readonly code: IntegrationErrorCode;
+    readonly status: number;
+    readonly requestId: string;
+    constructor(code: IntegrationErrorCode, message: string, options?: {
+        status?: number;
+        requestId?: string;
+    });
+}
+export interface ClientOptions {
+    baseUrl: string;
+    clientId: string;
+    clientSecret: string;
+    timeoutMs?: number;
+}
+export declare class MedFunnelsClient {
+    #private;
+    readonly baseUrl: string;
+    readonly clientId: string;
+    constructor(options: ClientOptions);
+    /** Never print the secret in logs. */
+    toJSON(): {
+        baseUrl: string;
+        clientId: string;
+    };
+    testConnection(): Promise<Record<string, any>>;
+    listQuestionnaires(options?: {
+        query?: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<Record<string, any>>;
+    getQuestionnaire(questionnaireId: string): Promise<Record<string, any>>;
+    listReleases(questionnaireId: string, options?: {
+        afterVersion?: number;
+    }): Promise<Record<string, any>>;
+    releaseUpdates(options?: {
+        cursor?: string;
+    }): Promise<Record<string, any>>;
+    getManifest(releaseId: string): Promise<Record<string, any>>;
+    downloadArtifact(releaseId: string, name: string): Promise<Uint8Array>;
+}

package/dist/client.js

@@ -0,0 +1,118 @@
+// Server-side client for the medFunnels Integration API v1. Runs on your backend only: the client secret must
+// never reach a browser. Read operations only; there is deliberately no method that sends patient data.
+const USER_AGENT = "medfunnels-node/1.0";
+export class IntegrationError extends Error {
+    code;
+    status;
+    requestId;
+    constructor(code, message, options = {}) {
+        super(message);
+        this.name = "IntegrationError";
+        this.code = code;
+        this.status = options.status ?? 0;
+        this.requestId = options.requestId ?? "";
+    }
+}
+const STATUS_CODES = { 400: "protocol", 401: "auth", 402: "plan_required", 403: "forbidden", 404: "not_found", 429: "rate_limited" };
+export class MedFunnelsClient {
+    baseUrl;
+    clientId;
+    #clientSecret;
+    #timeoutMs;
+    #token = null;
+    constructor(options) {
+        const url = new URL(options.baseUrl);
+        if (url.protocol !== "https:" && !["localhost", "127.0.0.1"].includes(url.hostname)) {
+            throw new Error("The medFunnels API endpoint must use https.");
+        }
+        this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.clientId = options.clientId;
+        this.#clientSecret = options.clientSecret;
+        this.#timeoutMs = options.timeoutMs ?? 15_000;
+    }
+    /** Never print the secret in logs. */
+    toJSON() {
+        return { baseUrl: this.baseUrl, clientId: this.clientId };
+    }
+    async #send(method, path, init = {}) {
+        let response;
+        try {
+            response = await fetch(this.baseUrl + path, {
+                method,
+                body: init.body,
+                headers: { "User-Agent": USER_AGENT, Accept: "application/json", ...init.headers },
+                signal: AbortSignal.timeout(this.#timeoutMs),
+                redirect: "error",
+            });
+        }
+        catch (error) {
+            throw new IntegrationError("network", `Could not reach medFunnels: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (response.ok)
+            return response;
+        const requestId = response.headers.get("X-Request-Id") ?? "";
+        let detail = "";
+        try {
+            const data = (await response.json());
+            const error = data.error;
+            detail = typeof error === "object" && error !== null ? String(error.message ?? "") : String(data.detail ?? data.error_description ?? "");
+        }
+        catch {
+            detail = "";
+        }
+        const code = STATUS_CODES[response.status] ?? (response.status >= 500 ? "server" : "protocol");
+        throw new IntegrationError(code, detail || `HTTP ${response.status}`, { status: response.status, requestId });
+    }
+    async #accessToken() {
+        if (this.#token && this.#token.expiresAt - 30_000 > Date.now())
+            return this.#token.value;
+        const basic = Buffer.from(`${this.clientId}:${this.#clientSecret}`).toString("base64");
+        const response = await this.#send("POST", "/api/v1/oauth/token", {
+            body: new URLSearchParams({ grant_type: "client_credentials" }).toString(),
+            headers: { Authorization: `Basic ${basic}`, "Content-Type": "application/x-www-form-urlencoded" },
+        });
+        const data = (await response.json());
+        this.#token = { value: data.access_token, expiresAt: Date.now() + Number(data.expires_in ?? 300) * 1000 };
+        return this.#token.value;
+    }
+    async #get(path, params = {}, accept = "application/json") {
+        const query = new URLSearchParams(Object.entries(params).filter(([, v]) => v !== undefined && v !== "").map(([k, v]) => [k, String(v)])).toString();
+        const target = query ? `${path}?${query}` : path;
+        const request = async () => this.#send("GET", target, { headers: { Authorization: `Bearer ${await this.#accessToken()}`, Accept: accept } });
+        try {
+            return await request();
+        }
+        catch (error) {
+            if (error instanceof IntegrationError && error.code === "auth" && this.#token) {
+                this.#token = null; // revoked or expired early: retry once with a fresh token
+                return request();
+            }
+            throw error;
+        }
+    }
+    async #json(path, params) {
+        return (await (await this.#get(path, params)).json());
+    }
+    testConnection() {
+        return this.#json("/api/v1/integration/connection");
+    }
+    listQuestionnaires(options = {}) {
+        return this.#json("/api/v1/questionnaires", { q: options.query, cursor: options.cursor, limit: options.limit ?? 50 });
+    }
+    getQuestionnaire(questionnaireId) {
+        return this.#json(`/api/v1/questionnaires/${encodeURIComponent(questionnaireId)}`);
+    }
+    listReleases(questionnaireId, options = {}) {
+        return this.#json(`/api/v1/questionnaires/${encodeURIComponent(questionnaireId)}/releases`, { after_version: options.afterVersion || undefined });
+    }
+    releaseUpdates(options = {}) {
+        return this.#json("/api/v1/releases/updates", { cursor: options.cursor });
+    }
+    getManifest(releaseId) {
+        return this.#json(`/api/v1/releases/${encodeURIComponent(releaseId)}/manifest`);
+    }
+    async downloadArtifact(releaseId, name) {
+        const response = await this.#get(`/api/v1/releases/${encodeURIComponent(releaseId)}/artifacts/${encodeURIComponent(name)}`, {}, "*/*");
+        return new Uint8Array(await response.arrayBuffer());
+    }
+}

package/dist/contract.d.ts

@@ -0,0 +1,51 @@
+export declare const ANSWER_CONTRACT = "medicalforms.answers/v1";
+export type Answers = Record<string, unknown>;
+export interface Question {
+    key: string;
+    kind: string;
+    required?: boolean;
+    validation?: Record<string, unknown>;
+    options?: Array<{
+        key: string;
+        label: string;
+    }>;
+    visibleWhen?: unknown;
+    [field: string]: unknown;
+}
+export interface Definition {
+    pages: Array<{
+        key?: string;
+        visibleWhen?: unknown;
+        questions: Question[];
+        [field: string]: unknown;
+    }>;
+    [field: string]: unknown;
+}
+export interface NormalizedAnswer {
+    questionKey: string;
+    kind: string;
+    value: unknown;
+    /** Readable text for reviewers, e.g. option labels or "Yes". */
+    displayValue: string;
+    question: Question;
+}
+/** `errors` maps question keys (or "_" for the whole response) to messages to show the patient. */
+export declare class ContractError extends Error {
+    readonly errors: Record<string, string>;
+    constructor(errors: Record<string, string>);
+}
+export declare function isAnswered(value: unknown): boolean;
+export declare function evaluateCondition(condition: unknown, answers: Answers | Map<string, unknown>): boolean;
+export declare function visibleQuestions(definition: Definition, answers: Answers | Map<string, unknown>): Question[];
+export declare function answerError(question: Question, value: unknown): string;
+export declare function displayValue(question: Question, value: unknown): string;
+/**
+ * Validate a browser-submitted response against a verified definition. Rejects the wrong contract or release,
+ * unknown or duplicate questions, answers to questions the patient never saw, values outside the allowed
+ * options or ranges, missing required answers, and answers that reach a stop screen. Returns answers in
+ * definition order with display text for reviewers. Throws ContractError otherwise.
+ */
+export declare function validateResponse(definition: Definition, response: unknown, options: {
+    questionnaireId: string;
+    releaseId: string;
+}): NormalizedAnswer[];

package/dist/contract.js

@@ -0,0 +1,239 @@
+// Server-side answer contract (`medicalforms.answers/v1`), a line-by-line port of the Python SDK's contract.py.
+// Call validateResponse on your own server with the definition you synced and verified. The browser's checks
+// are a convenience only; this is the authority. Both SDKs pass the same cases in sdk/conformance.
+export const ANSWER_CONTRACT = "medicalforms.answers/v1";
+const CHOICE_KINDS = new Set(["single_choice", "multi_choice"]);
+const ANSWERABLE_KINDS = new Set(["text", "textarea", "single_choice", "multi_choice", "boolean", "number", "date"]);
+const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+const DEFAULT_MAX_TEXT = 2000;
+/** `errors` maps question keys (or "_" for the whole response) to messages to show the patient. */
+export class ContractError extends Error {
+    errors;
+    constructor(errors) {
+        super(Object.entries(errors).map(([key, message]) => `${key}: ${message}`).join("; "));
+        this.name = "ContractError";
+        this.errors = errors;
+    }
+}
+const isNumber = (value) => typeof value === "number" && Number.isFinite(value);
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const length = (text) => Array.from(text).length; // code points, like Python's len()
+/** Python's str() for numbers (e.g. 1e-05), so messages and display text match the Python SDK. */
+function numberText(value) {
+    if (Number.isInteger(value) || Math.abs(value) >= 1e-4)
+        return String(value);
+    const [mantissa, exponent] = value.toExponential().split("e");
+    const sign = exponent.startsWith("-") ? "-" : "+";
+    return `${mantissa}e${sign}${exponent.replace(/^[+-]/, "").padStart(2, "0")}`;
+}
+export function isAnswered(value) {
+    if (value === null || value === undefined)
+        return false;
+    if (typeof value === "boolean")
+        return true;
+    if (typeof value === "string")
+        return value.trim() !== "";
+    if (Array.isArray(value))
+        return value.length > 0;
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    return false;
+}
+/** Python equality, except booleans never equal numbers (mirrors the browser runtime). */
+function same(left, right) {
+    if (typeof left === "boolean" || typeof right === "boolean")
+        return left === right;
+    if (isNumber(left) && isNumber(right))
+        return left === right;
+    if (Array.isArray(left) && Array.isArray(right))
+        return left.length === right.length && left.every((item, i) => same(item, right[i]));
+    if (isObject(left) && isObject(right)) {
+        const keys = Object.keys(left);
+        return keys.length === Object.keys(right).length && keys.every((key) => key in right && same(left[key], right[key]));
+    }
+    return left === right;
+}
+function lookup(answers, key) {
+    if (typeof key !== "string")
+        return undefined;
+    return answers instanceof Map ? answers.get(key) : Object.prototype.hasOwnProperty.call(answers, key) ? answers[key] : undefined;
+}
+export function evaluateCondition(condition, answers) {
+    if (!isObject(condition))
+        return true;
+    const op = condition.op;
+    if (op === "all")
+        return (Array.isArray(condition.conditions) ? condition.conditions : []).every((item) => evaluateCondition(item, answers));
+    if (op === "any")
+        return (Array.isArray(condition.conditions) ? condition.conditions : []).some((item) => evaluateCondition(item, answers));
+    if (op === "not")
+        return !evaluateCondition(condition.condition, answers);
+    const value = lookup(answers, condition.question);
+    if (op === "answered")
+        return isAnswered(value);
+    if (!isAnswered(value))
+        return false;
+    const target = condition.value;
+    if (op === "equals")
+        return same(value, target);
+    if (op === "not_equals")
+        return !same(value, target);
+    if (op === "in")
+        return Array.isArray(condition.values) && condition.values.some((item) => same(value, item));
+    if (op === "includes")
+        return Array.isArray(value) && value.some((item) => same(item, target));
+    if (!isNumber(value) || !isNumber(target))
+        return false;
+    if (op === "gt")
+        return value > target;
+    if (op === "gte")
+        return value >= target;
+    if (op === "lt")
+        return value < target;
+    if (op === "lte")
+        return value <= target;
+    return false;
+}
+function pruneHidden(definition, answers) {
+    let current = new Map(answers);
+    for (let round = 0; round < 10; round += 1) {
+        const next = new Map();
+        for (const page of definition.pages) {
+            const pageVisible = evaluateCondition(page.visibleWhen, current);
+            for (const question of page.questions) {
+                if (pageVisible && evaluateCondition(question.visibleWhen, current) && current.has(question.key))
+                    next.set(question.key, current.get(question.key));
+            }
+        }
+        if (next.size === current.size)
+            return next;
+        current = next;
+    }
+    return current;
+}
+export function visibleQuestions(definition, answers) {
+    const pruned = pruneHidden(definition, answers instanceof Map ? answers : new Map(Object.entries(answers)));
+    return definition.pages
+        .filter((page) => evaluateCondition(page.visibleWhen, pruned))
+        .flatMap((page) => page.questions.filter((question) => evaluateCondition(question.visibleWhen, pruned)));
+}
+export function answerError(question, value) {
+    const kind = question.kind;
+    if (kind === "statement" || kind === "end")
+        return "";
+    // Like Python's question.get("required", True): absent means required, an explicit null means optional.
+    const required = "required" in question ? Boolean(question.required) : true;
+    if (!isAnswered(value))
+        return required ? "This question is required." : "";
+    const rules = isObject(question.validation) ? question.validation : {};
+    if (kind === "text" || kind === "textarea") {
+        if (typeof value !== "string")
+            return "Enter text.";
+        if (length(value) > Math.trunc(Number(rules.maxLength) || DEFAULT_MAX_TEXT))
+            return "Answer is too long.";
+    }
+    else if (kind === "number") {
+        if (!isNumber(value))
+            return "Enter a number.";
+        if (isNumber(rules.min) && value < rules.min)
+            return `Enter ${numberText(rules.min)} or more.`;
+        if (isNumber(rules.max) && value > rules.max)
+            return `Enter ${numberText(rules.max)} or less.`;
+    }
+    else if (kind === "date") {
+        if (typeof value !== "string" || !DATE_PATTERN.test(value))
+            return "Enter a date.";
+        if (rules.minDate && value < String(rules.minDate))
+            return "Enter a later date.";
+        if (rules.maxDate && value > String(rules.maxDate))
+            return "Enter an earlier date.";
+    }
+    else if (kind === "boolean") {
+        if (typeof value !== "boolean")
+            return "Choose yes or no.";
+    }
+    else if (CHOICE_KINDS.has(kind)) {
+        const keys = (question.options ?? []).map((option) => option.key);
+        if (kind === "single_choice" && !keys.includes(value))
+            return "Choose an option.";
+        if (kind === "multi_choice" && (!Array.isArray(value) || value.some((item) => !keys.includes(item)) || new Set(value).size !== value.length))
+            return "Choose from the options.";
+    }
+    return "";
+}
+export function displayValue(question, value) {
+    if (!isAnswered(value))
+        return "";
+    if (question.kind === "boolean")
+        return value ? "Yes" : "No";
+    if (CHOICE_KINDS.has(question.kind)) {
+        const labels = new Map((question.options ?? []).map((option) => [option.key, option.label]));
+        return (Array.isArray(value) ? value : [value]).map((key) => labels.get(key) ?? String(key)).join(", ");
+    }
+    return typeof value === "number" ? numberText(value) : String(value);
+}
+/**
+ * Validate a browser-submitted response against a verified definition. Rejects the wrong contract or release,
+ * unknown or duplicate questions, answers to questions the patient never saw, values outside the allowed
+ * options or ranges, missing required answers, and answers that reach a stop screen. Returns answers in
+ * definition order with display text for reviewers. Throws ContractError otherwise.
+ */
+export function validateResponse(definition, response, options) {
+    if (!isObject(response))
+        throw new ContractError({ _: "Response must be an object." });
+    if (response.contract !== ANSWER_CONTRACT)
+        throw new ContractError({ _: "Unsupported answer contract." });
+    if (response.questionnaireId !== options.questionnaireId || response.releaseId !== options.releaseId) {
+        throw new ContractError({ _: "Response does not belong to the active questionnaire release." });
+    }
+    const items = response.answers;
+    if (!Array.isArray(items) || items.length > 500)
+        throw new ContractError({ _: "Answers must be a list." });
+    const questions = new Map(definition.pages.flatMap((page) => page.questions.map((question) => [question.key, question])));
+    const submitted = new Map();
+    const errors = {};
+    for (const item of items) {
+        if (!isObject(item) || typeof item.questionKey !== "string")
+            throw new ContractError({ _: "Each answer needs a questionKey." });
+        const key = item.questionKey;
+        const question = questions.get(key);
+        if (!question || !ANSWERABLE_KINDS.has(question.kind)) {
+            errors[key] = "Unknown question.";
+            continue;
+        }
+        if (submitted.has(key)) {
+            errors[key] = "Answered more than once.";
+            continue;
+        }
+        if (item.kind !== question.kind) {
+            errors[key] = "Answer kind does not match the question.";
+            continue;
+        }
+        submitted.set(key, item.value);
+    }
+    if (Object.keys(errors).length)
+        throw new ContractError(errors);
+    const visible = visibleQuestions(definition, submitted);
+    // A visible stop screen means the patient was told they can't continue; never accept such a response.
+    const stopped = visible.filter((question) => question.kind === "end").map((question) => question.key);
+    if (stopped.length)
+        throw new ContractError({ [stopped[0]]: "These answers end the questionnaire at a stop screen, so it cannot be submitted." });
+    const visibleKeys = new Set(visible.map((question) => question.key));
+    for (const key of submitted.keys()) {
+        if (!visibleKeys.has(key))
+            errors[key] = "This question was not shown and cannot be answered.";
+    }
+    for (const question of visible) {
+        const message = answerError(question, submitted.get(question.key));
+        if (message)
+            errors[question.key] = message;
+    }
+    if (Object.keys(errors).length)
+        throw new ContractError(errors);
+    return visible
+        .filter((question) => ANSWERABLE_KINDS.has(question.kind) && isAnswered(submitted.get(question.key)))
+        .map((question) => {
+        const value = submitted.get(question.key);
+        return { questionKey: question.key, kind: question.kind, value, displayValue: displayValue(question, value), question };
+    });
+}

package/dist/frame.d.ts

@@ -0,0 +1,16 @@
+export declare const FRAME_SANDBOX = "allow-scripts allow-forms";
+export declare function frameCsp(scriptHash: string, frameAncestors?: string): string;
+export declare function frameHeaders(scriptHash: string, frameAncestors?: string): Record<string, string>;
+export declare function buildFrameHtml(bundle: Uint8Array, options: {
+    title: string;
+    lang?: string;
+}): Uint8Array;
+/** Returns the page and the exact headers to send with it; the CSP hash binds the page to these bundle bytes. */
+export declare function buildFrame(bundle: Uint8Array, options: {
+    title: string;
+    lang?: string;
+    frameAncestors?: string;
+}): {
+    html: Uint8Array;
+    headers: Record<string, string>;
+};

package/dist/frame.js

@@ -0,0 +1,55 @@
+// The sandboxed frame your server serves for a verified bundle (port of the Python SDK's frame.py).
+// Isolation: the host embeds it with sandbox="allow-scripts allow-forms" (never allow-same-origin), the CSP
+// re-applies that sandbox if the URL is opened directly, script-src allows only the verified bytes, and every
+// network directive is 'none', so answers leave only by postMessage to your page.
+import { cspHash } from "./canonical.js";
+export const FRAME_SANDBOX = "allow-scripts allow-forms";
+export function frameCsp(scriptHash, frameAncestors = "'self'") {
+    return [
+        "default-src 'none'",
+        `script-src '${scriptHash}'`,
+        "style-src 'unsafe-inline'",
+        "img-src 'none'",
+        "font-src 'none'",
+        "connect-src 'none'",
+        "media-src 'none'",
+        "object-src 'none'",
+        "child-src 'none'",
+        "worker-src 'none'",
+        "manifest-src 'none'",
+        "form-action 'none'",
+        "base-uri 'none'",
+        `frame-ancestors ${frameAncestors}`,
+        `sandbox ${FRAME_SANDBOX}`,
+    ].join("; ");
+}
+export function frameHeaders(scriptHash, frameAncestors = "'self'") {
+    return {
+        "Content-Type": "text/html; charset=utf-8",
+        "Content-Security-Policy": frameCsp(scriptHash, frameAncestors),
+        "X-Content-Type-Options": "nosniff",
+        "Referrer-Policy": "no-referrer",
+        "Cross-Origin-Resource-Policy": "same-origin",
+        "Permissions-Policy": "camera=(), microphone=(), geolocation=(), payment=(), usb=(), clipboard-read=(), clipboard-write=()",
+        "Cache-Control": "private, max-age=300",
+    };
+}
+/** Python's html.escape(text, quote=True). */
+function escapeHtml(text) {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#x27;");
+}
+const truncate = (text, max) => Array.from(text).slice(0, max).join("");
+export function buildFrameHtml(bundle, options) {
+    if (Buffer.from(bundle).toString("latin1").toLowerCase().includes("</script")) {
+        throw new Error("Bundle contains a closing script tag and cannot be inlined.");
+    }
+    const head = Buffer.from("<!doctype html>"
+        + `<html lang="${escapeHtml(truncate(options.lang ?? "en", 20))}"><head><meta charset="utf-8">`
+        + '<meta name="viewport" content="width=device-width, initial-scale=1">'
+        + `<title>${escapeHtml(truncate(options.title, 240))}</title></head><body><script>`, "utf8");
+    return new Uint8Array(Buffer.concat([head, Buffer.from(bundle), Buffer.from("</script></body></html>", "utf8")]));
+}
+/** Returns the page and the exact headers to send with it; the CSP hash binds the page to these bundle bytes. */
+export function buildFrame(bundle, options) {
+    return { html: buildFrameHtml(bundle, options), headers: frameHeaders(cspHash(bundle), options.frameAncestors) };
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { b64urlDecode, canonicalJson, cspHash, sha256Hex } from "./canonical.js";
+export { IntegrationError, MedFunnelsClient, type ClientOptions, type IntegrationErrorCode } from "./client.js";
+export { ANSWER_CONTRACT, ContractError, answerError, displayValue, evaluateCondition, isAnswered, validateResponse, visibleQuestions, type Answers, type Definition, type NormalizedAnswer, type Question, } from "./contract.js";
+export { FRAME_SANDBOX, buildFrame, buildFrameHtml, frameCsp, frameHeaders } from "./frame.js";
+export { BUNDLE_ARTIFACT, DEFINITION_ARTIFACT, VerificationError, checkCompatibility, verifyRelease, verifySignature, type Envelope, type Manifest, type VerificationErrorCode, type VerifiedRelease, type VerifyOptions, } from "./verify.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+// @medfunnels/sdk: fetch, verify, host and validate medFunnels questionnaire releases on your own server.
+// Nothing in this package sends patient data to medFunnels.
+export { b64urlDecode, canonicalJson, cspHash, sha256Hex } from "./canonical.js";
+export { IntegrationError, MedFunnelsClient } from "./client.js";
+export { ANSWER_CONTRACT, ContractError, answerError, displayValue, evaluateCondition, isAnswered, validateResponse, visibleQuestions, } from "./contract.js";
+export { FRAME_SANDBOX, buildFrame, buildFrameHtml, frameCsp, frameHeaders } from "./frame.js";
+export { BUNDLE_ARTIFACT, DEFINITION_ARTIFACT, VerificationError, checkCompatibility, verifyRelease, verifySignature, } from "./verify.js";

package/dist/verify.d.ts

@@ -0,0 +1,78 @@
+import { type Definition } from "./contract.js";
+export declare const BUNDLE_ARTIFACT = "questionnaire.js";
+export declare const DEFINITION_ARTIFACT = "definition.json";
+export type VerificationErrorCode = "malformed" | "bad_signature" | "untrusted_key" | "wrong_tenant" | "wrong_origin" | "not_published" | "incompatible" | "missing_artifact" | "digest_mismatch";
+export declare class VerificationError extends Error {
+    readonly code: VerificationErrorCode;
+    constructor(code: VerificationErrorCode, message: string);
+}
+export interface Envelope {
+    manifest: Manifest;
+    signature: {
+        alg: string;
+        keyId: string;
+        value: string;
+    };
+}
+export interface Manifest {
+    manifestVersion: number;
+    organizationId: string;
+    questionnaire: {
+        id: string;
+        slug: string;
+        name: string;
+    };
+    release: {
+        id: string;
+        version: number;
+        status: string;
+        publishedAt: string;
+        notes: string;
+    };
+    runtime: {
+        version: string;
+        definitionSchema: string;
+    };
+    deployment: {
+        allowedOrigins: string[];
+        localDevelopment: boolean;
+        previewOrigin: string;
+    };
+    artifacts: Array<{
+        name: string;
+        mediaType: string;
+        size: number;
+        sha256: string;
+        cspHash?: string;
+    }>;
+    compatibility: {
+        answerContract: string;
+        questionKinds: string[];
+        requiresNetwork: boolean;
+        [field: string]: unknown;
+    };
+    [field: string]: unknown;
+}
+export interface VerifiedRelease {
+    manifest: Manifest;
+    definition: Definition;
+    bundle: Uint8Array;
+    bundleSha256: string;
+    bundleCspHash: string;
+    questionnaireId: string;
+    releaseId: string;
+    version: number;
+}
+export interface VerifyOptions {
+    /** Key id → base64url raw Ed25519 public key. Pin these in configuration. */
+    trustedKeys: Record<string, string>;
+    /** The question kinds your platform accepts; releases using anything else are rejected. */
+    supportedKinds: Iterable<string>;
+    expectedOrganizationId?: string | null;
+    /** e.g. "https://intake.example.com": rejects releases locked to other websites. */
+    expectedOrigin?: string | null;
+}
+export declare function verifySignature(envelope: unknown, trustedKeys: Record<string, string>): Manifest;
+export declare function checkCompatibility(manifest: Manifest, supportedKinds: Iterable<string>): void;
+/** Check, in order: signature, workspace, website, status, compatibility, then each file's size, SHA-256 and the script's CSP hash. */
+export declare function verifyRelease(envelope: unknown, artifacts: Record<string, Uint8Array | undefined>, options: VerifyOptions): VerifiedRelease;

package/dist/verify.js

@@ -0,0 +1,98 @@
+// Release verification: authenticity (Ed25519 signature), integrity (SHA-256), compatibility.
+// A port of the Python SDK's verify.py. Pin medFunnels' signing public keys in your configuration;
+// never fetch and trust them at runtime.
+import { createPublicKey, verify as verifySignatureBytes } from "node:crypto";
+import { b64urlDecode, canonicalJson, cspHash, sha256Hex } from "./canonical.js";
+import { ANSWER_CONTRACT } from "./contract.js";
+const SUPPORTED_MANIFEST_VERSIONS = new Set([1]);
+const SUPPORTED_RUNTIME_MAJORS = new Set([1]);
+export const BUNDLE_ARTIFACT = "questionnaire.js";
+export const DEFINITION_ARTIFACT = "definition.json";
+export class VerificationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "VerificationError";
+        this.code = code;
+    }
+}
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+export function verifySignature(envelope, trustedKeys) {
+    const manifest = isObject(envelope) ? envelope.manifest : undefined;
+    const signature = isObject(envelope) && isObject(envelope.signature) ? envelope.signature : {};
+    if (!isObject(manifest))
+        throw new VerificationError("malformed", "Manifest envelope is missing its manifest.");
+    if (signature.alg !== "Ed25519")
+        throw new VerificationError("bad_signature", "Unsupported signature algorithm.");
+    const keyId = String(signature.keyId ?? "");
+    const key = Object.prototype.hasOwnProperty.call(trustedKeys, keyId) ? trustedKeys[keyId] : "";
+    if (!key)
+        throw new VerificationError("untrusted_key", `Signing key '${keyId}' is not trusted by this installation.`);
+    let valid = false;
+    try {
+        const publicKey = createPublicKey({ key: { kty: "OKP", crv: "Ed25519", x: key }, format: "jwk" });
+        valid = verifySignatureBytes(null, canonicalJson(manifest), publicKey, b64urlDecode(String(signature.value ?? "")));
+    }
+    catch {
+        valid = false;
+    }
+    if (!valid)
+        throw new VerificationError("bad_signature", "Release manifest signature is invalid.");
+    return manifest;
+}
+export function checkCompatibility(manifest, supportedKinds) {
+    if (!SUPPORTED_MANIFEST_VERSIONS.has(manifest.manifestVersion))
+        throw new VerificationError("incompatible", "Unsupported manifest version.");
+    const compatibility = isObject(manifest.compatibility) ? manifest.compatibility : {};
+    if (compatibility.answerContract !== ANSWER_CONTRACT)
+        throw new VerificationError("incompatible", "Unsupported answer contract.");
+    const runtimeVersion = String(manifest.runtime?.version || "0");
+    if (!SUPPORTED_RUNTIME_MAJORS.has(Number.parseInt(runtimeVersion.split(".")[0] || "0", 10))) {
+        throw new VerificationError("incompatible", `Unsupported runtime version ${runtimeVersion}.`);
+    }
+    if (compatibility.requiresNetwork !== false)
+        throw new VerificationError("incompatible", "Questionnaire runtime must not require network access.");
+    const supported = new Set(supportedKinds);
+    const unsupported = [...new Set(compatibility.questionKinds ?? [])].filter((kind) => !supported.has(kind)).sort();
+    if (unsupported.length)
+        throw new VerificationError("incompatible", `Unsupported question kinds: ${unsupported.join(", ")}.`);
+}
+/** Check, in order: signature, workspace, website, status, compatibility, then each file's size, SHA-256 and the script's CSP hash. */
+export function verifyRelease(envelope, artifacts, options) {
+    const manifest = verifySignature(envelope, options.trustedKeys);
+    if (options.expectedOrganizationId && manifest.organizationId !== options.expectedOrganizationId) {
+        throw new VerificationError("wrong_tenant", "Release belongs to a different organization.");
+    }
+    const allowed = manifest.deployment?.allowedOrigins ?? [];
+    const origin = options.expectedOrigin ? options.expectedOrigin.replace(/\/+$/, "") : "";
+    if (origin && allowed.length && !allowed.includes(origin)) {
+        throw new VerificationError("wrong_origin", `Release is locked to ${allowed.join(", ")}, not ${options.expectedOrigin}.`);
+    }
+    if (manifest.release?.status !== "published")
+        throw new VerificationError("not_published", "Release is not in published status.");
+    checkCompatibility(manifest, options.supportedKinds);
+    const declared = new Map((manifest.artifacts ?? []).map((item) => [item.name, item]));
+    for (const name of [BUNDLE_ARTIFACT, DEFINITION_ARTIFACT]) {
+        const meta = declared.get(name);
+        const data = artifacts[name];
+        if (!meta || !data)
+            throw new VerificationError("missing_artifact", `Release artifact ${name} is missing.`);
+        if (data.length !== Number(meta.size ?? -1) || sha256Hex(data) !== meta.sha256) {
+            throw new VerificationError("digest_mismatch", `Artifact ${name} does not match its signed digest.`);
+        }
+    }
+    const bundle = artifacts[BUNDLE_ARTIFACT];
+    if (declared.get(BUNDLE_ARTIFACT)?.cspHash !== cspHash(bundle))
+        throw new VerificationError("digest_mismatch", "Bundle CSP hash does not match.");
+    const definition = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(artifacts[DEFINITION_ARTIFACT]));
+    return {
+        manifest,
+        definition,
+        bundle,
+        bundleSha256: sha256Hex(bundle),
+        bundleCspHash: cspHash(bundle),
+        questionnaireId: manifest.questionnaire.id,
+        releaseId: manifest.release.id,
+        version: Number(manifest.release.version),
+    };
+}

package/package.json

@@ -1,6 +1,21 @@
 {
   "name": "@medfunnels/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Fetch, verify, host and validate medFunnels questionnaire releases on your own server.",
+  "license": "MIT",
+  "homepage": "https://www.medfunnels.app",
+  "keywords": ["medfunnels", "telehealth", "questionnaire", "intake", "hipaa"],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "engines": { "node": ">=18.17" },
+  "sideEffects": false,
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "test": "node --test test/*.test.mjs"
+  }
+}