@pimia/sdk 0.20.0 → 0.27.0

package/dist/central.js

@@ -0,0 +1,257 @@
+import { NotAuthenticatedError, PimiaApiError, RateLimitError } from './errors.js';
+export class PimiaCentralClient {
+    baseUrl;
+    token;
+    doFetch;
+    extraHeaders;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, '');
+        this.token = options.token;
+        this.doFetch = options.fetch ?? globalThis.fetch;
+        this.extraHeaders = options.headers ?? {};
+    }
+    // ── La cartera y la salud de la integración (habilidad `desarrollador`) ──
+    /** `GET /desarrollador/overview`: la cartera, con la atribución de cada alta. */
+    overview() {
+        return this.request('/desarrollador/overview');
+    }
+    /** `GET /desarrollador/salud`: clients, webhooks y propuestas, solo los propios. */
+    salud() {
+        return this.request('/desarrollador/salud');
+    }
+    /** `GET /desarrollador/facturacion`: lo que el integrador paga a Pimia (canal y asientos). */
+    facturacion() {
+        return this.request('/desarrollador/facturacion');
+    }
+    // ── El vínculo con cada cliente (habilidad `desarrollador`) ─────────────
+    get links() {
+        return {
+            list: () => this.request('/desarrollador/links'),
+            /** Un código `DEV-XXXX-XXXX` que el cliente teclea en su instancia. */
+            generateCode: () => this.request('/desarrollador/links/generate-code', {
+                method: 'POST',
+            }),
+            accept: (id) => this.request(`/desarrollador/links/${id}/accept`, {
+                method: 'POST',
+            }),
+            reject: (id) => this.request(`/desarrollador/links/${id}/reject`, {
+                method: 'POST',
+            }),
+        };
+    }
+    // ── Sus clients OAuth (habilidad `desarrollador`) ───────────────────────
+    get clients() {
+        return {
+            list: () => this.request('/desarrollador/clients'),
+            /**
+             * Reclamar un client confidencial CON su secreto: la única prueba de
+             * propiedad que el núcleo acepta (RFC 7591). El secreto no se guarda.
+             */
+            claim: (body) => this.request('/desarrollador/clients/claim', {
+                method: 'POST',
+                body,
+            }),
+        };
+    }
+    // ── Su catálogo: qué revende, a cuánto y a dónde manda a contratar ──────
+    //    (habilidad `desarrollador`; punto 12 de DECISIONES.md, regla 4)
+    get catalogo() {
+        return {
+            /**
+             * `GET /desarrollador/catalogo`: el catálogo propio (`perfil`, `currency`,
+             * `items`) y lo que se puede revender (`disponibles`: Pimia base, los
+             * módulos opcionales ofrecidos y las apps integradas activas).
+             */
+            get: () => this.request('/desarrollador/catalogo'),
+            /**
+             * `PUT /desarrollador/catalogo`: reemplaza el catálogo ENTERO. Es lo que
+             * el cliente del integrador ve en la pantalla de plan de su instancia en
+             * vez de los precios de Pimia; el precio es minorista y no toca el
+             * dinero de Pimia.
+             */
+            replace: (body) => this.request('/desarrollador/catalogo', {
+                method: 'PUT',
+                body,
+            }),
+        };
+    }
+    // ── La activación mayorista: lo que activa a cada cliente y paga en su ──
+    //    canal (habilidad `desarrollador`; regla 4 del punto 12)
+    get activaciones() {
+        return {
+            /**
+             * `GET /desarrollador/tenants/{slug}/activaciones`: la base (su asiento),
+             * los módulos y apps activos y lo que le cuestan al integrador al mes.
+             */
+            list: (tenantSlug) => this.request(`/desarrollador/tenants/${encodeURIComponent(tenantSlug)}/activaciones`),
+            /**
+             * `POST /desarrollador/tenants/{slug}/activaciones`: activar la base, un
+             * módulo o una app. La base es el asiento (la primera vez devuelve
+             * `checkout_url`); un módulo o una app exigen la base viva y se cobran
+             * al integrador como partida de su canal, sin prorrateo, en la factura
+             * del mes. Idempotente (`already_active`). Es lo que llama el webhook del
+             * integrador cuando su cliente le compra algo.
+             */
+            activate: (tenantSlug, body) => this.request(`/desarrollador/tenants/${encodeURIComponent(tenantSlug)}/activaciones`, { method: 'POST', body }),
+            /**
+             * `DELETE /desarrollador/tenants/{slug}/activaciones/{kind}/{item}`: dar de
+             * baja. El módulo se apaga y deja de cobrarse; la app se desinstala de
+             * todas las empresas; la base suelta el asiento.
+             */
+            deactivate: (tenantSlug, kind, item) => this.request(`/desarrollador/tenants/${encodeURIComponent(tenantSlug)}/activaciones/${kind}/${encodeURIComponent(item)}`, { method: 'DELETE' }),
+        };
+    }
+    // ── Su login: el nombre que sirve en su servidor y reenvía al AS del ──
+    //    ápice (habilidad `desarrollador`; regla 5 del punto 12, revisada el
+    //    2026-09-07)
+    get dominios() {
+        return {
+            /** `GET /desarrollador/dominios`: sus nombres de login, con el `upstream` y el bloque de proxy de cada uno. */
+            list: () => this.request('/desarrollador/dominios'),
+            /**
+             * `POST /desarrollador/dominios`: declarar el nombre público que el
+             * integrador sirve (`host`, p. ej. `login.erpstudio.es`) y su etiqueta
+             * interna (`slug`). Pimia no emite certificados ni toca DNS: devuelve
+             * `upstream` (`https://login-<slug>.<central>`), a donde su proxy tiene
+             * que reenviar con `Host` interno y el nombre público en
+             * `X-Forwarded-Host`, y `proxy`, el bloque de Caddy listo para pegar.
+             */
+            declare: (body) => this.request('/desarrollador/dominios', {
+                method: 'POST',
+                body,
+            }),
+            /** `DELETE /desarrollador/dominios/{slug}`: retirar el nombre; el host interno deja de contestar. */
+            remove: (slug) => this.request(`/desarrollador/dominios/${encodeURIComponent(slug)}`, { method: 'DELETE' }),
+        };
+    }
+    // ── Sus tokens de máquina (habilidad `desarrollador`; A3 cerrada) ───────
+    get tokens() {
+        return {
+            /** `GET /desarrollador/tokens`: los tokens de máquina vivos (nunca los de una sesión del panel). */
+            list: () => this.request('/desarrollador/tokens'),
+            /**
+             * `POST /desarrollador/tokens`: acuñar un token de máquina, acotado a la
+             * habilidad `desarrollador` y nada más. El token en claro (`data.token`)
+             * se devuelve UNA vez: guárdalo en tu servidor.
+             */
+            create: (body) => this.request('/desarrollador/tokens', {
+                method: 'POST',
+                body,
+            }),
+            /** `DELETE /desarrollador/tokens/{id}`: revocarlo. */
+            revoke: (id) => this.request(`/desarrollador/tokens/${id}`, {
+                method: 'DELETE',
+            }),
+        };
+    }
+    // ── Lo que hace en el grupo compartido (habilidad `central`) ────────────
+    get invitations() {
+        return {
+            list: () => this.request('/tenant-invitations'),
+            /** El cliente se registra y nace dueño; `billing` dice quién paga. */
+            create: (body) => this.request('/tenant-invitations', { method: 'POST', body }),
+            revoke: (id) => this.request(`/tenant-invitations/${id}`, {
+                method: 'DELETE',
+            }),
+        };
+    }
+    get billing() {
+        return {
+            /**
+             * `POST /billing/portal` (1.4.0): la URL del portal de Stripe de la
+             * cuenta del integrador —las facturas del canal y el método de pago
+             * viven allí, no en Pimia—. 404 si la cuenta no tiene cliente de Stripe
+             * todavía (nunca patrocinó a nadie).
+             */
+            portal: (body = {}) => this.request('/billing/portal', { method: 'POST', body }),
+        };
+    }
+    get sponsorship() {
+        return {
+            /** Asumir la licencia de un cliente: un asiento más en el plan de canal. */
+            sponsor: (body) => this.request('/billing/sponsorship', { method: 'POST', body }),
+            /** Soltar un cliente patrocinado (queda en gracia y puede rescatarse). */
+            release: (tenantSlug) => this.request('/billing/sponsorship', {
+                method: 'DELETE',
+                body: { tenant_slug: tenantSlug },
+            }),
+        };
+    }
+    get tenants() {
+        return {
+            /**
+             * `GET /tenants/{slug}/users` (1.4.0): quién pertenece a la instancia
+             * —nombre, correo, rol, `is_owner`—. Es a quién se le puede traspasar:
+             * `transferOwnership` pide el `user_id` de alguien que ya está dentro.
+             */
+            users: (slug) => this.request(`/tenants/${encodeURIComponent(slug)}/users`),
+            /** Traspasar la propiedad de la instancia a un usuario de la misma, antes de entregarla. */
+            transferOwnership: (slug, body) => this.request(`/tenants/${encodeURIComponent(slug)}/transfer-ownership`, { method: 'POST', body }),
+        };
+    }
+    // ── Transporte ──────────────────────────────────────────────────────────
+    async request(path, options = {}) {
+        const { data } = await this.requestWithMeta(path, options);
+        return data;
+    }
+    async requestWithMeta(path, options = {}) {
+        const token = typeof this.token === 'function' ? await this.token() : this.token;
+        if (!token) {
+            throw new NotAuthenticatedError('No hay token personal: acuña uno en la cuenta de desarrollador antes de llamar al plano central.');
+        }
+        const response = await this.doFetch(this.urlFor(path, options.query), {
+            method: options.method ?? 'GET',
+            headers: {
+                accept: 'application/json',
+                ...(options.body === undefined ? {} : { 'content-type': 'application/json' }),
+                ...this.extraHeaders,
+                ...options.headers,
+                authorization: `Bearer ${token}`,
+            },
+            body: options.body === undefined ? undefined : JSON.stringify(options.body),
+            signal: options.signal,
+        });
+        const requestId = response.headers.get('x-request-id') ?? undefined;
+        const body = await parseBody(response);
+        if (response.ok) {
+            return { data: body, meta: { status: response.status, requestId } };
+        }
+        if (response.status === 429) {
+            throw new RateLimitError(retryAfterSeconds(response), 429, 'Rate limit alcanzado', body, requestId);
+        }
+        throw PimiaApiError.from(response.status, body, requestId);
+    }
+    urlFor(path, query) {
+        const clean = path.replace(/^\/+/, '').replace(/^api\/?/, '');
+        const url = new URL(`${this.baseUrl}/api/${clean}`);
+        for (const [key, value] of Object.entries(query ?? {})) {
+            if (value === undefined || value === null)
+                continue;
+            if (Array.isArray(value)) {
+                for (const item of value)
+                    url.searchParams.append(`${key}[]`, String(item));
+                continue;
+            }
+            url.searchParams.set(key, String(value));
+        }
+        return url.toString();
+    }
+}
+async function parseBody(response) {
+    const text = await response.text();
+    if (text === '')
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function retryAfterSeconds(response) {
+    const raw = response.headers.get('retry-after');
+    if (raw === null)
+        return undefined;
+    const seconds = Number(raw);
+    return Number.isFinite(seconds) ? seconds : undefined;
+}

package/dist/client.d.ts

@@ -54,6 +54,33 @@ export type WarehouseRequest = Schemas['WarehouseRequest'];
  * null no emiten nada al confirmar.
  */
 export type StockCountRequest = Schemas['StockCountRequest'];
+/**
+ * Cuerpo del alta de una oportunidad: **a quién va dirigida**, y nada más.
+ *
+ * ⛔ La etapa, la probabilidad y el importe esperado son del CRM que llama —
+ * Pimia no los guarda—, así que mandarlos es un 422. Y está bien que lo sea: el
+ * día que los aceptara callando, habría dos sitios donde vive el embudo.
+ */
+export interface OpportunityRequest {
+    name: string;
+    contact_name?: string | null;
+    email?: string | null;
+    phone?: string | null;
+}
+/**
+ * Una oportunidad recién creada.
+ *
+ * ⚠️ **No sale del spec**: `POST /opportunities` es más nueva que la última
+ * sincronización del contrato (galeote/factSaas#805), así que el generador no
+ * la conoce todavía. Lo único que este tipo promete es `id`, que es lo que hace
+ * falta para colgarle presupuestos después; el resto llega y no se nombra.
+ * Cuando la ruta entre en el spec, esto pasará a salir de `Ok<…>` como los
+ * demás.
+ */
+export interface OpportunityResource {
+    id: number;
+    [key: string]: unknown;
+}
 /**
  * El sobre `{ data: … }` de Laravel para las escrituras que el spec **no
  * tipa**.
@@ -85,6 +112,32 @@ export interface PimiaClientOptions extends OAuthConfig {
     /** Cabeceras añadidas a cada petición (p. ej. un User-Agent propio). */
     headers?: Record<string, string>;
 }
+/**
+ * Lo que hace falta para un cliente que **reenvía el token de otro**.
+ *
+ * Sin `clientId`, sin `clientSecret`, sin `redirectUri` y sin `tokens`: no hay
+ * ceremonia OAuth que hacer ni nada tuyo que persistir, porque el grant no es
+ * tuyo. Ver {@link PimiaClient.withBorrowedToken}.
+ */
+export interface BorrowedTokenOptions {
+    /** Base del tenant, con o sin barra final: `https://acme.pimia.es`. */
+    baseUrl: string;
+    /** El bearer que te llegó, tal cual. */
+    accessToken: string;
+    fetch?: typeof globalThis.fetch;
+    /** Cabeceras fijas de cada llamada (p. ej. la `company` activa). */
+    headers?: Record<string, string>;
+    /**
+     * Reintentos ante 429 (default 2).
+     *
+     * ⚠️ Ponlo a **0** si atiendes una petición HTTP de un usuario que está
+     * esperando: los reintentos ESPERAN, y esperar 30 s dentro de una petición
+     * web es una petición colgada y un proceso ocupado.
+     */
+    maxRateLimitRetries?: number;
+    /** Espera máxima por reintento de 429, en ms (default 30 000). */
+    maxRetryDelayMs?: number;
+}
 export interface RequestOptions {
     method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
     /** Query string. Los `undefined`/`null` se omiten; los arrays se repiten. */
@@ -186,7 +239,14 @@ export type WriteOptions = Pick<RequestOptions, 'headers' | 'query' | 'signal' |
  */
 export type ReadOptions = Pick<RequestOptions, 'headers' | 'signal'>;
 export declare class PimiaClient {
-    readonly oauth: OAuth;
+    /**
+     * La ceremonia OAuth, o `null` si este cliente no tiene grant propio
+     * ({@link PimiaClient.withBorrowedToken}). Es `null` y no un objeto a medias
+     * a propósito: un `OAuth` sin `clientId` compondría una URL de autorización
+     * con `client_id=` vacío y el fallo aparecería en el navegador del usuario,
+     * lejos de aquí.
+     */
+    readonly oauth: OAuth | null;
     private readonly baseUrl;
     private readonly doFetch;
     private readonly store;
@@ -198,6 +258,43 @@ export declare class PimiaClient {
     private refreshing;
     private lastRateLimit;
     constructor(options: PimiaClientOptions);
+    /**
+     * Un cliente que **reenvía el token de otro**, sin identidad propia.
+     *
+     * ── Cuándo es esto lo correcto ─────────────────────────────────────────────
+     *
+     * Cuando tu servicio se sienta DELANTE de un usuario que ya entró en Pimia:
+     * el front te manda su `Authorization` y tú lo reenvías. No necesitas
+     * `clientId`, ni `clientSecret`, ni `redirectUri`, ni un `TokenStore` —no hay
+     * nada tuyo que guardar— y ganas la propiedad que hace esto seguro: **Pimia
+     * sigue decidiendo los permisos**. Tu servicio no puede darle a nadie más de
+     * lo que su token ya le daba, así que no hay una credencial de servicio que
+     * auditar aparte.
+     *
+     * ```ts
+     * const pimia = PimiaClient.withBorrowedToken({
+     *   baseUrl: `https://${tenant}.pimia.es`,
+     *   accessToken: bearerDeQuienLlama,
+     *   // La empresa activa viaja en cabecera, como en todo el API. OMÍTELA
+     *   // cuando no la sepas: `company:` vacía es una cabecera presente que no
+     *   // casa con ninguna empresa.
+     *   headers: empresa === null ? {} : { company: String(empresa) },
+     *   // Atiendes una petición web: no esperes dentro de ella.
+     *   maxRateLimitRetries: 0,
+     * })
+     *
+     * await pimia.bootstrap.currentCompanyId()
+     * ```
+     *
+     * ⚠️ **El token vive lo que viva la petición que lo trajo.** Construye uno por
+     * petición y no compartas la instancia: un cliente compartido es una
+     * credencial compartida, y aquí la credencial es de un usuario concreto.
+     *
+     * ⚠️ Un token prestado **no se refresca**: cuando caduca, el 401 sube como
+     * {@link UnauthorizedError} y quien tiene que conseguir otro es quien te lo
+     * prestó.
+     */
+    static withBorrowedToken(options: BorrowedTokenOptions): PimiaClient;
     /** Cabeceras `X-RateLimit-*` de la última respuesta. */
     get rateLimit(): RateLimit;
     get invoices(): {
@@ -1085,6 +1182,169 @@ export declare class PimiaClient {
             data: components["schemas"]["StockMovementResource"];
         }>;
     };
+    /**
+     * Oportunidades: **a quién va dirigido** un presupuesto.
+     *
+     * `estimates.opportunity_id` es el enlace transparente del núcleo —funciona
+     * venga el CRM de donde venga—, y es lo que permite preguntar «los
+     * presupuestos de este trato» sin que el trato viva en Pimia. Pero hasta el
+     * 2026-09-08 una oportunidad **sólo podía nacer dentro de un
+     * `POST /estimates`**, así que un CRM de fuera no tenía forma de estrenar una
+     * al dar de alta un lead: habría tenido que fabricar un presupuesto borrador y
+     * quemar un número de la serie del cliente por cada lead. Un lead no es una
+     * oferta.
+     *
+     * No estrena scope: cuelga de `estimates:write`, porque la oportunidad es a
+     * quién va dirigido un presupuesto y no una entidad del embudo.
+     *
+     * ⚠️ **Todavía no está en el spec publicado** (galeote/factSaas#805 es más
+     * nueva que la última sincronización del contrato). Contra una instancia
+     * anterior a esa ruta la llamada contesta 404, y eso es lo que hay que mirar
+     * antes de dar por hecho que el token está mal.
+     */
+    get opportunities(): {
+        /**
+         * Estrena una oportunidad. Manda `idempotencyKey` —una clave estable por
+         * lead, del estilo `lead:{id}:opportunity`— y el reintento tras un timeout
+         * no te estrenará una segunda para el mismo trato.
+         */
+        create: (body: OpportunityRequest, options?: WriteOptions) => Promise<ResourceEnvelope<OpportunityResource>>;
+    };
+    /**
+     * Lo que el CRM de Pimia publica para que OTRO CRM pueda sustituirlo.
+     *
+     * No son los leads —ésos los sirve `/crm/leads` y un integrador que trae su
+     * propio embudo no los usa—: es lo que un CRM sustituto necesita del núcleo
+     * aunque se haya llevado el embudo a su casa.
+     */
+    get crm(): {
+        /**
+         * Las personas a las que se les puede asignar una tarea o un lead.
+         *
+         * **Reenvía lo que conteste**, campos de más incluidos. Recortarlo tú es
+         * aplicar dos veces la misma política desde dos sitios que pueden
+         * divergir: Pimia esconde aquí a los superadmin de la plataforma y a la
+         * gestoría dueña del tenant, y recorta cada fila a `id` y `name`. Si
+         * mañana añade un campo para desempatar dos nombres iguales, tu copia lo
+         * borraría sin que nadie entendiera por qué.
+         *
+         * ⚠️ El scope: el contrato publicado la cobra con `crm:read`, pero el
+         * núcleo la abrió el 2026-09-08 a cualquier token válido de la empresa
+         * —precisamente para que un integrador que SUSTITUYE el CRM no tenga que
+         * pedir el scope del CRM que ya no usa—. Contra una instancia anterior a
+         * ese cambio sigue haciendo falta `crm:read`.
+         */
+        assignableUsers: (options?: ReadOptions) => Promise<{
+            data: {
+                id: number;
+                name: string;
+            }[];
+        }>;
+    };
+    /**
+     * El arranque de la sesión: en qué empresa trabaja este token y con qué
+     * moneda.
+     *
+     * ⛔ **`/bootstrap` NO envuelve en `data`.** Todo lo demás en el API contesta
+     * `{ data: … }`; ésta no: sus claves cuelgan de la raíz. Un desenvolvedor de
+     * `data` escrito «para todas las llamadas» no encuentra nada aquí y devuelve
+     * vacío **sin error**, así que el fallo no se ve como un fallo: se ve como una
+     * empresa sin resolver o como una moneda que cae al respaldo. Medido
+     * construyendo el CRM de la vertical, que tuvo que anotarlo en su código y en
+     * el arnés de sus tests.
+     *
+     * Lectura libre: la alcanza cualquier token válido, **sin scope** y sin
+     * consentimiento adicional del dueño del tenant.
+     *
+     * ⚠️ Cada método hace SU llamada: no hay caché. Es a propósito —el cliente no
+     * sabe cuánto vive una sesión tuya, y una empresa cacheada de más es una fila
+     * escrita en la empresa equivocada—, así que si necesitas las dos cosas en la
+     * misma petición, llama a `get()` una vez y léelas del objeto.
+     */
+    get bootstrap(): {
+        /** El arranque entero, sin envolver. */
+        get: (options?: ReadOptions) => Promise<{
+            current_user: components["schemas"]["UserResource"];
+            current_user_settings: unknown[];
+            current_user_abilities: string[] | Record<string, never>;
+            companies: components["schemas"]["CompanyResource"][];
+            current_company: components["schemas"]["CompanyResource"];
+            current_company_settings: string[];
+            current_company_currency: components["schemas"]["Currency"] | null;
+            config: string;
+            global_settings: string[];
+            main_menu: {
+                title: string | "";
+                link: string | "";
+                icon: string | "";
+                name: string | "";
+                group: string | "";
+            }[] | {
+                title: string;
+                link: string;
+                icon: string;
+                name: string;
+                group: string;
+            }[];
+            setting_menu: {
+                title: string | "";
+                link: string | "";
+                icon: string | "";
+                name: string | "";
+                group: string | "";
+            }[] | {
+                title: string;
+                link: string;
+                icon: string;
+                name: string;
+                group: string;
+            }[];
+            modules: unknown[];
+            installed_modules: string;
+        }>;
+        /**
+         * En qué empresa trabaja ESTA petición, según el núcleo.
+         *
+         * ⛔ No es «la primera empresa del usuario», aunque hoy coincidan. Pimia
+         * resuelve `current_company` con el mismo camino y el mismo respaldo que
+         * usa su middleware de empresa para servir cualquier otra llamada tuya —la
+         * cabecera `company` si vale, y si no la primera del usuario—, así que
+         * preguntarlo aquí es la única forma de que tu lado y el suyo no puedan
+         * discrepar. Deducirlo de la lista de `/me` reproduce la regla en un
+         * segundo sitio, y dos reglas iguales son dos reglas que pueden separarse:
+         * el día que dejaran de coincidir, escribirías con una empresa que Pimia
+         * nunca usó y sin un solo error que lo denuncie.
+         *
+         * `null` si el arranque no la publica. Trátalo como «no se puede servir
+         * esta sesión» y no como un cero: un cero es una empresa que no es de
+         * nadie y que ve cualquiera que también acabe ahí.
+         *
+         * ⚠️ El spec declara `current_company` obligatorio y el tipo generado dice
+         * que siempre está; la comprobación de aquí es de RUNTIME porque se ha
+         * visto llegar sin ella. Cuando eso pasa, lo que hay que devolver es
+         * `null`, no reventar.
+         */
+        currentCompanyId: (options?: ReadOptions) => Promise<number | null>;
+        /**
+         * La moneda de la empresa y su ESCALA.
+         *
+         * ⛔ La moneda no es siempre el euro y los decimales cambian con ella: el
+         * yen tiene 0, el dinar kuwaití 3. Suponer 2 —o peor, multiplicar por 100
+         * a mano— no da un error, da otro resultado: un filtro por importe
+         * devuelve otras filas y un alta guarda una moneda falsa en la ficha. Por
+         * eso la escala se PREGUNTA.
+         *
+         * `null` si el arranque no publica moneda (el campo admite nulo en el
+         * contrato), y ahí el SDK **no se inventa nada**: «EUR con 2 decimales» es
+         * una política de producto, la decide quien llama. Lo que sí se lee a la
+         * defensiva es `precision`, que el contrato declara obligatorio dentro de
+         * la moneda: un cuerpo sin él está roto, no es un caso de negocio.
+         */
+        currency: (options?: ReadOptions) => Promise<{
+            code: string;
+            precision: number;
+        } | null>;
+    };
     get<T = unknown>(path: string, query?: RequestOptions['query'], options?: ReadOptions): Promise<T>;
     post<T = unknown>(path: string, body?: unknown, options?: WriteOptions): Promise<T>;
     put<T = unknown>(path: string, body?: unknown, options?: WriteOptions): Promise<T>;