Workers Frontend - Guide d'utilisation

Ce guide explique comment utiliser les hooks et composants frontend pour le polling des job runs.

Hooks disponibles

useJobRun(jobRunId, options?)

Hook principal pour récupérer et suivre un job run avec polling automatique.

Caractéristiques :

• Polling automatique toutes les 2 secondes (configurable)
• Arrête automatiquement le polling quand le job est terminé (COMPLETED, FAILED, CANCELED)
• Callbacks onComplete et onError disponibles

Exemple :

import { useJobRun } from "@/client/job-runs/useJobRuns";

function ExportStatus({ exportJobId }: { exportJobId: string }) {
  const { data: jobRun, isLoading, error } = useJobRun(exportJobId, {
    onComplete: (completedJobRun) => {
      console.log("Export completed!", completedJobRun.result);
      // Rediriger vers le fichier téléchargé
    },
    onError: (error) => {
      console.error("Export failed:", error);
    },
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  if (!jobRun) return <div>Job not found</div>;

  return (
    <div>
      <p>Status: {jobRun.status}</p>
      {jobRun.error && <p>Error: {jobRun.error}</p>}
      {jobRun.result && <p>Result: {JSON.stringify(jobRun.result)}</p>}
    </div>
  );
}

useJobRunStatus(jobRunId, options?)

Helper hook qui retourne le status et des flags booléens pratiques.

Retourne :

• status: Le status actuel (QUEUED | RUNNING | COMPLETED | FAILED | CANCELED | null)
• jobRun: L'objet job run complet
• isRunning: true si QUEUED ou RUNNING
• isCompleted: true si COMPLETED
• isFailed: true si FAILED
• isCanceled: true si CANCELED

Exemple :

import { useJobRunStatus } from "@/client/job-runs/useJobRuns";

function ExportButton({ exportJobId }: { exportJobId: string }) {
  const { status, isRunning, isCompleted, isFailed } = useJobRunStatus(exportJobId);

  return (
    <button disabled={isRunning}>
      {isRunning && "Exporting..."}
      {isCompleted && "Download"}
      {isFailed && "Retry"}
      {!status && "Export"}
    </button>
  );
}

useJobRunsByEntity(entityType, entityId, options?)

Récupère tous les job runs pour une entité spécifique (ex: tous les jobs pour un export).

Exemple :

import { useJobRunsByEntity } from "@/client/job-runs/useJobRuns";

function ExportHistory({ exportJobId }: { exportJobId: string }) {
  const { data: jobRuns } = useJobRunsByEntity("EXPORT", exportJobId);

  return (
    <ul>
      {jobRuns?.map((jobRun) => (
        <li key={jobRun.id}>
          {jobRun.job_name} - {jobRun.status}
        </li>
      ))}
    </ul>
  );
}

useIsJobRunning(jobRunId)

Helper simple qui retourne un booléen indiquant si le job est en cours.

Exemple :

import { useIsJobRunning } from "@/client/job-runs/useJobRuns";

function ExportButton({ exportJobId }: { exportJobId: string }) {
  const isRunning = useIsJobRunning(exportJobId);

  return (
    <button disabled={isRunning}>
      {isRunning ? "Exporting..." : "Export"}
    </button>
  );
}

Composants disponibles

JobRunStatusBadge

Badge qui affiche le status avec une icône et polling automatique.

Props :

• jobRunId: string | null - ID du job run
• showIcon?: boolean - Afficher l'icône (défaut: true)
• className?: string - Classes CSS supplémentaires

Exemple :

import { JobRunStatusBadge } from "@/components/job-runs/JobRunStatusBadge";

function ExportCard({ exportJobId }: { exportJobId: string }) {
  return (
    <div>
      <h3>Export #123</h3>
      <JobRunStatusBadge jobRunId={exportJobId} />
    </div>
  );
}

JobRunProgress

Barre de progression avec polling automatique et toasts.

Props :

• jobRunId: string | null - ID du job run
• onComplete?: (jobRun) => void - Callback quand le job est terminé
• onError?: (error) => void - Callback en cas d'erreur
• showToast?: boolean - Afficher des toasts (défaut: true)

Exemple :

import { JobRunProgress } from "@/components/job-runs/JobRunProgress";

function ExportModal({ exportJobId, onComplete }: Props) {
  return (
    <div>
      <h2>Exporting data...</h2>
      <JobRunProgress
        jobRunId={exportJobId}
        onComplete={(jobRun) => {
          // Télécharger le fichier
          window.location.href = jobRun.result?.downloadUrl;
          onComplete();
        }}
      />
    </div>
  );
}

Exemple complet : Export avec polling

import { useState } from "react";
import { useJobRunStatus } from "@/client/job-runs/useJobRuns";
import { JobRunProgress } from "@/components/job-runs/JobRunProgress";
import { api } from "@/client/api";

function ExportButton() {
  const [exportJobId, setExportJobId] = useState<string | null>(null);
  const { isCompleted, jobRun } = useJobRunStatus(exportJobId);

  const handleExport = async () => {
    try {
      // Enqueue export job via API
      const response = await api.post("/exports", {
        type: "CONTACTS",
        format: "CSV",
      });
      
      // Start polling
      setExportJobId(response.jobRunId);
    } catch (error) {
      console.error("Failed to start export:", error);
    }
  };

  const handleDownload = () => {
    if (jobRun?.result?.fileObjectId) {
      // Télécharger le fichier
      window.open(`/api/file-objects/${jobRun.result.fileObjectId}/download`);
    }
  };

  return (
    <div>
      {!exportJobId && (
        <button onClick={handleExport}>Export Contacts</button>
      )}
      
      {exportJobId && !isCompleted && (
        <JobRunProgress jobRunId={exportJobId} />
      )}
      
      {isCompleted && (
        <button onClick={handleDownload}>Download Export</button>
      )}
    </div>
  );
}

Configuration du polling

Par défaut, le polling s'arrête automatiquement quand le job est terminé. Vous pouvez configurer l'intervalle :

useJobRun(jobRunId, {
  refetchInterval: 5000, // Poll toutes les 5 secondes au lieu de 2
});

Pour désactiver le polling automatique :

useJobRun(jobRunId, {
  refetchInterval: false, // Pas de polling automatique
});

Types TypeScript

Tous les types sont exportés depuis @/client/job-runs/useJobRuns :

import type {
  JobRun,
  JobRunStatus,
  JobRunEntityType,
  JobRunsQueryParams,
} from "@/client/job-runs/useJobRuns";