@viengut/vgq-sdk 0.1.0

package/README.md

@@ -0,0 +1,50 @@
+# @viengut/vgq-sdk
+
+SDK headless (TypeScript) cho nền tảng Form lâm sàng **VGQ** của Viện Gút: tải Form đã phát
+hành, quản lý trạng thái Response, đánh giá Enable Condition và validate Response Value —
+không kèm component UI, bạn tự dựng giao diện.
+
+```bash
+npm install @viengut/vgq-sdk
+```
+
+## Dùng nhanh
+
+```js
+import { ResponseSession, VgqClient } from '@viengut/vgq-sdk';
+
+const client = new VgqClient({ baseUrl: 'https://vgq.example.com', actor: 'app:demo' });
+
+// Tạo Response mới từ Publication key; draft tự đồng bộ sau mỗi 800ms không gõ.
+const session = await ResponseSession.start(client, {
+  publicationKey: 'health-declaration',
+  subjectRef: 'patient:VG2607000187',
+  careContextRef: 'checkin:1000034907',
+  idempotencyKey: crypto.randomUUID(),
+}, { debounceMs: 800, onSync: () => console.log('đã lưu nháp') });
+
+session.setValue('ho_ten', 'Nguyễn Văn A');       // ghi theo slug của Question
+session.getValue('ho_ten');
+session.activeState().activeIds;                   // Question đang bật theo Enable Condition
+const check = session.validate();                  // validate phía client (server vẫn là chốt cuối)
+if (check.ok) await session.complete();
+
+// Mở lại Draft đang dở:
+const resumed = await ResponseSession.resume(client, responseId);
+```
+
+Engine (Enable Condition, validation) mirror đúng logic server nên UI phản hồi tức thì mà
+không cần round-trip; mọi thay đổi vẫn được server validate lại khi hoàn tất Response.
+
+## Phát triển
+
+```bash
+npm install
+npm test          # vitest
+npm run build     # tsc -> dist/
+npx tsc --noEmit
+```
+
+Mã nguồn nằm trong repo [vgq-questionnaire](https://github.com/viengut-hospital/vgq-questionnaire)
+(thư mục `sdk/`). Bản quyền thuộc Viện Gút — publish công khai để tiện cài đặt, không kèm
+giấy phép sử dụng lại.

package/dist/client.d.ts

@@ -0,0 +1,48 @@
+import type { FormVersion, InvitationDto, JsonValue, MediaAssetDto, PublicationForm, ResponseDto, ValidationIssue } from './types.js';
+export interface VgqClientOptions {
+    /** Gốc của VGQ server, VD: https://vgq.viengut.vn */
+    baseUrl: string;
+    /** Danh tính người thao tác, gửi qua header X-Actor cho audit trail. */
+    actor?: string;
+    /** Cho phép thay fetch (test, môi trường không có fetch toàn cục). */
+    fetch?: typeof fetch;
+}
+export declare class VgqApiError extends Error {
+    readonly status: number;
+    readonly issues: ValidationIssue[];
+    readonly data: unknown;
+    constructor(status: number, message: string, data: unknown);
+}
+export interface StartResponseOptions {
+    subjectRef?: string;
+    respondentRef?: string;
+    careContextRef?: string;
+    /** Chống tạo Response trùng khi retry trên mạng không ổn định. */
+    idempotencyKey?: string;
+}
+export declare class VgqClient {
+    private readonly baseUrl;
+    private readonly actor?;
+    private readonly fetchImpl;
+    constructor(options: VgqClientOptions);
+    /** Tải Form đang phát hành qua Publication key ổn định. */
+    getPublicationForm(key: string): Promise<PublicationForm>;
+    /** Tải một Form Version bất biến (Response luôn gắn đúng version đã bắt đầu). */
+    getFormVersion(id: string): Promise<FormVersion>;
+    createResponse(publicationKey: string, options?: StartResponseOptions): Promise<ResponseDto>;
+    getInvitation(id: string): Promise<InvitationDto>;
+    /** Bắt đầu (hoặc mở lại) Response duy nhất của một Invitation. */
+    startInvitationResponse(invitationId: string): Promise<ResponseDto>;
+    getResponse(id: string): Promise<ResponseDto>;
+    /** Cập nhật Draft theo lô; value null xoá giá trị. Idempotent khi retry. */
+    updateValues(responseId: string, values: Record<string, JsonValue | null>): Promise<ResponseDto>;
+    /** Hoàn thành/xác nhận; server validate độc lập với SDK. */
+    completeResponse(id: string): Promise<ResponseDto>;
+    getMediaAsset(id: string): Promise<MediaAssetDto>;
+    /**
+     * URL tuyệt đối tới nội dung một Media Asset (ảnh nền Body Map, media nhúng
+     * trong Form). Ổn định theo id nên dùng thẳng trong thẻ img/video/audio.
+     */
+    mediaContentUrl(assetId: string): string;
+    private request;
+}

package/dist/client.js

@@ -0,0 +1,99 @@
+export class VgqApiError extends Error {
+    status;
+    issues;
+    data;
+    constructor(status, message, data) {
+        super(message);
+        this.name = 'VgqApiError';
+        this.status = status;
+        this.data = data;
+        const body = data;
+        this.issues = body?.issues ?? [];
+    }
+}
+export class VgqClient {
+    baseUrl;
+    actor;
+    fetchImpl;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, '');
+        this.actor = options.actor;
+        // Bọc thay vì gán trực tiếp: fetch tách khỏi globalThis sẽ ném
+        // "Illegal invocation" trên browser.
+        this.fetchImpl = options.fetch ?? ((...args) => fetch(...args));
+    }
+    /** Tải Form đang phát hành qua Publication key ổn định. */
+    getPublicationForm(key) {
+        return this.request('GET', `/api/publications/${encodeURIComponent(key)}/form`);
+    }
+    /** Tải một Form Version bất biến (Response luôn gắn đúng version đã bắt đầu). */
+    getFormVersion(id) {
+        return this.request('GET', `/api/form-versions/${encodeURIComponent(id)}`);
+    }
+    createResponse(publicationKey, options = {}) {
+        const headers = {};
+        if (options.idempotencyKey)
+            headers['idempotency-key'] = options.idempotencyKey;
+        return this.request('POST', `/api/publications/${encodeURIComponent(publicationKey)}/responses`, {
+            subject_ref: options.subjectRef ?? null,
+            respondent_ref: options.respondentRef ?? null,
+            care_context_ref: options.careContextRef ?? null,
+        }, headers);
+    }
+    getInvitation(id) {
+        return this.request('GET', `/api/invitations/${encodeURIComponent(id)}`);
+    }
+    /** Bắt đầu (hoặc mở lại) Response duy nhất của một Invitation. */
+    startInvitationResponse(invitationId) {
+        return this.request('POST', `/api/invitations/${encodeURIComponent(invitationId)}/responses`);
+    }
+    getResponse(id) {
+        return this.request('GET', `/api/responses/${encodeURIComponent(id)}`);
+    }
+    /** Cập nhật Draft theo lô; value null xoá giá trị. Idempotent khi retry. */
+    updateValues(responseId, values) {
+        return this.request('PUT', `/api/responses/${encodeURIComponent(responseId)}/values`, { values });
+    }
+    /** Hoàn thành/xác nhận; server validate độc lập với SDK. */
+    completeResponse(id) {
+        return this.request('POST', `/api/responses/${encodeURIComponent(id)}/complete`);
+    }
+    getMediaAsset(id) {
+        return this.request('GET', `/api/media/${encodeURIComponent(id)}`);
+    }
+    /**
+     * URL tuyệt đối tới nội dung một Media Asset (ảnh nền Body Map, media nhúng
+     * trong Form). Ổn định theo id nên dùng thẳng trong thẻ img/video/audio.
+     */
+    mediaContentUrl(assetId) {
+        return `${this.baseUrl}/api/media/${encodeURIComponent(assetId)}/content`;
+    }
+    async request(method, path, body, extraHeaders = {}) {
+        const headers = {
+            'content-type': 'application/json',
+            ...extraHeaders,
+        };
+        if (this.actor)
+            headers['x-actor'] = this.actor;
+        const response = await this.fetchImpl(this.baseUrl + path, {
+            method,
+            headers,
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const text = await response.text();
+        let data = null;
+        if (text) {
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                data = null;
+            }
+        }
+        if (!response.ok) {
+            const message = data?.error ?? response.statusText;
+            throw new VgqApiError(response.status, message, data);
+        }
+        return data;
+    }
+}

package/dist/engine.d.ts

@@ -0,0 +1,36 @@
+import type { FormDefinition, JsonValue, QuestionDef, ResponseValues, ValidationIssue } from './types.js';
+export declare function allQuestions(def: FormDefinition): QuestionDef[];
+/**
+ * Sắp xếp topo theo phụ thuộc Enable Condition (Kahn).
+ * `stuck` chứa id các Question nằm trong hoặc phụ thuộc vào chu trình.
+ */
+export declare function topoOrder(def: FormDefinition): {
+    order: string[];
+    stuck: string[];
+};
+export interface ActiveState {
+    /** Id các Question đang hoạt động. */
+    activeIds: Set<string>;
+    /** Giá trị hiệu lực theo slug: chỉ gồm giá trị của Question đang hoạt động. */
+    effectiveValues: ResponseValues;
+}
+/**
+ * Đánh giá Enable Condition toàn Form theo thứ tự topo. Giá trị của Question
+ * không hoạt động bị loại khỏi giá trị hiệu lực nên chuỗi phụ thuộc tắt theo.
+ */
+export declare function computeActive(def: FormDefinition, values: ResponseValues): ActiveState;
+export declare function isAnswered(value: JsonValue | undefined): boolean;
+export declare function deepEqual(a: JsonValue, b: JsonValue): boolean;
+export type CompletionResult = {
+    ok: true;
+    official: ResponseValues;
+} | {
+    ok: false;
+    issues: ValidationIssue[];
+};
+/**
+ * Validate hoàn thành giống server: Question bắt buộc đang hoạt động phải có
+ * giá trị hợp lệ; giá trị của Question không hoạt động bị loại khỏi kết quả
+ * chính thức nhưng vẫn nằm trong Draft.
+ */
+export declare function validateCompletion(def: FormDefinition, values: ResponseValues): CompletionResult;

package/dist/engine.js

@@ -0,0 +1,266 @@
+// Bản sao phía client của Form Engine: đánh giá Enable Condition và validate
+// Response Value đúng như server, để ứng dụng phản hồi ngay cho người dùng.
+// Server vẫn validate độc lập khi hoàn thành — SDK không phải chốt chặn cuối.
+export function allQuestions(def) {
+    const out = [];
+    const walk = (categories) => {
+        for (const category of categories) {
+            out.push(...category.questions);
+            walk(category.children ?? []);
+        }
+    };
+    walk(def.categories);
+    return out;
+}
+function conditionRefs(question) {
+    return (question.enable_condition?.any ?? []).flatMap((group) => group.all.map((condition) => condition.question_id));
+}
+/**
+ * Sắp xếp topo theo phụ thuộc Enable Condition (Kahn).
+ * `stuck` chứa id các Question nằm trong hoặc phụ thuộc vào chu trình.
+ */
+export function topoOrder(def) {
+    const questions = allQuestions(def);
+    const known = new Set(questions.map((q) => q.id));
+    const inDegree = new Map();
+    const dependents = new Map();
+    for (const q of questions) {
+        const valid = conditionRefs(q).filter((ref) => known.has(ref));
+        inDegree.set(q.id, valid.length);
+        for (const ref of valid) {
+            const list = dependents.get(ref) ?? [];
+            list.push(q.id);
+            dependents.set(ref, list);
+        }
+    }
+    const queue = [...inDegree.entries()].filter(([, d]) => d === 0).map(([id]) => id);
+    const order = [];
+    while (queue.length > 0) {
+        const id = queue.pop();
+        order.push(id);
+        for (const dependent of dependents.get(id) ?? []) {
+            const d = inDegree.get(dependent) - 1;
+            inDegree.set(dependent, d);
+            if (d === 0)
+                queue.push(dependent);
+        }
+    }
+    const done = new Set(order);
+    const stuck = [...known].filter((id) => !done.has(id)).sort();
+    return { order, stuck };
+}
+/**
+ * Đánh giá Enable Condition toàn Form theo thứ tự topo. Giá trị của Question
+ * không hoạt động bị loại khỏi giá trị hiệu lực nên chuỗi phụ thuộc tắt theo.
+ */
+export function computeActive(def, values) {
+    const questions = allQuestions(def);
+    const byId = new Map(questions.map((q) => [q.id, q]));
+    const { order, stuck } = topoOrder(def);
+    const evaluationOrder = stuck.length === 0 ? order : questions.map((q) => q.id);
+    const effectiveValues = {};
+    for (const q of questions) {
+        const v = values[q.slug];
+        if (v !== undefined && v !== null)
+            effectiveValues[q.slug] = v;
+    }
+    const activeIds = new Set();
+    for (const id of evaluationOrder) {
+        const q = byId.get(id);
+        const active = !q.enable_condition || evalCondition(q.enable_condition, effectiveValues, byId);
+        if (active)
+            activeIds.add(id);
+        else
+            delete effectiveValues[q.slug];
+    }
+    return { activeIds, effectiveValues };
+}
+function evalCondition(condition, effective, byId) {
+    return condition.any.some((group) => group.all.every((c) => evalSingle(c, effective, byId)));
+}
+function evalSingle(c, effective, byId) {
+    const question = byId.get(c.question_id);
+    const value = question ? effective[question.slug] : undefined;
+    const target = c.value === undefined ? null : c.value;
+    switch (c.operator) {
+        case 'answered':
+            return isAnswered(value);
+        case 'not_answered':
+            return !isAnswered(value);
+        case 'eq':
+            return value !== undefined && deepEqual(value, target);
+        case 'neq':
+            return isAnswered(value) && !deepEqual(value, target);
+        case 'gt':
+            return compare(value, target) === 1;
+        case 'gte': {
+            const ordering = compare(value, target);
+            return ordering === 0 || ordering === 1;
+        }
+        case 'lt':
+            return compare(value, target) === -1;
+        case 'lte': {
+            const ordering = compare(value, target);
+            return ordering === 0 || ordering === -1;
+        }
+        case 'contains':
+            return contains(value, target);
+    }
+}
+export function isAnswered(value) {
+    if (value === undefined || value === null)
+        return false;
+    if (typeof value === 'string')
+        return value.trim().length > 0;
+    if (Array.isArray(value))
+        return value.length > 0;
+    return true;
+}
+export function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        return a.length === b.length && a.every((item, i) => deepEqual(item, b[i]));
+    }
+    if (a !== null && b !== null &&
+        typeof a === 'object' && typeof b === 'object' &&
+        !Array.isArray(a) && !Array.isArray(b)) {
+        const keysA = Object.keys(a);
+        const keysB = Object.keys(b);
+        return (keysA.length === keysB.length &&
+            keysA.every((k) => k in b && deepEqual(a[k], b[k])));
+    }
+    return false;
+}
+/** So sánh số với số, chuỗi với chuỗi (chuỗi ISO so sánh đúng theo từ điển). */
+function compare(value, target) {
+    if (typeof value === 'number' && typeof target === 'number') {
+        return value < target ? -1 : value > target ? 1 : 0;
+    }
+    if (typeof value === 'string' && typeof target === 'string') {
+        return value < target ? -1 : value > target ? 1 : 0;
+    }
+    return null;
+}
+function contains(value, target) {
+    if (Array.isArray(value))
+        return value.some((item) => deepEqual(item, target));
+    if (typeof value === 'string' && typeof target === 'string') {
+        return value.includes(target);
+    }
+    return false;
+}
+/**
+ * Validate hoàn thành giống server: Question bắt buộc đang hoạt động phải có
+ * giá trị hợp lệ; giá trị của Question không hoạt động bị loại khỏi kết quả
+ * chính thức nhưng vẫn nằm trong Draft.
+ */
+export function validateCompletion(def, values) {
+    const issues = [];
+    const questions = allQuestions(def);
+    const knownSlugs = new Set(questions.map((q) => q.slug));
+    for (const slug of Object.keys(values)) {
+        if (!knownSlugs.has(slug)) {
+            issues.push({
+                path: slug,
+                code: 'unknown_question',
+                message: `Không có Question nào mang slug '${slug}' trong Form Version này`,
+            });
+        }
+    }
+    const state = computeActive(def, values);
+    for (const q of questions) {
+        if (!state.activeIds.has(q.id))
+            continue;
+        const value = state.effectiveValues[q.slug];
+        if (!isAnswered(value)) {
+            if (q.required) {
+                issues.push({
+                    path: q.slug,
+                    code: 'required',
+                    message: `Question bắt buộc '${q.label}' chưa có Response Value`,
+                });
+            }
+            continue;
+        }
+        const problem = checkValue(q, value);
+        if (problem)
+            issues.push({ path: q.slug, code: 'invalid_value', message: problem });
+    }
+    if (issues.length > 0)
+        return { ok: false, issues };
+    const official = {};
+    for (const q of questions) {
+        const value = state.effectiveValues[q.slug];
+        if (value !== undefined)
+            official[q.slug] = value;
+    }
+    return { ok: true, official };
+}
+function checkValue(q, v) {
+    const dt = q.data_type;
+    switch (dt.type) {
+        case 'boolean':
+            return typeof v === 'boolean' ? null : 'Giá trị phải là boolean';
+        case 'text':
+        case 'long_text':
+            return typeof v === 'string' ? null : 'Giá trị phải là chuỗi';
+        case 'integer':
+            return typeof v === 'number' && Number.isInteger(v)
+                ? null
+                : 'Giá trị phải là số nguyên';
+        case 'decimal':
+        case 'measurement':
+            return typeof v === 'number' && Number.isFinite(v)
+                ? null
+                : 'Giá trị phải là số';
+        case 'date': {
+            if (typeof v !== 'string')
+                return 'Giá trị ngày phải là chuỗi YYYY-MM-DD';
+            if (!/^\d{4}-\d{2}-\d{2}$/.test(v) || Number.isNaN(Date.parse(v))) {
+                return `'${v}' không phải ngày hợp lệ (YYYY-MM-DD)`;
+            }
+            return null;
+        }
+        case 'date_time': {
+            if (typeof v !== 'string')
+                return 'Giá trị thời điểm phải là chuỗi RFC 3339';
+            const rfc3339 = /^\d{4}-\d{2}-\d{2}[Tt ]\d{2}:\d{2}:\d{2}(\.\d+)?([Zz]|[+-]\d{2}:\d{2})$/;
+            if (!rfc3339.test(v) || Number.isNaN(Date.parse(v))) {
+                return `'${v}' không phải thời điểm RFC 3339 hợp lệ`;
+            }
+            return null;
+        }
+        case 'attachment':
+            return typeof v === 'string' && v.trim().length > 0
+                ? null
+                : 'Giá trị attachment phải là tham chiếu chuỗi';
+        // Body Map trả lời bằng slug của các vị trí đã chọn, cùng luật với choice.
+        case 'choice':
+        case 'body_map': {
+            const optionSlugs = new Set(q.options.map((o) => o.slug));
+            const checkOne = (item) => {
+                if (typeof item !== 'string')
+                    return 'Giá trị choice phải là slug của Option';
+                return optionSlugs.has(item)
+                    ? null
+                    : `'${item}' không phải Option của Question này`;
+            };
+            if (dt.multiple) {
+                if (!Array.isArray(v))
+                    return 'Choice nhiều lựa chọn phải là mảng slug';
+                const seen = new Set();
+                for (const item of v) {
+                    const problem = checkOne(item);
+                    if (problem)
+                        return problem;
+                    if (seen.has(item))
+                        return 'Các lựa chọn không được lặp lại';
+                    seen.add(item);
+                }
+                return null;
+            }
+            return checkOne(v);
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './types.js';
+export { allQuestions, computeActive, isAnswered, topoOrder, validateCompletion, } from './engine.js';
+export type { ActiveState, CompletionResult } from './engine.js';
+export { VgqApiError, VgqClient } from './client.js';
+export type { StartResponseOptions, VgqClientOptions } from './client.js';
+export { ResponseSession } from './session.js';
+export type { SessionClient, SessionOptions, StartSessionOptions, } from './session.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './types.js';
+export { allQuestions, computeActive, isAnswered, topoOrder, validateCompletion, } from './engine.js';
+export { VgqApiError, VgqClient } from './client.js';
+export { ResponseSession } from './session.js';

package/dist/session.d.ts

@@ -0,0 +1,72 @@
+import type { VgqClient } from './client.js';
+import type { ActiveState, CompletionResult } from './engine.js';
+import type { FormDefinition, JsonValue, ResponseDto, ResponseValues } from './types.js';
+/** Phần VgqClient mà ResponseSession cần — thu hẹp để test dễ stub. */
+export type SessionClient = Pick<VgqClient, 'getFormVersion' | 'createResponse' | 'startInvitationResponse' | 'getResponse' | 'updateValues' | 'completeResponse'>;
+export interface SessionOptions {
+    /** Thời gian gom thay đổi trước khi đồng bộ lên server (ms). Mặc định 800. */
+    debounceMs?: number;
+    /** Gọi khi một lần đồng bộ Draft thất bại; thay đổi được giữ lại để thử lại. */
+    onSyncError?: (error: unknown) => void;
+    /** Gọi sau mỗi lần đồng bộ Draft thành công. */
+    onSync?: (response: ResponseDto) => void;
+}
+export interface StartSessionOptions {
+    /** Bắt đầu qua Publication key... */
+    publicationKey?: string;
+    /** ...hoặc qua Invitation đã được tạo sẵn. */
+    invitationId?: string;
+    subjectRef?: string;
+    respondentRef?: string;
+    careContextRef?: string;
+    idempotencyKey?: string;
+}
+/**
+ * Quản lý trạng thái một Response phía client: giữ giá trị cục bộ, đánh giá
+ * Question nào đang hoạt động, validate như server và đồng bộ Draft theo lô
+ * (debounce) để mạng chập chờn không tạo Response trùng hay mất dữ liệu.
+ */
+export declare class ResponseSession {
+    readonly definition: FormDefinition;
+    readonly responseId: string;
+    readonly formVersionId: string;
+    private readonly client;
+    private readonly options;
+    private readonly questionBySlug;
+    private values;
+    private lastServerState;
+    private dirty;
+    private timer;
+    private inflight;
+    private constructor();
+    /** Bắt đầu Response mới qua Publication hoặc Invitation. */
+    static start(client: SessionClient, start: StartSessionOptions, options?: SessionOptions): Promise<ResponseSession>;
+    /** Mở lại Draft đã có để tiếp tục nhập. */
+    static resume(client: SessionClient, responseId: string, options?: SessionOptions): Promise<ResponseSession>;
+    get response(): ResponseDto;
+    /** Ảnh chụp giá trị Draft cục bộ hiện tại. */
+    get draftValues(): ResponseValues;
+    getValue(slug: string): JsonValue | undefined;
+    /**
+     * Đặt giá trị cho một Question theo slug (null/undefined để xoá) và lên lịch
+     * đồng bộ. Giá trị của Question đang tắt vẫn được giữ — chỉ khi hoàn thành
+     * chúng mới bị loại khỏi kết quả chính thức.
+     */
+    setValue(slug: string, value: JsonValue | null | undefined): void;
+    /** Trạng thái hoạt động của các Question theo Enable Condition. */
+    activeState(): ActiveState;
+    isActive(slug: string): boolean;
+    /** Validate cục bộ giống server, dùng để phản hồi trước khi gửi. */
+    validate(): CompletionResult;
+    /** Đẩy ngay mọi thay đổi đang chờ lên server. */
+    flush(): Promise<void>;
+    /**
+     * Hoàn thành/xác nhận Response: đồng bộ nốt thay đổi rồi gọi server.
+     * Server validate độc lập; lỗi validation ném VgqApiError với `issues`.
+     */
+    complete(): Promise<ResponseDto>;
+    /** Hủy timer đồng bộ (khi rời màn hình). Thay đổi chưa đẩy vẫn giữ trong bộ nhớ. */
+    dispose(): void;
+    private schedule;
+    private push;
+}

package/dist/session.js

@@ -0,0 +1,156 @@
+import { computeActive, validateCompletion } from './engine.js';
+import { allQuestions } from './engine.js';
+/**
+ * Quản lý trạng thái một Response phía client: giữ giá trị cục bộ, đánh giá
+ * Question nào đang hoạt động, validate như server và đồng bộ Draft theo lô
+ * (debounce) để mạng chập chờn không tạo Response trùng hay mất dữ liệu.
+ */
+export class ResponseSession {
+    definition;
+    responseId;
+    formVersionId;
+    client;
+    options;
+    questionBySlug;
+    values;
+    lastServerState;
+    dirty = new Set();
+    timer = null;
+    inflight = Promise.resolve();
+    constructor(client, definition, response, options) {
+        this.client = client;
+        this.definition = definition;
+        this.responseId = response.id;
+        this.formVersionId = response.form_version_id;
+        this.options = options;
+        this.values = { ...response.draft_values };
+        this.lastServerState = response;
+        this.questionBySlug = new Map(allQuestions(definition).map((q) => [q.slug, q]));
+    }
+    /** Bắt đầu Response mới qua Publication hoặc Invitation. */
+    static async start(client, start, options = {}) {
+        let response;
+        if (start.invitationId) {
+            response = await client.startInvitationResponse(start.invitationId);
+        }
+        else if (start.publicationKey) {
+            response = await client.createResponse(start.publicationKey, {
+                subjectRef: start.subjectRef,
+                respondentRef: start.respondentRef,
+                careContextRef: start.careContextRef,
+                idempotencyKey: start.idempotencyKey,
+            });
+        }
+        else {
+            throw new Error('Cần publicationKey hoặc invitationId để bắt đầu Response');
+        }
+        // Định nghĩa lấy theo đúng Form Version mà Response đã ghim, không phải
+        // version mới nhất của Publication (Draft không đổi Form giữa chừng).
+        const version = await client.getFormVersion(response.form_version_id);
+        return new ResponseSession(client, version.definition, response, options);
+    }
+    /** Mở lại Draft đã có để tiếp tục nhập. */
+    static async resume(client, responseId, options = {}) {
+        const response = await client.getResponse(responseId);
+        const version = await client.getFormVersion(response.form_version_id);
+        return new ResponseSession(client, version.definition, response, options);
+    }
+    get response() {
+        return this.lastServerState;
+    }
+    /** Ảnh chụp giá trị Draft cục bộ hiện tại. */
+    get draftValues() {
+        return { ...this.values };
+    }
+    getValue(slug) {
+        return this.values[slug];
+    }
+    /**
+     * Đặt giá trị cho một Question theo slug (null/undefined để xoá) và lên lịch
+     * đồng bộ. Giá trị của Question đang tắt vẫn được giữ — chỉ khi hoàn thành
+     * chúng mới bị loại khỏi kết quả chính thức.
+     */
+    setValue(slug, value) {
+        if (!this.questionBySlug.has(slug)) {
+            throw new Error(`Không có Question nào mang slug '${slug}' trong Form Version này`);
+        }
+        if (value === null || value === undefined)
+            delete this.values[slug];
+        else
+            this.values[slug] = value;
+        this.dirty.add(slug);
+        this.schedule();
+    }
+    /** Trạng thái hoạt động của các Question theo Enable Condition. */
+    activeState() {
+        return computeActive(this.definition, this.values);
+    }
+    isActive(slug) {
+        const question = this.questionBySlug.get(slug);
+        return question ? this.activeState().activeIds.has(question.id) : false;
+    }
+    /** Validate cục bộ giống server, dùng để phản hồi trước khi gửi. */
+    validate() {
+        return validateCompletion(this.definition, this.values);
+    }
+    /** Đẩy ngay mọi thay đổi đang chờ lên server. */
+    flush() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        const run = this.inflight.then(() => this.push());
+        // Chuỗi inflight không được giữ trạng thái rejected, nếu không các lần
+        // flush sau sẽ không bao giờ chạy; lỗi vẫn trả về cho caller qua `run`.
+        this.inflight = run.catch(() => { });
+        return run;
+    }
+    /**
+     * Hoàn thành/xác nhận Response: đồng bộ nốt thay đổi rồi gọi server.
+     * Server validate độc lập; lỗi validation ném VgqApiError với `issues`.
+     */
+    async complete() {
+        await this.flush();
+        const response = await this.client.completeResponse(this.responseId);
+        this.lastServerState = response;
+        return response;
+    }
+    /** Hủy timer đồng bộ (khi rời màn hình). Thay đổi chưa đẩy vẫn giữ trong bộ nhớ. */
+    dispose() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+    }
+    schedule() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            // Lỗi đã được báo qua onSyncError; thay đổi được giữ lại để thử lại.
+            this.flush().catch(() => { });
+        }, this.options.debounceMs ?? 800);
+    }
+    async push() {
+        if (this.dirty.size === 0)
+            return;
+        const batch = {};
+        for (const slug of this.dirty) {
+            batch[slug] = this.values[slug] ?? null;
+        }
+        this.dirty.clear();
+        try {
+            const response = await this.client.updateValues(this.responseId, batch);
+            this.lastServerState = response;
+            this.options.onSync?.(response);
+        }
+        catch (error) {
+            // Giữ lại thay đổi để lần flush sau thử lại (PUT merge idempotent nên
+            // gửi trùng vô hại).
+            for (const slug of Object.keys(batch))
+                this.dirty.add(slug);
+            this.options.onSyncError?.(error);
+            throw error;
+        }
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,141 @@
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type FormType = 'bang_khai_bao' | 'phieu_ket_qua_chuyen_mon';
+export type DataType = {
+    type: 'boolean';
+} | {
+    type: 'text';
+} | {
+    type: 'long_text';
+} | {
+    type: 'integer';
+} | {
+    type: 'decimal';
+} | {
+    type: 'date';
+} | {
+    type: 'date_time';
+} | {
+    type: 'choice';
+    multiple?: boolean;
+} | {
+    type: 'measurement';
+    unit: string;
+} | {
+    type: 'attachment';
+} | {
+    type: 'body_map';
+    background_asset_id: string;
+    multiple?: boolean;
+};
+export type Operator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'answered' | 'not_answered';
+export interface Condition {
+    question_id: string;
+    operator: Operator;
+    value?: JsonValue;
+}
+export interface ConditionGroup {
+    all: Condition[];
+}
+/** Các nhóm điều kiện ALL, kết hợp với nhau bằng ANY. */
+export interface EnableCondition {
+    any: ConditionGroup[];
+}
+/**
+ * Vị trí do người thiết kế đặt sẵn trên Body Map. Toạ độ chuẩn hoá 0..1 theo
+ * chiều rộng/cao của ảnh nền; `region` rỗng/vắng mặt nghĩa là Option dạng điểm.
+ */
+export interface BodyMapSpot {
+    x: number;
+    y: number;
+    region?: [number, number][];
+    color?: string;
+    /** Metadata lâm sàng tuỳ ý; VGQ không diễn giải. */
+    metadata?: JsonValue;
+}
+export interface OptionDef {
+    id: string;
+    slug: string;
+    label: string;
+    /** Chỉ có mặt khi Question có data type body_map. */
+    body_map?: BodyMapSpot | null;
+}
+export interface MediaAssetDto {
+    id: string;
+    file_name: string;
+    content_type: string;
+    kind: 'image' | 'video' | 'audio' | 'document';
+    size_bytes: number;
+    uploaded_by: string;
+    created_at: string;
+    /** Đường dẫn tương đối ổn định tới nội dung asset. */
+    url: string;
+}
+export interface QuestionDef {
+    id: string;
+    slug: string;
+    label: string;
+    data_type: DataType;
+    required?: boolean;
+    options: OptionDef[];
+    enable_condition?: EnableCondition | null;
+    display?: JsonValue;
+}
+/** Cấp tổ chức duy nhất trong Form: Category lồng nhau và chứa Question. */
+export interface CategoryDef {
+    id: string;
+    label: string;
+    children?: CategoryDef[];
+    questions: QuestionDef[];
+}
+export interface FormDefinition {
+    title: string;
+    form_type: FormType;
+    categories: CategoryDef[];
+}
+export interface ValidationIssue {
+    path: string;
+    code: string;
+    message: string;
+}
+export type ResponseValues = Record<string, JsonValue>;
+export type ResponseStatus = 'draft' | 'completed' | 'confirmed';
+export interface ResponseDto {
+    id: string;
+    form_version_id: string;
+    status: ResponseStatus;
+    subject_ref: string | null;
+    respondent_ref: string | null;
+    care_context_ref: string | null;
+    draft_values: ResponseValues;
+    official_values: ResponseValues | null;
+    created_at: string;
+    updated_at: string;
+    completed_at: string | null;
+    completed_by: string | null;
+}
+export interface PublicationForm {
+    publication_key: string;
+    form_version_id: string;
+    version_number: number;
+    definition: FormDefinition;
+}
+export interface FormVersion {
+    id: string;
+    form_id: string;
+    version_number: number;
+    definition: FormDefinition;
+    published_by: string;
+    published_at: string;
+}
+export interface InvitationDto {
+    id: string;
+    publication_key: string;
+    subject_ref: string | null;
+    respondent_ref: string | null;
+    care_context_ref: string | null;
+    response_id: string | null;
+    created_by: string;
+    created_at: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@viengut/vgq-sdk",
+  "version": "0.1.0",
+  "description": "Headless TypeScript SDK for the VGQ clinical form platform: load published Forms, manage Response state, evaluate Enable Conditions and validate Response Values without any UI components.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/viengut-hospital/vgq-questionnaire.git",
+    "directory": "sdk"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "vitest": "^3.0.0"
+  }
+}