Patterns d'intégration

Client ──POST /v1/classify/jobs──> API ──> Job cree
Client <── id ──────────────────────────────────┘

Client ──GET /v1/classify/jobs/:id──> API ──> Statut du job
Client <── status + result ────────────────────────────────┘

interface Ranking {
  rank: number;
  hs_code: string;
  description: string;
  confidence: number;
  gri_justification: string;
  validated: boolean;
}

interface ClassifyResult {
  classification: { rankings: Ranking[] };
  text: string;
  session_id: string;
}

interface JobResponse {
  id: string;
  status: 'pending' | 'processing' | 'completed' | 'failed';
  result?: ClassifyResult;
  error?: string;
}

class TradeHubClient {
  private baseUrl = 'https://api.thetradehub.eu/v1';
  private apiKey: string;

  constructor(apiKey: string) {
    this.apiKey = apiKey;
  }

  private async request<T>(path: string, options?: RequestInit): Promise<T> {
    const response = await fetch(`${this.baseUrl}${path}`, {
      ...options,
      headers: {
        'X-API-Key': this.apiKey,
        'Content-Type': 'application/json',
        ...options?.headers,
      },
    });

    if (!response.ok) {
      const error = await response.json().catch(() => ({}));
      throw new ApiError(response.status, error.detail ?? 'Unknown error');
    }

    return response.json() as Promise<T>;
  }

  async classify(
    content: string,
    options?: { originCountry?: string }
  ): Promise<ClassifyResult> {
    // 1. Créer le job
    const { id: job_id } = await this.request<{ id: string }>('/classify/jobs', {
      method: 'POST',
      body: JSON.stringify({
        content,
        origin_country: options?.originCountry,
      }),
    });

    // 2. Polling avec backoff exponentiel
    return this.pollResult(job_id);
  }

  private async pollResult(
    jobId: string,
    maxAttempts = 30,
    initialDelay = 500
  ): Promise<ClassifyResult> {
    let delay = initialDelay;

    for (let attempt = 0; attempt < maxAttempts; attempt++) {
      const job = await this.request<JobResponse>(`/classify/jobs/${jobId}`);

      if (job.status === 'completed' && job.result) {
        return job.result;
      }

      if (job.status === 'failed') {
        throw new Error(`Classification failed: ${job.error}`);
      }

      // Backoff exponentiel avec jitter
      await new Promise((resolve) =>
        setTimeout(resolve, delay + Math.random() * 200)
      );
      delay = Math.min(delay * 1.5, 5000); // Max 5 secondes entre les tentatives
    }

    throw new Error(`Classification timed out after ${maxAttempts} attempts`);
  }
}

class ApiError extends Error {
  constructor(
    public status: number,
    message: string
  ) {
    super(message);
    this.name = 'ApiError';
  }
}

import time
import random
import requests
from dataclasses import dataclass
from typing import Optional


@dataclass
class Ranking:
    rank: int
    hs_code: str
    description: str
    confidence: float
    gri_justification: str
    validated: bool

@dataclass
class ClassifyResult:
    rankings: list  # list[Ranking]
    text: str
    session_id: str


class ApiError(Exception):
    def __init__(self, status: int, message: str):
        self.status = status
        super().__init__(message)


class TradeHubClient:
    def __init__(self, api_key: str):
        self.base_url = "https://api.thetradehub.eu/v1"
        self.session = requests.Session()
        self.session.headers.update({
            "X-API-Key": api_key,
            "Content-Type": "application/json",
        })

    def classify(
        self,
        content: str,
        origin_country: Optional[str] = None,
    ) -> ClassifyResult:
        # 1. Créer le job
        payload = {"content": content}
        if origin_country:
            payload["origin_country"] = origin_country

        response = self.session.post(
            f"{self.base_url}/classify/jobs",
            json=payload,
        )
        response.raise_for_status()
        job_id = response.json()["id"]

        # 2. Polling avec backoff exponentiel
        return self._poll_result(job_id)

    def _poll_result(
        self,
        job_id: str,
        max_attempts: int = 30,
        initial_delay: float = 0.5,
    ) -> ClassifyResult:
        delay = initial_delay

        for _ in range(max_attempts):
            response = self.session.get(
                f"{self.base_url}/classify/jobs/{job_id}"
            )
            response.raise_for_status()
            data = response.json()

            if data["status"] == "completed":
                r = data["result"]
                return ClassifyResult(
                    rankings=r["classification"]["rankings"],
                    text=r.get("text", ""),
                    session_id=r.get("session_id", ""),
                )

            if data["status"] == "failed":
                raise ApiError(500, f"Classification failed: {data.get('error')}")

            # Backoff exponentiel avec jitter
            time.sleep(delay + random.uniform(0, 0.2))
            delay = min(delay * 1.5, 5.0)

        raise TimeoutError(f"Classification timed out after {max_attempts} attempts")

interface BatchItem {
  id: string;  // Votre identifiant interne
  content: string;
  origin_country?: string;
}

interface BatchResponse {
  batch_id: string;
  total_items: number;
  status: 'processing' | 'completed' | 'partial';
  results: Array<{
    id: string;
    status: 'completed' | 'failed';
    result?: ClassifyResult;
    error?: string;
  }>;
  progress: number;  // 0 à 1
}

async function classifyBatch(
  client: TradeHubClient,
  items: BatchItem[]
): Promise<BatchResponse> {
  // 1. Soumettre le batch
  const { id: batch_id } = await client.request<{ id: string }>(
    '/classify/batch',
    {
      method: 'POST',
      body: JSON.stringify({ items }),
    }
  );

  // 2. Polling du batch (intervalles plus longs)
  let delay = 2000;
  const maxAttempts = 60;

  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const batch = await client.request<BatchResponse>(
      `/classify/batch/${batch_id}`
    );

    if (batch.status === 'completed') {
      return batch;
    }

    console.log(`Batch progress: ${Math.round(batch.progress * 100)}%`);

    await new Promise((r) => setTimeout(r, delay));
    delay = Math.min(delay * 1.2, 10000);
  }

  throw new Error('Batch timed out');
}

// Utilisation
const items: BatchItem[] = [
  { id: 'SKU-001', content: 'Câble USB-C vers Lightning' },
  { id: 'SKU-002', content: 'Coque de protection iPhone 15 en silicone' },
  { id: 'SKU-003', content: 'Chargeur sans fil Qi 15W' },
];

const results = await classifyBatch(client, items);

async function withRetry<T>(
  fn: () => Promise<T>,
  options = { maxRetries: 3, initialDelay: 1000 }
): Promise<T> {
  let lastError: Error | undefined;
  let delay = options.initialDelay;

  for (let i = 0; i <= options.maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error as Error;

      // Ne pas retrier les erreurs client (4xx sauf 429)
      if (error instanceof ApiError && error.status < 500 && error.status !== 429) {
        throw error;
      }

      if (i < options.maxRetries) {
        await new Promise((r) => setTimeout(r, delay + Math.random() * 500));
        delay *= 2;
      }
    }
  }

  throw lastError;
}

// Utilisation
const result = await withRetry(() => client.classify('Mon produit'));
const topRanking = result.classification.rankings[0];
console.log(`Code HS: ${topRanking.hs_code} (confiance: ${topRanking.confidence})`);

class RateLimiter {
  private remaining: number;

  constructor(private limit: number = 10) {
    this.remaining = limit;
  }

  updateFromHeaders(headers: Headers): void {
    const remaining = headers.get('X-RateLimit-Remaining');
    if (remaining) this.remaining = parseInt(remaining, 10);
  }

  async waitIfNeeded(): Promise<void> {
    if (this.remaining <= 0) {
      // Fenêtre fixe de 1 minute - attendre le reset
      await new Promise((r) => setTimeout(r, 60_000));
      this.remaining = this.limit;
    }
    this.remaining--;
  }
}

// Enregistrer un webhook
await client.request('/webhooks', {
  method: 'POST',
  body: JSON.stringify({
    url: 'https://api.votredomaine.com/webhooks/tradehub',
    events: ['classification.completed', 'classification.failed'],
    secret: 'whsec_votre_secret_de_verification',
  }),
});

// Votre endpoint de réception
app.post('/webhooks/tradehub', (req, res) => {
  // Vérifier la signature
  const signature = req.headers['x-tradehub-signature'];
  const isValid = verifySignature(req.body, signature, webhookSecret);

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  const event = req.body;

  if (event.type === 'classification.completed') {
    processResult(event.data.job_id, event.data.result);
  }

  res.status(200).send('OK');
});