@junctura/health-contracts 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,13 @@
+Junctura Health
+Copyright 2026 Junctura Contributors
+
+Original Junctura Health source code is licensed under the Apache License,
+Version 2.0. The attribution above is subject to each contributor's actual
+rights and agreement; it does not claim ownership of upstream components.
+
+External components retain their own copyright, license and notice terms.
+Dependencies are declared in package manifests and installed from their
+registries; no third-party source code has been copied into this project.
+Patient data under seed/data/ is synthetic: produced by this project's own
+generator (seed/generate.mjs) from team-written vocabulary. It describes no
+real person. Diagnosis codes follow ICD-10 (WHO) and vaccine codes follow CVX.

package/README.md

@@ -1,3 +1,62 @@
-# Temporary Holding Version
+<!-- SPDX-FileCopyrightText: 2026 Junctura Contributors -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
 
-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.
+# Hợp đồng năng lực Junctura Health
+
+Nguồn duy nhất cho các năng lực mà ứng dụng Tầng 2 cung cấp và gọi qua Junctura. Bên cung cấp và bên gọi cùng dùng một định nghĩa, nên không lệch nhau.
+
+## Cấu trúc
+
+| Đường dẫn | Nội dung |
+| --- | --- |
+| `capabilities/<slug>.json` | Một hợp đồng: phiên bản, bên cung cấp, bên gọi, mục đích được phép, có cho cấp cứu không, tiêu đề, mô tả, schema vào/ra, thời gian chờ |
+| `examples/<slug>.json` | Một cặp `input`/`output` hợp lệ, dùng cho test và dữ liệu demo |
+| `index.mjs`, `index.d.ts` | Thư viện dùng chung (không phụ thuộc thư viện ngoài) |
+
+Schema dùng đúng profile payload của Junctura: `object` (bắt buộc `properties`, `required`, `additionalProperties: false`), `array` (bắt buộc `maxItems`), `string` (bắt buộc `maxLength`), `integer`/`number` (bắt buộc `minimum`/`maximum`), `boolean`, `null`. Profile không có `enum` hay `pattern`, nên các giá trị cố định (ví dụ `severity`: `mild | moderate | severe`) được ghi trong `description` và do bên cung cấp đảm bảo.
+
+## Quy tắc chung
+
+- Mọi năng lực đều về **một người bệnh**. Người bệnh không nằm trong `input` mà đi qua `context.dataSubject` (Keycloak `sub` của người bệnh); Junctura kiểm tra đồng thuận của người đó trước khi cấp vé.
+- Bên gọi luôn khai `context.purpose`, phải nằm trong `purposes` của hợp đồng.
+- `emergency: true` (truy cập cấp cứu) chỉ dùng được với năng lực có `emergencyAccess: true`, kèm `justification`, và bị rà soát sau.
+- Dữ liệu trả về là **tối thiểu**: ví dụ `claim-verify` chỉ trả `matches` có/không, không có chẩn đoán.
+
+## Dùng trong ứng dụng
+
+```js
+import { buildManifest, checkContext, validateValue, getContract } from "@junctura/health-contracts";
+
+// Bên cung cấp: đăng ký manifest với ID ứng dụng đã enroll.
+const manifest = buildManifest("allergy-list", process.env.JUNCTURA_APP_ID);
+
+// Bên cung cấp: sau khi đổi vé (SDK redeemTicket), kiểm tra context rồi mới trả dữ liệu.
+const decision = checkContext("allergy-list", redeemed.context);
+if (!decision.allowed) return reply(403, { error: decision.reason });
+
+// Cả hai bên: kiểm tra dữ liệu đúng hợp đồng.
+const issues = validateValue(getContract("allergy-list").outputSchema, output);
+```
+
+## Đổi hợp đồng
+
+Mở PR ở repo này. Thay đổi không tương thích (bỏ trường, đổi kiểu, siết giới hạn) phải tăng **major** version; thêm trường không bắt buộc tăng **minor**. Cập nhật ví dụ, `CHANGELOG.md`, và báo các repo app liên quan.
+
+## Cài đặt
+
+```sh
+npm install @junctura/health-contracts
+```
+
+Gói không phụ thuộc thư viện ngoài, chạy trên Node 24, có sẵn kiểu TypeScript (`index.d.ts`). Mỗi bản phát hành lên npm kèm provenance (có thể kiểm tra bản build đến từ repo này).
+
+## Phát hành lên npm
+
+Sau khi PR đổi hợp đồng đã merge: sửa `version` trong `contracts/package.json`, rồi đẩy tag trùng version:
+
+```sh
+git tag contracts-v1.0.0
+git push origin contracts-v1.0.0
+```
+
+Workflow `Publish contracts library` kiểm tra tag khớp version, chạy test, rồi publish.

package/capabilities/allergy-list.json

@@ -0,0 +1,75 @@
+{
+  "slug": "allergy-list",
+  "version": "1.0.0",
+  "provider": "junctura-clinic",
+  "consumers": [
+    "junctura-hospital",
+    "junctura-pharmacy"
+  ],
+  "purposes": [
+    "treatment",
+    "dispensing"
+  ],
+  "emergencyAccess": true,
+  "title": "Danh sách dị ứng",
+  "description": "Các chất gây dị ứng đã ghi nhận của người bệnh, dùng để cảnh báo khi kê đơn hoặc phát thuốc.",
+  "inputSchema": {
+    "type": "object",
+    "description": "Không có tham số: người bệnh được xác định qua context.dataSubject.",
+    "properties": {},
+    "required": [],
+    "additionalProperties": false
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "allergies": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "substance": {
+              "type": "string",
+              "maxLength": 120,
+              "description": "Chất gây dị ứng, ví dụ Penicillin."
+            },
+            "severity": {
+              "type": "string",
+              "maxLength": 16,
+              "description": "mild | moderate | severe"
+            },
+            "reaction": {
+              "type": "string",
+              "maxLength": 240,
+              "description": "Biểu hiện đã ghi nhận."
+            }
+          },
+          "required": [
+            "substance",
+            "severity",
+            "reaction"
+          ],
+          "additionalProperties": false
+        },
+        "maxItems": 50
+      },
+      "updatedAt": {
+        "type": "string",
+        "minLength": 20,
+        "maxLength": 30,
+        "description": "Thời điểm ISO 8601 (UTC)."
+      }
+    },
+    "required": [
+      "allergies",
+      "updatedAt"
+    ],
+    "additionalProperties": false
+  },
+  "sideEffects": {
+    "kind": "none",
+    "description": "Chỉ đọc; không thay đổi dữ liệu của bên cung cấp.",
+    "idempotency": "none"
+  },
+  "timeoutMs": 2000
+}

package/capabilities/claim-verify.json

@@ -0,0 +1,62 @@
+{
+  "slug": "claim-verify",
+  "version": "1.0.0",
+  "provider": "junctura-hospital",
+  "consumers": [
+    "junctura-insurance"
+  ],
+  "purposes": [
+    "claim_review"
+  ],
+  "emergencyAccess": false,
+  "title": "Xác minh chi phí điều trị",
+  "description": "Cho bên bảo hiểm biết một khoản chi có khớp với hồ sơ điều trị hay không. Chỉ trả lời có/không, không trả chẩn đoán hay chi tiết điều trị.",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "claimId": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 64,
+        "description": "Mã hồ sơ thanh toán."
+      },
+      "amountVnd": {
+        "type": "integer",
+        "minimum": 0,
+        "maximum": 1000000000000,
+        "description": "Số tiền đề nghị thanh toán (VND)."
+      }
+    },
+    "required": [
+      "claimId",
+      "amountVnd"
+    ],
+    "additionalProperties": false
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "matches": {
+        "type": "boolean",
+        "description": "Khoản chi khớp với hồ sơ điều trị."
+      },
+      "checkedAt": {
+        "type": "string",
+        "minLength": 20,
+        "maxLength": 30,
+        "description": "Thời điểm ISO 8601 (UTC)."
+      }
+    },
+    "required": [
+      "matches",
+      "checkedAt"
+    ],
+    "additionalProperties": false
+  },
+  "sideEffects": {
+    "kind": "none",
+    "description": "Chỉ đọc; không thay đổi dữ liệu của bên cung cấp.",
+    "idempotency": "none"
+  },
+  "timeoutMs": 2000
+}

package/capabilities/pre-visit-summary.json

@@ -0,0 +1,202 @@
+{
+  "slug": "pre-visit-summary",
+  "version": "1.0.0",
+  "provider": "junctura-clinic",
+  "consumers": [
+    "junctura-hospital"
+  ],
+  "purposes": [
+    "treatment"
+  ],
+  "emergencyAccess": true,
+  "title": "Tóm tắt trước khám",
+  "description": "Dị ứng, bệnh mạn tính, thuốc đang dùng và tối đa 3 lần khám gần nhất của người bệnh tại trạm y tế, để bác sĩ tuyến trên khám không phải hỏi lại.",
+  "inputSchema": {
+    "type": "object",
+    "description": "Không có tham số: người bệnh được xác định qua context.dataSubject.",
+    "properties": {},
+    "required": [],
+    "additionalProperties": false
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "patientName": {
+        "type": "string",
+        "maxLength": 120,
+        "description": "Họ tên người bệnh."
+      },
+      "birthYear": {
+        "type": "integer",
+        "minimum": 1900,
+        "maximum": 2100,
+        "description": "Năm sinh."
+      },
+      "sex": {
+        "type": "string",
+        "maxLength": 16,
+        "description": "female | male | other"
+      },
+      "allergies": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "substance": {
+              "type": "string",
+              "maxLength": 120,
+              "description": "Chất gây dị ứng, ví dụ Penicillin."
+            },
+            "severity": {
+              "type": "string",
+              "maxLength": 16,
+              "description": "mild | moderate | severe"
+            },
+            "reaction": {
+              "type": "string",
+              "maxLength": 240,
+              "description": "Biểu hiện đã ghi nhận."
+            }
+          },
+          "required": [
+            "substance",
+            "severity",
+            "reaction"
+          ],
+          "additionalProperties": false
+        },
+        "maxItems": 50
+      },
+      "chronicConditions": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "code": {
+              "type": "string",
+              "maxLength": 16,
+              "description": "Mã ICD-10."
+            },
+            "name": {
+              "type": "string",
+              "maxLength": 160
+            },
+            "since": {
+              "type": "string",
+              "minLength": 10,
+              "maxLength": 10,
+              "description": "Ngày dạng YYYY-MM-DD."
+            }
+          },
+          "required": [
+            "code",
+            "name",
+            "since"
+          ],
+          "additionalProperties": false
+        },
+        "maxItems": 50
+      },
+      "currentMedications": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string",
+              "maxLength": 160
+            },
+            "dose": {
+              "type": "string",
+              "maxLength": 80,
+              "description": "Liều dùng, ví dụ 500 mg x 2 lần/ngày."
+            },
+            "since": {
+              "type": "string",
+              "minLength": 10,
+              "maxLength": 10,
+              "description": "Ngày dạng YYYY-MM-DD."
+            }
+          },
+          "required": [
+            "name",
+            "dose",
+            "since"
+          ],
+          "additionalProperties": false
+        },
+        "maxItems": 50
+      },
+      "recentEncounters": {
+        "type": "array",
+        "description": "Tối đa 3 lần khám gần nhất, mới nhất trước.",
+        "items": {
+          "type": "object",
+          "properties": {
+            "date": {
+              "type": "string",
+              "minLength": 10,
+              "maxLength": 10,
+              "description": "Ngày dạng YYYY-MM-DD."
+            },
+            "reason": {
+              "type": "string",
+              "maxLength": 240,
+              "description": "Lý do khám."
+            },
+            "diagnosis": {
+              "type": "object",
+              "properties": {
+                "code": {
+                  "type": "string",
+                  "maxLength": 16,
+                  "description": "Mã ICD-10."
+                },
+                "name": {
+                  "type": "string",
+                  "maxLength": 160,
+                  "description": "Tên chẩn đoán."
+                }
+              },
+              "required": [
+                "code",
+                "name"
+              ],
+              "additionalProperties": false
+            }
+          },
+          "required": [
+            "date",
+            "reason",
+            "diagnosis"
+          ],
+          "additionalProperties": false
+        },
+        "maxItems": 3
+      },
+      "updatedAt": {
+        "type": "string",
+        "minLength": 20,
+        "maxLength": 30,
+        "description": "Thời điểm ISO 8601 (UTC)."
+      }
+    },
+    "required": [
+      "patientName",
+      "birthYear",
+      "sex",
+      "allergies",
+      "chronicConditions",
+      "currentMedications",
+      "recentEncounters",
+      "updatedAt"
+    ],
+    "additionalProperties": false
+  },
+  "sideEffects": {
+    "kind": "none",
+    "description": "Chỉ đọc; không thay đổi dữ liệu của bên cung cấp.",
+    "idempotency": "none"
+  },
+  "timeoutMs": 3000
+}

package/capabilities/prescription-verify.json

@@ -0,0 +1,105 @@
+{
+  "slug": "prescription-verify",
+  "version": "1.0.0",
+  "provider": "junctura-hospital",
+  "consumers": [
+    "junctura-pharmacy"
+  ],
+  "purposes": [
+    "dispensing"
+  ],
+  "emergencyAccess": false,
+  "title": "Xác minh đơn thuốc",
+  "description": "Kiểm tra một đơn thuốc do bệnh viện kê: còn hiệu lực không, gồm những thuốc gì, đã phát chưa.",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "prescriptionCode": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 32,
+        "description": "Mã đơn thuốc in trên đơn."
+      }
+    },
+    "required": [
+      "prescriptionCode"
+    ],
+    "additionalProperties": false
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "valid": {
+        "type": "boolean",
+        "description": "Đơn tồn tại, đúng người bệnh và còn hạn."
+      },
+      "issuedAt": {
+        "type": "string",
+        "minLength": 20,
+        "maxLength": 30,
+        "description": "Thời điểm ISO 8601 (UTC)."
+      },
+      "expiresAt": {
+        "type": "string",
+        "minLength": 20,
+        "maxLength": 30,
+        "description": "Thời điểm ISO 8601 (UTC)."
+      },
+      "items": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string",
+              "maxLength": 160,
+              "description": "Tên thuốc."
+            },
+            "strength": {
+              "type": "string",
+              "maxLength": 80,
+              "description": "Hàm lượng."
+            },
+            "quantity": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 1000,
+              "description": "Số lượng."
+            },
+            "instructions": {
+              "type": "string",
+              "maxLength": 240,
+              "description": "Cách dùng."
+            }
+          },
+          "required": [
+            "name",
+            "strength",
+            "quantity",
+            "instructions"
+          ],
+          "additionalProperties": false
+        },
+        "maxItems": 20
+      },
+      "dispensed": {
+        "type": "boolean",
+        "description": "Đơn đã được phát thuốc."
+      }
+    },
+    "required": [
+      "valid",
+      "issuedAt",
+      "expiresAt",
+      "items",
+      "dispensed"
+    ],
+    "additionalProperties": false
+  },
+  "sideEffects": {
+    "kind": "none",
+    "description": "Chỉ đọc; không thay đổi dữ liệu của bên cung cấp.",
+    "idempotency": "none"
+  },
+  "timeoutMs": 2000
+}

package/capabilities/referral-summary.json

@@ -0,0 +1,106 @@
+{
+  "slug": "referral-summary",
+  "version": "1.0.0",
+  "provider": "junctura-clinic",
+  "consumers": [
+    "junctura-hospital"
+  ],
+  "purposes": [
+    "referral_intake"
+  ],
+  "emergencyAccess": false,
+  "title": "Hồ sơ chuyển tuyến",
+  "description": "Phiếu chuyển tuyến điện tử từ trạm y tế: lý do chuyển, chẩn đoán sơ bộ và xử trí đã làm.",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "referralId": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 64,
+        "description": "Mã phiếu chuyển tuyến do trạm y tế cấp."
+      }
+    },
+    "required": [
+      "referralId"
+    ],
+    "additionalProperties": false
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "referralId": {
+        "type": "string",
+        "maxLength": 64
+      },
+      "issuedAt": {
+        "type": "string",
+        "minLength": 20,
+        "maxLength": 30,
+        "description": "Thời điểm ISO 8601 (UTC)."
+      },
+      "fromFacility": {
+        "type": "string",
+        "maxLength": 160,
+        "description": "Cơ sở chuyển đi."
+      },
+      "toFacility": {
+        "type": "string",
+        "maxLength": 160,
+        "description": "Cơ sở tiếp nhận."
+      },
+      "urgency": {
+        "type": "string",
+        "maxLength": 16,
+        "description": "routine | urgent | emergency"
+      },
+      "reason": {
+        "type": "string",
+        "maxLength": 500,
+        "description": "Lý do chuyển tuyến."
+      },
+      "provisionalDiagnosis": {
+        "type": "object",
+        "properties": {
+          "code": {
+            "type": "string",
+            "maxLength": 16,
+            "description": "Mã ICD-10."
+          },
+          "name": {
+            "type": "string",
+            "maxLength": 160,
+            "description": "Tên chẩn đoán."
+          }
+        },
+        "required": [
+          "code",
+          "name"
+        ],
+        "additionalProperties": false
+      },
+      "treatmentGiven": {
+        "type": "string",
+        "maxLength": 1000,
+        "description": "Xử trí đã thực hiện trước khi chuyển."
+      }
+    },
+    "required": [
+      "referralId",
+      "issuedAt",
+      "fromFacility",
+      "toFacility",
+      "urgency",
+      "reason",
+      "provisionalDiagnosis",
+      "treatmentGiven"
+    ],
+    "additionalProperties": false
+  },
+  "sideEffects": {
+    "kind": "none",
+    "description": "Chỉ đọc; không thay đổi dữ liệu của bên cung cấp.",
+    "idempotency": "none"
+  },
+  "timeoutMs": 3000
+}

package/capabilities/vaccination-history.json

@@ -0,0 +1,81 @@
+{
+  "slug": "vaccination-history",
+  "version": "1.0.0",
+  "provider": "junctura-clinic",
+  "consumers": [
+    "junctura-hospital"
+  ],
+  "purposes": [
+    "treatment"
+  ],
+  "emergencyAccess": false,
+  "title": "Lịch sử tiêm chủng",
+  "description": "Các mũi vắc xin người bệnh đã tiêm tại trạm y tế.",
+  "inputSchema": {
+    "type": "object",
+    "description": "Không có tham số: người bệnh được xác định qua context.dataSubject.",
+    "properties": {},
+    "required": [],
+    "additionalProperties": false
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "vaccinations": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "vaccine": {
+              "type": "string",
+              "maxLength": 120,
+              "description": "Tên vắc xin."
+            },
+            "code": {
+              "type": "string",
+              "maxLength": 16,
+              "description": "Mã CVX."
+            },
+            "date": {
+              "type": "string",
+              "minLength": 10,
+              "maxLength": 10,
+              "description": "Ngày tiêm, YYYY-MM-DD."
+            },
+            "doseNumber": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 10,
+              "description": "Mũi thứ mấy."
+            }
+          },
+          "required": [
+            "vaccine",
+            "code",
+            "date",
+            "doseNumber"
+          ],
+          "additionalProperties": false
+        },
+        "maxItems": 200
+      },
+      "updatedAt": {
+        "type": "string",
+        "minLength": 20,
+        "maxLength": 30,
+        "description": "Thời điểm ISO 8601 (UTC)."
+      }
+    },
+    "required": [
+      "vaccinations",
+      "updatedAt"
+    ],
+    "additionalProperties": false
+  },
+  "sideEffects": {
+    "kind": "none",
+    "description": "Chỉ đọc; không thay đổi dữ liệu của bên cung cấp.",
+    "idempotency": "none"
+  },
+  "timeoutMs": 2000
+}

package/examples/allergy-list.json

@@ -0,0 +1,13 @@
+{
+  "input": {},
+  "output": {
+    "allergies": [
+      {
+        "substance": "Penicillin",
+        "severity": "severe",
+        "reaction": "Nổi mề đay, khó thở"
+      }
+    ],
+    "updatedAt": "2026-10-28T09:15:00.000Z"
+  }
+}

package/examples/claim-verify.json

@@ -0,0 +1,10 @@
+{
+  "input": {
+    "claimId": "HS-2026-00987",
+    "amountVnd": 2450000
+  },
+  "output": {
+    "matches": true,
+    "checkedAt": "2026-11-02T04:00:00.000Z"
+  }
+}

package/examples/pre-visit-summary.json

@@ -0,0 +1,50 @@
+{
+  "input": {},
+  "output": {
+    "patientName": "Nguyễn Văn An",
+    "birthYear": 1968,
+    "sex": "male",
+    "allergies": [
+      {
+        "substance": "Penicillin",
+        "severity": "severe",
+        "reaction": "Nổi mề đay, khó thở"
+      }
+    ],
+    "chronicConditions": [
+      {
+        "code": "I10",
+        "name": "Tăng huyết áp vô căn",
+        "since": "2019-03-12"
+      },
+      {
+        "code": "E11",
+        "name": "Đái tháo đường type 2",
+        "since": "2021-08-02"
+      }
+    ],
+    "currentMedications": [
+      {
+        "name": "Amlodipin",
+        "dose": "5 mg x 1 lần/ngày",
+        "since": "2019-03-12"
+      },
+      {
+        "name": "Metformin",
+        "dose": "500 mg x 2 lần/ngày",
+        "since": "2021-08-02"
+      }
+    ],
+    "recentEncounters": [
+      {
+        "date": "2026-10-28",
+        "reason": "Đau ngực, khó thở khi gắng sức",
+        "diagnosis": {
+          "code": "I20.9",
+          "name": "Cơn đau thắt ngực"
+        }
+      }
+    ],
+    "updatedAt": "2026-10-28T09:15:00.000Z"
+  }
+}

package/examples/prescription-verify.json

@@ -0,0 +1,19 @@
+{
+  "input": {
+    "prescriptionCode": "DT-2026-004521"
+  },
+  "output": {
+    "valid": true,
+    "issuedAt": "2026-10-29T03:00:00.000Z",
+    "expiresAt": "2026-11-03T03:00:00.000Z",
+    "items": [
+      {
+        "name": "Clopidogrel",
+        "strength": "75 mg",
+        "quantity": 30,
+        "instructions": "Uống 1 viên/ngày sau ăn sáng"
+      }
+    ],
+    "dispensed": false
+  }
+}

package/examples/referral-summary.json

@@ -0,0 +1,18 @@
+{
+  "input": {
+    "referralId": "CT-2026-000123"
+  },
+  "output": {
+    "referralId": "CT-2026-000123",
+    "issuedAt": "2026-10-28T09:30:00.000Z",
+    "fromFacility": "Trạm Y tế phường Hòa Khánh Bắc",
+    "toFacility": "Bệnh viện Đà Nẵng",
+    "urgency": "urgent",
+    "reason": "Đau ngực tái diễn, cần đánh giá tim mạch chuyên sâu",
+    "provisionalDiagnosis": {
+      "code": "I20.9",
+      "name": "Cơn đau thắt ngực"
+    },
+    "treatmentGiven": "Nitroglycerin ngậm dưới lưỡi 0,5 mg; theo dõi huyết áp 30 phút"
+  }
+}

package/examples/vaccination-history.json

@@ -0,0 +1,20 @@
+{
+  "input": {},
+  "output": {
+    "vaccinations": [
+      {
+        "vaccine": "Vắc xin uốn ván (VAT)",
+        "code": "112",
+        "date": "2024-05-10",
+        "doseNumber": 1
+      },
+      {
+        "vaccine": "Vắc xin cúm mùa",
+        "code": "141",
+        "date": "2025-10-02",
+        "doseNumber": 1
+      }
+    ],
+    "updatedAt": "2025-10-02T02:00:00.000Z"
+  }
+}

package/index.d.ts

@@ -0,0 +1,24 @@
+// SPDX-FileCopyrightText: 2026 Junctura Contributors
+// SPDX-License-Identifier: Apache-2.0
+export type Schema =
+  | { type: "object"; description?: string; properties: Record<string, Schema>; required: string[]; additionalProperties: false }
+  | { type: "array"; description?: string; items: Schema; minItems?: number; maxItems: number }
+  | { type: "string"; description?: string; minLength?: number; maxLength: number }
+  | { type: "integer" | "number"; description?: string; minimum: number; maximum: number }
+  | { type: "boolean" | "null"; description?: string };
+export type AppName = "junctura-clinic" | "junctura-hospital" | "junctura-myhealth" | "junctura-pharmacy" | "junctura-insurance";
+export type Contract = Readonly<{
+  slug: string; version: string; provider: AppName; consumers: AppName[]; purposes: string[]; emergencyAccess: boolean;
+  title: string; description: string; inputSchema: Schema; outputSchema: Schema;
+  sideEffects: { kind: "none" | "non-idempotent" | "idempotent"; description: string; idempotency: "none" | "provider-key" };
+  timeoutMs: number;
+}>;
+export const PURPOSE: RegExp;
+export const APPS: readonly AppName[];
+export const CONTRACTS: readonly Contract[];
+export function getContract(slug: string): Contract;
+export function buildManifest(slugOrContract: string | Contract, providerAppId: string): Record<string, unknown>;
+export function validateValue(schema: Schema, value: unknown, path?: string): { path: string; message: string }[];
+export function checkContext(slugOrContract: string | Contract, context: { purpose?: string; dataSubject?: string; emergency?: boolean } | undefined):
+  { allowed: true } | { allowed: false; reason: "data_subject_required" | "purpose_not_allowed" | "emergency_not_allowed" };
+export function isSlug(value: unknown): boolean;

package/index.mjs

@@ -0,0 +1,107 @@
+// SPDX-FileCopyrightText: 2026 Junctura Contributors
+// SPDX-License-Identifier: Apache-2.0
+// Shared capability contracts of Junctura Health. One JSON file per capability in
+// capabilities/; the provider application turns it into a Junctura manifest with
+// its own enrolled application ID (buildManifest), and both sides validate payloads
+// and invocation context against the same definition.
+import { readFileSync, readdirSync } from "node:fs";
+
+const HERE = new URL("./capabilities/", import.meta.url);
+const SLUG = /^[a-z][a-z0-9-]{0,62}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+export const PURPOSE = /^[a-z][a-z0-9_]{1,62}$/;
+export const APPS = Object.freeze(["junctura-clinic", "junctura-hospital", "junctura-myhealth", "junctura-pharmacy", "junctura-insurance"]);
+const PLATFORM = ["caller-active", "provider-active", "grant-active", "same-tenant"];
+
+const deepFreeze = value => {
+  if (value && typeof value === "object") { Object.values(value).forEach(deepFreeze); Object.freeze(value); }
+  return value;
+};
+
+export const CONTRACTS = deepFreeze(readdirSync(HERE).filter(name => name.endsWith(".json")).sort()
+  .map(name => JSON.parse(readFileSync(new URL(name, HERE), "utf8"))));
+
+export function getContract(slug) {
+  const contract = CONTRACTS.find(item => item.slug === slug);
+  if (!contract) throw new RangeError(`Unknown capability contract: ${slug}`);
+  return contract;
+}
+
+/** The Junctura manifest (manifestVersion 1.0) a provider registers for this contract. */
+export function buildManifest(slugOrContract, providerAppId) {
+  const contract = typeof slugOrContract === "string" ? getContract(slugOrContract) : slugOrContract;
+  if (typeof providerAppId !== "string" || !UUID.test(providerAppId)) throw new TypeError("providerAppId must be the provider's enrolled lowercase UUID");
+  return {
+    manifestVersion: "1.0",
+    capabilityId: `urn:junctura:capability:${providerAppId}:${contract.slug}`,
+    providerAppId,
+    version: contract.version,
+    title: contract.title,
+    description: contract.description,
+    inputSchema: structuredClone(contract.inputSchema),
+    outputSchema: structuredClone(contract.outputSchema),
+    invocation: { protocol: "http-json", method: "POST", path: `/capabilities/${contract.slug}`, mediaType: "application/json" },
+    requiredPermissions: [`urn:junctura:permission:${providerAppId}:${contract.slug}`],
+    sideEffects: structuredClone(contract.sideEffects),
+    timeoutMs: contract.timeoutMs,
+    preconditions: { approval: "none", platform: [...PLATFORM] },
+  };
+}
+
+/**
+ * Validates a JSON value against a contract schema (the Junctura payload profile:
+ * object/array/string/integer/number/boolean/null with bounds). Returns issues;
+ * an empty array means valid.
+ */
+export function validateValue(schema, value, path = "") {
+  const issues = [];
+  const fail = message => issues.push({ path: path || "/", message });
+  switch (schema.type) {
+    case "object":
+      if (value === null || typeof value !== "object" || Array.isArray(value)) { fail("expected object"); break; }
+      for (const key of Object.keys(value)) if (!Object.hasOwn(schema.properties, key)) issues.push({ path: `${path}/${key}`, message: "unknown property" });
+      for (const key of schema.required) if (!Object.hasOwn(value, key)) issues.push({ path: `${path}/${key}`, message: "required" });
+      for (const [key, child] of Object.entries(schema.properties)) if (Object.hasOwn(value, key)) issues.push(...validateValue(child, value[key], `${path}/${key}`));
+      break;
+    case "array":
+      if (!Array.isArray(value)) { fail("expected array"); break; }
+      if (value.length > schema.maxItems || value.length < (schema.minItems ?? 0)) fail(`expected ${schema.minItems ?? 0}-${schema.maxItems} items`);
+      value.forEach((item, index) => issues.push(...validateValue(schema.items, item, `${path}/${index}`)));
+      break;
+    case "string": {
+      if (typeof value !== "string") { fail("expected string"); break; }
+      const length = [...value].length;
+      if (length > schema.maxLength || length < (schema.minLength ?? 0)) fail(`expected length ${schema.minLength ?? 0}-${schema.maxLength}`);
+      break;
+    }
+    case "integer":
+    case "number":
+      if (typeof value !== "number" || !Number.isFinite(value) || (schema.type === "integer" && !Number.isSafeInteger(value))) { fail(`expected ${schema.type}`); break; }
+      if (value < schema.minimum || value > schema.maximum) fail(`expected ${schema.minimum}-${schema.maximum}`);
+      break;
+    case "boolean":
+      if (typeof value !== "boolean") fail("expected boolean");
+      break;
+    case "null":
+      if (value !== null) fail("expected null");
+      break;
+    default:
+      fail(`unsupported schema type ${schema.type}`);
+  }
+  return issues;
+}
+
+/**
+ * Provider-side policy check on the redeemed invocation context: every health
+ * capability concerns one person, is called for a declared purpose, and accepts
+ * emergency (break-glass) calls only when the contract allows them.
+ */
+export function checkContext(slugOrContract, context) {
+  const contract = typeof slugOrContract === "string" ? getContract(slugOrContract) : slugOrContract;
+  if (!context || typeof context.dataSubject !== "string" || !context.dataSubject) return { allowed: false, reason: "data_subject_required" };
+  if (!contract.purposes.includes(context.purpose)) return { allowed: false, reason: "purpose_not_allowed" };
+  if (context.emergency === true && !contract.emergencyAccess) return { allowed: false, reason: "emergency_not_allowed" };
+  return { allowed: true };
+}
+
+export const isSlug = value => typeof value === "string" && SLUG.test(value);

package/package.json

@@ -1,6 +1,15 @@
 {
   "name": "@junctura/health-contracts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Shared capability contracts of Junctura Health: schemas, manifests and purpose rules for connected-care applications on Junctura DX-OS.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "homepage": "https://junctura.studio",
+  "repository": { "type": "git", "url": "git+https://github.com/vku2-open-source-2026/junctura-health.git", "directory": "contracts" },
+  "bugs": { "url": "https://github.com/vku2-open-source-2026/junctura-health/issues" },
+  "engines": { "node": ">=24 <25" },
+  "exports": { ".": { "types": "./index.d.ts", "import": "./index.mjs" } },
+  "types": "./index.d.ts",
+  "files": ["index.mjs", "index.d.ts", "capabilities/", "examples/", "README.md", "LICENSE", "NOTICE"],
+  "sideEffects": false
+}