@selfhelp/sh2-shp-survey-js-mobile 0.3.0

package/package.json

@@ -0,0 +1,70 @@
+{
+    "name": "@selfhelp/sh2-shp-survey-js-mobile",
+    "version": "0.3.0",
+    "description": "SurveyJS v2 mobile renderer for the SelfHelp plugin ecosystem. Hosts the official SurveyJS web runtime (survey-core + survey-react-ui) in an isolated, self-contained WebView (react-native-webview on native, iframe on web export) driven by a typed postMessage bridge; the native host owns all authenticated API calls.",
+    "license": "MPL-2.0",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/humdek-unibe-ch/sh2-shp-survey-js.git",
+        "directory": "mobile"
+    },
+    "homepage": "https://github.com/humdek-unibe-ch/sh2-shp-survey-js#readme",
+    "bugs": {
+        "url": "https://github.com/humdek-unibe-ch/sh2-shp-survey-js/issues"
+    },
+    "main": "dist/index.js",
+    "module": "dist/index.mjs",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.mjs",
+            "require": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "src",
+        "README.md"
+    ],
+    "scripts": {
+        "build:webview": "vite build --config vite.webview.config.ts && node scripts/wrap-webview-html.mjs",
+        "build": "npm run build:webview && tsup",
+        "typecheck": "tsc --noEmit",
+        "test": "vitest run"
+    },
+    "dependencies": {
+        "survey-core": "2.5.25",
+        "survey-react-ui": "2.5.25"
+    },
+    "peerDependencies": {
+        "@selfhelp/shared": "^1.16.0",
+        "react": "^19.2.0",
+        "react-dom": "^19.2.0",
+        "react-native": "^0.83.0",
+        "react-native-webview": ">=13.0.0 <14.0.0"
+    },
+    "peerDependenciesMeta": {
+        "react-dom": {
+            "optional": true
+        }
+    },
+    "devDependencies": {
+        "@selfhelp/shared": "^1.16.0",
+        "@types/react": "^19.2.14",
+        "react": "^19.2.0",
+        "react-dom": "^19.2.7",
+        "react-native": "^0.83.6",
+        "react-native-webview": "^13.17.0",
+        "survey-core": "2.5.25",
+        "survey-react-ui": "2.5.25",
+        "tsup": "^8.3.5",
+        "typescript": "^5.9.3",
+        "vite": "^7.3.5",
+        "vitest": "^3.0.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "sideEffects": false
+}

package/src/api/surveys.ts

@@ -0,0 +1,205 @@
+/*
+SPDX-FileCopyrightText: 2026 Humdek, University of Bern
+SPDX-License-Identifier: MPL-2.0
+*/
+/**
+ * Public SurveyJS plugin API client for the MOBILE host shell.
+ *
+ * Unlike the frontend client, the mobile renderer does NOT own authenticated
+ * network access: every call goes through the native host-services bridge
+ * (`IMobileHostServices.request`), which attaches the bearer token, applies
+ * `X-Client-Type: mobile`, and performs the single 401-refresh round-trip
+ * host-side. The WebView runtime never sees the token — it emits intents and
+ * the shell calls these functions in response.
+ *
+ * Routes/payloads mirror the frontend client (`frontend/src/api/surveys.ts`)
+ * exactly, so a mobile submission stores a real `SurveyRun` identically to web
+ * (there is no preview/test branch on the backend).
+ *
+ * Only the runtime routes the renderer needs are wrapped: hydrate
+ * (`published`), per-page progress (`progress`), submit (`submit`). The
+ * file/choices/edit pipeline stays web-only.
+ */
+
+import type { IMobileHostServices } from '@selfhelp/shared/plugin-sdk';
+
+export interface IRuntimeConfig {
+    restartOnRefresh: boolean;
+    autoSaveIntervalSeconds: number;
+    timeoutMinutes: number;
+    savePdf: boolean;
+    closeModalAtEnd: boolean;
+    redirectAtEnd: string | null;
+    urlParams: boolean;
+    startTime: string | null;
+    endTime: string | null;
+    oncePerUser: boolean;
+    oncePerSchedule: boolean;
+    ownEntriesOnly: boolean;
+    allowAnonymous: boolean;
+    labelSurveyDone: string | null;
+    labelSurveyNotActive: string | null;
+}
+
+export interface IPublishedRuntimeState {
+    isAuthenticated: boolean;
+    visitorId: string | null;
+    lockoutReason: { reason: string; responseId: string; submittedAt: string | null } | null;
+    draft: { responseId: string; pageNo: number; lastSavedAt: string } | null;
+    completedResponseId: string | null;
+}
+
+export interface IPublishedSurvey {
+    surveyId: string;
+    name: string;
+    themeCode: string | null;
+    revision: number;
+    definition: Record<string, unknown>;
+    extraParams: Record<string, string | number | boolean>;
+    tokens: Record<string, string>;
+    runtimeConfig: IRuntimeConfig;
+    state: IPublishedRuntimeState;
+}
+
+export interface ISubmitResult {
+    runId: number;
+    responseId: string;
+    submittedAt: string;
+}
+
+export interface IDraftPayload {
+    responseId: string;
+    pageNo: number;
+    payload: Record<string, unknown>;
+    lastSavedAt: string;
+    expiresAt: string;
+}
+
+export interface ISubmissionEnforcePayload {
+    oncePerUser?: boolean;
+    oncePerSchedule?: boolean;
+    allowAnonymous?: boolean;
+    windowStart?: string | null;
+    windowEnd?: string | null;
+    responseId?: string;
+    editMode?: boolean;
+    progress?: Record<string, unknown>;
+}
+
+/** Error thrown when a host request fails; carries the lifecycle discriminator. */
+export class SurveyHostError extends Error {
+    readonly status: number;
+    readonly reason?: string;
+    readonly sessionExpired: boolean;
+
+    constructor(message: string, status: number, reason?: string, sessionExpired = false) {
+        super(message);
+        this.name = 'SurveyHostError';
+        this.status = status;
+        this.reason = reason;
+        this.sessionExpired = sessionExpired;
+    }
+}
+
+const PLUGIN_API_PATH = '/cms-api/v1/plugins/sh2-shp-survey-js';
+
+/** Unwrap a host response into the inner API-envelope `data`, throwing on failure. */
+function unwrap<T>(res: {
+    ok: boolean;
+    status: number;
+    data: unknown;
+    reason?: string;
+    error?: string;
+    sessionExpired?: boolean;
+}): T {
+    if (!res.ok) {
+        const reason = res.reason ?? extractReason(res.data);
+        throw new SurveyHostError(
+            res.error ?? `HTTP ${res.status}`,
+            res.status,
+            reason,
+            res.sessionExpired ?? res.status === 401,
+        );
+    }
+    const body = res.data as { data?: T } | null;
+    return (body?.data ?? null) as T;
+}
+
+function extractReason(body: unknown): string | undefined {
+    if (body && typeof body === 'object' && 'reason' in body) {
+        const reason = (body as { reason?: unknown }).reason;
+        if (typeof reason === 'string') return reason;
+    }
+    return undefined;
+}
+
+export async function loadPublishedSurvey(
+    host: IMobileHostServices,
+    key: string,
+    serverConfig?: Record<string, unknown>,
+    extraParams?: Record<string, string | number | boolean>,
+): Promise<IPublishedSurvey> {
+    const query: Record<string, string | number | boolean> = {};
+    if (extraParams) {
+        for (const [k, v] of Object.entries(extraParams)) {
+            query[`extraParams[${k}]`] = v;
+        }
+    }
+    const headers: Record<string, string> = {};
+    if (serverConfig) {
+        try {
+            headers['X-SurveyJs-Runtime-Config'] = JSON.stringify(serverConfig);
+        } catch {
+            /* non-serialisable config — send without the echo header */
+        }
+    }
+    const res = await host.request<{ data: IPublishedSurvey }>({
+        path: `${PLUGIN_API_PATH}/published/${encodeURIComponent(key)}`,
+        method: 'GET',
+        headers,
+        query,
+    });
+    return unwrap<IPublishedSurvey>(res);
+}
+
+export async function fetchDraft(
+    host: IMobileHostServices,
+    key: string,
+    responseId?: string,
+): Promise<IDraftPayload | null> {
+    const query: Record<string, string | number | boolean> = {};
+    if (responseId) query.responseId = responseId;
+    const res = await host.request<{ data: IDraftPayload | null }>({
+        path: `${PLUGIN_API_PATH}/published/${encodeURIComponent(key)}/progress`,
+        method: 'GET',
+        query,
+    });
+    return unwrap<IDraftPayload | null>(res);
+}
+
+export async function saveProgress(
+    host: IMobileHostServices,
+    key: string,
+    payload: { responseId?: string; pageNo: number; payload: Record<string, unknown> },
+): Promise<IDraftPayload> {
+    const res = await host.request<{ data: IDraftPayload }>({
+        path: `${PLUGIN_API_PATH}/published/${encodeURIComponent(key)}/progress`,
+        method: 'PUT',
+        body: payload,
+    });
+    return unwrap<IDraftPayload>(res);
+}
+
+export async function submitSurvey(
+    host: IMobileHostServices,
+    key: string,
+    answers: Record<string, unknown>,
+    enforce?: ISubmissionEnforcePayload,
+): Promise<ISubmitResult> {
+    const res = await host.request<{ data: ISubmitResult }>({
+        path: `${PLUGIN_API_PATH}/published/${encodeURIComponent(key)}/submit`,
+        method: 'POST',
+        body: { answers, enforce: enforce ?? {} },
+    });
+    return unwrap<ISubmitResult>(res);
+}

package/src/bridge/messages.ts

@@ -0,0 +1,264 @@
+/*
+SPDX-FileCopyrightText: 2026 Humdek, University of Bern
+SPDX-License-Identifier: MPL-2.0
+*/
+/**
+ * Typed postMessage contract between the isolated SurveyJS WebView runtime
+ * and the native RN shell (host).
+ *
+ * Security model (enforced by both sides):
+ *   - Every message carries `source: 'sh2-surveyjs'` and a known `type`.
+ *   - The receiver runs the matching type guard and DROPS anything that does
+ *     not match the expected shape (no `eval`, no trusting arbitrary data).
+ *   - The WebView NEVER receives the access token and NEVER performs a
+ *     backend call: it emits *intents* (`LOAD_SURVEY` / `SAVE_PROGRESS` /
+ *     `SUBMIT_SURVEY`) and consumes *results* the native host returns after
+ *     performing the authenticated request via the host-services bridge.
+ *
+ * This module is framework-free so it can be imported by the WebView runtime
+ * bundle, the RN shell, and the contract tests alike.
+ */
+
+import type {
+    IPublishedRuntimeState,
+    IRuntimeConfig,
+    ISubmissionEnforcePayload,
+} from '../api/surveys';
+import type { IRuntimeSectionConfig } from '../styles/section';
+
+/** Protocol tag stamped on every message in both directions. */
+export const BRIDGE_SOURCE = 'sh2-surveyjs' as const;
+
+/** Bumped when the message contract changes in a breaking way. */
+export const BRIDGE_PROTOCOL_VERSION = 1 as const;
+
+/* ------------------------------------------------------------------ *
+ * WebView -> Host (intents + UI signals)
+ * ------------------------------------------------------------------ */
+
+export type TWebviewToHostType =
+    | 'READY'
+    | 'LOAD_SURVEY'
+    | 'SAVE_PROGRESS'
+    | 'SUBMIT_SURVEY'
+    | 'RESIZE'
+    | 'REQUEST_REDIRECT'
+    | 'RUNTIME_ERROR'
+    | 'UNSUPPORTED';
+
+interface IBridgeEnvelope<TType extends string> {
+    source: typeof BRIDGE_SOURCE;
+    type: TType;
+}
+
+/** Runtime has booted and is ready to receive `INIT`. */
+export interface IReadyMessage extends IBridgeEnvelope<'READY'> {
+    protocolVersion: number;
+}
+
+/** Runtime asks the host to load the published survey definition. */
+export interface ILoadSurveyMessage extends IBridgeEnvelope<'LOAD_SURVEY'> {
+    surveyKey: string;
+}
+
+/** Runtime asks the host to persist per-page progress (draft). */
+export interface ISaveProgressMessage extends IBridgeEnvelope<'SAVE_PROGRESS'> {
+    responseId: string;
+    pageNo: number;
+    data: Record<string, unknown>;
+    locale?: string;
+}
+
+/** Runtime asks the host to submit the completed survey. */
+export interface ISubmitSurveyMessage extends IBridgeEnvelope<'SUBMIT_SURVEY'> {
+    responseId: string | null;
+    data: Record<string, unknown>;
+    enforce: ISubmissionEnforcePayload;
+}
+
+/** Runtime reports its measured content height (native sizing). */
+export interface IResizeMessage extends IBridgeEnvelope<'RESIZE'> {
+    height: number;
+}
+
+/** Runtime asks the host to redirect after completion. */
+export interface IRequestRedirectMessage extends IBridgeEnvelope<'REQUEST_REDIRECT'> {
+    target: string;
+    external: boolean;
+}
+
+/** Runtime reports an unrecoverable runtime error. */
+export interface IRuntimeErrorMessage extends IBridgeEnvelope<'RUNTIME_ERROR'> {
+    message: string;
+}
+
+/** Runtime reports an unsupported feature (degrades in place, never crashes). */
+export interface IUnsupportedMessage extends IBridgeEnvelope<'UNSUPPORTED'> {
+    feature: string;
+}
+
+export type TWebviewToHostMessage =
+    | IReadyMessage
+    | ILoadSurveyMessage
+    | ISaveProgressMessage
+    | ISubmitSurveyMessage
+    | IResizeMessage
+    | IRequestRedirectMessage
+    | IRuntimeErrorMessage
+    | IUnsupportedMessage;
+
+/* ------------------------------------------------------------------ *
+ * Host -> WebView (results + inputs; never a raw token)
+ * ------------------------------------------------------------------ */
+
+export type THostToWebviewType =
+    | 'INIT'
+    | 'SURVEY_LOADED'
+    | 'PROGRESS_SAVED'
+    | 'SUBMIT_RESULT'
+    | 'SESSION_EXPIRED'
+    | 'SET_LOCALE';
+
+/** Host bootstraps the runtime (config + display inputs, no token). */
+export interface IInitMessage extends IBridgeEnvelope<'INIT'> {
+    surveyKey: string;
+    config: IRuntimeSectionConfig;
+    theme: string | null;
+    locale: string | null;
+}
+
+/** Host returns the loaded survey definition + server state + draft. */
+export interface ISurveyLoadedMessage extends IBridgeEnvelope<'SURVEY_LOADED'> {
+    definition: Record<string, unknown>;
+    tokens: Record<string, string>;
+    extraParams: Record<string, string | number | boolean>;
+    runtimeConfig: IRuntimeConfig;
+    state: IPublishedRuntimeState;
+    draft: { responseId: string; pageNo: number; data: Record<string, unknown> } | null;
+}
+
+/** Host confirms a progress save. */
+export interface IProgressSavedMessage extends IBridgeEnvelope<'PROGRESS_SAVED'> {
+    ok: boolean;
+    responseId?: string;
+}
+
+/** Host returns the submission outcome. */
+export type ISubmitResultMessage = IBridgeEnvelope<'SUBMIT_RESULT'> &
+    (
+        | { ok: true; responseId: string; submittedAt: string }
+        | { ok: false; reason?: string; message: string }
+    );
+
+/** Host signals the session could not be refreshed (auth expired). */
+export type ISessionExpiredMessage = IBridgeEnvelope<'SESSION_EXPIRED'>;
+
+/** Host pushes a locale change to the runtime. */
+export interface ISetLocaleMessage extends IBridgeEnvelope<'SET_LOCALE'> {
+    locale: string;
+}
+
+export type THostToWebviewMessage =
+    | IInitMessage
+    | ISurveyLoadedMessage
+    | IProgressSavedMessage
+    | ISubmitResultMessage
+    | ISessionExpiredMessage
+    | ISetLocaleMessage;
+
+/* ------------------------------------------------------------------ *
+ * Guards — every receiver validates the shape before acting.
+ * ------------------------------------------------------------------ */
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null;
+}
+
+function hasBridgeEnvelope(value: unknown): value is { source: string; type: string } {
+    return (
+        isRecord(value) &&
+        value.source === BRIDGE_SOURCE &&
+        typeof value.type === 'string'
+    );
+}
+
+const WEBVIEW_TO_HOST_TYPES: ReadonlySet<string> = new Set<TWebviewToHostType>([
+    'READY',
+    'LOAD_SURVEY',
+    'SAVE_PROGRESS',
+    'SUBMIT_SURVEY',
+    'RESIZE',
+    'REQUEST_REDIRECT',
+    'RUNTIME_ERROR',
+    'UNSUPPORTED',
+]);
+
+const HOST_TO_WEBVIEW_TYPES: ReadonlySet<string> = new Set<THostToWebviewType>([
+    'INIT',
+    'SURVEY_LOADED',
+    'PROGRESS_SAVED',
+    'SUBMIT_RESULT',
+    'SESSION_EXPIRED',
+    'SET_LOCALE',
+]);
+
+/**
+ * Validate a message coming FROM the WebView (the native host calls this).
+ * Performs per-type field checks so a malformed/hostile message is dropped.
+ */
+export function isWebviewToHostMessage(value: unknown): value is TWebviewToHostMessage {
+    if (!hasBridgeEnvelope(value) || !WEBVIEW_TO_HOST_TYPES.has(value.type)) return false;
+    const msg = value as Record<string, unknown>;
+    switch (msg.type) {
+        case 'READY':
+            return true;
+        case 'LOAD_SURVEY':
+            return typeof msg.surveyKey === 'string' && msg.surveyKey !== '';
+        case 'SAVE_PROGRESS':
+            return (
+                typeof msg.responseId === 'string' &&
+                typeof msg.pageNo === 'number' &&
+                isRecord(msg.data)
+            );
+        case 'SUBMIT_SURVEY':
+            return (
+                (msg.responseId === null || typeof msg.responseId === 'string') &&
+                isRecord(msg.data) &&
+                isRecord(msg.enforce)
+            );
+        case 'RESIZE':
+            return typeof msg.height === 'number' && Number.isFinite(msg.height);
+        case 'REQUEST_REDIRECT':
+            return typeof msg.target === 'string' && typeof msg.external === 'boolean';
+        case 'RUNTIME_ERROR':
+            return typeof msg.message === 'string';
+        case 'UNSUPPORTED':
+            return typeof msg.feature === 'string';
+        default:
+            return false;
+    }
+}
+
+/**
+ * Validate a message coming FROM the host (the WebView runtime calls this).
+ */
+export function isHostToWebviewMessage(value: unknown): value is THostToWebviewMessage {
+    if (!hasBridgeEnvelope(value) || !HOST_TO_WEBVIEW_TYPES.has(value.type)) return false;
+    const msg = value as Record<string, unknown>;
+    switch (msg.type) {
+        case 'INIT':
+            return typeof msg.surveyKey === 'string' && isRecord(msg.config);
+        case 'SURVEY_LOADED':
+            return isRecord(msg.definition) && isRecord(msg.state);
+        case 'PROGRESS_SAVED':
+            return typeof msg.ok === 'boolean';
+        case 'SUBMIT_RESULT':
+            return typeof msg.ok === 'boolean';
+        case 'SESSION_EXPIRED':
+            return true;
+        case 'SET_LOCALE':
+            return typeof msg.locale === 'string';
+        default:
+            return false;
+    }
+}

package/src/css.d.ts

@@ -0,0 +1,13 @@
+/*
+SPDX-FileCopyrightText: 2026 Humdek, University of Bern
+SPDX-License-Identifier: MPL-2.0
+*/
+/**
+ * Ambient module for side-effect CSS imports.
+ *
+ * The interactive web runtime lazily `import('survey-core/survey-core.css')`
+ * inside a try/catch so the Expo Metro web bundler injects the SurveyJS base
+ * styles. The mobile tsconfig has no DOM/bundler CSS typing, so declare the
+ * wildcard module to keep `tsc --noEmit` happy without pulling in a CSS loader.
+ */
+declare module '*.css';

package/src/index.ts

@@ -0,0 +1,57 @@
+/*
+SPDX-FileCopyrightText: 2026 Humdek, University of Bern
+SPDX-License-Identifier: MPL-2.0
+*/
+/**
+ * `@selfhelp/sh2-shp-survey-js-mobile` — mobile entry.
+ *
+ * Bundled into mobile builds by the host's `plugins:sync` script
+ * (per EAS profile). Exports `registerMobile` which returns the
+ * plugin's `IMobilePluginRegistration` — the `surveyjs` style.
+ *
+ * The style (`styles/SurveyJsStyle`) is a thin native shell that hosts the
+ * OFFICIAL SurveyJS web runtime (`survey-core` + `survey-react-ui`) inside an
+ * isolated, self-contained WebView — `react-native-webview` on native, an
+ * `iframe` on the Expo web export — driven by a typed postMessage bridge.
+ * This gives mobile full parity with the web frontend (same JSON, question
+ * types, validation, conditional logic, completion, redirect). The native
+ * host owns ALL authenticated API calls via `@selfhelp/shared`
+ * `MobileHostServices`; the WebView never sees the access token.
+ */
+
+import { defineMobilePlugin } from '@selfhelp/shared/plugin-sdk';
+import type { IMobilePluginRegistration } from '@selfhelp/shared/plugin-sdk';
+
+import { SurveyJsStyle } from './styles/SurveyJsStyle';
+
+export const PLUGIN_ID = 'sh2-shp-survey-js';
+/**
+ * Must match `plugin.json#version` and the mobile `package.json#version`.
+ * `PluginRuntime.registerOne()` (web) and the mobile sync script both
+ * compare these constants against the manifest version; a mismatch
+ * silently breaks the plugin.
+ */
+export const PLUGIN_VERSION = '0.3.0';
+
+export const registerMobile = (): IMobilePluginRegistration =>
+    defineMobilePlugin({
+        id: PLUGIN_ID,
+        version: PLUGIN_VERSION,
+        pluginApiVersion: '0.1.0',
+        styles: [
+            {
+                name: 'surveyjs',
+                description: 'Mobile renderer for a published SurveyJS survey (official SurveyJS runtime in a WebView; full submit/validation/redirect parity with web).',
+                category: 'forms',
+                canHaveChildren: false,
+                component: SurveyJsStyle as never,
+            },
+        ],
+        featureFlags: [
+            { key: 'gpx', label: 'GPX question type', defaultEnabled: false },
+            { key: 'video', label: 'Video question type', defaultEnabled: false },
+            { key: 'rich-text', label: 'Rich-text question type', defaultEnabled: true },
+        ],
+    });
+
+export default registerMobile;