Construire un client CaptchaAI rapide avec le runtime Bun

Périmètre sûr : ce guide s'applique exclusivement à vos propres applications, à vos environnements de QA, de préproduction ou de production, ou à des systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne vise ni l'automatisation de sites tiers, ni l'évasion des protections anti-bot.

Bun démarre en quelques millisecondes et exécute TypeScript sans étape de compilation : deux atouts décisifs quand un client de résolution CAPTCHA tourne en boucle dans un job planifié. Ce guide montre comment construire un client CaptchaAI rapide sur le runtime Bun, puis le rendre stable pour la QA et la production.

Pourquoi choisir Bun pour ce client

Node.js reste valable, mais Bun offre un démarrage plus court, une compatibilité npm complète et le support natif de TypeScript — d'où des démarrages à froid plus rapides.

Le contrat de l'API ne change pas : le même code se transpose vers Node.js ou Deno sans réécriture.

Préparer l'environnement

Avant d'écrire la moindre ligne, isolez votre environnement de QA de la production, stockez la clé CaptchaAI dans un secret CI ou un coffre, et vérifiez que vos endpoints internes acceptent les requêtes de test. Épinglez aussi une version de Bun dans votre image Docker : un runtime figé rend vos exécutions reproductibles entre le poste et la CI.

Encapsuler l'appel à l'API CaptchaAI

Regroupez l'appel dans une fonction réutilisable : vos tests appellent une seule interface, et vous changez de type de CAPTCHA (reCAPTCHA v2, Cloudflare Turnstile, GeeTest v3) sans toucher au reste du code. Elle enchaîne quatre étapes :

1. Elle reçoit la sitekey et l'URL de votre propre application.
2. Elle soumet la tâche et récupère un identifiant.
3. Elle interroge le résultat jusqu'à obtenir le token.
4. Elle renvoie le token en traçant la durée et le code retour.

Exemple : créer une tâche Turnstile

L'exemple ci-dessous soumet une tâche Cloudflare Turnstile et renvoie l'identifiant à interroger ensuite :

import fetch from 'node-fetch';

const API_KEY = process.env.CAPTCHAAI_KEY;

export async function createTurnstileTask(siteKey, pageUrl) {
  const res = await fetch('https://api.captchaai.com/createTask', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      clientKey: API_KEY,
      task: {
        type: 'TurnstileTaskProxyless',
        websiteURL: pageUrl,
        websiteKey: siteKey,
      },
    }),
  });
  const data = await res.json();
  return data.taskId;
}

Vérifier le token côté backend

Le token renvoyé doit être validé par votre propre backend avant toute opération métier, sous peine d'accepter une requête sur un token périmé ou forgé. Appliquez-le dans la même session que le défi — mêmes cookies, même contexte HTTP.

Instrumenter et journaliser les appels

Instrumentez chaque appel CAPTCHA et corrélez chaque entrée à votre traçage distribué (OpenTelemetry, par exemple) pour rejouer un scénario. Tracez au minimum :

1. La durée d'obtention du token, pour repérer les lenteurs.
2. Le code retour HTTP, pour séparer panne réseau et rejet applicatif.
3. L'identifiant de tâche, pour isoler une exécution.
4. La taille de la file d'attente interne, signe d'un engorgement.

Côté RGPD, ne journalisez que le nécessaire — identifiant de tâche et horodatage, jamais de données personnelles.

Un exemple concret : un worker planifié en Europe

Prenez un worker Bun déployé sur OVHcloud ou Scaleway, en région Paris, qui traverse chaque nuit une étape protégée par un CAPTCHA dans votre propre application. L'enjeu n'est pas le premier passage, mais la tenue à travers déploiements, coupures réseau et changement de type de CAPTCHA.

Côté facturation, CaptchaAI applique un modèle par thread avec résolutions illimitées : votre coût dépend du nombre de tâches simultanées, pas du volume total.

Liste de contrôle avant la mise en production

Passez cette liste en revue avant chaque déploiement :

1. Le périmètre reste limité à vos propres applications ou à des sources autorisées.
2. La clé CaptchaAI vit dans un secret CI ou un coffre, jamais dans le code source.
3. La version de Bun est épinglée dans votre image et votre intégration continue.
4. Les durées d'appel et les codes retour sont tracés à chaque exécution.
5. Un retry idempotent avec backoff exponentiel borné couvre les erreurs transitoires.
6. Les tests sont rejouables depuis votre intégration continue.

FAQ

Pourquoi utiliser Bun plutôt que Node.js pour ce client ?

Pour le gain au démarrage et la simplicité : Bun démarre plus vite et exécute TypeScript sans étape de build, ce qui compte pour un job planifié relancé souvent. Le contrat de l'API CaptchaAI étant identique, vous pouvez rester sur Node.js.

Comment stocker la clé API CaptchaAI en toute sécurité ?

Placez-la dans un secret d'intégration continue ou un coffre (Vault, secrets GitHub Actions), puis lisez-la via une variable d'environnement au démarrage. Ne la committez jamais et faites-la tourner si elle a pu fuiter.

Que faire quand l'API renvoie une erreur transitoire ?

Appliquez un retry avec backoff exponentiel borné : trois tentatives, délai doublé à chaque essai, plafond à 30 secondes. Tracez chaque échec avec son identifiant. Si l'erreur persiste, vérifiez la configuration réseau (DNS, certificats) et le solde de votre clé.

Guides connexes

• Le démarrage rapide CaptchaAI
• La QA CAPTCHA en environnements autorisés
• Tester l'endpoint API sur vos formulaires
• Intégrer la résolution CAPTCHA en CI
• Résoudre reCAPTCHA v2 via l'API

Adoptez une approche méthodique et reproductible pour vos workflows CAPTCHA. – Obtenez votre clé CaptchaAI.