@xcerebro/shared

Paquete compartido de xCerebro para tipos TypeScript y utilidades relacionadas con análisis EEG y neurotecnología.

🚀 Instalación

npm install @xcerebro/shared

� Importaciones Modulares

Este paquete soporta importaciones modulares para optimizar el bundle y habilitar tree-shaking. Puedes importar solo los tipos que necesites:

Importación Completa (Backward Compatibility)

// Importa todos los tipos de todos los dominios
import {
  EEGBands,
  VisionAnalysisResult,
  GPTAnalysisData,
} from '@xcerebro/shared';

Importaciones Modulares (Recomendado)

🧠 Dominio EEG

// Solo tipos relacionados con EEG y análisis cerebral
import { EEGBands, BrainWave, ZScores } from '@xcerebro/shared/eeg';
import { MappingPhase, EEGPattern } from '@xcerebro/shared/eeg';
import { EEGDeviceInfo, RealTimeData } from '@xcerebro/shared/eeg';

👁️ Dominio Vision

// Solo tipos relacionados con análisis de visión
import {
  VisionAnalysisResult,
  FaceDetectionResult,
} from '@xcerebro/shared/vision';
import { EyeTrackingData, VisionSessionData } from '@xcerebro/shared/vision';

🤖 Dominio Analysis (GPT)

// Solo tipos relacionados con análisis GPT
import { GPTAnalysisData, GPTAnalysisResult } from '@xcerebro/shared/analysis';
import {
  AnalysisRequest,
  QuickAnalysisResult,
} from '@xcerebro/shared/analysis';

🔧 Tipos Comunes

// Tipos compartidos entre dominios
import { ApiResponse, PaginatedResponse } from '@xcerebro/shared/common';
import { DateRange, FileMetadata } from '@xcerebro/shared/common';

📚 Tipos Disponibles por Dominio

🧠 EEG Domain (@xcerebro/shared/eeg)

EEGBands

Estructura base para todas las bandas de frecuencia EEG.

import { EEGBands } from '@xcerebro/shared/eeg';

const eegData: EEGBands = {
  delta: 1500, // 0.5-4 Hz
  theta: 2000, // 4-8 Hz
  lowAlpha: 3000, // 8-10 Hz
  highAlpha: 2500, // 10-12 Hz
  lowBeta: 1800, // 12-16 Hz
  highBeta: 1200, // 16-30 Hz
  lowGamma: 800, // 30-40 Hz
  midGamma: 600, // 40-50 Hz
};

BrainWave

Alias para datos EEG crudos (valores de amplitud en μV).

import { BrainWave } from '@xcerebro/shared/eeg';

const rawData: BrainWave = {
  delta: 15000, // Valores típicos: 1000-50000+ μV
  theta: 20000,
  // ... resto de bandas
};

ZScores

Alias para valores EEG normalizados (desviaciones estándar).

import { ZScores } from '@xcerebro/shared/eeg';

const normalizedData: ZScores = {
  delta: 1.5, // Valores típicos: -3.0 a +3.0
  theta: 2.0,
  // ... resto de bandas
};

EEGDeviceInfo

Información completa del dispositivo EEG conectado.

import { EEGDeviceInfo } from '@xcerebro/shared/eeg';

const device: EEGDeviceInfo = {
  deviceId: 'eeg_001',
  deviceName: 'OpenBCI Cyton',
  model: 'Cyton',
  firmware: '3.1.2',
  serialNumber: '210001234',
  batteryLevel: 85,
  signalQuality: 95,
  electrodeCount: 8,
  samplingRate: 250,
  connectionType: 'bluetooth',
};

RealTimeData

Datos EEG en tiempo real con información de calidad.

import { RealTimeData } from '@xcerebro/shared/eeg';

const liveData: RealTimeData = {
  timestamp: '2024-01-15T10:30:00Z',
  rawValues: {
    /* EEGBands */
  },
  processedValues: {
    /* EEGBands */
  },
  zScores: {
    /* EEGBands */
  },
  quality: 92,
  artifacts: false,
  deviceInfo: device,
};

👁️ Vision Domain (@xcerebro/shared/vision)

VisionAnalysisResult

Resultado básico de análisis de Azure Vision.

import { VisionAnalysisResult } from '@xcerebro/shared/vision';

const visionResult: VisionAnalysisResult = {
  tagName: 'person',
  probability: 0.95,
  details: 'Person detected in central region',
};

FaceDetectionResult

Análisis completo de detección facial con emociones y landmarks.

import { FaceDetectionResult } from '@xcerebro/shared/vision';

const faceData: FaceDetectionResult = {
  faceId: 'face_001',
  confidence: 0.98,
  boundingBox: { x: 100, y: 50, width: 200, height: 250 },
  landmarks: {
    leftEye: { x: 150, y: 120 },
    rightEye: { x: 200, y: 120 },
    nose: { x: 175, y: 150 },
    mouthLeft: { x: 160, y: 200 },
    mouthRight: { x: 190, y: 200 },
  },
  emotions: {
    happiness: 0.85,
    neutral: 0.1,
    anger: 0.05,
    // ... otras emociones
  },
  attributes: {
    age: 28,
    gender: 'male',
    glasses: 'noGlasses',
    smile: 0.8,
  },
};

EyeTrackingData

Datos de seguimiento ocular en tiempo real.

import { EyeTrackingData } from '@xcerebro/shared/vision';

const eyeData: EyeTrackingData = {
  timestamp: '2024-01-15T10:30:00.500Z',
  leftEye: {
    x: 150,
    y: 120,
    pupilDiameter: 4.2,
    blinkState: 'open',
  },
  rightEye: {
    x: 200,
    y: 120,
    pupilDiameter: 4.1,
    blinkState: 'open',
  },
  gazePoint: { x: 400, y: 300, confidence: 0.95 },
  fixationDuration: 250,
};

🤖 Analysis Domain (@xcerebro/shared/analysis)

GPTAnalysisData

Datos de entrada para análisis GPT.

import { GPTAnalysisData } from '@xcerebro/shared/analysis';

const analysisInput: GPTAnalysisData = {
  averageDataByPhase: {
    rest: { delta: 1500, theta: 2000 /* ... */ },
    focus: { delta: 1200, theta: 1800 /* ... */ },
  },
  visionResults: {
    phase1: [
      { timestamp: '2024-01-15T10:30:00Z', tag: 'focus', probability: 0.8 },
    ],
  },
  timestamp: '2024-01-15T10:30:00Z',
  totalDuration: 300,
};

GPTAnalysisResult

Resultado completo del análisis GPT.

import { GPTAnalysisResult } from '@xcerebro/shared/analysis';

const analysisResult: GPTAnalysisResult = {
  speechText: 'El usuario muestra patrones de alta concentración...',
  technicalReport: 'Análisis técnico detallado...',
  tags: {
    global: ['concentrado', 'productivo'],
    restPhase: ['relajado', 'baseline'],
    readingPhase: ['atento', 'comprensivo'],
    listeningPhase: ['receptivo', 'alerta'],
    imaginationPhase: ['creativo', 'divergente'],
  },
  date: '2024-01-15',
};

🔧 Common Domain (@xcerebro/shared/common)

ApiResponse<T>

Respuesta estándar de API con datos tipados.

import { ApiResponse, BaseApiData } from '@xcerebro/shared/common';

// Respuesta exitosa
const success: ApiResponse<{ sessionId: string }> = {
  success: true,
  data: { sessionId: 'session_123' },
  message: 'Sesión iniciada correctamente',
  timestamp: '2024-01-15T10:30:00Z',
};

// Respuesta de error
const error: ApiResponse = {
  success: false,
  error: 'INVALID_CREDENTIALS',
  message: 'Credenciales inválidas',
  timestamp: '2024-01-15T10:30:00Z',
};

PaginatedResponse<T>

Respuesta paginada para listas.

import { PaginatedResponse } from '@xcerebro/shared/common';

const sessionList: PaginatedResponse<{ id: string; name: string }> = {
  items: [
    { id: '1', name: 'Sesión 1' },
    { id: '2', name: 'Sesión 2' },
  ],
  total: 25,
  page: 1,
  pageSize: 10,
  totalPages: 3,
};

// ... resto de bandas };

### Sistema y Estados

## 💡 Ejemplos de Uso Avanzado

### Ejemplo: Aplicación de Análisis EEG

```typescript
// app.ts
import { EEGBands, RealTimeData, EEGDeviceInfo } from '@xcerebro/shared/eeg';
import { ApiResponse } from '@xcerebro/shared/common';

class EEGAnalyzer {
  private device: EEGDeviceInfo;

  constructor(device: EEGDeviceInfo) {
    this.device = device;
  }

  processRealTimeData(data: RealTimeData): ApiResponse<{ analysis: string }> {
    // Procesar datos EEG en tiempo real
    const analysis = this.analyzePatterns(data.processedValues);

    return {
      success: true,
      data: { analysis },
      message: "Análisis completado",
      timestamp: new Date().toISOString()
    };
  }

  private analyzePatterns(bands: EEGBands): string {
    // Lógica de análisis...
    return "Patrón de concentración detectado";
  }
}

Ejemplo: Integración de Vision y EEG

// multimodal.ts
import { FaceDetectionResult, EyeTrackingData } from '@xcerebro/shared/vision';
import { BrainWave, ZScores } from '@xcerebro/shared/eeg';
import { GPTAnalysisData } from '@xcerebro/shared/analysis';

class MultimodalAnalyzer {
  combineData(
    eegData: BrainWave[],
    faceData: FaceDetectionResult[],
    eyeData: EyeTrackingData[]
  ): GPTAnalysisData {
    return {
      averageDataByPhase: this.processEEGPhases(eegData),
      visionResults: {
        session: faceData.map((face) => ({
          timestamp: new Date().toISOString(),
          tag: face.emotions.happiness > 0.5 ? 'happy' : 'neutral',
          probability: face.confidence,
          details: `Age: ${face.attributes.age}, Gender: ${face.attributes.gender}`,
        })),
      },
      timestamp: new Date().toISOString(),
      totalDuration: 300,
    };
  }

  private processEEGPhases(
    data: BrainWave[]
  ): Record<string, Record<string, number>> {
    // Procesar fases EEG...
    return {
      baseline: { delta: 1500, theta: 2000 },
      task: { delta: 1200, theta: 1800 },
    };
  }
}

🎯 Ventajas de las Importaciones Modulares

✅ Tree Shaking

Solo el código que importes será incluido en tu bundle final:

// ❌ Importa TODO el paquete (grande)
import { EEGBands } from '@xcerebro/shared';

// ✅ Solo importa el dominio EEG (optimizado)
import { EEGBands } from '@xcerebro/shared/eeg';

✅ Mejor Organización

// Separación clara por funcionalidad
import /* tipos EEG */ '@xcerebro/shared/eeg';
import /* tipos Vision */ '@xcerebro/shared/vision';
import /* tipos Analysis */ '@xcerebro/shared/analysis';

✅ Compatibilidad

// Backward compatibility: sigue funcionando
import { EEGBands, VisionAnalysisResult } from '@xcerebro/shared';

// Nueva forma modular: más eficiente
import { EEGBands } from '@xcerebro/shared/eeg';
import { VisionAnalysisResult } from '@xcerebro/shared/vision';

🏗️ Estructura del Proyecto

src/
├── index.ts           # Re-exports para backward compatibility
├── common/           # Tipos compartidos (ApiResponse, etc.)
│   └── index.ts
├── eeg/              # Tipos EEG y análisis cerebral
│   └── index.ts
├── vision/           # Tipos de análisis visual
│   └── index.ts
└── analysis/         # Tipos de análisis GPT
    └── index.ts

🚀 Desarrollo

# Clonar el repositorio
git clone https://github.com/Martin-Alba/shared.git

# Instalar dependencias
npm install

# Compilar TypeScript
npm run build

# Publicar (automático con semantic-release)
git commit -m "feat: nueva funcionalidad"
git push origin main

📦 Versionado

Este paquete usa semantic-release para versionado automático basado en commits convencionales:

• feat: → versión minor (1.1.0 → 1.2.0)
• fix: → versión patch (1.1.0 → 1.1.1)
• BREAKING CHANGE: → versión major (1.1.0 → 2.0.0)

🔗 Enlaces

• Semantic Release
• Repository
• Issues
• Pull Requests
• xCerebro

xCerebro Team - Neurotecnología avanzada para el futuro.