---
name: add_contact_dav
kind: pipeline
lang: py
domain: pipelines
version: "1.0.0"
purity: impure
signature: "def add_contact_dav(name: str, *, tels=None, emails=None, adrs=None, org='', note='', uid='', base_url=DEFAULT_BASE_URL, username=DEFAULT_USERNAME, collection_path=DEFAULT_COLLECTION, secret_path='dav/xandikos-enmanuel', timeout_s=20.0, verify_tls=True) -> dict"
description: "One-shot que anade UN contacto a la libreta CardDAV de Enmanuel (Xandikos) en una sola llamada. Compone build_vcard + contact_import_key + pass_get_secret + carddav_put_vcard. Idempotente por uid: re-anadir el mismo contacto sobrescribe, no duplica. La contrasena se resuelve desde pass y nunca se logea."
tags: [dav, carddav, vcard, contact, contacts, pipelines]
params:
  - name: name
    desc: "Nombre completo del contacto (FN del vCard). Obligatorio."
  - name: tels
    desc: "Telefono(s). Acepta lista, string suelto o None."
  - name: emails
    desc: "Email(s). Acepta lista, string suelto o None."
  - name: adrs
    desc: "Direccion(es). Acepta lista, string suelto o None."
  - name: org
    desc: "Organizacion (ORG). Vacio = se omite."
  - name: note
    desc: "Nota libre (NOTE). Vacio = se omite."
  - name: uid
    desc: "UID explicito del vCard. Vacio => se calcula con contact_import_key (telefono > email > nombre) para idempotencia."
  - name: base_url
    desc: "URL base del servidor DAV. Default = libreta CardDAV de Enmanuel."
  - name: username
    desc: "Usuario HTTP Basic. Default = enmanuel."
  - name: collection_path
    desc: "Ruta de la coleccion CardDAV destino."
  - name: secret_path
    desc: "Ruta del secreto en pass cuya primera linea es la contrasena CardDAV."
  - name: timeout_s
    desc: "Timeout del PUT en segundos. Default 20.0."
  - name: verify_tls
    desc: "Si True (default) verifica el certificado TLS. No desactivar fuera de pruebas."
output: "dict. Exito: {status:'ok', http_status:int, url:str, uid:str}. Error (sin lanzar): {status:'error', error:str, uid:str, http_status:int|None}. Si la pass no se encuentra, devuelve error sin tocar la red."
uses_functions: [build_vcard_py_core, contact_import_key_py_core, carddav_put_vcard_py_infra, pass_get_secret_py_infra]
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: []
tested: false
tests: []
test_file_path: ""
file_path: "python/functions/pipelines/add_contact_dav.py"
---

## Ejemplo

```bash
# Anadir un contacto en una sola llamada (uid determinista por telefono):
./fn run add_contact_dav --name "Juan Perez" --tel +34600111222 --email juan@example.com --org "ACME"

# Multi-valor: --tel y --email son repetibles -> se serializan como listas.
./fn run add_contact_dav --name "Maria Lopez" \
  --tel +34611000111 --tel +34922000222 \
  --email maria@example.com --email m.lopez@work.com \
  --note "Conocida del evento OSINT"
```

Salida (JSON): `{"status": "ok", "http_status": 201, "url": "https://dav-.../enmanuel/contacts/addressbook/v1-<hash>.vcf", "uid": "v1-<hash>"}`.

## Cuando usarla

Usala cuando quieras dar de alta o actualizar UN contacto en la libreta CardDAV
de Enmanuel sin montar el flujo a mano (serializar vCard, sacar la pass, PUT).
Si re-ejecutas con el mismo telefono/email (o el mismo `--uid`), el contacto se
sobrescribe en vez de duplicarse. Para importar muchos contactos de golpe, este
pipeline no es lo idoneo: llamalo en bucle o construye un pipeline batch.

## Gotchas

- **Escritura remota real**: hace un HTTP PUT contra el servidor DAV. No es un
  dry-run. Cada llamada con `status:'ok'` ha creado/actualizado un recurso real.
- **Idempotencia por uid**: si no pasas `--uid`, el UID se deriva de forma
  determinista (telefono > email > nombre). Mismo telefono/email = mismo recurso
  = sobrescritura. Distinto telefono pero mismo nombre = recurso distinto.
- **Secreto desde pass, nunca hardcode**: la contrasena se lee de
  `pass show dav/xandikos-enmanuel` (configurable con `secret_path`). Nunca se
  logea ni aparece en el dict de retorno. Si `pass` falla o la entry no existe,
  devuelve `{status:'error'}` sin tocar la red.
- **verify_tls**: por defecto verifica el certificado TLS. `--no-verify-tls`
  solo para pruebas controladas; nunca contra el servidor real de produccion.