@controldealquiler/sdk 1.2.1 → 1.3.0

package/LICENSE

@@ -6,6 +6,9 @@ Copyright © 2026 Trajano Labs, S.L. (CIF B05655378). Todos los derechos reserva
 incluirlo sin modificar en tus programas y distribuirlo con ellos, solo para conectar esos programas con
 controldealquiler.com. Para usar la API necesitas, además, una API key y aceptar las Condiciones de la API para
 agencias, en controldealquiler.com/condiciones-api.
+También puedes encargar a un tercero que observe, estudie o verifique por ti el funcionamiento del paquete, como
+dice el punto 3, para evaluar tu integración, siempre que se comprometa contigo a guardar confidencialidad, no
+modifique el paquete y solo te comunique a ti lo que obtenga.
 
 **2. Lo que no te permitimos.** No puedes:
 - modificar el paquete, traducirlo ni hacer obras derivadas de él, salvo lo que el punto 3 dice que la ley te permite
@@ -20,9 +23,10 @@ agencias, en controldealquiler.com/condiciones-api.
 **3. Lo que la ley te permite siempre.** Nada de esta licencia limita lo que el artículo 100 del texto refundido de la
 Ley de Propiedad Intelectual permite a quien tiene derecho a usar un programa:
 - hacer la copia de seguridad necesaria para usarlo;
-- observar, estudiar o verificar su funcionamiento mientras lo carga, ejecuta o almacena, para conocer las ideas y
-  principios en que se basa;
-- y lo que permite para conseguir la interoperabilidad de un programa creado de forma independiente.
+- observar, estudiar o verificar su funcionamiento mientras lo carga, visualiza, ejecuta, transmite o almacena, para
+  conocer las ideas y principios en que se basa;
+- y lo que permite para conseguir la interoperabilidad de un programa creado de forma independiente, también por
+  medio de una persona a la que autorices.
 
 **4. Componentes de terceros.** El paquete incluye componentes de terceros. Su lista, con la licencia completa de cada
 uno y, si la traen, sus avisos (NOTICE), está en el fichero THIRD_PARTY_NOTICES. Para esos componentes manda su licencia, y nada de esta te quita lo que ella te

package/README.md

@@ -95,11 +95,34 @@ documentación de desarrolladores.
 - `caja` de cada fichero: `contract`, `tenant_id`, `other`, `acta`, `movimientos` o `foto`. Solo se admite una `foto` por vivienda.
 - Las escrituras se pueden reintentar con la misma `Idempotency-Key` durante 24 horas.
 
+## Entorno de pruebas
+
+Para desarrollar sin tocar tu cuenta real, usa el entorno de pruebas con una key que empiece por `cda_test_`:
+
+```ts
+import { crearCliente, URL_BASE_SANDBOX } from '@controldealquiler/sdk'
+const cda = crearCliente({ apiKey: process.env.CDA_API_KEY, baseUrl: URL_BASE_SANDBOX })
+```
+
+Con la línea de comandos: `CDA_BASE_URL=https://sandbox.controldealquiler.com/api`.
+
+El acceso lo damos nosotros: pídelo y te creamos una cuenta de agencia de pruebas. Usa una contraseña de cifrado y un par de claves de integración distintos de los de producción. Allí no se envía ningún correo, los créditos son de prueba y los datos se borran solos (los clientes, a los 30 días). Si mezclas una key de producción con el entorno de pruebas, o al revés, el SDK falla antes de enviar nada.
+
 ## Qué viaja cifrado
 
 El SDK sella en tu sistema, con la clave pública de tu agencia, el nombre de tus clientes, la calle y el código postal de cada vivienda y los ficheros: nuestro servidor no puede abrirlos. Llegan y se guardan legibles el correo de tu cliente, la provincia y el municipio de cada vivienda, el porcentaje de propiedad, tus referencias y lo que lee el lector (importes, fechas y conceptos y, de un contrato, sus fechas, la renta y el número de inquilinos). No uses como referencia el nombre, el documento de identidad ni el correo de un cliente.
 
-Si pasamos a leer en nuestro servidor (las [Condiciones de la API](https://controldealquiler.com/condiciones-api) dicen que te avisaremos antes), la API responde `409 AGENCIA_MODO_SERVIDOR` y el SDK, por su cuenta y sin opción para evitarlo, manda además una copia del fichero sin el cifrado de extremo a extremo, protegida solo en el camino, para que la leamos en memoria sin guardarla. La copia que se guarda sigue sellada. `controldealquiler alta` hace lo mismo. Por su cuenta, el SDK no pide escaneos con inteligencia artificial.
+Si pasamos a leer en nuestro servidor (las [Condiciones de la API](https://controldealquiler.com/condiciones-api) dicen que te avisaremos antes), la API responde `409 AGENCIA_MODO_SERVIDOR`. Por defecto (`lecturaEnServidor: 'permitir'`) el SDK manda entonces una copia del fichero sin el cifrado de extremo a extremo, protegida solo en el camino, para que la leamos en memoria sin guardarla. La copia que se guarda sigue sellada. `controldealquiler alta` hace lo mismo.
+
+Si prefieres que el fichero no salga nunca de tu sistema en claro, fija `lecturaEnServidor: 'rechazar'`:
+
+```ts
+const cda = crearCliente({ apiKey, descifrador, lecturaEnServidor: 'rechazar' })
+```
+
+Con `'rechazar'` no sale ningún multipart, ni al leer (`borradores.leer`, `crearBorradores`) ni en el alta (`clientes.crear`, `crearVarios`). El 409 se relanza; en el alta llega como `ErrorAlta` con el paso y el fichero, `reintentable: false` y `corta: true` (`crearVarios` corta la pasada). En la línea de comandos, la variable `CDA_LECTURA_EN_SERVIDOR=rechazar` es equivalente.
+
+Por su cuenta, el SDK no pide escaneos con inteligencia artificial. Ojo: si llamas tú al endpoint de escaneo con IA (`escanear-ia`), ese siempre sube el fichero en claro, con independencia de `lecturaEnServidor`.
 
 ## Gestión de clientes y de la cuenta
 
@@ -183,10 +206,17 @@ Se configura por entorno:
 | `CDA_BASE_URL` | Opcional. Dirección de la API. Para el sandbox: `https://sandbox.controldealquiler.com/api` con una key `cda_test_`; el SDK rechaza en local cruzar una key de un entorno con la base del otro |
 | `CDA_CLAVE_INTEGRACION` | Ruta al fichero PEM de la clave privada de la integración (no la clave) |
 | `CDA_CLAVE_INTEGRACION_PEM` | Alternativa a la ruta: el contenido del PEM de la clave privada, con sus saltos de línea. Gana a `CDA_CLAVE_INTEGRACION` |
+| `CDA_LECTURA_EN_SERVIDOR` | Opcional. `rechazar` evita que el SDK suba ningún fichero por multipart si la API pasa a leer en el servidor (`409 AGENCIA_MODO_SERVIDOR`); `permitir` (por defecto) lo sube. Otro valor es un error de uso |
 | `CDA_SOBRE_INTEGRACION` | Ruta a un fichero JSON con el sobre de integración: el campo `sobre` de la respuesta de `GET /v1/integracion` |
 
 `controldealquiler` sin argumentos muestra la ayuda de cada comando.
 
+## Cambios en 1.3.0
+
+- Nueva opción `lecturaEnServidor: 'permitir' | 'rechazar'` (por defecto `'permitir'`, como hasta ahora). Con `'rechazar'`, el `409 AGENCIA_MODO_SERVIDOR` no sube el fichero por multipart: `borradores.leer`, `crearBorradores` y el alta fallan, y el alta lanza `ErrorAlta` con `corta: true` y `reintentable: false`.
+- `controldealquiler` acepta `CDA_LECTURA_EN_SERVIDOR=rechazar`.
+- `AGENCIA_MODO_SERVIDOR` cuenta como fallo que corta la pasada en `ErrorAlta` (antes nunca llegaba al alta).
+
 ## Cambios en 1.2.1
 
 - Incluye los tipos de TypeScript (`dist/index.d.ts`) y los metadatos del paquete.