@centricare/contracts

@centricare/contracts adalah shared package yang memuat definisi OpenAPI 3.0 schemas, TypeScript types, dan Zod validation schemas untuk ekosistem CentriCare.

Package ini menggunakan Kubb untuk meng-generate TypeScript definitions dan Zod schemas secara otomatis dari spesifikasi OpenAPI.

[!IMPORTANT] Persyaratan Dependency: Untuk menggunakan package @centricare/contracts, pastikan Anda juga meng-install zod di aplikasi konsumen (peer dependency):

npm install zod

📦 Import & Penggunaan

Package ini menyediakan dua entry point utama:

1. TypeScript Types (Default Export)

Gunakan untuk type checking dan antarmuka data pada aplikasi TypeScript:

import type {
  Patient,
  Address,
  Contact,
  Identifier,
} from "@centricare/contracts";

const patientData: Patient = {
  id: "pat_123",
  organization_id: "org_456",
  registering_facility_id: "fac_789",
  name: {
    first: "John",
    last: "Doe",
    salutation: "Mr.",
  },
  // ...
};

2. Zod Schemas (/zod)

Gunakan untuk validasi runtime (misalnya validasi form, payload API, atau parsing data):

import { patientSchema, addressSchema } from "@centricare/contracts/zod";

// Validasi data runtime
const result = patientSchema.safeParse(incomingData);

if (!result.success) {
  console.error("Validation errors:", result.error.format());
} else {
  console.log("Valid patient data:", result.data);
}

📁 Struktur Direktori

contracts/
├── schemas/                # Definisi OpenAPI 3.0 (YAML)
│   ├── index.yaml          # Entrypoint utama OpenAPI spec
│   ├── primitives/         # Tipe dasar (email, phone, datetime, timestamp, urn)
│   ├── blocks/             # Blok komponen reusable (address, contact, identifier, time-log)
│   └── entities/           # Spesifikasi entitas utama (patient, patient-additional)
├── dist/                   # Hasil auto-generate dari Kubb (Jangan di-edit manual)
│   ├── types.ts            # Generated TypeScript interfaces & types
│   └── zod.ts              # Generated Zod validation schemas
├── kubb.config.ts          # Konfigurasi Kubb code generator
└── package.json

🛠️ Development & Build

Requirements

• Node.js (v18+)
• npm

1. Install Dependencies

npm install

2. Generate Types & Zod Schemas

Untuk mengompilasi skema OpenAPI di folder schemas/ menjadi file TypeScript & Zod di folder dist/:

npm run build

🔄 Alur Kerja Mengubah Schema

1. Edit atau tambahkan file definisi YAML baru di folder schemas/ (primitives/, blocks/, atau entities/).
2. Pastikan file baru direferensikan dalam schemas/index.yaml jika berupa entitas atau komponen utama.
3. Jalankan command build:

   npm run build

4. Periksa file yang ter-generate di dist/types.ts dan dist/zod.ts.
5. Commit skema YAML dan file dist/ ter-generate.

📄 Lisensi

ISC