useBulkOperationStatus

Overview

useBulkOperationStatus polls a bulk operation's status at a configurable interval. It calls GET {apiUrl}/bulk-operations/{operationId} repeatedly until the operation reaches a terminal status (completed or failed).

import { useBulkOperationStatus } from '@roomkit/react';

Usage

function ImportProgress({ operationId }: { operationId: string }) {
    const { data, isLoading } = useBulkOperationStatus({
        operationId,
        pollIntervalMs: 2000,
        onComplete: (op) => {
            console.log('Import finished:', op.processedItems, 'items');
        },
    });

    if (!data) return <div>Loading...</div>;

    const progress = data.totalItems > 0
        ? Math.round((data.processedItems / data.totalItems) * 100)
        : 0;

    return (
        <div>
            <p>Status: {data.status}</p>
            <progress value={data.processedItems} max={data.totalItems} />
            <p>{progress}% — {data.processedItems}/{data.totalItems} items</p>
            {data.conflictsDetected > 0 && (
                <p>{data.conflictsDetected} conflicts detected</p>
            )}
        </div>
    );
}

UseBulkOperationStatusOptions

interface UseBulkOperationStatusOptions {
    operationId: string;
    pollIntervalMs?: number;
    enabled?: boolean;
    onSuccess?: (data: BulkOperation) => void;
    onError?: (error: Error) => void;
    onComplete?: (data: BulkOperation) => void;
}

Option	Type	Required	Description
`operationId`	`string`	Yes	The bulk operation ID to poll
`pollIntervalMs`	`number`	No	Polling interval in milliseconds (default: `2000`)
`enabled`	`boolean`	No	Set to `false` to pause polling
`onSuccess`	`(data) => void`	No	Called on each successful poll
`onError`	`(error) => void`	No	Called when a poll request fails
`onComplete`	`(data) => void`	No	Called once when the operation reaches a terminal status

Return Value

Field	Type	Description
`data`	`BulkOperation \| null`	Latest operation status
`isLoading`	`boolean`	`true` while a poll request is in flight
`error`	`Error \| null`	The error if the last poll failed
`refetch`	`() => Promise<void>`	Manually trigger a poll

Polling automatically stops when the operation status is completed or failed.

API Endpoint

GET {apiUrl}/bulk-operations/{operationId}