@pimia/sdk 0.1.0

package/dist/oauth.js

@@ -0,0 +1,147 @@
+/**
+ * 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 { OAuthError } from './errors.js';
+import { tokenSetFromResponse } from './tokens.js';
+export class OAuth {
+    config;
+    baseUrl;
+    doFetch;
+    constructor(config) {
+        this.config = config;
+        this.baseUrl = config.baseUrl.replace(/\/+$/, '');
+        this.doFetch = config.fetch ?? globalThis.fetch;
+    }
+    /** `GET /.well-known/oauth-authorization-server` — útil para no cablear rutas. */
+    async metadata() {
+        const response = await this.doFetch(`${this.baseUrl}/.well-known/oauth-authorization-server`, {
+            headers: { accept: 'application/json' },
+        });
+        if (!response.ok) {
+            throw new OAuthError('metadata_unavailable', `HTTP ${response.status}`);
+        }
+        return (await response.json());
+    }
+    /**
+     * 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 }) {
+        const query = new URLSearchParams({
+            client_id: this.config.clientId,
+            redirect_uri: this.config.redirectUri,
+            response_type: 'code',
+            scope: scopes.join(' '),
+            state,
+            code_challenge: pkce.challenge,
+            code_challenge_method: pkce.method,
+        });
+        return `${this.baseUrl}/oauth/authorize?${query.toString()}`;
+    }
+    /**
+     * 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).
+     */
+    async exchangeCode(code, pkce) {
+        return this.tokenRequest({
+            grant_type: 'authorization_code',
+            code,
+            redirect_uri: this.config.redirectUri,
+            code_verifier: pkce.verifier,
+        });
+    }
+    /**
+     * 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.
+     */
+    async refresh(refreshToken) {
+        return this.tokenRequest({ grant_type: 'refresh_token', refresh_token: refreshToken });
+    }
+    /**
+     * 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.
+     */
+    async revoke(token) {
+        const response = await this.doFetch(`${this.baseUrl}/oauth/revoke`, {
+            method: 'POST',
+            headers: this.formHeaders(),
+            body: this.formBody({ token }),
+        });
+        // 200 aunque el token no exista (el AS no filtra si existía).
+        if (!response.ok) {
+            const body = await safeJson(response);
+            throw new OAuthError(body?.error ?? 'revocation_failed', body?.error_description ?? `HTTP ${response.status}`);
+        }
+    }
+    async tokenRequest(params) {
+        const response = await this.doFetch(`${this.baseUrl}/oauth/token`, {
+            method: 'POST',
+            headers: this.formHeaders(),
+            body: this.formBody(params),
+        });
+        const body = await safeJson(response);
+        if (!response.ok) {
+            const error = body;
+            throw new OAuthError(error?.error ?? 'token_request_failed', error?.error_description);
+        }
+        return tokenSetFromResponse(body);
+    }
+    formHeaders() {
+        return {
+            'content-type': 'application/x-www-form-urlencoded',
+            accept: 'application/json',
+        };
+    }
+    formBody(params) {
+        const body = new URLSearchParams({ ...params, client_id: this.config.clientId });
+        if (this.config.clientSecret) {
+            body.set('client_secret', this.config.clientSecret);
+        }
+        return body.toString();
+    }
+}
+/**
+ * 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 async function createPkceChallenge() {
+    const bytes = new Uint8Array(32);
+    crypto.getRandomValues(bytes);
+    const verifier = base64Url(bytes);
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier));
+    return { verifier, challenge: base64Url(new Uint8Array(digest)), method: 'S256' };
+}
+/** `state` anti-CSRF. Compáralo al volver del callback. */
+export function createState() {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    return base64Url(bytes);
+}
+function base64Url(bytes) {
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+async function safeJson(response) {
+    const text = await response.text();
+    if (text === '')
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}

package/dist/tokens.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Tokens y su persistencia.
+ *
+ * ⚠️ LO MÁS IMPORTANTE DE ESTE SDK. El refresh token de Pimia **rota**: cada
+ * canje devuelve uno nuevo y mata el anterior, y **reusar uno ya rotado se
+ * trata como robo: revoca el grant entero en cascada** (todos los tokens de tu
+ * app para ese usuario mueren y el usuario tiene que volver a autorizarte).
+ *
+ * Por eso el SDK nunca guarda tokens «en una variable y ya»: exige un
+ * TokenStore y persiste el conjunto ENTERO tras cada refresh. Si tu app corre
+ * en varios procesos, el store debe ser compartido (Redis, BD…) y, si dos
+ * procesos pueden refrescar a la vez, serializa el refresh — dos refrescos
+ * concurrentes con el mismo token son, para el servidor, un reuse.
+ */
+export interface TokenSet {
+    accessToken: string;
+    /** Ausente si el operador desactivó los refresh (OAUTH_ACCESS_TOKEN_TTL=0). */
+    refreshToken?: string;
+    /** Epoch en ms. Ausente = el servidor no dio expiración. */
+    expiresAt?: number;
+    scope?: string;
+    tokenType?: string;
+}
+export interface TokenStore {
+    load(): Promise<TokenSet | null> | TokenSet | null;
+    save(tokens: TokenSet): Promise<void> | void;
+    clear(): Promise<void> | void;
+}
+/** Store de memoria: vale para scripts y tests, NO para producción con varios procesos. */
+export declare class MemoryTokenStore implements TokenStore {
+    private tokens;
+    constructor(tokens?: TokenSet | null);
+    load(): TokenSet | null;
+    save(tokens: TokenSet): void;
+    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. */
+export declare function tokenSetFromResponse(payload: {
+    access_token: string;
+    refresh_token?: string;
+    expires_in?: number;
+    scope?: string;
+    token_type?: string;
+}, now?: number): TokenSet;

package/dist/tokens.js

@@ -0,0 +1,46 @@
+/**
+ * Tokens y su persistencia.
+ *
+ * ⚠️ LO MÁS IMPORTANTE DE ESTE SDK. El refresh token de Pimia **rota**: cada
+ * canje devuelve uno nuevo y mata el anterior, y **reusar uno ya rotado se
+ * trata como robo: revoca el grant entero en cascada** (todos los tokens de tu
+ * app para ese usuario mueren y el usuario tiene que volver a autorizarte).
+ *
+ * Por eso el SDK nunca guarda tokens «en una variable y ya»: exige un
+ * TokenStore y persiste el conjunto ENTERO tras cada refresh. Si tu app corre
+ * en varios procesos, el store debe ser compartido (Redis, BD…) y, si dos
+ * procesos pueden refrescar a la vez, serializa el refresh — dos refrescos
+ * concurrentes con el mismo token son, para el servidor, un reuse.
+ */
+/** Store de memoria: vale para scripts y tests, NO para producción con varios procesos. */
+export class MemoryTokenStore {
+    tokens;
+    constructor(tokens = null) {
+        this.tokens = tokens;
+    }
+    load() {
+        return this.tokens;
+    }
+    save(tokens) {
+        this.tokens = tokens;
+    }
+    clear() {
+        this.tokens = null;
+    }
+}
+/** ¿Caduca dentro de `skewSeconds`? Sin expiresAt se asume que sigue vivo. */
+export function isExpired(tokens, skewSeconds = 60, now = Date.now()) {
+    if (tokens.expiresAt === undefined)
+        return false;
+    return tokens.expiresAt - skewSeconds * 1000 <= now;
+}
+/** Respuesta cruda del token endpoint → TokenSet. */
+export function tokenSetFromResponse(payload, now = Date.now()) {
+    return {
+        accessToken: payload.access_token,
+        refreshToken: payload.refresh_token,
+        expiresAt: payload.expires_in ? now + payload.expires_in * 1000 : undefined,
+        scope: payload.scope,
+        tokenType: payload.token_type ?? 'bearer',
+    };
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@pimia/sdk",
+  "version": "0.1.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)",
+  "homepage": "https://github.com/Pimia-AI/pimia-sdks/tree/main/typescript#readme",
+  "bugs": {
+    "url": "https://github.com/Pimia-AI/pimia-sdks/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Pimia-AI/pimia-sdks.git",
+    "directory": "typescript"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./api": {
+      "types": "./dist/api.d.ts",
+      "import": "./dist/api.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "generate:types": "openapi-typescript ../spec/pimia-api-v1.json -o src/api.ts",
+    "test": "node --test test/*.test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "openapi-typescript": "^7.4.4",
+    "typescript": "^5.7.2"
+  },
+  "keywords": [
+    "pimia",
+    "facturacion",
+    "verifactu",
+    "oauth",
+    "sdk"
+  ]
+}