@pimia/sdk 0.1.0

package/dist/api.js

@@ -0,0 +1,5 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export {};

package/dist/client.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Cliente HTTP de la API de Pimia.
+ *
+ * Lo que resuelve por ti, que es justo donde se equivoca una integración
+ * escrita a mano:
+ *
+ *  - **rotación de refresh**: refresca al detectar caducidad o un 401, y
+ *    persiste el TokenSet nuevo en tu TokenStore antes de reintentar;
+ *  - **un solo refresh a la vez** dentro del proceso: dos refrescos paralelos
+ *    con el mismo token son un reuse para el servidor, y un reuse revoca el
+ *    grant entero. Entre procesos, esto no basta: usa un store compartido con
+ *    su propio candado;
+ *  - **429**: respeta `Retry-After` y reintenta con espera acotada;
+ *  - **errores tipados**: MissingScopeError trae el scope exacto que falta.
+ */
+import { OAuth, type OAuthConfig } from './oauth.js';
+import { type TokenStore } from './tokens.js';
+export interface PimiaClientOptions extends OAuthConfig {
+    tokens: TokenStore;
+    /** Segundos de margen para refrescar antes de que caduque (default 60). */
+    expirySkewSeconds?: number;
+    /** Reintentos ante 429 (default 2). */
+    maxRateLimitRetries?: number;
+    /** Espera máxima por reintento de 429, en ms (default 30 000). */
+    maxRetryDelayMs?: number;
+    /** Cabeceras añadidas a cada petición (p. ej. un User-Agent propio). */
+    headers?: Record<string, string>;
+}
+export interface RequestOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** Query string. Los `undefined`/`null` se omiten; los arrays se repiten. */
+    query?: Record<string, string | number | boolean | undefined | null | Array<string | number>>;
+    /** Cuerpo JSON. */
+    body?: unknown;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+/** Cabeceras de rate limit que devuelve la API en cada respuesta. */
+export interface RateLimit {
+    limit?: number;
+    remaining?: number;
+}
+export declare class PimiaClient {
+    readonly oauth: OAuth;
+    private readonly baseUrl;
+    private readonly doFetch;
+    private readonly store;
+    private readonly skew;
+    private readonly maxRateLimitRetries;
+    private readonly maxRetryDelayMs;
+    private readonly extraHeaders;
+    /** Refresco en vuelo: cualquier petición que llegue mientras tanto lo espera. */
+    private refreshing;
+    private lastRateLimit;
+    constructor(options: PimiaClientOptions);
+    /** Cabeceras `X-RateLimit-*` de la última respuesta. */
+    get rateLimit(): RateLimit;
+    get invoices(): {
+        list: (query?: RequestOptions["query"]) => Promise<unknown>;
+        get: (id: number | string) => Promise<unknown>;
+        create: (body: unknown) => Promise<unknown>;
+        update: (id: number | string, body: unknown) => Promise<unknown>;
+    };
+    get customers(): {
+        list: (query?: RequestOptions["query"]) => Promise<unknown>;
+        get: (id: number | string) => Promise<unknown>;
+        create: (body: unknown) => Promise<unknown>;
+        update: (id: number | string, body: unknown) => Promise<unknown>;
+    };
+    get estimates(): {
+        list: (query?: RequestOptions["query"]) => Promise<unknown>;
+        get: (id: number | string) => Promise<unknown>;
+        create: (body: unknown) => Promise<unknown>;
+    };
+    get<T = unknown>(path: string, query?: RequestOptions['query']): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown): Promise<T>;
+    put<T = unknown>(path: string, body?: unknown): Promise<T>;
+    patch<T = unknown>(path: string, body?: unknown): Promise<T>;
+    delete<T = unknown>(path: string): Promise<T>;
+    /**
+     * Petición cruda contra `/api/v1`. `path` puede llevar el prefijo o no:
+     * `/invoices` y `/api/v1/invoices` son lo mismo.
+     */
+    request<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+    private currentTokens;
+    /**
+     * Refresca UNA sola vez aunque lo pidan N peticiones en paralelo, y persiste
+     * el resultado. Sin esta serialización, dos peticiones caducadas a la vez
+     * canjearían el mismo refresh y el servidor lo leería como reuse → grant
+     * revocado en cascada.
+     */
+    private refreshTokens;
+    private urlFor;
+    private captureRateLimit;
+    private retryDelay;
+}

package/dist/client.js

@@ -0,0 +1,232 @@
+/**
+ * Cliente HTTP de la API de Pimia.
+ *
+ * Lo que resuelve por ti, que es justo donde se equivoca una integración
+ * escrita a mano:
+ *
+ *  - **rotación de refresh**: refresca al detectar caducidad o un 401, y
+ *    persiste el TokenSet nuevo en tu TokenStore antes de reintentar;
+ *  - **un solo refresh a la vez** dentro del proceso: dos refrescos paralelos
+ *    con el mismo token son un reuse para el servidor, y un reuse revoca el
+ *    grant entero. Entre procesos, esto no basta: usa un store compartido con
+ *    su propio candado;
+ *  - **429**: respeta `Retry-After` y reintenta con espera acotada;
+ *  - **errores tipados**: MissingScopeError trae el scope exacto que falta.
+ */
+import { NotAuthenticatedError, OAuthError, PimiaApiError, RateLimitError, UnauthorizedError, } from './errors.js';
+import { OAuth } from './oauth.js';
+import { isExpired } from './tokens.js';
+export class PimiaClient {
+    oauth;
+    baseUrl;
+    doFetch;
+    store;
+    skew;
+    maxRateLimitRetries;
+    maxRetryDelayMs;
+    extraHeaders;
+    /** Refresco en vuelo: cualquier petición que llegue mientras tanto lo espera. */
+    refreshing = null;
+    lastRateLimit = {};
+    constructor(options) {
+        this.oauth = new OAuth(options);
+        this.baseUrl = options.baseUrl.replace(/\/+$/, '');
+        this.doFetch = options.fetch ?? globalThis.fetch;
+        this.store = options.tokens;
+        this.skew = options.expirySkewSeconds ?? 60;
+        this.maxRateLimitRetries = options.maxRateLimitRetries ?? 2;
+        this.maxRetryDelayMs = options.maxRetryDelayMs ?? 30_000;
+        this.extraHeaders = options.headers ?? {};
+    }
+    /** Cabeceras `X-RateLimit-*` de la última respuesta. */
+    get rateLimit() {
+        return { ...this.lastRateLimit };
+    }
+    get invoices() {
+        return {
+            list: (query) => this.get('/invoices', query),
+            get: (id) => this.get(`/invoices/${id}`),
+            create: (body) => this.post('/invoices', body),
+            update: (id, body) => this.put(`/invoices/${id}`, body),
+        };
+    }
+    get customers() {
+        return {
+            list: (query) => this.get('/customers', query),
+            get: (id) => this.get(`/customers/${id}`),
+            create: (body) => this.post('/customers', body),
+            update: (id, body) => this.put(`/customers/${id}`, body),
+        };
+    }
+    get estimates() {
+        return {
+            list: (query) => this.get('/estimates', query),
+            get: (id) => this.get(`/estimates/${id}`),
+            create: (body) => this.post('/estimates', body),
+        };
+    }
+    get(path, query) {
+        return this.request(path, { method: 'GET', query });
+    }
+    post(path, body) {
+        return this.request(path, { method: 'POST', body });
+    }
+    put(path, body) {
+        return this.request(path, { method: 'PUT', body });
+    }
+    patch(path, body) {
+        return this.request(path, { method: 'PATCH', body });
+    }
+    delete(path) {
+        return this.request(path, { method: 'DELETE' });
+    }
+    /**
+     * Petición cruda contra `/api/v1`. `path` puede llevar el prefijo o no:
+     * `/invoices` y `/api/v1/invoices` son lo mismo.
+     */
+    async request(path, options = {}) {
+        let tokens = await this.currentTokens();
+        if (isExpired(tokens, this.skew)) {
+            tokens = await this.refreshTokens(tokens);
+        }
+        let attempt = 0;
+        let refreshedOn401 = false;
+        for (;;) {
+            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 ${tokens.accessToken}`,
+                },
+                body: options.body === undefined ? undefined : JSON.stringify(options.body),
+                signal: options.signal,
+            });
+            this.captureRateLimit(response);
+            if (response.ok) {
+                return (await parseBody(response));
+            }
+            const body = await parseBody(response);
+            const requestId = response.headers.get('x-request-id') ?? undefined;
+            // 401: un intento de refresco y se reintenta. Si el usuario revocó la
+            // app, el refresh también falla y el error sube tal cual — hay que
+            // volver a pedirle autorización.
+            if (response.status === 401 && !refreshedOn401 && tokens.refreshToken) {
+                refreshedOn401 = true;
+                tokens = await this.refreshTokens(tokens);
+                continue;
+            }
+            if (response.status === 429 && attempt < this.maxRateLimitRetries) {
+                attempt++;
+                await sleep(this.retryDelay(response, attempt));
+                continue;
+            }
+            if (response.status === 429) {
+                throw new RateLimitError(retryAfterSeconds(response), 429, 'Rate limit alcanzado', body, requestId);
+            }
+            throw PimiaApiError.from(response.status, body, requestId);
+        }
+    }
+    async currentTokens() {
+        const tokens = await this.store.load();
+        if (!tokens?.accessToken) {
+            throw new NotAuthenticatedError('No hay tokens en el TokenStore: completa el flujo de autorización antes de llamar a la API.');
+        }
+        return tokens;
+    }
+    /**
+     * Refresca UNA sola vez aunque lo pidan N peticiones en paralelo, y persiste
+     * el resultado. Sin esta serialización, dos peticiones caducadas a la vez
+     * canjearían el mismo refresh y el servidor lo leería como reuse → grant
+     * revocado en cascada.
+     */
+    async refreshTokens(current) {
+        if (this.refreshing)
+            return this.refreshing;
+        if (!current.refreshToken) {
+            throw new UnauthorizedError(401, 'El access token caducó y no hay refresh token: vuelve a pedir autorización al usuario.', null);
+        }
+        this.refreshing = (async () => {
+            try {
+                const rotated = await this.oauth.refresh(current.refreshToken);
+                await this.store.save(rotated);
+                return rotated;
+            }
+            catch (error) {
+                // Un refresco fallido significa siempre lo mismo para quien llama:
+                // este grant ya no vale y hay que volver a pedir autorización al
+                // usuario (revocó la app, caducó el refresh, o se reusó uno rotado).
+                // Se traduce a UnauthorizedError para que un solo `catch` cubra el
+                // caso: sin esto, el error del token endpoint (OAuthError
+                // invalid_grant) se colaba por debajo del contrato del cliente —
+                // detectado en el e2e real contra dev al revocar desde el panel.
+                if (error instanceof OAuthError) {
+                    const unauthorized = new UnauthorizedError(401, `No se pudo refrescar el token (${error.error}): vuelve a pedir autorización al usuario.`, null);
+                    unauthorized.cause = error;
+                    throw unauthorized;
+                }
+                throw error;
+            }
+            finally {
+                this.refreshing = null;
+            }
+        })();
+        return this.refreshing;
+    }
+    urlFor(path, query) {
+        const clean = path.replace(/^\/+/, '').replace(/^api\/v1\/?/, '');
+        const url = new URL(`${this.baseUrl}/api/v1/${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();
+    }
+    captureRateLimit(response) {
+        const limit = response.headers.get('x-ratelimit-limit');
+        const remaining = response.headers.get('x-ratelimit-remaining');
+        this.lastRateLimit = {
+            limit: limit === null ? undefined : Number(limit),
+            remaining: remaining === null ? undefined : Number(remaining),
+        };
+    }
+    retryDelay(response, attempt) {
+        const retryAfter = retryAfterSeconds(response);
+        const base = retryAfter !== undefined ? retryAfter * 1000 : 2 ** attempt * 500;
+        return Math.min(base, this.maxRetryDelayMs);
+    }
+}
+function retryAfterSeconds(response) {
+    const header = response.headers.get('retry-after');
+    if (header === null)
+        return undefined;
+    const seconds = Number(header);
+    return Number.isFinite(seconds) ? seconds : undefined;
+}
+async function parseBody(response) {
+    if (response.status === 204)
+        return null;
+    const text = await response.text();
+    if (text === '')
+        return null;
+    const type = response.headers.get('content-type') ?? '';
+    if (!type.includes('json'))
+        return text;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/errors.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Errores del SDK. La API de Pimia tiene un contrato de errores estable
+ * (docs/guia-integradores.md §7) y merece tipos propios: un 403 por scope no
+ * se arregla reintentando, un 422 tampoco, y un 429 sí.
+ */
+export declare class PimiaError extends Error {
+    constructor(message: string);
+}
+/** Respuesta HTTP de error de la API. */
+export declare class PimiaApiError extends PimiaError {
+    readonly status: number;
+    readonly body: unknown;
+    readonly requestId?: string | undefined;
+    constructor(status: number, message: string, body: unknown, requestId?: string | undefined);
+    static from(status: number, body: unknown, requestId?: string): PimiaApiError;
+}
+/**
+ * 401: el access token no vale (caducado, revocado o el usuario retiró el
+ * acceso desde Ajustes → Apps conectadas). El cliente intenta refrescar una
+ * vez por su cuenta; si vuelve a salir, hay que re-autorizar al usuario.
+ */
+export declare class UnauthorizedError extends PimiaApiError {
+}
+export declare class ForbiddenError extends PimiaApiError {
+}
+/**
+ * 403 del api-guard: al token le falta un scope. `scope` viene parseado del
+ * mensaje («Token lacks the invoices:write scope») para que el partner sepa
+ * exactamente qué pedir en el próximo authorize.
+ */
+export declare class MissingScopeError extends ForbiddenError {
+    readonly scope: string;
+    constructor(scope: 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. */
+export declare class ValidationError extends PimiaApiError {
+    get errors(): Record<string, string[]>;
+}
+/** 429: pasado el rate limit. `retryAfter` en segundos si la API lo dijo. */
+export declare class RateLimitError extends PimiaApiError {
+    readonly retryAfter: number | undefined;
+    constructor(retryAfter: number | undefined, status: number, message: string, body: unknown, requestId?: string);
+}
+/** Error del flujo OAuth (token endpoint, revocación). */
+export declare class OAuthError extends PimiaError {
+    readonly error: string;
+    readonly description?: string | undefined;
+    constructor(error: string, description?: string | undefined);
+}
+/**
+ * No hay tokens con los que trabajar (o se perdieron). Distinto de un 401:
+ * aquí ni se intentó la llamada.
+ */
+export declare class NotAuthenticatedError extends PimiaError {
+}

package/dist/errors.js

@@ -0,0 +1,109 @@
+/**
+ * Errores del SDK. La API de Pimia tiene un contrato de errores estable
+ * (docs/guia-integradores.md §7) y merece tipos propios: un 403 por scope no
+ * se arregla reintentando, un 422 tampoco, y un 429 sí.
+ */
+export class PimiaError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+/** Respuesta HTTP de error de la API. */
+export class PimiaApiError extends PimiaError {
+    status;
+    body;
+    requestId;
+    constructor(status, message, body, requestId) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.requestId = requestId;
+    }
+    static from(status, body, requestId) {
+        const message = messageFrom(body) ?? `HTTP ${status}`;
+        if (status === 401)
+            return new UnauthorizedError(status, message, body, requestId);
+        if (status === 403) {
+            const scope = scopeFrom(message);
+            if (scope)
+                return new MissingScopeError(scope, status, message, body, requestId);
+            return new ForbiddenError(status, message, body, requestId);
+        }
+        if (status === 422)
+            return new ValidationError(status, message, body, requestId);
+        if (status === 404)
+            return new NotFoundError(status, message, body, requestId);
+        return new PimiaApiError(status, message, body, requestId);
+    }
+}
+/**
+ * 401: el access token no vale (caducado, revocado o el usuario retiró el
+ * acceso desde Ajustes → Apps conectadas). El cliente intenta refrescar una
+ * vez por su cuenta; si vuelve a salir, hay que re-autorizar al usuario.
+ */
+export class UnauthorizedError extends PimiaApiError {
+}
+export class ForbiddenError extends PimiaApiError {
+}
+/**
+ * 403 del api-guard: al token le falta un scope. `scope` viene parseado del
+ * mensaje («Token lacks the invoices:write scope») para que el partner sepa
+ * exactamente qué pedir en el próximo authorize.
+ */
+export class MissingScopeError extends ForbiddenError {
+    scope;
+    constructor(scope, status, message, body, requestId) {
+        super(status, message, body, requestId);
+        this.scope = scope;
+    }
+}
+export class NotFoundError extends PimiaApiError {
+}
+/** 422: validación de negocio. `errors` es el mapa campo → mensajes. */
+export class ValidationError extends PimiaApiError {
+    get errors() {
+        const body = this.body;
+        return body?.errors ?? {};
+    }
+}
+/** 429: pasado el rate limit. `retryAfter` en segundos si la API lo dijo. */
+export class RateLimitError extends PimiaApiError {
+    retryAfter;
+    constructor(retryAfter, status, message, body, requestId) {
+        super(status, message, body, requestId);
+        this.retryAfter = retryAfter;
+    }
+}
+/** Error del flujo OAuth (token endpoint, revocación). */
+export class OAuthError extends PimiaError {
+    error;
+    description;
+    constructor(error, description) {
+        super(description ? `${error}: ${description}` : error);
+        this.error = error;
+        this.description = description;
+    }
+}
+/**
+ * No hay tokens con los que trabajar (o se perdieron). Distinto de un 401:
+ * aquí ni se intentó la llamada.
+ */
+export class NotAuthenticatedError extends PimiaError {
+}
+function messageFrom(body) {
+    if (typeof body === 'string' && body !== '')
+        return body;
+    if (body && typeof body === 'object') {
+        const record = body;
+        for (const key of ['message', 'error_description', 'error']) {
+            if (typeof record[key] === 'string' && record[key] !== '')
+                return record[key];
+        }
+    }
+    return undefined;
+}
+/** «Token lacks the invoices:write scope» → `invoices:write`. */
+function scopeFrom(message) {
+    return /Token lacks the (\S+) scope/.exec(message)?.[1];
+}

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @pimia/sdk — cliente TypeScript de la API de Pimia para apps de partner.
+ *
+ * Un tenant = una base URL = un token (modelo un-token-por-tienda). Empieza
+ * por README.md; el contrato completo de endpoints está en el OpenAPI del que
+ * salen los tipos de `./api`.
+ */
+export { PimiaClient } from './client.js';
+export type { PimiaClientOptions, RateLimit, RequestOptions } from './client.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 type { TokenSet, TokenStore } from './tokens.js';
+export { ForbiddenError, MissingScopeError, NotAuthenticatedError, NotFoundError, OAuthError, PimiaApiError, PimiaError, RateLimitError, UnauthorizedError, ValidationError, } from './errors.js';
+/** Scopes granulares del catálogo de Pimia (paso 4). Pide siempre lo mínimo. */
+export declare const SCOPES: {
+    readonly invoicesRead: "invoices:read";
+    readonly invoicesWrite: "invoices:write";
+    readonly estimatesRead: "estimates:read";
+    readonly estimatesWrite: "estimates:write";
+    readonly customersRead: "customers:read";
+    readonly customersWrite: "customers:write";
+    readonly expensesRead: "expenses:read";
+    readonly expensesWrite: "expenses:write";
+    readonly paymentsRead: "payments:read";
+    readonly paymentsWrite: "payments:write";
+    readonly itemsRead: "items:read";
+    readonly itemsWrite: "items:write";
+    readonly bankingRead: "banking:read";
+    readonly bankingWrite: "banking:write";
+    readonly crmRead: "crm:read";
+    readonly crmWrite: "crm:write";
+    readonly agendaRead: "agenda:read";
+    readonly agendaWrite: "agenda:write";
+    readonly reportsRead: "reports:read";
+};
+export type Scope = (typeof SCOPES)[keyof typeof SCOPES];

package/dist/index.js

@@ -0,0 +1,33 @@
+/**
+ * @pimia/sdk — cliente TypeScript de la API de Pimia para apps de partner.
+ *
+ * Un tenant = una base URL = un token (modelo un-token-por-tienda). Empieza
+ * por README.md; el contrato completo de endpoints está en el OpenAPI del que
+ * salen los tipos de `./api`.
+ */
+export { PimiaClient } from './client.js';
+export { OAuth, createPkceChallenge, createState } from './oauth.js';
+export { MemoryTokenStore, isExpired, tokenSetFromResponse } from './tokens.js';
+export { ForbiddenError, MissingScopeError, NotAuthenticatedError, NotFoundError, OAuthError, PimiaApiError, PimiaError, RateLimitError, UnauthorizedError, ValidationError, } from './errors.js';
+/** Scopes granulares del catálogo de Pimia (paso 4). Pide siempre lo mínimo. */
+export const SCOPES = {
+    invoicesRead: 'invoices:read',
+    invoicesWrite: 'invoices:write',
+    estimatesRead: 'estimates:read',
+    estimatesWrite: 'estimates:write',
+    customersRead: 'customers:read',
+    customersWrite: 'customers:write',
+    expensesRead: 'expenses:read',
+    expensesWrite: 'expenses:write',
+    paymentsRead: 'payments:read',
+    paymentsWrite: 'payments:write',
+    itemsRead: 'items:read',
+    itemsWrite: 'items:write',
+    bankingRead: 'banking:read',
+    bankingWrite: 'banking:write',
+    crmRead: 'crm:read',
+    crmWrite: 'crm:write',
+    agendaRead: 'agenda:read',
+    agendaWrite: 'agenda:write',
+    reportsRead: 'reports:read',
+};

package/dist/oauth.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Ceremonia OAuth 2.0 contra el Authorization Server de Pimia.
+ *
+ * Un tenant = un servidor de autorización (`https://{tenant}.pimia.es`), y un
+ * token vale solo para ese tenant (modelo un-token-por-tienda). Todo lo que
+ * hay aquí es de la parte «servidor» de tu app salvo `createPkceChallenge` y
+ * `buildAuthorizeUrl`, que también valen en el navegador.
+ */
+import { type TokenSet } from './tokens.js';
+export interface OAuthConfig {
+    /** Base del tenant, con o sin barra final: `https://acme.pimia.es`. */
+    baseUrl: string;
+    clientId: string;
+    /** Solo clients confidenciales (app server-side). Nunca en el navegador. */
+    clientSecret?: string;
+    redirectUri: string;
+    fetch?: typeof globalThis.fetch;
+}
+export interface PkceChallenge {
+    verifier: string;
+    challenge: string;
+    method: 'S256';
+}
+export interface AuthorizeUrlOptions {
+    /** Scopes granulares: `['invoices:read', 'customers:read']`. Pide lo mínimo. */
+    scopes: string[];
+    state: string;
+    pkce: PkceChallenge;
+}
+/** Metadata del AS (RFC 8414). */
+export interface AuthorizationServerMetadata {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    registration_endpoint?: string;
+    revocation_endpoint?: string;
+    scopes_supported?: string[];
+    grant_types_supported?: string[];
+}
+export declare class OAuth {
+    private readonly config;
+    private readonly baseUrl;
+    private readonly doFetch;
+    constructor(config: OAuthConfig);
+    /** `GET /.well-known/oauth-authorization-server` — útil para no cablear rutas. */
+    metadata(): Promise<AuthorizationServerMetadata>;
+    /**
+     * URL a la que mandas al usuario. Verás la pantalla de consentimiento de
+     * Pimia con los permisos de los scopes que pidas.
+     */
+    buildAuthorizeUrl({ scopes, state, pkce }: AuthorizeUrlOptions): string;
+    /**
+     * Canje del `code` del callback. El código dura 10 minutos y un solo uso.
+     *
+     * Acepta el challenge completo o solo `{ verifier }`: en un flujo real el
+     * verifier se recupera de la sesión del usuario y el challenge ya no hace
+     * falta (lo tiene el servidor, que lo comparará con el hash del verifier).
+     */
+    exchangeCode(code: string, pkce: Pick<PkceChallenge, 'verifier'>): Promise<TokenSet>;
+    /**
+     * Refresco CON ROTACIÓN: el refresh que pasas queda invalidado y el TokenSet
+     * devuelto trae uno nuevo. Persístelo antes de volver a llamar a la API (ver
+     * tokens.ts) — reusar el viejo revoca el grant entero.
+     */
+    refresh(refreshToken: string): Promise<TokenSet>;
+    /**
+     * Revocación RFC 7009. Con un refresh token cae el grant ENTERO (todos los
+     * access tokens de tu app para ese usuario); con un access token, solo ese.
+     * Llámalo cuando el usuario desconecte tu app: es la cortesía mínima.
+     */
+    revoke(token: string): Promise<void>;
+    private tokenRequest;
+    private formHeaders;
+    private formBody;
+}
+/**
+ * PKCE S256. Obligatorio para clients públicos y recomendable siempre: liga el
+ * código de autorización a quien lo pidió. Guarda el `verifier` en la sesión
+ * del usuario hasta que vuelva del callback.
+ */
+export declare function createPkceChallenge(): Promise<PkceChallenge>;
+/** `state` anti-CSRF. Compáralo al volver del callback. */
+export declare function createState(): string;