@phenyxhealth/sdk 1.0.15 → 1.1.0

package/.claude/phenyx-sdk.md

@@ -0,0 +1,481 @@
+# PhenyxHealth SDK - Asistente de desarrollo
+
+Estoy trabajando en un proyecto JavaScript/TypeScript que usa `@phenyxhealth/sdk`, el SDK oficial de PhenyxHealth para gestionar sistemas de radioterapia.
+
+Usa la siguiente referencia completa de la API para ayudarme a escribir codigo correcto, eficiente y siguiendo los patrones del SDK.
+
+---
+
+## Instalacion
+
+```bash
+npm install @phenyxhealth/sdk
+```
+
+## Imports disponibles
+
+```javascript
+import {
+  PhenyxSDK,            // Clase principal
+  checkGlobals,         // Validar configuracion global
+  beSureGlobalExists,   // Asegurar elementos globales
+  beSureDoctorExists,   // Validar/crear doctores
+  beSureLinacsExists,   // Validar/crear LINACs
+  today,                // Fecha actual YYYY-MM-DD
+  formatDate,           // Date -> YYYY-MM-DD
+  formatDateString,     // DD/MM/YYYY -> YYYY-MM-DD
+} from '@phenyxhealth/sdk';
+```
+
+---
+
+## PhenyxSDK - Clase principal
+
+### Propiedades de instancia
+
+| Propiedad | Tipo | Descripcion |
+|-----------|------|-------------|
+| `apiToken` | `string \| null` | Token JWT de autenticacion |
+| `apiHost` | `string \| null` | URL base de la API |
+| `user` | `UserInfo \| null` | Info del usuario autenticado |
+| `config` | `Record<string, any>` | Configuracion del cliente |
+| `globalInfo` | `GlobalInfo[] \| null` | Info global del sistema |
+| `activeTables` | `any[] \| null` | Tablas activas |
+| `doctors` | `HumanResourceData[]` | Lista de doctores/fisicos medicos |
+| `defaultDuration` | `Record<string, string>` | Duraciones por defecto de sesiones |
+| `defaultCompatibleLinacs` | `Array<{id, name}>` | LINACs compatibles por defecto |
+| `oars` | `any[]` | Lista de Organs At Risk |
+
+### Metodos estaticos
+
+```typescript
+// Generar UUID v4
+PhenyxSDK.newId(): string
+
+// Generar color RGB contrastante aleatorio ("R, G, B")
+PhenyxSDK.getContrastingColor(): string
+```
+
+### Autenticacion
+
+```typescript
+// Login - inicializa la instancia con token, globalInfo, doctors, etc.
+await api.login({ apiHost: string, user: string, password: string }): Promise<void>
+
+// Obtener token JWT actual
+api.getToken(): string | null
+
+// Habilitar/deshabilitar logs HTTP
+api.showLogs(showLogs: boolean): void
+```
+
+### Informacion global
+
+```typescript
+// Recuperar info global del servidor
+await api.retrieveGlobalInfo(): Promise<GlobalInfo[]>
+
+// Recuperar tablas activas
+await api.retrieveActiveTables(): Promise<any[]>
+
+// Recuperar configuracion por defecto
+await api.retrieveDefaults(): Promise<Object>
+
+// Recuperar lista de OARs
+await api.retrieveOars(): Promise<any[]>
+
+// Obtener info global por tipo
+api.getGlobalInfo(globalType: GlobalType): GlobalInfo | undefined
+
+// Obtener elemento especifico de info global
+api.getGlobalInfoElement(globalType: GlobalType, elementName: string): GlobalInfoElement | undefined
+
+// Obtener ID de elemento global por nombre
+api.getGlobalInfoElementId(globalType: GlobalType, elementName: string): string | null
+
+// Actualizar info global
+// IMPORTANTE: El servidor reasigna los IDs de los elementos nuevos al guardar.
+// Despues de llamar a updateGlobalInfo, debes volver a llamar a getGlobalInfo()
+// para obtener los IDs reales asignados por el servidor.
+await api.updateGlobalInfo(globalTypeId: string, data: any): Promise<void>
+```
+
+### Pacientes
+
+```typescript
+// Obtener todos los pacientes
+await api.getPatients(): Promise<PatientData[]>
+
+// Obtener datos clinicos de un paciente
+await api.getPatient(id: string): Promise<PatientData>
+
+// Crear paciente - retorna el ID del paciente creado
+await api.createPatient(data: CreatePatientData): Promise<string>
+
+// Eliminar paciente
+await api.deletePatient(id: string): Promise<void>
+
+// Crear cambio de estado
+await api.createPatientStateChanges({
+  formDataId: string,       // ID del caso
+  date?: string,            // Fecha YYYY-MM-DD
+  humanResourceId?: string, // ID del doctor responsable
+  nextStateCode: string     // Codigo del siguiente estado
+}): Promise<void>
+```
+
+### Recursos humanos
+
+```typescript
+// Obtener todos los recursos humanos
+await api.getHumanResources(): Promise<HumanResourceData[]>
+
+// Crear recurso humano
+await api.createHumanResource({ name, typeId, agenda }): Promise<void>
+
+// Buscar doctor por nombre
+api.getDoctorIdByName(name: string): string | null
+api.getDoctorTypeIdByName(name: string): string | null
+api.getDoctorTypeNameByName(name: string): string | null
+```
+
+### Equipos/Recursos
+
+```typescript
+// Obtener tipos de recursos
+await api.getResourcesTypes(): Promise<any[]>
+
+// Obtener todos los recursos (LINACs, etc)
+await api.getResources(): Promise<ResourceData[]>
+
+// Crear recurso
+await api.createResource({ name, author?, typeId, agenda }): Promise<void>
+```
+
+### Lookups de elementos
+
+```typescript
+api.getSendingDepartmentIdByName(name: string): string  // throws si no existe
+api.getCei9IdByName(name: string): string                // throws si no existe
+api.getCie10IdByName(name: string): string               // throws si no existe
+api.getCie10CodeExists(name: string): boolean
+api.getElementIdByName(type: string, name: string): string | null
+```
+
+### QA y estados
+
+```typescript
+api.getQaStatus(section: any): string | null
+api.getRewiewedStatus(status: string): any[]
+api.getSortedQa(qa: any): any[]
+await api.updateSectionQaStatus(qa: any, formDataId: string): Promise<void>
+```
+
+---
+
+## Constantes del SDK
+
+### `api.globalTypes` - 20 tipos de configuracion global
+
+```javascript
+api.globalTypes.humanResources
+api.globalTypes.sendingDepartment
+api.globalTypes.cei9               // Codigos CEI-9
+api.globalTypes.cie10              // Codigos CIE-10
+api.globalTypes.treatmentClass
+api.globalTypes.treatmentSubClass
+api.globalTypes.treatmentTechnique
+api.globalTypes.treatmentType
+api.globalTypes.treatmentGoal
+api.globalTypes.treatmentParticles
+api.globalTypes.noTreatmentReasons
+api.globalTypes.ctSimProtocols
+api.globalTypes.linacsAllocationCriteria
+api.globalTypes.sessionDurationCriteria
+api.globalTypes.contouringTools
+api.globalTypes.fractionationTypes
+api.globalTypes.dosimetryCalculationMethods
+api.globalTypes.dosimetrySecondaryCalculationMethods
+api.globalTypes.tps
+api.globalTypes.treatmentVerificationProtocols
+```
+
+### `api.allStatus` - 16 estados de workflow
+
+```javascript
+api.allStatus.NOTSTARTED
+api.allStatus.COMPLETED
+api.allStatus.INPROGRESS
+api.allStatus.ONREQUEST
+api.allStatus.READYTOSTART
+api.allStatus.DONE
+api.allStatus.REVIEWED
+api.allStatus.VALIDATED
+api.allStatus.PEERREVIEWING
+api.allStatus.PEERREVIEWED
+api.allStatus.DONEMAIN
+api.allStatus.DONESECONDCALCULATION
+api.allStatus.STARTPROPOSED
+api.allStatus.STARTCONFIRMED
+api.allStatus.CANCELED
+api.allStatus.CANCELLED
+```
+
+---
+
+## Funciones de validacion (standalone)
+
+### `beSureDoctorExists(api, doctors)`
+Valida que los doctores existan en el sistema. Si no existen, los crea automaticamente.
+
+```javascript
+const doctors = await beSureDoctorExists(api, [
+  { name: 'Dr. Garcia', hrGroup: 'RadOnc' },    // Radiation Oncologist
+  { name: 'Dr. Lopez', hrGroup: 'MedPhys' },     // Medical Physicist
+]);
+// Retorna: HumanResourceData[]
+```
+
+### `beSureLinacsExists(api, linacs)`
+Valida que los LINACs existan. Si no, los crea.
+
+```javascript
+const linacs = await beSureLinacsExists(api, ['LINAC-01', 'LINAC-02']);
+// Retorna: ResourceData[]
+```
+
+### `checkGlobals(api, globalType, extraValues?)`
+Valida que los valores globales existan. Si no, los crea.
+
+```javascript
+await checkGlobals(api, api.globalTypes.treatmentType, ['IMRT', 'VMAT', 'SRS']);
+```
+
+### `beSureGlobalExists(api, currentList, toBeList)`
+Nivel mas bajo: asegura que elementos especificos existan en una lista global.
+
+```javascript
+const treatmentTypes = api.getGlobalInfo(api.globalTypes.treatmentType);
+await beSureGlobalExists(api, treatmentTypes, ['IMRT', 'VMAT']);
+```
+
+---
+
+## Utilidades de fecha
+
+```javascript
+today()                          // "2026-02-16" (fecha actual)
+formatDate(new Date())           // "2026-02-16" (Date -> string)
+formatDateString('16/02/2026')   // "2026-02-16" (DD/MM/YYYY -> YYYY-MM-DD)
+```
+
+---
+
+## Interfaces TypeScript principales
+
+```typescript
+interface LoginCredentials {
+  apiHost: string;
+  user: string;
+  password: string;
+}
+
+interface PatientData {
+  id: string;
+  name: string;
+  birthDate: string;
+  sendingDepartmentId?: string;
+  cei9Id?: string;
+  cie10Id?: string;
+  [key: string]: any;
+}
+
+interface CreatePatientData {
+  name: string;
+  birthDate: string;
+  sendingDepartmentId?: string;
+  cei9Id?: string;
+  cie10Id?: string;
+  [key: string]: any;
+}
+
+interface HumanResourceData {
+  id: string;
+  name: string;
+  typeId: string;
+  typeName: string;
+  agenda: AgendaItem[];
+}
+
+interface DoctorValidation {
+  name: string;
+  hrGroup: 'RadOnc' | 'MedPhys';
+}
+
+interface ResourceData {
+  id: string;
+  name: string;
+  typeId: string;
+  author: string;
+  agenda: AgendaItem[];
+}
+
+interface GlobalInfo {
+  id: string;
+  name: string;
+  typeName: string;
+  elements: GlobalInfoElement[];
+}
+
+interface GlobalInfoElement {
+  id: string;
+  name: string;
+  color: string;
+  createdAt: string;
+  updatedAt: string;
+  isDeleted: boolean;
+  modality: string;
+}
+
+interface GlobalType {
+  type: string;
+  name: string;
+  values?: Record<string, string>;
+}
+
+interface StateChangeParams {
+  formDataId: string;
+  date?: string;
+  humanResourceId?: string | null;
+  nextStateCode: string;
+}
+
+interface AgendaItem {
+  id: string;
+  date: string;
+  startTime: string;
+  endTime: string;
+  description?: string;
+}
+```
+
+---
+
+## Patrones comunes
+
+### Setup basico
+
+```javascript
+const api = new PhenyxSDK();
+await api.login({ apiHost: HOST, user: USER, password: PASS });
+```
+
+### Crear paciente completo
+
+```javascript
+const patientId = await api.createPatient({
+  name: 'Juan Perez',
+  birthDate: '1975-03-15',
+  sendingDepartmentId: api.getSendingDepartmentIdByName('Oncologia'),
+  cei9Id: api.getCei9IdByName('C78.9'),
+  cie10Id: api.getCie10IdByName('C78.9'),
+});
+
+await api.createPatientStateChanges({
+  formDataId: patientId,
+  date: today(),
+  humanResourceId: api.getDoctorIdByName('Dr. Garcia'),
+  nextStateCode: api.allStatus.INPROGRESS,
+});
+```
+
+### Configurar clinica
+
+```javascript
+await beSureDoctorExists(api, [
+  { name: 'Dr. Garcia', hrGroup: 'RadOnc' },
+  { name: 'Dr. Lopez', hrGroup: 'MedPhys' },
+]);
+
+await beSureLinacsExists(api, ['LINAC-01', 'LINAC-02']);
+
+await checkGlobals(api, api.globalTypes.treatmentType, ['IMRT', 'VMAT', 'SRS']);
+await checkGlobals(api, api.globalTypes.treatmentGoal, ['Curative', 'Palliative']);
+```
+
+### Crear elementos globales con dependencias entre si
+
+Cuando creas elementos en un globalInfo, debes enviar un `id` (con `PhenyxSDK.newId()`), pero el servidor **ignora ese id y asigna uno nuevo**. Por lo tanto, despues de `updateGlobalInfo()` debes volver a obtener los datos con `getGlobalInfo()` para tener los IDs reales. Esto es critico cuando necesitas referenciar los elementos recien creados (ej: crear subclases que apuntan a clases).
+
+```javascript
+// 1) Obtener el global y añadir elementos
+const treatmentClass = api.getGlobalInfo(api.globalTypes.treatmentClass);
+
+treatmentClass.elements.push({
+  id: PhenyxSDK.newId(),  // obligatorio enviarlo, pero el servidor lo va a reemplazar
+  name: 'Radioterapia Externa',
+  color: PhenyxSDK.getContrastingColor(),
+  createdAt: new Date().toISOString(),
+  updatedAt: new Date().toISOString(),
+  isDeleted: false,
+  modality: '',
+});
+
+// 2) Guardar
+await api.updateGlobalInfo(treatmentClass.id, treatmentClass);
+
+// 3) OBLIGATORIO: Recargar para obtener los IDs reales del servidor
+const createdClasses = api.getGlobalInfo(api.globalTypes.treatmentClass);
+
+// 4) Ahora si puedes usar los IDs reales para crear elementos que los referencian
+const parentClass = createdClasses.elements.find(e => e.name === 'Radioterapia Externa');
+const treatmentSubClass = api.getGlobalInfo(api.globalTypes.treatmentSubClass);
+
+treatmentSubClass.elements.push({
+  id: PhenyxSDK.newId(),
+  name: 'IMRT',
+  treatmentClass: parentClass.id,  // ID real del servidor
+  color: PhenyxSDK.getContrastingColor(),
+  createdAt: new Date().toISOString(),
+  updatedAt: new Date().toISOString(),
+  isDeleted: false,
+  modality: '',
+});
+
+await api.updateGlobalInfo(treatmentSubClass.id, treatmentSubClass);
+```
+
+### Flujo QA
+
+```javascript
+const doctorId = api.getDoctorIdByName('Dr. Lopez');
+
+// Listo para QA -> Peer reviewing -> Peer reviewed -> Validado
+for (const status of [
+  api.allStatus.READYTOSTART,
+  api.allStatus.PEERREVIEWING,
+  api.allStatus.PEERREVIEWED,
+  api.allStatus.VALIDATED,
+]) {
+  await api.createPatientStateChanges({
+    formDataId: patientId,
+    date: today(),
+    humanResourceId: doctorId,
+    nextStateCode: status,
+  });
+}
+```
+
+---
+
+## Notas importantes
+
+- `PhenyxSDK` es un alias de `PhenyxApi` (se exporta como default y como named export `PhenyxSDK`)
+- `login()` inicializa automaticamente: `globalInfo`, `activeTables`, `doctors`, `defaultDuration`, `defaultCompatibleLinacs`, y `oars`
+- Los metodos `get*ByName` buscan en los datos ya cargados en memoria (no hacen llamadas HTTP)
+- Los metodos `getSendingDepartmentIdByName`, `getCei9IdByName`, `getCie10IdByName` lanzan Error si no encuentran el elemento
+- `getContrastingColor()` y `newId()` son metodos estaticos - se usan sin instancia: `PhenyxSDK.newId()`
+- **IDs en GlobalInfo**: Al hacer `push` de un elemento nuevo a `globalInfo.elements`, debes enviar un `id` (el servidor da error si no lo envias), pero el servidor lo ignora y asigna su propio ID. Siempre haz `getGlobalInfo()` despues de `updateGlobalInfo()` si necesitas referenciar los elementos creados
+- Las funciones de validacion (`beSureDoctorExists`, `beSureLinacsExists`, `checkGlobals`) crean automaticamente los recursos que no existan
+- El SDK usa ESM (`"type": "module"` en package.json)
+- Compatible con Node.js >= 16

package/README.md

@@ -408,6 +408,18 @@ const patient: PatientData = await api.getPatient("id");
 const doctors: HumanResourceData[] = await api.getHumanResources();
 ```
 
+## Uso con Claude Code
+
+Si usas [Claude Code](https://claude.com/claude-code) para desarrollar, este SDK incluye un archivo de referencia completa de la API que puedes cargar automaticamente en tu proyecto.
+
+Agrega la siguiente linea en el `CLAUDE.md` de tu proyecto:
+
+```
+@node_modules/@phenyxhealth/sdk/.claude/phenyx-sdk.md
+```
+
+Esto le dara a Claude Code el contexto completo de la API del SDK: todos los metodos, interfaces TypeScript, constantes, patrones de uso y notas importantes para que te asista correctamente al escribir codigo con `@phenyxhealth/sdk`.
+
 ## Contribución
 
 Las contribuciones son bienvenidas. Please:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phenyxhealth/sdk",
-  "version": "1.0.15",
+  "version": "1.1.0",
   "type": "module",
   "description": "SDK oficial para PhenyxHealth - Sistema integral de gestión de radioterapia. Incluye gestión de pacientes, recursos humanos, equipos médicos y configuración global.",
   "main": "./src/index.js",
@@ -11,6 +11,7 @@
   "files": [
     "src/",
     "types/",
+    ".claude/",
     "README.md"
   ],
   "scripts": {