@vlxx/oreus-sdk

Client TypeScript de l'API Oreus.

npm i @vlxx/oreus-sdk

import { OreusClient } from "@vlxx/oreus-sdk";

const oreus = new OreusClient({
  basePath: "https://api.oreus.fr",
  accessToken: () => session.accessToken,
});

const { profile, organization, orbs } = await oreus.loadDashboard();
const reply = await oreus.ask("Bonjour Vox");

Le paquet est livré en ESM et en CommonJS, avec les types.

Les deux moitiés

| Dossier | Origine | Édition | | ---------------- | ---------------------------------------------- | -------------------------------------------------------------- | | src/generated/ | OpenAPI Generator, depuis la spec de la racine | jamais — artefact non commité, réécrit à chaque génération | | src/ | écrit à la main | c'est ici qu'on ajoute |

src/index.ts ré-exporte les deux : le consommateur installe un paquet et n'a pas à savoir ce qui vient d'où. Les classes générées restent accessibles (oreus.users, oreus.organizations, oreus.vox) — la couche manuelle ajoute, elle ne masque pas.

Ce que contient aujourd'hui la couche manuelle, et que la spec ne peut pas décrire : la configuration du jeton porteur, loadDashboard() qui lance quatre appels en parallèle, ask() qui aplatit la signature de sendMessage, et getDisplayName() qui recompose un nom que le payload garde séparé.

Générer en local

Ni la spec ni le client généré ne sont commités : un clone frais ne compile pas tant qu'on n'a pas généré. Depuis la racine du dépôt :

pnpm run spec:pull -- --url https://api.oreus.fr/api/doc-json
pnpm run generate
pnpm run build

spec:pull écrit openapi.json à la racine : un seul fichier partagé par tous les SDK, pour qu'ils ne puissent pas être générés depuis deux versions différentes du contrat.

spec:pull refuse une spec inexploitable plutôt que de produire un SDK muet : opération sans operationId, sans tag, ou deux opérations portant le même operationId — ce dernier cas fait silencieusement disparaître une méthode du SDK généré.

C'est aussi ce que fait le workflow Publish npm sur chaque push : il récupère la spec, génère, compile, et dépose le SDK produit en artefact. La rupture visible en CI, c'est le typecheck — le contrat bouge, les méthodes écrites à la main pointent encore vers l'ancienne surface.

Publier

La publication est faite par Publish npm au merge sur main. Ce qui reste à faire à la main, c'est la version — la CI n'écrit pas dans le dépôt, et main est protégée :

pnpm changeset          # décrire le changement et son niveau
pnpm changeset version  # appliquer aux versions et aux CHANGELOG

Ces deux fichiers partent dans la PR. Au merge, la CI constate que la version manque au registre et la publie.

Scripts

| Script | Rôle | | ----------- | ----------------------------------------------------- | | generate | régénère src/generated/ depuis la spec de la racine | | build | compile en ESM + CJS + types (tsup) | | typecheck | tsc --noEmit |