@pimia/sdk 0.20.0 → 0.27.0

package/dist/client.js

@@ -15,8 +15,15 @@
  */
 import { NotAuthenticatedError, OAuthError, PimiaApiError, RateLimitError, UnauthorizedError, } from './errors.js';
 import { OAuth } from './oauth.js';
-import { isExpired } from './tokens.js';
+import { BorrowedTokenStore, isExpired } from './tokens.js';
 export class PimiaClient {
+    /**
+     * 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í.
+     */
     oauth;
     baseUrl;
     doFetch;
@@ -29,7 +36,9 @@ export class PimiaClient {
     refreshing = null;
     lastRateLimit = {};
     constructor(options) {
-        this.oauth = new OAuth(options);
+        /* Sin `clientId` no hay a quién identificar ante el Authorization Server:
+           este cliente no tiene grant propio y no puede tener ceremonia. */
+        this.oauth = options.clientId ? new OAuth(options) : null;
         this.baseUrl = options.baseUrl.replace(/\/+$/, '');
         this.doFetch = options.fetch ?? globalThis.fetch;
         this.store = options.tokens;
@@ -38,6 +47,63 @@ export class PimiaClient {
         this.maxRetryDelayMs = options.maxRetryDelayMs ?? 30_000;
         this.extraHeaders = options.headers ?? {};
     }
+    /**
+     * 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) {
+        if (options.accessToken.trim() === '') {
+            /* Antes de construir nada: un cliente con el token vacío llamaría igual y
+               el 401 llegaría desde Pimia, que es tarde y confuso — parece un token
+               caducado y es un token que nunca hubo. */
+            throw new NotAuthenticatedError('El token prestado está vacío: no hay nada que reenviar. Comprueba la cabecera ' +
+                '`Authorization` de la petición que atiendes.');
+        }
+        return new PimiaClient({
+            baseUrl: options.baseUrl,
+            // Vacíos: es lo que dice «este cliente no tiene grant propio», y lo que
+            // deja `oauth` a null.
+            clientId: '',
+            redirectUri: '',
+            fetch: options.fetch,
+            tokens: new BorrowedTokenStore(options.accessToken),
+            headers: options.headers,
+            maxRateLimitRetries: options.maxRateLimitRetries,
+            maxRetryDelayMs: options.maxRetryDelayMs,
+        });
+    }
     /** Cabeceras `X-RateLimit-*` de la última respuesta. */
     get rateLimit() {
         return { ...this.lastRateLimit };
@@ -294,6 +360,142 @@ export class PimiaClient {
             adjust: (itemId, body, options) => this.post(`/items/${itemId}/stock-adjustments`, body, options),
         };
     }
+    /**
+     * 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() {
+        return {
+            /**
+             * 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, options) => this.post('/opportunities', body, options),
+        };
+    }
+    /**
+     * 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() {
+        return {
+            /**
+             * 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) => this.get('/crm/assignable-users', undefined, options),
+        };
+    }
+    /**
+     * 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() {
+        return {
+            /** El arranque entero, sin envolver. */
+            get: (options) => this.get('/bootstrap', undefined, options),
+            /**
+             * 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: async (options) => {
+                const body = await this.get('/bootstrap', undefined, options);
+                const id = body.current_company?.id;
+                return typeof id === 'number' ? id : 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: async (options) => {
+                const body = await this.get('/bootstrap', undefined, options);
+                const currency = body.current_company_currency;
+                if (!currency || typeof currency.code !== 'string')
+                    return null;
+                return {
+                    code: currency.code,
+                    precision: typeof currency.precision === 'number' ? currency.precision : 2,
+                };
+            },
+        };
+    }
     get(path, query, options) {
         return this.request(path, { ...options, method: 'GET', query });
     }
@@ -462,6 +664,14 @@ export class PimiaClient {
     async refreshTokens(current) {
         if (this.refreshing)
             return this.refreshing;
+        if (this.oauth === null) {
+            /* Token prestado: no hay grant propio con el que refrescar. Hoy no se
+               llega aquí —sin `refreshToken` el 401 sube tal cual—, y el guardia está
+               para que el día que ese camino cambie el error diga lo que pasa en vez
+               de reventar contra un `null`. */
+            throw new UnauthorizedError(401, 'Este cliente usa un token prestado y no puede refrescarlo: pide uno nuevo a ' +
+                'quien te lo prestó.', null);
+        }
         if (!current.refreshToken) {
             throw new UnauthorizedError(401, 'El access token caducó y no hay refresh token: vuelve a pedir autorización al usuario.', null);
         }

package/dist/errors.d.ts

@@ -32,6 +32,17 @@ export declare class MissingScopeError extends ForbiddenError {
     readonly scope: string;
     constructor(scope: string, status: number, message: string, body: unknown, requestId?: string);
 }
+/**
+ * 403 del plano central (`token_sin_habilidad`): al token personal le falta
+ * la habilidad del plano al que llama. `ability` viene del propio cuerpo
+ * (`required_ability`): `central` para invitaciones, patrocinio y traspaso;
+ * `desarrollador` para `/desarrollador/*`. No se arregla reintentando: hay
+ * que acuñar el token con esa habilidad.
+ */
+export declare class MissingAbilityError extends ForbiddenError {
+    readonly ability: string;
+    constructor(ability: string, status: number, message: string, body: unknown, requestId?: string);
+}
 export declare class NotFoundError extends PimiaApiError {
 }
 /** 422: validación de negocio. `errors` es el mapa campo → mensajes. */

package/dist/errors.js

@@ -28,6 +28,9 @@ export class PimiaApiError extends PimiaError {
             const scope = scopeFrom(message);
             if (scope)
                 return new MissingScopeError(scope, status, message, body, requestId);
+            const ability = abilityFrom(body);
+            if (ability)
+                return new MissingAbilityError(ability, status, message, body, requestId);
             return new ForbiddenError(status, message, body, requestId);
         }
         if (status === 422) {
@@ -63,6 +66,20 @@ export class MissingScopeError extends ForbiddenError {
         this.scope = scope;
     }
 }
+/**
+ * 403 del plano central (`token_sin_habilidad`): al token personal le falta
+ * la habilidad del plano al que llama. `ability` viene del propio cuerpo
+ * (`required_ability`): `central` para invitaciones, patrocinio y traspaso;
+ * `desarrollador` para `/desarrollador/*`. No se arregla reintentando: hay
+ * que acuñar el token con esa habilidad.
+ */
+export class MissingAbilityError extends ForbiddenError {
+    ability;
+    constructor(ability, status, message, body, requestId) {
+        super(status, message, body, requestId);
+        this.ability = ability;
+    }
+}
 export class NotFoundError extends PimiaApiError {
 }
 /** 422: validación de negocio. `errors` es el mapa campo → mensajes. */
@@ -187,3 +204,10 @@ function duplicateExternalRefFrom(body) {
 function scopeFrom(message) {
     return /Token lacks the (\S+) scope/.exec(message)?.[1];
 }
+/** `required_ability` del 403 `token_sin_habilidad` del plano central. */
+function abilityFrom(body) {
+    const b = body;
+    if (b?.error !== 'token_sin_habilidad')
+        return undefined;
+    return typeof b.required_ability === 'string' && b.required_ability !== '' ? b.required_ability : undefined;
+}

package/dist/index.d.ts

@@ -6,12 +6,14 @@
  * salen los tipos de `./api`.
  */
 export { PimiaClient, toFormData } from './client.js';
-export type { ContractRequest, ContractResource, CustomerRequest, CustomerResource, EstimateResource, EstimatesRequest, InvoiceResource, InvoicesRequest, ItemWarehouseStockResource, PimiaClientOptions, RateLimit, ReadOptions, RequestOptions, ResourceEnvelope, ResponseMeta, ResponseWithMeta, StockCountRequest, StockCountResource, WarehouseRequest, WarehouseResource, WriteOptions, } from './client.js';
+export type { BorrowedTokenOptions, ContractRequest, ContractResource, CustomerRequest, CustomerResource, EstimateResource, EstimatesRequest, InvoiceResource, InvoicesRequest, ItemWarehouseStockResource, OpportunityRequest, OpportunityResource, PimiaClientOptions, RateLimit, ReadOptions, RequestOptions, ResourceEnvelope, ResponseMeta, ResponseWithMeta, StockCountRequest, StockCountResource, WarehouseRequest, WarehouseResource, WriteOptions, } from './client.js';
+export { PimiaCentralClient } from './central.js';
+export type { ActivacionMayoristaRequest, CatalogoDelIntegradorRequest, CentralRequestOptions, CentralResponseMeta, CentralResponseWithMeta, IntegradorDominioRequest, IntegradorTokenRequest, PimiaCentralClientOptions, SponsorshipRequest, BillingPortalRequest, TenantInvitationRequest, TransferOwnershipRequest, } from './central.js';
 export { OAuth, createPkceChallenge, createState } from './oauth.js';
 export type { AuthorizationServerMetadata, AuthorizeUrlOptions, OAuthConfig, PkceChallenge, } from './oauth.js';
-export { MemoryTokenStore, isExpired, tokenSetFromResponse } from './tokens.js';
+export { BorrowedTokenStore, MemoryTokenStore, isExpired, tokenSetFromResponse } from './tokens.js';
 export type { TokenSet, TokenStore } from './tokens.js';
-export { DuplicateExternalRefError, ForbiddenError, MissingScopeError, NotAuthenticatedError, NotFoundError, OAuthError, PimiaApiError, PimiaError, RateLimitError, UnauthorizedError, ValidationError, } from './errors.js';
+export { DuplicateExternalRefError, ForbiddenError, MissingAbilityError, MissingScopeError, NotAuthenticatedError, NotFoundError, OAuthError, PimiaApiError, PimiaError, RateLimitError, UnauthorizedError, ValidationError, } from './errors.js';
 export { WEBHOOK_DEFAULT_TOLERANCE_SECONDS, WEBHOOK_EVENTS, WEBHOOK_HEADERS, WEBHOOK_SIGNATURE_VERSION, WebhookVerificationError, isWebhookEvent, signWebhook, verifyWebhook, } from './webhooks.js';
 export type { ApprovalDecidedPayload, AppRevokedPayload, CustomerPayload, EstimateAcceptedPayload, ExternalRef, InvoiceCreatedPayload, InvoicePaidPayload, InvoiceReceivedPayload, IsoDateTime, KnownWebhook, PimiaWebhook, SignWebhookOptions, UnknownWebhook, VerifyWebhookOptions, WebhookBodyInput, WebhookEvent, WebhookHeadersInput, WebhookPayloads, WebhookVerificationReason, } from './webhooks.js';
 /** Scopes granulares del catálogo de Pimia (paso 4). Pide siempre lo mínimo. */
@@ -52,6 +54,24 @@ export declare const SCOPES: {
     readonly workRead: "work:read";
     /** Crear y modificar obras y proyectos, tareas y partes de horas. */
     readonly workWrite: "work:write";
+    /**
+     * Leer la campana: tareas vencidas, ausencias y correcciones de fichaje.
+     *
+     * ⚠️ Desde la 0.21.0 `/notifications` tiene dominio propio y `crm:read` ya
+     * no lo alcanza (núcleo galeote/factSaas#677). Lo que la campana lleva lo
+     * emiten los módulos de Trabajo y de Personal, no el embudo comercial.
+     */
+    readonly notificationsRead: "notifications:read";
+    /** Marcar avisos como leídos y borrarlos. */
+    readonly notificationsWrite: "notifications:write";
+    /**
+     * Leer el catálogo de apps integradas y qué tiene instalada la empresa
+     * (`/apps`, `/apps/{slug}`, `/apps/{slug}/config`). Entra en la 0.22.0 con
+     * la fase 1 de apps integradas del núcleo (galeote/factSaas#697-#702).
+     */
+    readonly appsRead: "apps:read";
+    /** Instalar y desinstalar una app en la empresa, ajustar su configuración y acuñar su credencial de entrada. */
+    readonly appsWrite: "apps:write";
     readonly agendaRead: "agenda:read";
     readonly agendaWrite: "agenda:write";
     readonly reportsRead: "reports:read";

package/dist/index.js

@@ -6,9 +6,10 @@
  * salen los tipos de `./api`.
  */
 export { PimiaClient, toFormData } from './client.js';
+export { PimiaCentralClient } from './central.js';
 export { OAuth, createPkceChallenge, createState } from './oauth.js';
-export { MemoryTokenStore, isExpired, tokenSetFromResponse } from './tokens.js';
-export { DuplicateExternalRefError, ForbiddenError, MissingScopeError, NotAuthenticatedError, NotFoundError, OAuthError, PimiaApiError, PimiaError, RateLimitError, UnauthorizedError, ValidationError, } from './errors.js';
+export { BorrowedTokenStore, MemoryTokenStore, isExpired, tokenSetFromResponse } from './tokens.js';
+export { DuplicateExternalRefError, ForbiddenError, MissingAbilityError, MissingScopeError, NotAuthenticatedError, NotFoundError, OAuthError, PimiaApiError, PimiaError, RateLimitError, UnauthorizedError, ValidationError, } from './errors.js';
 export { WEBHOOK_DEFAULT_TOLERANCE_SECONDS, WEBHOOK_EVENTS, WEBHOOK_HEADERS, WEBHOOK_SIGNATURE_VERSION, WebhookVerificationError, isWebhookEvent, signWebhook, verifyWebhook, } from './webhooks.js';
 /** Scopes granulares del catálogo de Pimia (paso 4). Pide siempre lo mínimo. */
 export const SCOPES = {
@@ -48,6 +49,24 @@ export const SCOPES = {
     workRead: 'work:read',
     /** Crear y modificar obras y proyectos, tareas y partes de horas. */
     workWrite: 'work:write',
+    /**
+     * Leer la campana: tareas vencidas, ausencias y correcciones de fichaje.
+     *
+     * ⚠️ Desde la 0.21.0 `/notifications` tiene dominio propio y `crm:read` ya
+     * no lo alcanza (núcleo galeote/factSaas#677). Lo que la campana lleva lo
+     * emiten los módulos de Trabajo y de Personal, no el embudo comercial.
+     */
+    notificationsRead: 'notifications:read',
+    /** Marcar avisos como leídos y borrarlos. */
+    notificationsWrite: 'notifications:write',
+    /**
+     * Leer el catálogo de apps integradas y qué tiene instalada la empresa
+     * (`/apps`, `/apps/{slug}`, `/apps/{slug}/config`). Entra en la 0.22.0 con
+     * la fase 1 de apps integradas del núcleo (galeote/factSaas#697-#702).
+     */
+    appsRead: 'apps:read',
+    /** Instalar y desinstalar una app en la empresa, ajustar su configuración y acuñar su credencial de entrada. */
+    appsWrite: 'apps:write',
     agendaRead: 'agenda:read',
     agendaWrite: 'agenda:write',
     reportsRead: 'reports:read',

package/dist/tokens.d.ts

@@ -20,6 +20,12 @@ export interface TokenSet {
     expiresAt?: number;
     scope?: string;
     tokenType?: string;
+    /**
+     * A qué instancia pertenece el token. Lo dice el canje del AS del ÁPICE
+     * (`tenant_id`), donde la app no lo sabe por el host; el AS de un tenant no
+     * lo manda (ahí el host ya lo dice).
+     */
+    tenantId?: string;
 }
 export interface TokenStore {
     load(): Promise<TokenSet | null> | TokenSet | null;
@@ -34,6 +40,44 @@ export declare class MemoryTokenStore implements TokenStore {
     save(tokens: TokenSet): void;
     clear(): void;
 }
+/**
+ * El «store» de un token que NO es tuyo.
+ *
+ * ── Para qué existe ─────────────────────────────────────────────────────────
+ *
+ * Hay integraciones que no poseen ningún grant y **no deben poseerlo**: un
+ * servicio al que el front le manda, en cada petición, el `Authorization` del
+ * usuario que ha entrado en Pimia, y que lo reenvía tal cual. La consecuencia
+ * buena es que Pimia sigue decidiendo los permisos: ese servicio no puede darle
+ * a nadie más de lo que su token ya le daba, y no hay una credencial propia que
+ * auditar aparte.
+ *
+ * Un token prestado **no trae refresh** —el refresh es del dueño del grant— y
+ * dura lo que dure la petición. Eso hace que todo lo que este SDK protege del
+ * {@link TokenStore} de verdad no aplique aquí: no hay rotación que persistir,
+ * ni reuse que evitar, ni candado por usuario que sostener.
+ *
+ * ── Por qué `save()` REVIENTA en vez de callar ──────────────────────────────
+ *
+ * Porque llegar ahí significaría que el cliente ha creído refrescar un token
+ * ajeno. Hoy no puede pasar por construcción —sin `refreshToken` el 401 sube
+ * tal cual en vez de disparar un refresco—, y justo por eso el día que alguien
+ * cambie ese camino conviene que se entere aquí, con el nombre de la clase
+ * dentro, y no en producción como un grant de otro revocado en cascada.
+ *
+ * No se construye a mano: sale de `PimiaClient.withBorrowedToken()`.
+ */
+export declare class BorrowedTokenStore implements TokenStore {
+    private readonly accessToken;
+    constructor(accessToken: string);
+    load(): TokenSet;
+    save(): void;
+    /**
+     * No-op, y no es pereza: no hay nada que borrar. El token vive en la petición
+     * que lo trajo y muere con ella.
+     */
+    clear(): void;
+}
 /** ¿Caduca dentro de `skewSeconds`? Sin expiresAt se asume que sigue vivo. */
 export declare function isExpired(tokens: TokenSet, skewSeconds?: number, now?: number): boolean;
 /** Respuesta cruda del token endpoint → TokenSet. */
@@ -43,4 +87,5 @@ export declare function tokenSetFromResponse(payload: {
     expires_in?: number;
     scope?: string;
     token_type?: string;
+    tenant_id?: string;
 }, now?: number): TokenSet;

package/dist/tokens.js

@@ -12,6 +12,7 @@
  * procesos pueden refrescar a la vez, serializa el refresh — dos refrescos
  * concurrentes con el mismo token son, para el servidor, un reuse.
  */
+import { PimiaError } from './errors.js';
 /** Store de memoria: vale para scripts y tests, NO para producción con varios procesos. */
 export class MemoryTokenStore {
     tokens;
@@ -28,6 +29,55 @@ export class MemoryTokenStore {
         this.tokens = null;
     }
 }
+/**
+ * El «store» de un token que NO es tuyo.
+ *
+ * ── Para qué existe ─────────────────────────────────────────────────────────
+ *
+ * Hay integraciones que no poseen ningún grant y **no deben poseerlo**: un
+ * servicio al que el front le manda, en cada petición, el `Authorization` del
+ * usuario que ha entrado en Pimia, y que lo reenvía tal cual. La consecuencia
+ * buena es que Pimia sigue decidiendo los permisos: ese servicio no puede darle
+ * a nadie más de lo que su token ya le daba, y no hay una credencial propia que
+ * auditar aparte.
+ *
+ * Un token prestado **no trae refresh** —el refresh es del dueño del grant— y
+ * dura lo que dure la petición. Eso hace que todo lo que este SDK protege del
+ * {@link TokenStore} de verdad no aplique aquí: no hay rotación que persistir,
+ * ni reuse que evitar, ni candado por usuario que sostener.
+ *
+ * ── Por qué `save()` REVIENTA en vez de callar ──────────────────────────────
+ *
+ * Porque llegar ahí significaría que el cliente ha creído refrescar un token
+ * ajeno. Hoy no puede pasar por construcción —sin `refreshToken` el 401 sube
+ * tal cual en vez de disparar un refresco—, y justo por eso el día que alguien
+ * cambie ese camino conviene que se entere aquí, con el nombre de la clase
+ * dentro, y no en producción como un grant de otro revocado en cascada.
+ *
+ * No se construye a mano: sale de `PimiaClient.withBorrowedToken()`.
+ */
+export class BorrowedTokenStore {
+    accessToken;
+    constructor(accessToken) {
+        this.accessToken = accessToken;
+    }
+    load() {
+        /* Sin `refreshToken` y sin `expiresAt`: los dos son del dueño del grant.
+           Sin expiración el cliente no intenta refrescar por su cuenta, y sin
+           refresh un 401 sube tal cual — que es lo correcto: quien tiene que
+           conseguir otro token es quien te prestó éste. */
+        return { accessToken: this.accessToken };
+    }
+    save() {
+        throw new PimiaError('Este cliente usa un token prestado: no hay grant propio que rotar ni nada que ' +
+            'persistir. Si has llegado aquí, alguien ha intentado refrescar el token de otro.');
+    }
+    /**
+     * No-op, y no es pereza: no hay nada que borrar. El token vive en la petición
+     * que lo trajo y muere con ella.
+     */
+    clear() { }
+}
 /** ¿Caduca dentro de `skewSeconds`? Sin expiresAt se asume que sigue vivo. */
 export function isExpired(tokens, skewSeconds = 60, now = Date.now()) {
     if (tokens.expiresAt === undefined)
@@ -42,5 +92,8 @@ export function tokenSetFromResponse(payload, now = Date.now()) {
         expiresAt: payload.expires_in ? now + payload.expires_in * 1000 : undefined,
         scope: payload.scope,
         tokenType: payload.token_type ?? 'bearer',
+        ...(typeof payload.tenant_id === 'string' && payload.tenant_id !== ''
+            ? { tenantId: payload.tenant_id }
+            : {}),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pimia/sdk",
-  "version": "0.20.0",
+  "version": "0.27.0",
   "description": "Cliente TypeScript de la API de Pimia para apps de partner: OAuth con PKCE, rotación de refresh persistida, reintentos de rate limit y tipos generados del OpenAPI.",
   "license": "MIT",
   "author": "Pimia (https://pimia.es)",
@@ -28,6 +28,10 @@
     "./api": {
       "types": "./dist/api.d.ts",
       "import": "./dist/api.js"
+    },
+    "./central-api": {
+      "types": "./dist/central-api.d.ts",
+      "import": "./dist/central-api.js"
     }
   },
   "files": [