SDK
Utiliser @unifam/core-sdk pour typer et valider les échanges avec l'API.
@unifam/core-sdk est une bibliothèque de contrats : schémas Zod et types TypeScript dérivés. Elle ne contient aucune logique applicative et ne dépend ni de NestJS, ni de Prisma, ni de React, ni de la bibliothèque d'authentification.
Pourquoi un SDK de contrats ?
Un seul référentiel de types garantit que le backend, le frontend et les intégrations parlent le même langage. Les schémas Zod sont la source de vérité : les types TypeScript en sont dérivés.
Installation
Le SDK est publié sur le registre npm privé du serveur Forgejo du projet, sous le scope @unifam.
1. Configurer le registre
npm config set @unifam:registry https://<serveur-forgejo>/api/packages/UniFam/npm/
npm config set -- '//<serveur-forgejo>/api/packages/UniFam/npm/:_authToken' "<token>"Le token est un token d'accès personnel Forgejo, avec le droit de lecture sur les paquets. Ne le versionnez jamais.
Dans la seconde commande, l'adresse du registre doit être écrite sans https: au début, sinon l'authentification échoue.
2. Installer
npm install @unifam/core-sdk zodTODO : confirmer si Zod est une dépendance directe ou une dépendance pair du SDK.
Contrats disponibles
TODO : noms exacts à confirmer avec les exports de src/index.ts. Les noms ci-dessous suivent les conventions du SDK.
| Ressource | Contrats |
|---|---|
| Utilisateur | UserSchema, User, CreateUserInput, UpdateUserInput |
| Foyer | FamilySchema, Family et leurs variantes de saisie |
| Rôle | FamilyRoleSchema, FamilyRole (owner, admin, member) |
| Membre | FamilyMemberSchema, FamilyMember, UpdateFamilyMemberSchema |
| Erreur d'API | ApiErrorSchema, ApiError |
Un User contient son identifiant, son e-mail, son nom, et des champs d'audit (createdAt, createdBy, updatedAt, updatedBy). Un FamilyMember relie un utilisateur (userId) à un foyer (familyId) avec un rôle, sans embarquer l'objet utilisateur complet.
Utilisation
import { FamilyMemberSchema, type FamilyMember } from '@unifam/core-sdk';
const member: FamilyMember = FamilyMemberSchema.parse(await response.json());Valider une erreur de l'API :
import { ApiErrorSchema } from '@unifam/core-sdk';
const error = ApiErrorSchema.parse(await response.json());
console.error(error.code, error.message);Conventions
- Nommage :
UserSchemapour le schéma,Userpour le type,CreateUserInputetUpdateUserInputpour les saisies. Pas de suffixeDto. - Modification partielle (PATCH) : les schémas
Update*sont toujours construits avec.partial(), même quand un seul champ est modifiable. - Exports explicites : chaque contrat public est exporté nommément depuis
src/index.ts, jamais avecexport *. - Règles métier côté backend : par exemple « un seul propriétaire par foyer » n'est pas vérifié dans le SDK.
- Bibliothèque d'authentification non exposée : aucun de ses types n'apparaît dans les contrats.
Règles
- Les contrats du Core sont dans
@unifam/core-sdk. - Les contrats d'un module (Project, Task pour Taskify) sont dans le SDK du module.
- Le SDK ne dépend ni du backend ni de la base de données.