Construye sobre Pimia
SDKs oficiales en TypeScript y PHP, con licencia MIT: la ceremonia OAuth, la rotación del refresh token y los reintentos, resueltos. Tu app vive en tu infraestructura y habla con el núcleo por REST.
@pimia/sdk
El cliente TypeScript de la API de Pimia. Resuelve lo que se hace mal a mano: la ceremonia OAuth con PKCE, la rotación del refresh token y los reintentos. Tipos de todos los endpoints, sacados del OpenAPI.
Lo que trae:
- Node 20 o superior, o cualquier runtime con fetch y WebCrypto
- El refresh token rota: el cliente lo persiste en tu TokenStore y serializa el refresco
- Tipos del contrato con `import type { paths } from "@pimia/sdk/api"`
Instalar:
npm install @pimia/sdkEjemplo:
import { OAuth, PimiaClient, MemoryTokenStore, SCOPES, createPkceChallenge, createState } from "@pimia/sdk"
const config = {
baseUrl: "https://acme.pimia.es",
clientId: process.env.PIMIA_CLIENT_ID!,
clientSecret: process.env.PIMIA_CLIENT_SECRET, // sólo app server-side
redirectUri: "https://miapp.example/callback",
}
// 1. Mandas al usuario a autorizar (guarda verifier y state en su sesión)
const pkce = await createPkceChallenge()
const state = createState()
const url = new OAuth(config).buildAuthorizeUrl({
scopes: [SCOPES.invoicesRead, SCOPES.customersRead],
state,
pkce,
})
// 2. En tu callback: canjeas el code y guardas los tokens en TU store
const tokens = new MemoryTokenStore() // en producción: tu BD
tokens.save(await new OAuth(config).exchangeCode(code, pkce))
// 3. A partir de aquí, el cliente refresca y reintenta solo
const pimia = new PimiaClient({ ...config, tokens })
const invoices = await pimia.invoices.list({ page: 1 })Flujos reales, sobre el núcleo
Emite facturas con VeriFactu desde tu appEmite facturas con VeriFactu desde tu app: el sello y la numeración los pone el servidor
Lee clientes, presupuestos y cobrosLee clientes, presupuestos y cobros de cada tenant con el consentimiento de su dueño
Recibe webhooks firmados cuando algo cambie en el tenant
Levanta tu vertical desde el starterLevanta tu vertical desde examples/starter-vertical, con el OAuth resuelto
19191919191919191919191919191919
Seguro por defecto
OAuth con PKCE y scopes por dominio que el dueño consiente uno a uno. El refresh token rota en cada refresco, y reusar uno rotado revoca el grant entero.