interface Actor {
  type: 'client' | 'provider' | 'organization' | 'agent';
  id: string;
  on_behalf_of?: {              // cuando alguien actúa por otro
    type: 'client' | 'provider' | 'organization';
    id: string;
  };
}

// scheduling.book()
// Crea una nueva sesión

Request: {
  organization_id: string,
  service_id: string,
  provider_id: string,
  client_id: string,
  starts_at: ISO8601,
  actor: Actor               // quién inicia la reserva
}

Response: {
  session: Session,
  status: 'confirmed' | 'pending_confirmation',
  confirmation_required_from?: Actor  // null si auto-confirm
}

┌──────────────┐       tiene        ┌───────────────┐
│ Organización │───────────────────▶│ Profesionales │
└──────────────┘                    └───────┬───────┘
                                            │ ofrecen
                                            ▼
                                    ┌───────────────┐
                                    │   Servicios   │
                                    └───────┬───────┘
                                            │
┌──────────────┐  participan en     ┌───────▼───────┐   iniciadas por   ┌──────────┐
│   Clientes   │◄──────────────────▶│   Sesiones    │◄─────────────────│  Actores  │
│  (reciben)   │                    └───────┬───────┘  (cualquier tipo) └──────────┘
└──────────────┘                            │ generan
                                            ▼
                                    ┌───────────────┐
                                    │  Movimientos  │
                                    │  financieros  │
                                    └───────┬───────┘
                                            │ se liquidan via
                                            ▼
                                    ┌───────────────┐
                                    │   Acuerdos    │
                                    │  financieros  │
                                    └───────────────┘

interface Organization {
  id: string;
  name: string;
  slug: string;
  timezone: string;
  created_at: string; // ISO 8601
}

interface Professional {
  id: string;
  organization_id: string;
  name: string;
  email: string;
  specialties: string[];
  active: boolean;
}

interface Client {
  id: string;
  organization_id: string;
  name: string;
  email?: string;
  phone?: string;
}

interface Service {
  id: string;
  organization_id: string;
  name: string;
  duration_minutes: number;
  price: number;
  currency: string; // ISO 4217
}

interface Session {
  id: string;
  organization_id: string;
  service_id: string;
  provider_id: string;
  client_id: string;

  // Cuándo y dónde
  starts_at: ISO8601;
  ends_at: ISO8601;
  modality: 'in_person' | 'remote' | 'home_visit';
  location?: string;

  // Quién la creó
  initiated_by: Actor;

  // Estado
  status: 'created' | 'confirmed' | 'reminded' | 'in_progress'
        | 'completed' | 'no_show' | 'cancelled' | 'rescheduled';

  // Trazabilidad
  status_history: Array<{
    from: string;
    to: string;
    changed_by: Actor;
    changed_at: ISO8601;
    reason?: string;
  }>;

  // Referencias
  previous_session_id?: string;  // si fue reagendada
  referral_source?: {            // si viene de derivación
    organization_id: string;
    provider_id?: string;
  };
}

interface FinancialAgreement {
  id: string;
  organization_id: string;
  professional_id: string;
  type: 'fixed' | 'percentage' | 'tiered';
  value: number;
  effective_from: string; // ISO 8601
  effective_until?: string;
}

interface FinancialMovement {
  id: string;
  session_id: string;
  type: 'charge' | 'payment' | 'adjustment';
  amount: number;
  currency: string;
  created_at: string;
}

created ──► confirmed ──► reminded ──► in_progress ──► completed
    │           │             │              │
    │           │             │              └──► no_show
    │           │             │
    └───────────┴─────────────┴──► cancelled
                │
                └──► rescheduled (crea nueva sesión)

{
  "mcpServers": {
    "servicialo": {
      "command": "npx",
      "args": ["-y", "@servicialo/mcp-server"],
      "env": {
        "SERVICIALO_API_KEY": "tu_api_key",
        "SERVICIALO_ORG_ID": "org_01"
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "scheduling.check_availability",
    "arguments": {
      "provider_id": "pro_paula",
      "service_id": "srv_kinesiologia",
      "date_range": {
        "from": "2026-02-14",
        "to": "2026-02-18"
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"available_slots\":[{\"date\":\"2026-02-14\",\"times\":[\"09:00\",\"10:00\",\"14:00\"]},{\"date\":\"2026-02-16\",\"times\":[\"11:00\",\"15:00\"]}]}"
      }
    ]
  }
}

{
  "method": "tools/call",
  "params": {
    "name": "scheduling.book",
    "arguments": {
      "organization_id": "org_mamapro",
      "service_id": "srv_kinesiologia",
      "provider_id": "pro_paula",
      "client_id": "cli_maria",
      "starts_at": "2026-02-14T10:00:00-03:00",
      "actor": {
        "type": "agent",
        "id": "claude_mcp",
        "on_behalf_of": {
          "type": "client",
          "id": "cli_maria"
        }
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"session\":{\"id\":\"ses_01\",\"status\":\"confirmed\",\"starts_at\":\"2026-02-14T10:00:00-03:00\",\"ends_at\":\"2026-02-14T10:45:00-03:00\",\"provider\":\"Paula Méndez\",\"client\":\"María López\",\"service\":\"Sesión de kinesiología\",\"initiated_by\":{\"type\":\"agent\",\"id\":\"claude_mcp\",\"on_behalf_of\":{\"type\":\"client\",\"id\":\"cli_maria\"}}},\"status\":\"confirmed\",\"confirmation_required_from\":null}"
      }
    ]
  }
}