@controldealquiler/sdk 0.0.0-stage → 1.2.1

package/dist/index.d.ts

@@ -0,0 +1,739 @@
+/// <reference lib="dom" />
+interface OpcionesHttp {
+    apiKey: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    /** Reintentos máximos tras el primer intento (por defecto 3). */
+    maxReintentos?: number;
+}
+interface Peticion {
+    metodo: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    ruta: string;
+    cuerpo?: unknown;
+    /** Cuerpo ya formado (p. ej. multipart); sustituye a `cuerpo`. */
+    cuerpoCrudo?: BodyInit;
+    query?: Record<string, string | number | undefined>;
+    /** `false` fuerza sin clave; un string fija la clave (para repetir una llamada en otro proceso). */
+    idempotencia?: boolean | string;
+    cabeceras?: Record<string, string>;
+    /** Recibe las cabeceras de la respuesta recibida (la última, tras los reintentos), sea o no un error. */
+    alResponder?: (cabeceras: Headers) => void;
+}
+declare class ErrorApiSdk extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly problema: unknown;
+    readonly requestId: string | null;
+    /** `requestId`: cabecera `X-Request-Id` de la respuesta de error (o `null`); para citar el fallo al soporte. */
+    constructor(status: number, code: string, problema: unknown, requestId?: string | null);
+}
+declare const URL_BASE_SANDBOX = "https://sandbox.controldealquiler.com/api";
+/** Cruce de entornos: una key de producción contra el sandbox, o una de pruebas contra producción. Se lanza antes de `fetch`. */
+declare class ErrorDeEntorno extends Error {
+    readonly code: 'KEY_DE_PRODUCCION' | 'KEY_DE_PRUEBAS';
+    constructor(code: 'KEY_DE_PRODUCCION' | 'KEY_DE_PRUEBAS');
+}
+declare const admiteIdempotencia: (metodo: string, ruta: string) => boolean;
+declare function esperaDeRetryAfter(valor: string | null, intento: number, ahora?: number): number;
+declare function crearHttp(o: OpcionesHttp): {
+    peticion: <T = unknown>(p: Peticion) => Promise<T>;
+};
+type Http = ReturnType<typeof crearHttp>;
+
+declare function bytesToBase64(bytes: Uint8Array): string;
+declare function base64ToBytes(b64: string): Uint8Array;
+
+interface Sobre {
+    wrapped_key: Uint8Array;
+    cipher: Uint8Array;
+    iv: Uint8Array;
+}
+interface FicheroSellado {
+    /** iv||cipher: se sube tal cual al bucket (formato del vault). */
+    blob: Uint8Array;
+    wrapped_file_key: Uint8Array;
+    nombre_cipher: Uint8Array;
+    nombre_iv: Uint8Array;
+}
+/** (Sin AAD en AES-GCM, compatible con `envelope.ts` tal cual: el formato no ata el sobre a su cliente.) */
+/** Sella un JSON con la pública del destinatario (un único sobre). */
+declare function sellarJson(valor: unknown, publicaSpki: Uint8Array): Promise<Sobre>;
+/** Abre un sobre con la privada (CryptoKey RSA-OAEP con `decrypt`). */
+declare function abrirJson<T = unknown>(sobre: Sobre, privada: CryptoKey): Promise<T>;
+/** Sella un fichero: clave de fichero aleatoria envuelta; el nombre, sellado con esa misma clave. */
+declare function sellarFichero(contenido: Uint8Array, nombre: string, publicaSpki: Uint8Array): Promise<FicheroSellado>;
+declare function abrirNombreFichero(f: Pick<FicheroSellado, 'wrapped_file_key' | 'nombre_cipher' | 'nombre_iv'>, privada: CryptoKey): Promise<string>;
+declare function abrirContenidoFichero(blob: Uint8Array, wrappedFileKey: Uint8Array, privada: CryptoKey): Promise<Uint8Array>;
+/**
+ * Vuelve a envolver la clave de un fichero: la abre con la privada de la agencia y la sella con la pública del
+ * cliente. El contenido del objeto no cambia (sigue cifrado con la misma clave); solo cambia a quién se le abre.
+ */
+declare function reenvolverClave(wrapped: Uint8Array, privada: CryptoKey, publicaSpki: Uint8Array): Promise<Uint8Array>;
+
+interface SobreB64Cliente {
+    wrapped_key_b64: string;
+    cipher_b64: string;
+    iv_b64: string;
+}
+declare function sellarSobreB64(valor: unknown, spkiB64: string): Promise<SobreB64Cliente>;
+
+/** Abre un sobre y devuelve los bytes en claro (el `Descifrador` devuelve bytes; el JSON lo interpreta quien llama). */
+declare function abrirSobreBytes(sobre: Sobre, privada: CryptoKey): Promise<Uint8Array>;
+/** Importa una privada PKCS#8 (DER) como clave RSA-OAEP-SHA256 de solo descifrar. */
+declare function importarPrivadaPkcs8(pkcs8: Uint8Array): Promise<CryptoKey>;
+/** SHA-256 en hexadecimal (el hash del fichero en claro que se declara al subirlo). */
+declare function sha256Hex(bytes: Uint8Array): Promise<string>;
+/** Sobre en la forma JSON de la API (`*_b64`) -> bytes. */
+declare function sobreDeB64(s: {
+    wrapped_key_b64: string;
+    cipher_b64: string;
+    iv_b64: string;
+}): Sobre;
+
+interface Descifrador {
+    abrirSobre(s: Sobre): Promise<Uint8Array>;
+    /** Pública SPKI (base64) de la agencia: a quién se sellan los ficheros subidos. */
+    publicaAgenciaSpki(): Promise<string>;
+    /**
+     * La privada de sobres de la agencia como clave no extraíble, solo en memoria del proceso. La usa `clientes.crear` para
+     * re-envolver las claves de los ficheros hacia la llave efímera del alta (el mismo `sellarBorradorParaEfimera` del panel).
+     */
+    clavePrivadaSobres(): Promise<CryptoKey>;
+}
+interface OrigenClaveIntegracion {
+    /** El PEM mismo (p. ej. sacado de un gestor de secretos). Gana a la variable de entorno y al fichero. */
+    pem?: string;
+    /** Ruta a un fichero PEM. Solo se lee si no hay `pem` ni variable de entorno. */
+    ruta?: string;
+    /** Entorno donde buscar `CDA_CLAVE_INTEGRACION_PEM`. Por defecto `process.env`. */
+    env?: Record<string, string | undefined>;
+}
+/** Un PEM inválido (o cifrado con contraseña, que el SDK no acepta) da este error fijo: nunca lleva el contenido. */
+declare class ErrorClaveIntegracion extends Error {
+    constructor(m: string);
+}
+/** Lee la privada de integración (PEM PKCS#8, sin contraseña) de un fichero. Para leerla también de la opción `pem` o de `CDA_CLAVE_INTEGRACION_PEM` (gestor de secretos, variable de entorno o fichero), usa `descifradorDeClave`. */
+declare function descifradorDeFichero(rutaPem: string, sobreIntegracion: Sobre): Descifrador;
+/** Como `descifradorDeFichero`, con la privada desde el PEM, la variable `CDA_CLAVE_INTEGRACION_PEM` o un fichero, por ese orden. */
+declare function descifradorDeClave(origen: OrigenClaveIntegracion, sobreIntegracion: Sobre): Descifrador;
+
+declare const LEASE_WARNING_CODES: readonly ["avalistas_excluidos", "fin_calculado_por_duracion", "mas_de_4_inquilinos", "telefono_sin_atribuir"];
+type LeaseWarningCode = (typeof LEASE_WARNING_CODES)[number];
+
+interface ParsedLeaseTenant {
+    name: string;
+    nif: string | null;
+    phone: string | null;
+    email: string | null;
+}
+interface ParsedLeaseContract {
+    raw_response: string;
+    tenants: ParsedLeaseTenant[];
+    contract_date: string | null;
+    start_date: string | null;
+    end_date: string | null;
+    monthly_rent: number | null;
+    confidence: number | null;
+    warning_codes: LeaseWarningCode[];
+    /** RC de 20 caracteres con dígitos de control correctos, en mayúsculas y sin repetir. */
+    cadastral_refs: string[];
+    /** Dirección de la vivienda tal como consta (una línea, sin trocear), máx. 200 caracteres. */
+    property_address: string | null;
+    /**
+     * Solo el lector sin IA de las agencias (`lib/agencia/lectores/contrato.ts`) lo fija, tras parsear (este parser nunca lo lee del JSON): la RC de la VIVIENDA que se importa a su
+     * ficha (ya validada por dígitos de control), o null si el contrato no la fija. Ausente en la lectura por IA.
+     */
+    cadastral_ref_vivienda?: string | null;
+}
+
+type MotivoContrato = 'contrato_no_reconocido' | 'sin_inquilinos' | 'firma_no_consta' | 'firma_incoherente' | 'sello_otro_anio' | 'sin_inicio' | 'sin_duracion' | 'fin_no_calculable' | 'sin_renta' | 'renta_no_mensual' | 'renta_ambigua' | 'fecha_inexistente' | 'error_interno';
+
+interface VentanaEjercicios {
+    anios: number[];
+    /** YYYY-MM: último mes admitido del año del alta. */
+    hastaMes: string;
+    /** Fecha (YYYY-MM-DD) del fin de campaña del año anterior si este sigue incluido; si no, null. */
+    caducaAntesDe: string | null;
+}
+
+/** Lo que dice la certificación de la agencia (`agencia_lector`): qué parser y qué conceptos están certificados. */
+interface LectorCertificado {
+    parser: string;
+    conceptos: string[];
+}
+
+type MotivoAlta = MotivoContrato | 'sin_texto' | 'lector_fallo' | 'concepto_no_certificado' | 'resumen_anual' | 'fuera_de_ventana' | 'demasiado_grande' | 'tope';
+/** Lo único que se guarda de un contrato leído: fechas, renta y recuento. Sin nombres, NIF ni dirección. */
+interface HuellaAlta {
+    inicio: string | null;
+    fin: string | null;
+    firma: string | null;
+    renta: number | null;
+    nInquilinos: number;
+    parser: string;
+    version: string;
+}
+/** Fila de un movimiento: solo importes, fechas y categoría fiscal (constantes del sistema). Sin texto libre. */
+interface FilaAlta {
+    tipo: 'income' | 'expense';
+    categoria: string;
+    importe: number;
+    /** Emisión de la factura o pago de la renta (YYYY-MM-DD). */
+    fecha: string;
+    /** Fecha de imputación de la transacción (YYYY-MM-DD): la que se compara con la ventana. */
+    devengo: string;
+    /** Periodo de servicio de la fila (YYYY-MM-DD) o `null`: lo que lee el lector, no texto. */
+    periodo_desde: string | null;
+    periodo_hasta: string | null;
+    /** Página del PDF en la que sale la fila (para citarla), o `null`. */
+    pagina: number | null;
+}
+type ResultadoLecturaAlta = {
+    ok: true;
+    tipo: 'contrato';
+    contrato: ParsedLeaseContract;
+    huella: HuellaAlta;
+    direccion: string | null;
+} | {
+    ok: true;
+    tipo: 'movimiento';
+    filas: FilaAlta[];
+    huella: string[];
+    parser: string;
+    version: string;
+    direccion: string | null;
+    conceptos: string[];
+    aRevision: 'prorrata' | null;
+    emision: string | null;
+    /** Filas leídas pero fuera de la ventana de ejercicios: se quitan con aviso. */
+    filasFuera: number;
+    /**
+     * Rótulo de cada fila de `filas` (mismo orden, ≤200 caracteres): texto libre del PDF. NUNCA va a la BD ni a la
+     * respuesta del servidor (`lecturaAGuardar` y `respuestaDe` eligen campos a mano): solo lo usa el navegador de la
+     * agencia para el sobre E2EE del titular, donde es el concepto de la transacción.
+     */
+    rotulos: string[];
+} | {
+    ok: false;
+    motivo: MotivoAlta;
+    transitorio: boolean;
+};
+
+/** Mismo tope que el servidor y el navegador (`leer-alta-navegador.ts`, `leer-fichero.ts`). */
+declare const TOPE_BYTES = 4000000;
+/** Lector vivo de la agencia: `parser` y conceptos certificados (constantes del sistema, sin PII). */
+type LectorVigente = LectorCertificado;
+/** Cajas que se leen en local (las demás no tienen lector). */
+type CajaLectura = 'contract' | 'movimientos';
+type SalidaLectorLocal = {
+    resultado: Record<string, unknown>;
+    textoSha256: string | undefined;
+} | {
+    demasiadoGrande: true;
+};
+interface OpcionesLector {
+    caja: CajaLectura;
+    lector: LectorVigente | null;
+    /** El servidor aplica la ventana: aquí se lee con una ventana abierta, igual que el navegador. */
+    ventana?: VentanaEjercicios;
+    mime?: string;
+    /** Solo para los tests: sustituye a pdf.js. */
+    extraer?: (b: Uint8Array) => Promise<string | null>;
+}
+declare function leerFicheroLocal(bytes: Uint8Array, a: OpcionesLector): Promise<SalidaLectorLocal>;
+interface Borradores {
+    /**
+     * Lee un fichero del borrador: JSON con el resultado de la lectura local; si la API responde `409 AGENCIA_MODO_SERVIDOR`,
+     * multipart con el fichero. Un fichero de más de 4 MB se notifica como el navegador (`demasiado_grande`, definitivo).
+     */
+    leer(b: string, f: string, bytes: Uint8Array, a: OpcionesLector): Promise<unknown>;
+    /**
+     * Lo mismo que `leer`, pero devuelve además la lectura local (contrato, dirección y rótulos, que no viajan a la API) para quien
+     * arma el alta (`clientes.crear`). `local` es `null` si se leyó por multipart (la lectura la hizo el servidor) o si pesa más de 4 MB.
+     */
+    leerDetalle(b: string, f: string, bytes: Uint8Array, a: OpcionesLector): Promise<{
+        respuesta: unknown;
+        local: ResultadoLecturaAlta | null;
+    }>;
+}
+declare function crearBorradores(http: Http): Borradores;
+
+/** Todas las cajas de un fichero del alta: `acta` (0 o 1 por contrato) y `movimientos` solo van con paquete. */
+declare const CAJAS: readonly ["contract", "tenant_id", "other", "acta", "movimientos", "foto"];
+type Caja = (typeof CAJAS)[number];
+
+type PasoAlta = 'validar' | 'foto' | 'abrir' | 'vivienda' | 'fichero' | 'leer' | 'cotejar' | 'listo' | 'paquete' | 'lote' | 'enlace';
+type Creado = true | false | 'desconocido';
+type Consejo = 'repetir' | 'manifiesto' | 'cuenta';
+interface ContextoAlta {
+    ref: string;
+    paso: PasoAlta;
+    vivienda?: string | number;
+    caja?: string;
+    fichero?: number;
+    loteId?: string;
+    indice?: number;
+    clientId?: string;
+    creado: Creado;
+}
+declare class ErrorAlta extends ErrorApiSdk {
+    readonly ref: string;
+    readonly paso: PasoAlta;
+    readonly vivienda?: string | number;
+    readonly caja?: string;
+    readonly fichero?: number;
+    readonly loteId?: string;
+    readonly indice?: number;
+    readonly clientId?: string;
+    readonly creado: Creado;
+    readonly reintentable: boolean;
+    readonly consejo: Consejo;
+    readonly corta: boolean;
+    constructor(ctx: ContextoAlta, info: {
+        status: number;
+        code: string;
+        requestId: string | null;
+        problema: unknown;
+    }, clase: {
+        reintentable: boolean;
+        consejo: Consejo;
+        corta: boolean;
+    }, causa?: unknown);
+}
+declare function codigoDe(err: unknown): {
+    status: number;
+    code: string;
+    requestId: string | null;
+};
+declare function clasificar(code: string, status: number, ctx: ContextoAlta): {
+    reintentable: boolean;
+    consejo: Consejo;
+    corta: boolean;
+};
+/** Envuelve cualquier fallo del alta en `ErrorAlta`; si ya lo es, lo devuelve tal cual. */
+declare function envolver(err: unknown, ctx: ContextoAlta): ErrorAlta;
+
+interface OpcionesVarios {
+    aLaVez?: 1 | 2;
+    repetir?: 0 | 1 | 2;
+}
+interface FallidoAlta extends ContextoAlta {
+    status: number;
+    code: string;
+    requestId: string | null;
+    reintentable: boolean;
+    consejo: Consejo;
+    intentos: number;
+}
+interface InformeVarios {
+    completados: Array<ResultadoAlta & {
+        ref: string;
+        intentos: number;
+    }>;
+    fallidos: FallidoAlta[];
+    noIntentados: string[];
+    cortadoPor: {
+        status: number;
+        code: string;
+        requestId: string | null;
+    } | null;
+}
+declare function crearVarios(alta: (e: EntradaAlta, previo?: {
+    creado: Creado;
+}) => Promise<ResultadoAlta>, entradas: EntradaAlta[], o?: OpcionesVarios, dormir?: (ms: number) => Promise<void>): Promise<InformeVarios>;
+
+interface FicheroAlta {
+    caja: Caja;
+    nombre: string;
+    bytes: Uint8Array;
+    mime: string;
+}
+interface ViviendaAlta {
+    ref?: string;
+    provincia: string;
+    municipio?: string;
+    direccion: string;
+    /**
+     * Código postal (5 cifras), OBLIGATORIO: el sobre de la vivienda lo exige (`sobreViviendaSchema`) y el dueño lo ve. Desvío
+     * del plan (su interfaz no lo traía); nunca se inventa uno (decisión de la Reina, 28-10).
+     */
+    cp: string;
+    ficheros: FicheroAlta[];
+}
+interface EntradaAlta {
+    ref: string;
+    email: string;
+    nombre?: string;
+    viviendas: ViviendaAlta[];
+}
+interface ResultadoAlta {
+    estado: 'creado' | 'ya_existia';
+    clientId: string;
+    /** Enlace para el titular, o `'activado'` si la cuenta ya está activa (no hay enlace que entregar). */
+    enlace: string | 'activado';
+    correo: 'enviado' | 'no_enviado';
+    motivo?: 'CUPO_DIARIO' | 'ENTORNO_PRUEBAS';
+}
+interface DepsAlta {
+    http: Http;
+    borradores: Borradores;
+    descifrador: Descifrador;
+    /** `fetch` para subir los objetos a la URL firmada del Storage. */
+    fetch?: typeof fetch;
+    /** Origen del sitio (`https://controldealquiler.com`) para componer el enlace. */
+    origen: string;
+    /** Solo para los tests: sustituye a pdf.js. */
+    extraer?: OpcionesLector['extraer'];
+    /** «Hoy» de Madrid para validar los contratos; por defecto `lib/time/madrid.ts`. */
+    hoy?: () => string;
+    /** Espera entre sondeos del lote y entre reintentos de lectura (ms). */
+    intervaloMs?: number;
+    /** Cuánto se espera el resultado del lote antes de rendirse (ms). Por defecto 120 s. */
+    maxEsperaMs?: number;
+    dormir?: (ms: number) => Promise<void>;
+    /**
+     * Ficheros de una misma vivienda que se suben y leen a la vez (entero de 1 a 8; fuera de rango se acota). Si no se fija,
+     * se usa la sugerencia del servidor (`GET /v1/yo` → `limites.concurrencia_ficheros`) y, si falta o falla, 4.
+     * 1 los procesa uno tras otro. Las viviendas siguen en serie. Cada fichero cuesta unas 3 llamadas a la API y la API admite
+     * 10 peticiones/s por cuenta con ráfaga de 50 (`apps/web/lib/api/limites.ts`): un 429 se reintenta con `Retry-After`.
+     */
+    concurrenciaFicheros?: number;
+    /** Uso interno: la sugerencia del servidor, memorizada por cliente (`concurrenciaDelServidor`). */
+    concurrenciaSugerida?: () => Promise<number>;
+}
+/** `crearAlta(d, e)` = `crearAltaConContexto(d, e)`. Lanza SIEMPRE `ErrorAlta` (nada más). */
+declare function crearAlta(deps: DepsAlta, e: EntradaAlta): Promise<ResultadoAlta>;
+interface Clientes {
+    /**
+     * Alta de un cliente con sus viviendas y ficheros por el circuito del panel. Idempotente por `ref`.
+     * `previo` es de uso interno de `crearVarios` y del CLI: arrastra `creado: 'desconocido'` entre intentos de una misma `ref`.
+     */
+    crear(e: EntradaAlta, previo?: {
+        creado: Creado;
+    }): Promise<ResultadoAlta>;
+    /** Varias altas seguidas: nunca lanza, repite lo transitorio y corta lo que afecta a todos (ver `InformeVarios`). */
+    crearVarios(entradas: EntradaAlta[], o?: OpcionesVarios): Promise<InformeVarios>;
+}
+declare function crearClientes(deps: DepsAlta): Clientes;
+
+interface ErrorCliente {
+    cliente_id: string;
+    code: string;
+}
+interface ResultadoMantenimiento {
+    entregadas: number;
+    imposibles: number;
+    /** Un error de un cliente (lote inválido, fallo del servidor…) no tumba la pasada: se recoge aquí y se sigue con los demás. */
+    errores: ErrorCliente[];
+    /** Sobres que la privada de la agencia no abre o que no validan: se quedan pendientes (ver el residual de F1 arriba). */
+    sobresSinAbrir: number;
+    /** `false` si en algún momento faltó una cabecera `Date` válida del servidor: en ese caso no se declaró nada. */
+    relojServidor: boolean;
+}
+interface Mantenimiento {
+    ejecutar(): Promise<ResultadoMantenimiento>;
+}
+interface DepsMantenimiento {
+    http: Http;
+    descifrador: Descifrador;
+}
+declare function crearMantenimiento(deps: DepsMantenimiento): Mantenimiento;
+
+type SobreApi = {
+    wrapped_key_b64: string;
+    cipher_b64: string;
+    iv_b64: string;
+};
+type BuzonApi = {
+    buzon_id: string;
+    direccion: string;
+    activo: boolean;
+};
+type ViviendaApi = {
+    vivienda_id: string;
+    ref: string | null;
+    provincia: string;
+    municipio: string | null;
+    copia_direccion: SobreApi | null;
+    version: string;
+    buzones?: BuzonApi[] | undefined;
+};
+type ClienteApi = {
+    client_id: string;
+    ref: string | null;
+    estado: 'invitado' | 'activo' | 'eliminando';
+    email: string | null;
+    clave_publica_recepcion: string | null;
+    desde_borrador: boolean;
+    copia_nombre: SobreApi | null;
+    renovacion: {
+        efectiva: 'automatica' | 'manual';
+        propia: 'automatica' | 'manual' | null;
+    };
+    creado_at: string;
+    version: string;
+    viviendas?: ViviendaApi[] | undefined;
+};
+
+type ModoRenovacion = 'automatica' | 'manual';
+type Incluir = 'viviendas' | 'viviendas.buzones';
+interface OpcionesListar {
+    estado?: 'invitado' | 'activo' | 'eliminando';
+    cambiado_desde?: string;
+    incluir?: Incluir;
+    /** Tamaño de página (1-500; por defecto el del servidor). */
+    limite?: number;
+}
+interface PaginaClientes {
+    clientes: ClienteApi[];
+    lapidas: Array<{
+        client_id: string;
+        ref: string | null;
+    }>;
+    siguiente: string | null;
+    cambios_hasta?: string;
+}
+interface ViviendaEdicion {
+    /** `vivienda_id` (property_id). */
+    vivienda: string;
+    ref?: string | null;
+    renovacion?: ModoRenovacion | null;
+    /** Corregir la dirección (solo cliente `invitado`): exige `cp` y la provincia sale del CP. */
+    direccion?: string;
+    cp?: string;
+    /** Código INE (5 dígitos); `null` lo limpia. OBLIGATORIO si se manda `direccion`/`cp` (el SDK no deduce el municipio del CP). */
+    municipio?: string | null;
+}
+interface EdicionCliente {
+    ref?: string | null;
+    renovacion?: ModoRenovacion | null;
+    /** Nombre del cliente (etiqueta de la agencia). `''` o `null` lo borra. Ausente: no se toca. */
+    nombre?: string | null;
+    viviendas?: ViviendaEdicion[];
+}
+interface OpcionesEscritura {
+    /** Versión esperada del cliente (`version` de `clientes.leer`, o el ETag `"v12"`). `'*'` vale con cualquiera. Obligatoria. */
+    ifMatch: string;
+}
+interface Escrito {
+    ok: true;
+    version: string | number | null;
+}
+interface ClientesGestion {
+    /** Itera TODOS los clientes: pide páginas hasta que llega una vacía o no hay `siguiente`. */
+    listar(o?: OpcionesListar): AsyncIterableIterator<ClienteApi>;
+    listarPagina(o?: OpcionesListar & {
+        cursor?: string;
+    }): Promise<PaginaClientes>;
+    leer(clienteId: string, o?: {
+        incluir?: Incluir;
+    }): Promise<ClienteApi>;
+    editar(clienteId: string, cambios: EdicionCliente, o: OpcionesEscritura): Promise<Escrito>;
+    desvincular(clienteId: string, o: OpcionesEscritura): Promise<Escrito>;
+    /** Corrige el correo de un cliente `invitado` sin confirmar y le manda un enlace nuevo. */
+    correo(clienteId: string, correo: string): Promise<Escrito>;
+    revocarEnlace(clienteId: string): Promise<Escrito>;
+}
+interface Viviendas {
+    listar(clienteId: string): Promise<ViviendaApi[]>;
+}
+interface Remitentes {
+    listar(): Promise<string[]>;
+    anadir(correo: string): Promise<{
+        remitentes: string[];
+        clientesActualizados: number;
+    }>;
+    quitar(correo: string): Promise<string[]>;
+}
+interface Creditos {
+    leer(): Promise<{
+        saldo: number;
+    }>;
+}
+interface ReglaRenovacion {
+    agencia: ModoRenovacion;
+    clientes: Array<{
+        cliente_id: string;
+        renovacion: ModoRenovacion;
+    }>;
+    viviendas: Array<{
+        vivienda_id: string;
+        cliente_id: string;
+        renovacion: ModoRenovacion;
+    }>;
+}
+type FijarRenovacion = {
+    nivel: 'agencia';
+    renovacion: ModoRenovacion;
+} | {
+    nivel: 'cliente';
+    cliente_id: string;
+    renovacion: ModoRenovacion | null;
+} | {
+    nivel: 'vivienda';
+    cliente_id: string;
+    vivienda_id: string;
+    renovacion: ModoRenovacion | null;
+};
+interface RenovacionApi {
+    leer(): Promise<ReglaRenovacion>;
+    fijar(f: FijarRenovacion): Promise<unknown>;
+}
+/**
+ * Tipos públicos de webhook (v10 § 4.8). Viven como DATOS en `api_webhook_tipo` (migración, columna A); el SDK es
+ * público y no importa del servidor, así que los repite aquí y `tests/api/webhook-tipos-sdk.test.ts` los compara con la
+ * migración para que no se desfasen.
+ */
+declare const TIPOS_WEBHOOK: readonly ["cliente.activado", "cliente.ido", "lote.terminado", "credencial.caduca_pronto", "mantenimiento.pendiente"];
+type TipoWebhook = (typeof TIPOS_WEBHOOK)[number];
+interface DestinoWebhook {
+    webhook_id: string;
+    url: string;
+    tipos: TipoWebhook[];
+    activo: boolean;
+    desactivado_motivo: string | null;
+    creado_at: string;
+}
+interface EntregaWebhook {
+    entrega_id: string;
+    evento_id: number;
+    tipo: string;
+    estado: string;
+    intento: number;
+    ultimo_codigo: number | null;
+    ultimo_motivo: string | null;
+    proxima_at: string;
+}
+interface Webhooks {
+    listar(): Promise<DestinoWebhook[]>;
+    /** El secreto `whsec_…` solo viene en la primera respuesta; un replay de la misma llamada no lo lleva. */
+    crear(e: {
+        url: string;
+        tipos: TipoWebhook[];
+    }): Promise<{
+        webhook_id: string;
+        url: string;
+        tipos: TipoWebhook[];
+        secreto?: string;
+        detail?: string;
+    }>;
+    borrar(webhookId: string): Promise<{
+        webhook_id: string;
+    }>;
+    rotarSecreto(webhookId: string): Promise<{
+        webhook_id: string;
+        secreto?: string;
+        previo_hasta: string;
+        detail?: string;
+    }>;
+    entregas(webhookId: string, o?: {
+        estado?: string;
+        cursor?: string;
+        limite?: number;
+    }): Promise<{
+        entregas: EntregaWebhook[];
+        siguiente: string | null;
+    }>;
+    reenviar(webhookId: string, entregaId: string): Promise<{
+        entrega_id: string;
+        estado: 'pendiente';
+    }>;
+}
+interface Gestion {
+    clientes: ClientesGestion;
+    viviendas: Viviendas;
+    remitentes: Remitentes;
+    creditos: Creditos;
+    renovacion: RenovacionApi;
+    webhooks: Webhooks;
+}
+interface DepsGestion {
+    http: Http;
+    descifrador: Descifrador;
+}
+/** `"v12"` a partir de `12`, `"12"` o `"\"v12\""`; `*` y las etiquetas ya formadas pasan tal cual. */
+declare function etiquetaIfMatch(v: string | number): string;
+declare function crearGestion(deps: DepsGestion): Gestion;
+
+declare const FOTO_LADO_MAX = 1600;
+declare const FOTO_CALIDAD = 0.82;
+declare const FOTO_CALIDAD_2 = 0.7;
+declare const FOTO_BYTES_OBJETIVO: number;
+type ResultadoFotoSdk = {
+    ok: true;
+    bytes: Uint8Array;
+    mime: 'image/jpeg';
+} | {
+    ok: false;
+    error: 'IMAGEN_NO_PROCESABLE';
+};
+/** Lo mínimo de `sharp` que usamos (se tipa a mano: la dependencia es opcional y puede no estar instalada). */
+interface SharpInstancia {
+    rotate(): SharpInstancia;
+    resize(o: Record<string, unknown>): SharpInstancia;
+    clone(): SharpInstancia;
+    jpeg(o: {
+        quality: number;
+    }): SharpInstancia;
+    toBuffer(): Promise<Uint8Array>;
+}
+type SharpFn = (entrada: Uint8Array, opciones?: Record<string, unknown>) => SharpInstancia;
+interface DepsFoto {
+    /** Solo para los tests: sustituye a la carga de `sharp` (`null` = no instalado). */
+    cargarSharp?: () => Promise<SharpFn | null>;
+}
+declare function prepararFoto(bytes: Uint8Array, mime: string, deps?: DepsFoto): Promise<ResultadoFotoSdk>;
+
+declare const TOLERANCIA_WEBHOOK_S = 300;
+type MotivoFirmaWebhook = 'CABECERAS' | 'TIMESTAMP' | 'FUERA_DE_VENTANA' | 'SECRETO' | 'FIRMA';
+declare class ErrorFirmaWebhook extends Error {
+    readonly motivo: MotivoFirmaWebhook;
+    constructor(motivo: MotivoFirmaWebhook);
+}
+type CabecerasWebhook = Headers | Record<string, string | string[] | undefined>;
+interface OpcionesVerificar {
+    /** «Ahora» en milisegundos Unix; por defecto `Date.now()`. Solo para tests. */
+    ahora?: () => number;
+    /** Ventana en segundos a cada lado (por defecto 300). */
+    toleranciaS?: number;
+}
+interface WebhookVerificado {
+    id: string;
+    /** Segundos Unix del intento. */
+    timestamp: number;
+}
+/** Verifica o lanza `ErrorFirmaWebhook`. `cuerpo` es el cuerpo CRUDO recibido, sin re-serializar. */
+declare function verificarWebhook(cuerpo: string | Uint8Array, cabeceras: CabecerasWebhook, secreto: string | readonly string[], opciones?: OpcionesVerificar): WebhookVerificado;
+
+interface ClienteCda {
+    /** Llamada de bajo nivel; las tareas siguientes cuelgan de aquí `clientes`, `borradores`, `mantenimiento`. */
+    peticion<T = unknown>(p: Peticion): Promise<T>;
+    http: Http;
+    descifrador: Descifrador;
+    borradores: Borradores;
+    clientes: Clientes & ClientesGestion;
+    viviendas: Gestion['viviendas'];
+    remitentes: Gestion['remitentes'];
+    creditos: Gestion['creditos'];
+    renovacion: Gestion['renovacion'];
+    webhooks: Gestion['webhooks'];
+    mantenimiento: Mantenimiento;
+}
+interface OpcionesCliente {
+    apiKey: string;
+    baseUrl?: string;
+    descifrador: Descifrador;
+    fetch?: typeof fetch;
+    /** Solo para los tests: sustituye a pdf.js al leer actas, contratos y movimientos. */
+    extraer?: OpcionesLector['extraer'];
+    hoy?: () => string;
+    intervaloMs?: number;
+    maxEsperaMs?: number;
+    dormir?: (ms: number) => Promise<void>;
+    /** Ficheros de una vivienda procesados a la vez (1 a 8). Si no se fija, el SDK usa la que sugiere `GET /v1/yo` o, si falta, 4. La API admite 10 peticiones/s por cuenta, ráfaga de 50. */
+    concurrenciaFicheros?: number;
+}
+declare function crearCliente(o: OpcionesCliente): ClienteCda;
+
+export { ErrorAlta, ErrorApiSdk, ErrorClaveIntegracion, ErrorDeEntorno, ErrorFirmaWebhook, FOTO_BYTES_OBJETIVO, FOTO_CALIDAD, FOTO_CALIDAD_2, FOTO_LADO_MAX, TIPOS_WEBHOOK, TOLERANCIA_WEBHOOK_S, TOPE_BYTES, URL_BASE_SANDBOX, abrirContenidoFichero, abrirJson, abrirNombreFichero, abrirSobreBytes, admiteIdempotencia, base64ToBytes, bytesToBase64, clasificar, codigoDe, crearAlta, crearBorradores, crearCliente, crearClientes, crearGestion, crearHttp, crearMantenimiento, crearVarios, descifradorDeClave, descifradorDeFichero, envolver, esperaDeRetryAfter, etiquetaIfMatch, importarPrivadaPkcs8, leerFicheroLocal, prepararFoto, reenvolverClave, sellarFichero, sellarJson, sellarSobreB64, sha256Hex, sobreDeB64, verificarWebhook };
+export type { Borradores, BuzonApi, CabecerasWebhook, ClienteApi, ClienteCda, Clientes, ClientesGestion, Consejo, ContextoAlta, Creado, Creditos, DepsAlta, DepsGestion, DepsMantenimiento, Descifrador, DestinoWebhook, EdicionCliente, EntradaAlta, EntregaWebhook, ErrorCliente, Escrito, FallidoAlta, FicheroAlta, FicheroSellado, FijarRenovacion, Gestion, Http, Incluir, InformeVarios, LectorVigente, Mantenimiento, ModoRenovacion, MotivoFirmaWebhook, OpcionesCliente, OpcionesEscritura, OpcionesHttp, OpcionesLector, OpcionesListar, OpcionesVarios, OpcionesVerificar, OrigenClaveIntegracion, PaginaClientes, PasoAlta, Peticion, ReglaRenovacion, Remitentes, RenovacionApi, ResultadoAlta, ResultadoFotoSdk, ResultadoMantenimiento, SalidaLectorLocal, Sobre, SobreApi, SobreB64Cliente, TipoWebhook, ViviendaAlta, ViviendaApi, ViviendaEdicion, Viviendas, WebhookVerificado, Webhooks };