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

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

@@ -0,0 +1,112 @@
+/**
+ * @title Remplacer les boucles par les primitives DuploJS.
+ *
+ * Accumulateurs immuables, sortie anticipée et répétitions conditionnelles.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+import * as DGenerator from "@duplojs/lang/generator";
+import * as DNumber from "@duplojs/lang/number";
+
+interface RunningTotals {
+	readonly total: number;
+	readonly subtotals: readonly number[];
+}
+
+const runningTotals = DCommon.pipe(
+	[2, -1, 4],
+	DArray.reduce(
+		DArray.reduceFrom<RunningTotals>({
+			total: 0,
+			subtotals: [],
+		}),
+		({ element, lastValue, nextWithObject }) => {
+			const total = DNumber.sum([lastValue.total, element]);
+			return nextWithObject(lastValue, {
+				total,
+				subtotals: DArray.push(lastValue.subtotals, total),
+			});
+		},
+	),
+);
+
+// Résultat : { total: 5, subtotals: [2, 1, 5] }. Chaque étape dépend du total précédent.
+// L'accumulateur initial et la source ne sont pas mutés.
+type _CheckRunningTotals = DCommon.ExpectType<typeof runningTotals, RunningTotals, "strict">;
+
+const totalOrStop = DCommon.pipe(
+	[2, -1, 4],
+	DArray.reduce(
+		0,
+		({ element, lastValue, next, exit }) => element < 0
+			? exit("negative-value")
+			: next(DNumber.sum([lastValue, element])),
+	),
+);
+
+// Résultat : "negative-value" ; 4 n'est pas traité. exit peut changer le type du résultat.
+type _CheckTotalOrStop = DCommon.ExpectType<typeof totalOrStop, number | string, "strict">;
+
+declare function loadAmount(id: string): Promise<number>;
+
+const loadedTotal = await DCommon.asyncPipe(
+	["first", "second"],
+	DGenerator.asyncReduce(
+		0,
+		async({ item, lastValue, next }) => {
+			const amount = await loadAmount(item);
+			return next(DNumber.sum([lastValue, amount]));
+		},
+	),
+);
+
+// Chaque chargement est attendu avant le suivant ; la source peut aussi être un AsyncIterable.
+type _CheckLoadedTotal = DCommon.ExpectType<typeof loadedTotal, number, "strict">;
+
+const reachedValue = DCommon.loopAccumulator(0, ({ accumulator, next, exit }) => {
+	// La condition est vérifiée avant le traitement, comme dans un while.
+	if (accumulator >= 3) {
+		return exit(accumulator);
+	}
+
+	return next(DNumber.sum([accumulator, 1]));
+});
+
+// Résultat : 3. L'état circule dans l'accumulateur de la boucle.
+type _CheckReachedValue = DCommon.ExpectType<typeof reachedValue, number, "strict">;
+
+declare function readBatchSize(index: number): Promise<number>;
+
+const processedTotal = await DCommon.asyncLoopAccumulator(0, async({
+	count,
+	accumulator,
+	next,
+	exit,
+}) => {
+	const size = await readBatchSize(count);
+
+	// La première taille nulle termine la lecture ; exit retourne le total accumulé.
+	if (size === 0) {
+		return exit(accumulator);
+	}
+
+	return next(DNumber.sum([accumulator, size]));
+});
+
+type _CheckProcessedTotal = DCommon.ExpectType<typeof processedTotal, number, "strict">;
+
+const emitted = DArray.from(DGenerator.loop(({ count, next, exit }) => count === 3
+	? exit("done")
+	: next(count)));
+
+// DGenerator.loop émet les sorties de next puis celles de exit.
+type _CheckEmitted = DCommon.ExpectType<typeof emitted, readonly (number | "done")[], "strict">;
+
+const emittedWithAccumulator = DArray.from(
+	DGenerator.loopAccumulator(0, ({ accumulator, count, next, exit }) => count === 3
+		? exit(accumulator)
+		: next(accumulator + 1, accumulator)),
+);
+
+// Chaque sortie peut être produite au même moment que le nouvel accumulateur est choisi.
+type _CheckEmittedWithAccumulator = DCommon.ExpectType<typeof emittedWithAccumulator, readonly number[], "strict">;

package/skills/fundamental/references/examples/result-selection.ts

@@ -0,0 +1,65 @@
+/**
+ * @title Sélectionner les résultats selon l'opération.
+ *
+ * Constater un état, sélectionner les issues utiles et conserver les refus.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DEither from "@duplojs/lang/either";
+
+interface Item {
+	id: string;
+	enabled: boolean;
+}
+
+function classifyItem(item: Item) {
+	if (item.enabled) {
+		return DEither.result("ready", item);
+	}
+
+	return DEither.result("blocked", item);
+}
+
+function prepareItem(item: Item) {
+	const selected = DCommon.pipe(
+		item,
+		classifyItem,
+		DEither.keepAsRightByInformation("ready"),
+		DEither.unwrapRight,
+	);
+
+	// unwrapRight conserve le Left : la garde peut suivre l'extraction.
+	if (DEither.isLeft(selected)) {
+		return selected;
+	}
+
+	return DEither.right("prepared", selected);
+}
+
+type _CheckPrepared = DCommon.ExpectType<
+	ReturnType<typeof prepareItem>,
+	DEither.Left<"blocked", Item> | DEither.Right<"prepared", Item>,
+	"strict"
+>;
+
+declare function loadItem(id: string): Promise<DEither.Maybe<Item>>;
+declare function saveItem(item: Item): Promise<DEither.Right<"saved", Item>>;
+
+const saved = await DEither.rightAsyncPipe(
+	loadItem("item"),
+	// L'inner pipe intervient après la recherche, à une étape intermédiaire.
+	DCommon.innerPipe(
+		classifyItem,
+		DEither.keepAsRightSelection({
+			ready: true,
+			blocked: false,
+		}),
+	),
+	// L'étape extérieure reçoit l'Item déballé ; un Left évite cet appel.
+	(item) => saveItem(item),
+);
+
+type _CheckSaved = DCommon.ExpectType<
+	typeof saved,
+	DEither.None | DEither.Left<"blocked", Item> | DEither.Right<"saved", Item>,
+	"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/iterations.md

@@ -0,0 +1,24 @@
+# Itérations
+
+## Parcourir une collection
+
+Configurer `DArray.reduce(initial, callback)` dans l'étape d'un `DCommon.pipe` recevant le tableau. La callback reçoit `element`, `index` et `lastValue`, initialement égal à l'accumulateur de départ :
+
+- `next(nouvelÉtat)` poursuit ; `next(lastValue)` ignore l'élément.
+- `exit(résultat)` arrête immédiatement et peut changer le type de sortie.
+
+Sans `exit`, le résultat est le dernier accumulateur ; une source vide retourne l'initial. Pour un état structuré, utiliser `DArray.reduceFrom<Type>(valeur)` et construire les nouveaux états sans mutation.
+
+Pour un autre itérable, utiliser `DGenerator.reduce`. `DGenerator.asyncReduce` accepte tableaux, itérables synchrones ou asynchrones et attend chaque étape. Leurs callbacks reçoivent `item` ; initialiser leurs états structurés avec `DGenerator.reduceFrom`.
+
+## Répéter jusqu'à une condition
+
+`DCommon.loop` fournit `count` depuis zéro. `next()` continue et `exit(valeur)` retourne le résultat final. La donnée optionnelle de `next` n'est pas transmise au tour suivant ; utiliser `DCommon.loopAccumulator(initial, callback)` lorsque les tours doivent partager un état. Sa callback reçoit `accumulator`, `count`, `next(nouvelAccumulateur)` et `exit(résultat)`. `DCommon.asyncLoop` et `DCommon.asyncLoopAccumulator` offrent les mêmes comportements en attendant la callback asynchrone.
+
+`DGenerator.loop(callback)` produit une séquence : chaque `next(...valeurs)` émet les valeurs définies et poursuit la boucle ; `exit(...valeurs)` émet sa dernière séquence puis termine. La callback reçoit `count`, pas la valeur du tour précédent. `DGenerator.asyncLoop` attend les callbacks et résout les valeurs promises avant de les émettre.
+
+Les variantes `DGenerator.loopAccumulator(initial, callback)` et `DGenerator.asyncLoopAccumulator(initial, callback)` font circuler un accumulateur avec `next(nouvelAccumulateur, ...valeursÀÉmettre)`. `exit(...valeursÀÉmettre)` termine en émettant les dernières valeurs. Utiliser `DGenerator.loopAccumulatorFrom<Type>(valeur)` pour préserver un type d'accumulateur structuré ou une union.
+
+Conserver la condition avant le traitement d'un `while`, après celui d'un `do...while`. Pour une répétition par compteur, utiliser aussi `loop`, sans fabriquer un tableau.
+
+Voir les [exemples typés](examples/iterations.ts), avec accumulateurs, sorties anticipées et variantes asynchrones.

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

@@ -0,0 +1,34 @@
+# Résultats et erreurs
+
+## Choisir le contrat
+
+Une fonction qui établit des états sans décider lesquels conviennent à l'appelant produit des `DEither.Result` nommés. Tous sont des `Right` ; les distinguer par leur information.
+
+Une fonction qui décide d'une réussite ou d'un refus prévisible les exprime en `Right` ou `Left`, y compris pour les absences et refus techniques. Toutes ses branches renvoient un `Either` ; `DEither.ok()` représente une réussite sans valeur.
+
+## Sélectionner et poursuivre
+
+| Intention du consommateur | Outil |
+| --- | --- |
+| Autoriser certaines informations et refuser toutes les autres, même futures | `keepAsRightByInformation` |
+| Décider explicitement du statut de chaque variante | `keepAsRightSelection` |
+| Décider explicitement des variantes d'une garde | `isSelected` |
+| Traiter chaque information | `matchInformation` |
+
+Les sélecteurs exhaustifs imposent de revoir la décision lorsqu'une variante apparaît. Une sélection partielle ou un repli exprime au contraire un comportement commun voulu.
+
+Le reclassement conserve information et valeur. `unwrapRight` extrait les valeurs acceptées et conserve les `Left` : une garde `isLeft` peut ensuite retourner le refus. Si le contrat garantit uniquement des `Right` admis, l'extraction peut être directe. Voir [la sélection et le retour anticipé](examples/result-selection.ts).
+
+Pour sélectionner à une étape d'un `rightPipe` avant son déballage automatique, lire [Composition](composition.md#asynchronisme-et-résultats).
+
+## Propager ou adapter un refus
+
+Une fonction réutilisable transmet ses refus à l'appelant, qui peut les propager, les adapter ou récupérer. Une absence exploitable reste un résultat, même issue d'une I/O. Voir [la propagation d'une erreur de lecture](examples/error-propagation.ts).
+
+Préférer une API sûre. Si une API lève sur un refus documenté, `safeCallback` ou `asyncSafeCallback` permettent sa capture ; examiner la cause avant de la traduire. Une défaillance imprévue déjà levée remonte implicitement. Si elle est capturée, conserver sa cause dans le résultat jusqu'à la consommation finale, sans la requalifier en refus métier ni la relancer dans l'adaptation.
+
+## Consommer le résultat final
+
+Réserver `throw` et `OrThrow` au code qui décide de la conséquence finale : réponse, diagnostic ou interruption du programme. Une fonction appelée depuis cette frontière reste responsable de transmettre ses résultats.
+
+Au démarrage, une configuration invalide peut empêcher l'exécution : voir [l'initialisation](examples/environment-initialization.ts). Dans un test, `OrThrow` peut affirmer un résultat ou préparer une fixture ; le code testé conserve ses refus typés. Pour les constantes prouvables, préférer les [déclarations sûres](examples/safe-declarations.ts).

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).