http.ts
Source : sdks/typescript/packages/sdk/src/http.ts. Retour à l'index de la référence du SDK TypeScript.
Cette page est générée par tools/docs/gen_sdk_reference.py depuis les sources du SDK et les dossiers de textes OpenAPI. Ne la modifiez pas à la main : changez la source et régénérez.
Alias de type FetchLike
Signature d'une fonction fetch : URL et options en entrée, Response en sortie.
Définition : (input: string, init?: RequestInit) => Promise<Response>.
Alias de type HttpMethod
GET, POST, PUT, PATCH ou DELETE.
Définition : "GET" \| "POST" \| "PUT" \| "PATCH" \| "DELETE".
Alias de type QueryValue
Valeur d'un paramètre de requête ; null et undefined sont omis et un tableau répète le paramètre.
Définition : string \| number \| boolean \| null \| undefined \| string[].
Interface ClientOptions
Options du client HTTP : URL de base, identifiants, en-têtes du mode dev, nouvelles tentatives, délai d'expiration et fetch.
Champs :
| Nom | Type | Requis | Description |
|---|---|---|---|
baseUrl | string | oui | URL de base du Control Plane, par exemple <control-plane-url> (sans /v1). |
apiKey | string | non | Clé d'API du tenant, envoyée en X-API-Key. |
token | string | (() => string | Promise<string>) | non | Jeton d'accès au Hub. En écriture seule, scellé ; nul conserve le jeton enregistré. |
tenant | string | non | Identifiant court du locataire. |
devUser | string | non | Identifiant utilisateur du mode dev, envoyé en X-Dev-User. |
devRoles | string[] | non | Rôles du mode dev, envoyés en X-Dev-Roles. |
project | string | non | Identifiant du projet auquel les résultats sont limités. |
environment | "dev" | "test" | "staging" | "prod" | (string & {}) | non | Environnement (dev, test, staging, prod ou un autre nom), envoyé en X-Environment. |
locale | Locale | non | Langue des messages, en (par défaut) ou fr, également envoyée en Accept-Language. |
fetch | FetchLike | non | Implémentation de fetch à utiliser ; par défaut, le fetch global. |
retries | number | non | Nombre de nouvelles tentatives sur 429, 5xx et erreurs réseau (2 par défaut). |
retryBaseDelayMs | number | non | Délai de base de l'attente exponentielle en ms (300 par défaut). |
retryMaxDelayMs | number | non | Délai maximal entre deux tentatives en ms (20000 par défaut). |
timeoutMs | number | non | Délai d'expiration par requête en ms (60000 par défaut, 0 le désactive). |
headers | Record<string | non | En-têtes de l'événement, valeurs textuelles. Le contexte de trace y est ajouté. |
sleep | (ms: number) => Promise<void> | non | Fonction d'attente utilisée entre les tentatives (injectable pour les tests). |
Interface RequestOptions
Options d'une requête : paramètres de chemin, requête, corps, en-têtes, clé d'idempotence, trace, signal et type de réponse.
Champs :
| Nom | Type | Requis | Description |
|---|---|---|---|
params | Record<string | non | Valeurs des emplacements {name} de la route. |
query | Record<string | non | Paramètres de la chaîne de requête ; les valeurs undefined et null sont omises, un tableau répète le paramètre. |
body | unknown | non | Corps de la requête : envoyé en JSON, ou tel quel pour FormData, Blob, ArrayBuffer et URLSearchParams. |
headers | Record<string | non | En-têtes de l'événement, valeurs textuelles. Le contexte de trace y est ajouté. |
idempotencyKey | string | non | Idempotency-Key d'un POST ; une clé aléatoire est générée en son absence. |
traceparent | string | non | En-tête W3C traceparent à envoyer ; un nouveau est généré en son absence. |
signal | AbortSignal | non | AbortSignal qui annule la requête. |
responseType | "json" | "text" | "binary" | "stream" | non | Traitement de la réponse : json (par défaut), text, binary, stream (Response brute). |
noRetry | boolean | non | Désactive les nouvelles tentatives pour cet appel. |
Interface ApiResponse
Corps décodé d'une réponse avec son statut HTTP, ses en-têtes et l'identifiant de la requête.
Champs :
| Nom | Type | Requis | Description |
|---|---|---|---|
data | T | oui | Corps décodé de la réponse. |
status | number | oui | Statut HTTP de la réponse. |
headers | Headers | oui | En-têtes de l'événement, valeurs textuelles. Le contexte de trace y est ajouté. |
requestId | string | undefined | oui | Valeur de l'en-tête de réponse x-request-id. |
Classe HttpClient
Transport HTTP du SDK : construit l'URL et les en-têtes, réessaie sur 429, 5xx et erreurs réseau, et convertit les erreurs en classes typées.
Attributs :
| Nom | Type | Requis | Description |
|---|---|---|---|
baseUrl | string | oui | URL de base sans ses barres obliques finales. |
locale | Locale | oui | Langue des messages et de Accept-Language. |
Constructeur HttpClient
new HttpClient(opts: ClientOptions)
Vérifie l'URL de base et l'implémentation de fetch ; lève missing_base_url, no_fetch ou TypeError sur une URL incorrecte.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
opts | ClientOptions | oui | Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes). |
HttpClient.headers
async headers(method: HttpMethod, o: RequestOptions): Promise<Record<string, string>>
Construit les en-têtes d'une requête : Accept, Accept-Language, traceparent, identifiants, mode dev, projet, environnement et Idempotency-Key sur POST.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
method | HttpMethod | oui | Méthode HTTP ; un POST reçoit un Idempotency-Key. | |
o | RequestOptions | oui | Options de l'appel (clé d'idempotence, traceparent, en-têtes). |
Retour : Promise<Record<string, string>>. Les en-têtes, ceux des options de la requête en dernier.
HttpClient.raw
async raw(method: HttpMethod, template: string, o: RequestOptions = {}): Promise<ApiResponse<T>>
Exécute une requête et renvoie le corps décodé avec le statut et les en-têtes.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
method | HttpMethod | oui | Méthode HTTP de la requête. | |
template | string | oui | Route relative à l'URL de base, dont les emplacements {name} sont remplis à partir de params. | |
o | RequestOptions | {} | non | Options de l'appel (clé d'idempotence, traceparent, en-têtes). |
Retour : Promise<ApiResponse<T>>. Corps, statut, en-têtes et identifiant de requête ; lève l'EaiError typée sur un statut d'erreur.
Erreurs levées : EaiError.
HttpClient.request
async request(method: HttpMethod, template: string, o: RequestOptions = {}): Promise<T>
Exécute une requête et ne renvoie que le corps décodé.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
method | HttpMethod | oui | Méthode HTTP de la requête. | |
template | string | oui | Route relative à l'URL de base, dont les emplacements {name} sont remplis à partir de params. | |
o | RequestOptions | {} | non | Options de l'appel (clé d'idempotence, traceparent, en-têtes). |
Retour : Promise<T>. Corps décodé de la réponse.
HttpClient.toJSON
toJSON(): Record<string, unknown>
N'expose jamais la clé d'API ni le jeton (console.log, JSON.stringify, util.inspect).
Cet élément ne prend aucun paramètre.
Retour : Record<string, unknown>. URL de base, langue, et la clé d'API et le jeton masqués.
HttpClient.transfer
async transfer(url: string, init: RequestInit): Promise<Response>
Transfert vers ou depuis une URL de stockage présignée : le fetch configuré, sans aucun identifiant de la plateforme.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
url | string | oui | URL de stockage présignée. | |
init | RequestInit | oui | Options fetch du transfert (méthode, corps, en-têtes) ; les redirections ne sont pas suivies. |
Retour : Promise<Response>. La réponse ; un statut de 300 ou plus lève storage_transfer_failed.
Erreurs levées : EaiError.
HttpClient.url
url(template: string, params?: Record<string, string | number>, query?: Record<string, QueryValue>): string
Construit l'URL complète d'une route.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
template | string | oui | Route relative à l'URL de base, avec des emplacements {name}. | |
params | Record<string, string | number> | non | Champs supplémentaires fusionnés dans la requête. | |
query | Record<string, QueryValue> | non | Paramètres de la chaîne de requête de la route. |
Retour : string. URL de base, chemin rempli et chaîne de requête.
Fonctions
isLocalHost
isLocalHost(host: string): boolean
Vrai pour localhost, 127.0.0.1 et ::1.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
host | string | oui | Nom d'hôte à vérifier, sans tenir compte de la casse. |
Retour : boolean. Vrai pour un hôte local.
validateBaseUrl
validateBaseUrl(raw: string): URL
Lève une erreur sauf si l'URL est en https, ou en http sur un hôte local, sans identifiants intégrés.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
raw | string | oui | Renvoie une ApiResponse (données, statut, en-têtes) au lieu du corps décodé. |
Retour : URL. L'URL analysée ; lève TypeError sinon.
Erreurs levées : TypeError.
validateWsUrl
validateWsUrl(raw: string): string
Lève une erreur sauf si l'URL est en wss, ou en ws sur un hôte local.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
raw | string | oui | Renvoie une ApiResponse (données, statut, en-têtes) au lieu du corps décodé. |
Retour : string. L'URL inchangée ; lève TypeError sinon.
Erreurs levées : TypeError.
generateTraceparent
generateTraceparent(): string
Valeur d'en-tête W3C trace context : version 00, identifiants de trace et de parent aléatoires, échantillonné.
Cet élément ne prend aucun paramètre.
Retour : string. Une valeur d'en-tête de la forme 00-<trace id>-<parent id>-01.
generateId
generateId(): string
Identifiant RFC 4122 version 4, utilisé pour Idempotency-Key.
Cet élément ne prend aucun paramètre.
Retour : string. Une chaîne UUID aléatoire.
parseRetryAfter
parseRetryAfter(value: string | null, now = Date.now()): number | undefined
Convertit Retry-After (secondes ou date HTTP) en millisecondes.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
value | string | null | oui | Valeur de l'en-tête Retry-After. | |
now | Date.now() | non | Heure courante en millisecondes, utilisée pour une date HTTP (Date.now() par défaut). |
Retour : number \| undefined. Délai en millisecondes, au moins 0, ou undefined quand la valeur est absente ou illisible.
fillPath
fillPath(template: string, params: Record<string, string | number> = {}): string
Remplit les emplacements {name}. L'emplacement {path} garde ses barres obliques.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
template | string | oui | Route avec des emplacements {name} ; une valeur manquante lève TypeError. | |
params | Record<string, string | number> | {} | non | Champs supplémentaires fusionnés dans la requête. |
Retour : string. La route avec les valeurs encodées pour l'URL.
Erreurs levées : TypeError.
buildQuery
buildQuery(query: Record<string, QueryValue> = {}): string
Construit une chaîne de requête à partir d'une table, en omettant null et undefined et en répétant les valeurs de tableau.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
query | Record<string, QueryValue> | {} | non | Paramètres de la chaîne de requête de la route. |
Retour : string. La chaîne de requête commençant par ?, ou une chaîne vide.