---
name: matrix_client_init
kind: function
lang: go
domain: infra
version: "0.1.0"
purity: impure
signature: "func MatrixClientInit(cfg MatrixClientInitConfig) (*MatrixClientInitResult, error)"
description: "Construye un *mautrix.Client listo para Sync a partir de un access_token ya obtenido (OIDC). Valida inputs, crea StoreDir con permisos 0700, descubre DeviceID via /whoami si no se proporciona. No maneja login — eso lo hace mas_oidc_loopback."
tags: [matrix, mautrix, sync, client, store, sqlite, infra, matrix-mas]
params:
  - name: cfg.HomeserverURL
    desc: "URL base del servidor Matrix (Synapse). Debe empezar con https://. Ejemplo: https://matrix-af2f3d.organic-machine.com"
  - name: cfg.UserID
    desc: "MXID del usuario en formato @local:servidor. Ejemplo: @egutierrez:matrix-af2f3d.organic-machine.com"
  - name: cfg.AccessToken
    desc: "Bearer token obtenido del flow OIDC (mas_oidc_loopback). No puede estar vacio."
  - name: cfg.DeviceID
    desc: "Device ID del cliente Matrix. Si vacio, se descubre via GET /whoami sumando ~100ms de latencia. Recomendado guardarlo en keyring tras el primer uso."
  - name: cfg.StoreDir
    desc: "Directorio donde se persiste el estado de sync (next_batch, filter_id). Se crea con permisos 0700. Puede ser relativo (se convierte a absoluto). Ejemplo: /home/lucas/.matrix_client_pc/egutierrez/"
  - name: cfg.EnableCrypto
    desc: "Si true, configura crypto store para E2EE (Olm/Megolm). En v0.1.0 devuelve error — implementacion completa en matrix_crypto_init_go_infra (issue 0150)."
output: "*MatrixClientInitResult con Client (*mautrix.Client listo para Sync), StorePath (ruta absoluta del directorio de estado) y CryptoPath (calculado pero vacio en v0.1.0)."
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports:
  - "maunium.net/go/mautrix"
  - "maunium.net/go/mautrix/id"
tested: true
tests:
  - "HomeserverURL invalido"
  - "UserID format invalido"
  - "DeviceID vacio Whoami exitoso"
  - "Whoami 401 token invalido"
  - "EnableCrypto true devuelve error not implemented"
  - "StoreDir se crea con permisos 0700"
test_file_path: "functions/infra/matrix/matrix_client_init_test.go"
file_path: "functions/infra/matrix/matrix_client_init.go"
---

## Ejemplo

```go
import (
    "fmt"
    infra "fn-registry/functions/infra"
)

cfg := infra.MatrixClientInitConfig{
    HomeserverURL: "https://matrix-af2f3d.organic-machine.com",
    UserID:        "@egutierrez:matrix-af2f3d.organic-machine.com",
    AccessToken:   "mxat_xyz...",  // de mas_oidc_loopback_go_infra
    DeviceID:      "",             // se descubre via whoami
    StoreDir:      "/home/lucas/.matrix_client_pc/egutierrez/",
    EnableCrypto:  false,          // v0.1.0
}
res, err := infra.MatrixClientInit(cfg)
if err != nil {
    panic(err)
}
// res.Client listo para res.Client.Sync()
fmt.Println("DeviceID:", res.Client.DeviceID)
fmt.Println("StorePath:", res.StorePath)
```

## Cuando usarla

Llamar UNA vez por sesion, justo tras obtener el access_token via OIDC flow (`mas_oidc_loopback_go_infra`). El `*mautrix.Client` resultante se pasa al loop de Sync, al sender de mensajes y al handler de eventos. No volver a llamarla mientras el token siga valido.

## Gotchas

- **DeviceID vacio dispara GET /whoami**: suma ~100ms de latencia al arranque. Si guardas el DeviceID en keyring tras el primer uso (recomendado), pasalo directamente para evitarlo.
- **StoreDir permisos 0700**: la funcion los aplica en Linux/macOS. En Windows el `MkdirAll` no soporta permisos Unix — usar una ubicacion bajo `os.UserConfigDir()` que ya esta protegida por el SO.
- **mautrix-go v0.28+ cambio de tipos**: `id.UserID` y `id.DeviceID` ya no son alias de `string`. Importar `maunium.net/go/mautrix/id` para conversiones explicitas.
- **EnableCrypto=true devuelve error en v0.1.0**: la inicializacion correcta de Olm/Megolm con cross-signing requiere configurar `crypto.OlmMachine` con su propio SQLite — issue 0150 lo aborda completo. No hacerlo a medias aqui evita estados de crypto corrompidos.
- **M_UNKNOWN_TOKEN en Whoami**: si el AccessToken esta caducado y DeviceID es vacio, el error menciona explicitamente "UNKNOWN_TOKEN". El caller debe refrescar via OIDC (refresh_token de `MasOidcLoopbackResult`).
- **mautrix.NewClient normaliza HomeserverURL**: llama `ParseAndNormalizeBaseURL` internamente. Si la URL tiene trailing slash o path extra, se normaliza. Verificar en `res.Client.HomeserverURL.String()` si hay dudas.

## Notas

- El `*mautrix.Client` usa `NewMemorySyncStore()` por defecto (no persiste next_batch entre reinicios). Para persistencia real del sync state, el caller debe configurar un `SQLiteSyncStore` apuntando a `{StoreDir}/sync.db` — ver documentacion de mautrix-go SQLite stores.
- `CryptoPath` se calcula como `{StoreDir}/crypto.db` pero no se inicializa. Reservado para `matrix_crypto_init_go_infra` (issue 0150).
- La funcion no configura un `Syncer` ni `StateStore` custom — el caller lo hace segun sus necesidades (DefaultSyncer con handlers de eventos para matrix_client_pc).