@duplojs/agents-kit 0.0.0-stage → 0.1.0-beta.6

package/skills/fundamental/references/examples/error-propagation.ts

@@ -0,0 +1,24 @@
+/**
+ * @title Propager les échecs dans le contrat de retour.
+ *
+ * Conserver les Left d’une opération dans une fonction réutilisable.
+ */
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+import * as DSFile from "@duplojs/server/file";
+import type * as DPath from "@duplojs/lang/path";
+
+async function loadText(path: string & DPath.Path) {
+	const result = await DSFile.readTextFile(path);
+	if (DEither.isLeft(result)) {
+		return result;
+	}
+
+	return DEither.right("text-loaded", DEither.unwrapRight(result));
+}
+
+type _CheckResult = DCommon.ExpectType<
+	Awaited<ReturnType<typeof loadText>>,
+	Exclude<DSFile.ReadTextFileResult, DEither.Right> | DEither.Right<"text-loaded", string>,
+	"strict"
+>;

package/skills/fundamental/references/examples/generic-inference.ts

@@ -0,0 +1,31 @@
+/**
+ * @title Fournir une cible de calcul en contexte générique.
+ *
+ * Utiliser satisfies avec cast et infer sur un paramètre générique direct.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import type * as DString from "@duplojs/lang/string";
+
+declare function defineName<GenericName extends string & DString.MinCharacters<3>>(
+	name: GenericName,
+): GenericName;
+
+const name = defineName(
+	DCommon.cast("Alice") satisfies string & DString.MinCharacters<3>,
+);
+
+const literalName = defineName(
+	DCommon.infer("Alice") satisfies string & DString.MinCharacters<3>,
+);
+
+type _CheckName = DCommon.ExpectType<
+	typeof name,
+	string & DString.MinCharacters<3>,
+	"strict"
+>;
+
+type _CheckLiteralName = DCommon.ExpectType<
+	typeof literalName,
+	"Alice" & DString.MinCharacters<3>,
+	"strict"
+>;

package/skills/fundamental/references/examples/guaranteed-array-access.ts

@@ -0,0 +1,31 @@
+/**
+ * @title Exploiter une taille minimale de tableau.
+ *
+ * Distinguer les indices garantis et les accès potentiellement absents.
+ */
+import * as DArray from "@duplojs/lang/array";
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DEither from "@duplojs/lang/either";
+
+const namesStructure = DDataStructure.array(
+	DDataStructure.string(),
+	[DDataStructure.minElements(2)],
+);
+
+declare const input: unknown;
+const result = namesStructure.check(input);
+if (DEither.isRight(result)) {
+	const names = DEither.unwrapRight(result);
+	const first = DArray.first(names);
+	const last = DArray.last(names);
+	const atZero = DArray.at(names, 0);
+	const atOne = DArray.at(names, 1);
+	const atTwo = DArray.at(names, 2);
+
+	type _CheckAccess = DCommon.ExpectType<
+		[typeof first, typeof last, typeof atZero, typeof atOne, typeof atTwo],
+		[string, string, string, string, string | undefined],
+		"strict"
+	>;
+}

package/skills/fundamental/references/examples/independent-inputs.ts

@@ -0,0 +1,18 @@
+/**
+ * @title Combiner des sources indépendantes.
+ *
+ * Préparer les arguments séparément avant leur combinaison.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DString from "@duplojs/lang/string";
+
+declare const users: readonly {
+	enabled: boolean;
+	name: string;
+}[];
+declare const rawSearch: string;
+declare function searchUsers(names: readonly string[], search: string): readonly string[];
+
+const names = DArray.map(users, (user) => user.name);
+const search = DString.trim(rawSearch);
+const matches = searchUsers(names, search);

package/skills/fundamental/references/examples/infer.ts

@@ -0,0 +1,21 @@
+/**
+ * @title Conserver une valeur littérale contrainte.
+ *
+ * Garder le littéral lors de la déclaration d’une propriété.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import type * as DString from "@duplojs/lang/string";
+
+declare function defineSettings<GenericSettings extends {
+	name: string & DString.MinCharacters<3>;
+}>(settings: GenericSettings): GenericSettings;
+
+const settings = defineSettings({
+	name: DCommon.infer("Alice"),
+});
+
+type _CheckName = DCommon.ExpectType<
+	typeof settings.name,
+	"Alice" & DString.MinCharacters<3>,
+	"strict"
+>;

package/skills/fundamental/references/examples/input-validation.ts

@@ -0,0 +1,37 @@
+/**
+ * @title Valider un contrat de données.
+ *
+ * Décrire les contraintes puis discriminer le résultat de validation.
+ */
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+
+const requestStructure = DDataStructure.object({
+	name: DDataStructure.string([
+		DDataStructure.minCharacters(3),
+		DDataStructure.maxCharacters(40),
+	]),
+	age: DDataStructure.number([
+		DDataStructure.integer(),
+		DDataStructure.greaterThanOrEqual(18),
+	]),
+	tags: DDataStructure.array(
+		DDataStructure.string(),
+		[DDataStructure.minElements(2)],
+	),
+});
+
+type Request = DDataStructure.StructureValue<typeof requestStructure>;
+
+function validateRequest(input: unknown) {
+	return requestStructure.check(input);
+}
+
+declare const input: unknown;
+const result = validateRequest(input);
+if (DEither.isRight(result)) {
+	const request = DEither.unwrapRight(result);
+
+	type _CheckRequest = DCommon.ExpectType<typeof request, Request, "strict">;
+}

package/skills/fundamental/references/examples/safe-declarations.ts

@@ -0,0 +1,25 @@
+/**
+ * @title Déclarer une valeur connue ou traiter une entrée runtime.
+ *
+ * Distinguer les déclarations sûres et les fabriques renvoyant un Either.
+ */
+import * as DChrono from "@duplojs/lang/chrono";
+import type * as DCommon from "@duplojs/lang/common";
+import * as DPath from "@duplojs/lang/path";
+
+const configPath = DPath.declarePath("resources/config.json");
+const releaseDate = DChrono.createDate("2026-09-30");
+const timeout = DChrono.createTime(2, "hour");
+
+declare const dateInput: string;
+declare const timeInput: number;
+
+// Les surcharges runtime renvoient des Either à traiter ou propager.
+const dateResult = DChrono.createDate({ value: dateInput });
+const timeResult = DChrono.createTime(timeInput);
+
+type _CheckCreation = DCommon.ExpectType<
+	[typeof releaseDate, typeof timeout, typeof dateResult, typeof timeResult],
+	[DChrono.TheDate, DChrono.TheTime, DChrono.MayBeDate, DChrono.MayBeTime],
+	"strict"
+>;

package/skills/fundamental/references/results-and-errors.md

@@ -0,0 +1,59 @@
+# Résultats typés et exceptions
+
+## Choisir selon la place de l'échec dans le traitement
+
+Identifier les issues prévisibles que l'appelant doit pouvoir exploiter, puis les exprimer dans le contrat `Either`. Un refus peut concerner une règle métier, une vérification ou une manipulation technique. Une opération sur l'environnement ne justifie donc pas à elle seule une exception. Pour la distinction conceptuelle avec une défaillance de l'environnement, lire « Conversion des absences et exceptions en résultats » depuis le routeur du package installé.
+
+Lorsqu'une fonction renvoie un `Either` dans une branche, toutes ses branches renvoient un `Either` : `DEither.Right` pour la réussite et `DEither.Left` pour le refus. Envelopper aussi une réussite sans valeur avec `DEither.ok()`, plutôt que retourner `undefined` à côté d'un `Left`. L'information identifie le cas ; la valeur associée transporte les détails utiles. Voir [une fonction qui propage les échecs de lecture](examples/error-propagation.ts).
+
+Le `Left` de lecture reste visible dans le type de retour. Une autre fonction peut le propager, l'adapter ou tenter une récupération. Une absence de ressource exploitable par l'algorithme ne devient pas une panne d'environnement parce qu'elle provient d'une I/O. Ne pas la masquer par un `throw` ou un unwrap qui lève.
+
+`DEither.rightPipe` et `DEither.rightAsyncPipe` composent les étapes sur les valeurs de réussite et arrêtent au premier `Left`. `DEither.isRight` et `DEither.isLeft` permettent une discrimination explicite avant `unwrapRight` ou `unwrapLeft`.
+
+Pour une API qui lève sur un refus prévisible, adapter ses erreurs documentées en résultats. `DEither.safeCallback` et `DEither.asyncSafeCallback` capturent les exceptions ; examiner ensuite la cause pour distinguer le refus attendu d'une défaillance imprévue. Conserver une cause technique capturée dans le résultat jusqu'à sa consommation finale, sans la requalifier en refus métier ni la relancer depuis l'adaptation réutilisable. Préférer d'abord l'API DuploJS sûre si elle existe ; ne pas capturer systématiquement les exceptions des dépendances.
+
+## Le consommateur final décide de l'effet
+
+La frontière d'exécution consomme le résultat après le retour des fonctions appelées et décide de sa conséquence finale. C'est à ce stade que le code applicatif peut écrire un `throw` ou utiliser `OrThrow` pour interrompre l'exécution. Déclarer une fonction au niveau d'un module ou l'appeler depuis un point d'entrée ne lui donne pas cette responsabilité.
+
+Exemples : initialisation du programme, callback d'une commande ou handler d'une route.
+
+```text
+entrée externe
+  → validation par les schémas du module
+  → point d'entrée du traitement
+    → fonction applicative
+      → sous-fonction : renvoie les issues prévues en Right ou Left
+    ← résultat typé
+  ← résultat typé
+  → le point d'entrée décide de l'effet final
+```
+
+Les fonctions applicatives et leurs sous-fonctions renvoient les refus prévisibles dans leur contrat de retour, sans créer leurs propres `throw`. Les exceptions déjà émises par les dépendances ou le runtime remontent implicitement à travers ces appels ; cette propagation ne demande pas d'ajouter un `throw`.
+
+À cette frontière, interpréter le `Left` selon le contrat d'exécution : par exemple produire une réponse HTTP, un diagnostic de commande ou une exception adaptée. Le fait qu'un appelant ignore le retour d'une fonction ne suffit pas à autoriser cette fonction à lever une exception.
+
+## Choisir entre version sûre et `OrThrow`
+
+Préférer une déclaration sûre pour une valeur connue. Pour une opération qui peut échouer, examiner les branches que `OrThrow` convertirait en exceptions avant de choisir cette variante.
+
+| Situation | Choix |
+| --- | --- |
+| Constante dont la validité est prouvable | `cast`, `infer`, helper de déclaration ou surcharge littérale sûre |
+| Vérification d'une donnée externe ou valeur runtime sans preuve | Validation ou fabrique sûre, puis traitement du `Either` |
+| Refus prévisible d'une fonction réutilisable, métier ou technique | Renvoyer, propager ou adapter le `Left` |
+| Exception de défaillance imprévue émise par une dépendance ou le runtime | La laisser remonter implicitement ; propager le résultat si elle a été capturée |
+| Point d'entrée décidant de l'effet final d'un résultat | Interpréter le `Left`, puis produire la réponse, la fin d'exécution ou l'exception adaptée |
+| Test affirmant un résultat attendu | `OrThrow` permet de faire échouer le test si le résultat diffère |
+
+La commodité de l'extraction, la rareté supposée d'un refus ou la complexité de propagation ne changent pas sa nature. Une variante qui lève sur une absence exploitable ne convient pas à une fonction réutilisable qui doit transmettre ce cas.
+
+## Démarrage et tests : interpréter le résultat
+
+Au démarrage, l'initialisation peut décider qu'une configuration invalide empêche l'exécution. `environmentVariableOrThrow` valide d'abord par la version sûre, puis traduit son `Left` en exception. Cet usage exprime la décision finale du point d'entrée ; une fonction qui doit transmettre le refus utilise `environmentVariable`.
+
+Voir [la validation de l'environnement au démarrage](examples/environment-initialization.ts). Pour les entrées reçues pendant le fonctionnement du logiciel, conserver les résultats de validation jusqu'à leur interprétation par la frontière concernée.
+
+En tests, `OrThrow` peut extraire le résultat attendu ou préparer une fixture : une issue différente doit interrompre le test. Une déclaration sûre reste adaptée aux constantes connues, comme dans [les déclarations sûres](examples/safe-declarations.ts). Le code testé conserve ses résultats ; ces assertions ne justifient pas de le faire lever sur ses refus prévisibles.
+
+Pour approfondir, rechercher les `Either`, l'environnement ou le contexte d'exécution concerné dans `docs/concepts.llms.md`, depuis la racine AgentKit indiquée par les instructions du projet.

package/skills/http-client/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: duplojs-http-client
+description: "Appeler une API HTTP DuploJS ou externe avec le client typé de @duplojs/http/client : configurer son contrat, sélectionner les réponses, traiter les erreurs et consommer les flux."
+---
+
+# Client HTTP DuploJS
+
+## Trouver les concepts
+
+Appliquer la démarche du skill et lire les ressources indiquées lorsque leur condition est rencontrée. Pour rechercher un concept ou un mécanisme non couvert, consulter `docs/concepts.llms.md` du package `@duplojs/agents-kit`.
+
+Le setup indique ce chemin dans `AGENTS.md` ou `CLAUDE.md`, relativement à leur dossier. Les chemins `docs/` partent du package installé, même avec `--copy`. Les références du skill partent de son dossier ; les liens d'un document se résolvent depuis ce document.
+
+Si le chemin du routeur manque, le retrouver depuis le projet consommateur :
+
+```sh
+node --input-type=module -e 'import { fileURLToPath } from "node:url"; console.log(fileURLToPath(import.meta.resolve("@duplojs/agents-kit/docs/concepts.llms.md")))'
+```
+
+## Retrouver le contrat et configurer le client
+
+Importer les symboles nommés depuis `@duplojs/http/client`. `createHttpClient<Routes>` utilise le type des routes pour vérifier les requêtes et les réponses attendues. Le client peut appeler une API DuploJS ou un serveur externe.
+
+Retrouver les routes consommées et le client existant avant d'en créer un. Pour créer le client ou modifier son contrat et sa configuration, lire [Contrat et configuration](references/configuration.md). L'[exemple d'API externe](references/examples/external-client.ts) montre un contrat écrit à la main et la sélection par code.
+
+Le mode Predicted est actif par défaut : les attentes refusent une réponse sans header `predicted`, même si son code ou son information correspond. Pour un fournisseur sans ce marqueur, configurer **`disabledPredictedMode: true`**. Le contrat TypeScript et ce marqueur ne valident pas le body au runtime ; utiliser une data structure lorsque le traitement exige cette garantie.
+
+## Sélectionner la réponse et traiter le résultat
+
+Chaque appel produit une `PromiseRequest`, sur laquelle les réactions locales s'enregistrent avant la sélection. Une réponse **prévue** appartient au contrat de l'API ; la réponse **voulue** est celle que le traitement accepte à cet endroit. Un refus métier prévu peut donc être rejeté ici.
+
+1. Fournir les paramètres typés de l'appel et attacher les hooks ou intercepteurs locaux nécessaires.
+2. Sélectionner le cas voulu avec `iWantInformation`, ou `iWantCode` si l'API ne fournit pas d'information. Pour répartir explicitement toutes les variantes du contrat, utiliser un sélecteur exhaustif.
+3. Attendre le résultat sélectionné. Les attentes sûres renvoient un `Either` ; elles ne renvoient plus une `PromiseRequest` à configurer.
+4. Discriminer le résultat, puis utiliser la réponse voulue ou traiter et propager les autres branches. Une réponse rejetée porte `unexpect-response` ; une erreur de requête porte `request-error`.
+
+Pour écrire ou modifier une sélection, lire [Choisir et traiter les réponses](references/responses.md). L'[exemple de sélecteurs](references/examples/client-expectations.ts) distingue les résultats par information ou par code. Dans une fonction réutilisable qui transforme le résultat, conserver toutes les branches sous `Either`, y compris la nouvelle valeur de réussite.
+
+## Ajouter les comportements nécessaires
+
+| Condition rencontrée | Ressource à lire |
+| --- | --- |
+| Un comportement commun ou une réaction locale doit observer ou transformer l'échange | [Hooks et intercepteurs](references/hooks.md), avant de placer la réaction dans le cycle. |
+| La réponse contient des SSE ou des données à recevoir progressivement | [Consommation d'un flux](references/streams.md) et l'[exemple SSE et stream](references/examples/client-streams.ts), avant de lancer la lecture. |
+
+Enregistrer les callbacks d'un flux ne démarre pas sa consommation. Après sélection de la réponse, parcourir son itérateur asynchrone ou appeler la méthode de consommation adaptée ; prévoir sa fermeture selon le cycle attendu.
+
+## Vérifier l'intégration
+
+Exécuter le typage et les vérifications du projet. Vérifier la réponse voulue et les branches de refus ou d'erreur concernées par la modification, y compris l'absence de traitement dépendant après un échec. Contrôler les headers réels du fournisseur pour le mode Predicted et valider le body lorsque le contrat exige une garantie runtime. Pour un flux, vérifier aussi le démarrage de la consommation et sa fermeture.

package/skills/http-client/references/configuration.md

@@ -0,0 +1,11 @@
+# Contrat et configuration du client
+
+Le client HTTP est utilisable partout où une application effectue une requête HTTP, que l'API soit développée avec DuploJS ou avec une autre technologie. `createHttpClient<Routes>` accepte un type compatible avec `ServerRoute` : chaque route décrit sa méthode, son chemin, ses entrées et l'union de ses réponses. Les types peuvent être écrits à la main, importés ou composés.
+
+Pour une API DuploJS, utiliser `RouteDeclarationToContract` depuis `@duplojs/http` avec le type d'une route (`typeof route`) ou une union de types de routes. Il reprend leurs entrées et leurs réponses, y compris les refus des étapes de vérification. Importer les routes avec `import type` pour éviter de charger les modules serveur dans le client. Voir `docs/concepts/03-client/10-http/10-init.ts` depuis le package installé.
+
+Décrire précisément les requêtes et les réponses connues, y compris les erreurs contractuelles. Éviter de perdre ces garanties avec un client non paramétré ou des assertions sur les résultats. Le typage décrit le contrat supposé de l'API ; il n'effectue pas de validation runtime du body. Utiliser une data structure lorsque cette validation est nécessaire.
+
+Créer un client par configuration d'API. Y placer l'URL de base, les options globales telles que `credentials` et `cache`, les headers par défaut et les hooks transversaux. Un header peut être calculé à chaque requête, par exemple pour récupérer le token courant. Les paramètres d'un appel peuvent préciser ses headers, ses options `initParams` et son `abortController`. Voir [un client pour une API externe](examples/external-client.ts), avec un contrat écrit à la main, sans header `information` ni `predicted`.
+
+Pour les exemples complémentaires de configuration et d’envoi de formulaires, rechercher le client HTTP dans `docs/concepts.llms.md` du package installé.

package/skills/http-client/references/examples/client-expectations.ts

@@ -0,0 +1,85 @@
+/**
+ * @title Choisir les réponses voulues depuis une PromiseRequest.
+ *
+ * Les sélecteurs imposent un choix pour chaque cas du contrat de la requête.
+ */
+import { createHttpClient } from "@duplojs/http/client";
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+
+interface Routes {
+	readonly method: "GET";
+	readonly path: "/profile";
+	readonly responses: {
+		readonly code: "200";
+		readonly information: "profile.found";
+		readonly body: { name: string };
+	} | {
+		readonly code: "401";
+		readonly information: "auth.required";
+		readonly body: undefined;
+	};
+}
+
+const client = createHttpClient<Routes>({
+	baseUrl: "https://duplo-api.example.com",
+	// Le mode Predicted reste actif pour cette API DuploJS.
+});
+
+export function requestProfile(onAuthenticationRequired: () => void) {
+	return client.get("/profile")
+		.addRequestInterceptor((params) => ({
+			...params,
+			headers: {
+				...params.headers,
+				"x-request-source": "profile-page",
+			},
+		}))
+		.whenInformation("auth.required", onAuthenticationRequired);
+}
+
+export async function selectProfile(onAuthenticationRequired: () => void) {
+	const result = await requestProfile(onAuthenticationRequired)
+		.toEitherByInformation({
+			"profile.found": true,
+			"auth.required": false,
+		});
+
+	if (DEither.hasInformation(result, "profile.found")) {
+		const response = DEither.unwrapRight(result);
+
+		type _CheckCode = DCommon.ExpectType<typeof response.code, "200", "strict">;
+		type _CheckBody = DCommon.ExpectType<typeof response.body, { name: string }, "strict">;
+
+		return DEither.success(response.body);
+	}
+
+	// Les autres branches portent unexpect-response ou request-error.
+	return result;
+}
+
+export async function classifyProfileByCode() {
+	const result = await client.get("/profile").toEitherByCode({
+		200: true,
+		401: true,
+	});
+
+	// Une erreur métier peut être un résultat voulu à cet endroit du programme.
+	if (DEither.hasInformation(result, "response-401")) {
+		const response = DEither.unwrapRight(result);
+
+		type _CheckInformation = DCommon.ExpectType<typeof response.information, "auth.required", "strict">;
+		void response;
+	}
+
+	return result;
+}
+
+// Illustration de compilation, sans créer de requête supplémentaire.
+export function checkSelectorContract(request: ReturnType<typeof client.get>) {
+	// @ts-expect-error Le sélecteur doit aussi décider du cas auth.required.
+	void request.toEitherByInformation({ "profile.found": true });
+
+	// @ts-expect-error Le sélecteur doit aussi décider du code 401.
+	void request.toEitherByCode({ 200: true });
+}

package/skills/http-client/references/examples/client-streams.ts

@@ -0,0 +1,74 @@
+/**
+ * @title Consommer des événements SSE et un stream typés.
+ *
+ * La sélection de la réponse précède la lecture progressive du flux.
+ */
+import { createHttpClient } from "@duplojs/http/client";
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+
+type Routes = {
+	method: "GET";
+	path: "/events";
+	responses: {
+		code: "200";
+		information: "events.open";
+		events: {
+			progress: { percent: number };
+			finished: { id: string };
+		};
+	};
+} | {
+	method: "GET";
+	path: "/text-stream";
+	responses: {
+		code: "200";
+		information: "text.open";
+		flux: string;
+	};
+};
+
+const client = createHttpClient<Routes>({
+	baseUrl: "https://duplo-api.example.com",
+});
+
+export async function consumeEvents(onProgress: (percent: number) => void) {
+	const result = await client.get("/events").iWantInformation("events.open");
+
+	if (DEither.isLeft(result)) {
+		return result;
+	}
+
+	const response = DEither.unwrapRight(result);
+	response.onReceiveEvent("progress", (event) => {
+		type _CheckData = DCommon.ExpectType<typeof event.data, { percent: number }, "strict">;
+
+		onProgress(event.data.percent);
+	});
+	response.onReceiveEvent("finished", (_event, stream) => {
+		stream.closeEventStream();
+	});
+
+	// Enregistrer les callbacks ne démarre pas la lecture.
+	await response.consumeEventStream();
+	return DEither.ok();
+}
+
+export async function consumeText(onChunk: (chunk: string) => void) {
+	// Cette réponse fournit predicted, x-duplojs-body-options: stream
+	// et un content-type text/plain, cohérents avec le contrat flux: string.
+	const result = await client.get("/text-stream").iWantInformation("text.open");
+
+	if (DEither.isLeft(result)) {
+		return result;
+	}
+
+	const response = DEither.unwrapRight(result);
+	for await (const chunk of response) {
+		type _CheckChunk = DCommon.ExpectType<typeof chunk, string, "strict">;
+
+		onChunk(chunk);
+	}
+
+	return DEither.ok();
+}

package/skills/http-client/references/examples/external-client.ts

@@ -0,0 +1,78 @@
+/**
+ * @title Typer une API externe sans génération DuploJS.
+ *
+ * Le contrat est écrit à la main ; les réponses n'ont aucun header DuploJS.
+ */
+import { createHttpClient } from "@duplojs/http/client";
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+
+interface ExternalRoutes {
+	method: "GET";
+	path: "/users/{userId}";
+	params: {
+		userId: number;
+	};
+	responses: {
+		code: "200";
+		// Rendre l'absence explicite préserve l'inférence avec l'API actuelle.
+		information?: undefined;
+		body: {
+			id: number;
+			name: string;
+		};
+	} | {
+		code: "404";
+		information?: undefined;
+		body: {
+			message: string;
+		};
+	};
+}
+
+export const externalClient = createHttpClient<ExternalRoutes>({
+	baseUrl: "https://api.example.com",
+	// L'API ne fournit pas le marqueur de réponses prévues.
+	disabledPredictedMode: true,
+});
+
+export function configureExternalClient(getToken: () => string) {
+	externalClient.addDefaultHeader("authorization", () => `Bearer ${getToken()}`);
+	// Transformer ici les options communes à tous les appels de cette API.
+	externalClient.addRequestHook((params) => ({
+		...params,
+		initParams: {
+			...params.initParams,
+			credentials: "omit",
+		},
+	}));
+}
+
+export async function readExternalUser(userId: number) {
+	const result = await externalClient
+		.get("/users/{userId}", { params: { userId } })
+		.whenCode("404", ({ body }) => {
+			type _CheckError = DCommon.ExpectType<typeof body, { message: string }, "strict">;
+			console.log(body.message);
+		})
+		.iWantCode("200");
+
+	if (DEither.isRight(result)) {
+		const response = DEither.unwrapRight(result);
+
+		type _CheckBody = DCommon.ExpectType<
+			typeof response.body,
+			{
+				id: number;
+				name: string;
+			},
+			"strict"
+		>;
+
+		return DEither.success(response.body);
+	}
+
+	// Le 404 et les autres réponses reçues restent accessibles via unexpect-response.
+	// Les erreurs de transport ou de traitement portent request-error.
+	return result;
+}

package/skills/http-client/references/hooks.md

@@ -0,0 +1,7 @@
+# Placer les hooks et intercepteurs
+
+Le client porte les comportements communs : `addRequestHook`, `addResponseHook`, `addErrorHook` et les hooks ciblant une information, un code ou une famille de réponses. Les hooks de requête et de réponse peuvent transformer leur entrée ; retourner la valeur destinée à la suite du cycle. Les réactions globales telles que les loaders ou la journalisation se placent à ce niveau.
+
+Chaque appel retourne une `PromiseRequest`, représentation de cet échange. Lui attacher immédiatement les traitements locaux avant `await` : les `when*` enregistrent des callbacks et renvoient la même `PromiseRequest`. Ils permettent de composer plusieurs réactions sans sélectionner ni extraire le résultat. `addRequestInterceptor` et `addResponseInterceptor` permettent les transformations locales. `whenError` traite une erreur de requête ; `whenNotPredictedResponse` observe une réponse sans marqueur lorsque le mode de réponses prévues est actif.
+
+Après les hooks locaux, choisir l’attente ou le sélecteur selon [le résultat voulu](responses.md). Pour ajouter un loader ou une instrumentation globale, lire `docs/concepts/03-client/10-http/30-hook.ts` depuis le package installé : cet exemple suit les effets communs pendant le cycle d'un échange.

package/skills/http-client/references/responses.md

@@ -0,0 +1,39 @@
+# Choisir et traiter les réponses
+
+## Attentes et sélecteurs
+
+Les méthodes d'attente transforment ensuite le résultat en une promesse de réponse ou d'`Either`. Choisir l'attente après les hooks locaux ; un appel à `iWant*` ne renvoie plus une `PromiseRequest`. Voir [les attentes et sélecteurs](examples/client-expectations.ts).
+
+| Besoin | Choix et résultat après `await` |
+| --- | --- |
+| Réagir à un cas sans modifier le résultat | `whenInformation`, `whenCode` ou une famille `when*` ; callback avec la réponse ciblée |
+| Exiger un cas précis | `iWantInformation` ou `iWantCode` ; `Right<"response", RéponseVoulue>` ou un `Left` |
+| À la consommation finale du résultat, obtenir la réponse ou interrompre l'exécution | Variante `OrThrow` ; réponse voulue ou exception. Dans une fonction réutilisable, conserver le `Either`. |
+| Répartir toutes les informations du contrat entre résultats voulus et non voulus | `iSelectExpectedResponseByInformation` ; sélecteur exhaustif `true` / `false`, résultat sous `Either` |
+| Discriminer les `Right` par l'information de la réponse | `toEitherByInformation` ; sélecteur exhaustif, `Right<Information, Réponse>` pour les entrées `true` |
+| Discriminer les `Right` par le code HTTP | `toEitherByCode` ; sélecteur exhaustif, `Right<"response-<code>", Réponse>` pour les entrées `true` |
+
+Les sélecteurs exigent une décision pour chaque information ou code déclaré dans les réponses de la requête. Une évolution du contrat impose ainsi de revoir ce choix. `false` conserve la réponse dans un `Left<"unexpect-response", ...>` ; les erreurs de requête restent des `Left<"request-error", ...>`. Les `Left` ne prennent pas le nom de l'information ou du code rejeté. Traiter ces branches avec les outils `Either` ; une réponse non voulue n'est pas supprimée silencieusement. Les variantes `OrThrow` lèvent une erreur pour ces branches, y compris les erreurs de requête.
+
+La famille `ExpectedResponse` sans sélecteur (`whenExpectedResponse`, `iWantExpectedResponse`) regroupe les codes `2xx` et `4xx`. Elle ne signifie pas « tous les codes déclarés dans le contrat » et ne remplace pas le choix des cas utiles à l'application. Pour un scénario précis, sélectionner l'information attendue, ou le code si l'API ne fournit pas d'information.
+
+## Réponses prévues et mode Predicted
+
+Une réponse **prévue** appartient aux réponses contractuelles de l'API. Elle peut être un succès ou une erreur métier, par exemple un `404` déclaré. Une réponse **voulue** est celle que le consommateur décide d'accepter à cet endroit du programme. Une réponse prévue peut donc être rejetée par un sélecteur.
+
+Le serveur DuploJS ajoute le header `predicted` aux `PredictedResponse` et à leurs équivalents SSE et stream. Ce marqueur permet au client de reconnaître les réponses prévues par l'API. Une erreur de parsing du body ou une erreur interne peut produire une réponse imprévue. Son code ou son information peut coïncider avec celui d'une réponse prévue, sans garantir le même body.
+
+Par défaut, `disabledPredictedMode` vaut `false`. Le client vérifie la **présence** du header indiqué par `predictedHeaderKey` (`predicted` par défaut). Sans ce header, les hooks ciblés par information, code ou famille ne s'exécutent pas et les attentes et sélecteurs renvoient `Left<"unexpect-response", ...>`, même si le code ou l'information correspond. Cela évite d'utiliser sous un type contractuel le contenu d'une autre réponse. Les hooks généraux de réponse et le hook dédié aux réponses imprévues restent disponibles.
+
+Cette règle concerne les attentes : un `await` direct sur la `PromiseRequest`, sans sélection, conserve une réponse HTTP reçue dans un `Right<"response", ...>`, y compris sans marqueur. Utiliser une attente pour obtenir la réponse correspondant au besoin ; ne pas confondre réception d'une réponse et acceptation de son contrat.
+
+## Adapter le client au protocole du fournisseur
+
+Pour une API **sans ce marqueur**, créer son client avec `disabledPredictedMode: true`. Les attentes se fondent alors sur le code ou l'information sans imposer le header. Sans information de réponse, sélectionner par code. Si seuls les noms des headers diffèrent, configurer `predictedHeaderKey` et `informationHeaderKey` selon le protocole de l'API. Conserver le mode actif pour une API DuploJS qui fournit le marqueur.
+
+Le marqueur est une convention du protocole, pas une validation du contenu ni une preuve d'authenticité. Le body reste à valider lorsque le traitement exige une garantie runtime.
+
+## Particularité d'inférence d'un contrat sans information
+
+Avec l'API actuelle, un contrat de réponses sans header d'information doit déclarer explicitement `information?: undefined` dans chaque réponse pour conserver leur inférence. L'[exemple d'API externe](examples/external-client.ts) applique cette forme et sélectionne par code. Cette déclaration répond au typage de l'API cliente ; elle n'ajoute aucun header au protocole.
+

package/skills/http-client/references/streams.md

@@ -0,0 +1,10 @@
+# Consommer progressivement un flux
+
+Décrire les événements SSE avec `responses.events` et les données d'un stream avec `responses.flux`. Après sélection de la réponse, consommer l'itérateur asynchrone pour traiter les éléments au fur et à mesure, ou enregistrer les callbacks puis lancer la consommation. Voir [SSE et stream](examples/client-streams.ts).
+
+- **SSE** : `onReceiveEvent` cible un événement typé, `onStreamEvent` observe le cycle, `consumeEventStream` lance la lecture et `closeEventStream` ferme le flux. La réponse est reconnue par le content-type `text/event-stream`.
+- **Stream** : `onStream` observe notamment `receiveData`, `consumeStream` lance la lecture et `closeStream` ferme le flux. Cette couche est activée par le header `x-duplojs-body-options` contenant `stream` ; les chunks sont décodés en texte si le content-type contient `text`, sinon ils restent des `Uint8Array`. Les chunks ne sont pas nécessairement des messages applicatifs complets : gérer le découpage si le protocole l'exige.
+
+`whenReceiveServerEvent` et `whenReceiveDataStream` permettent aussi d'attacher les callbacks depuis la `PromiseRequest` ; ils ne lancent pas à eux seuls la consommation. Les hooks globaux du client peuvent instrumenter le démarrage, la réception, les erreurs et la fermeture. Le mode de réponses prévues s'applique également à ces réponses : le désactiver pour un fournisseur sans marqueur. Le typage seul ne transforme pas un flux arbitraire en SSE ou en stream reconnu par cette couche ; vérifier les headers et le format de l'API.
+
+Pour choisir la réponse avant sa consommation, consulter [les attentes et le mode Predicted](responses.md).