Bulk operation components

Create Bulk operations with a trusted server client. The React package reads progress, submits authorized cancellation, and exposes chunk-level delivery records.

Create on the server

const tenantIncld = new Incld({
 apiKey: process.env.INCLD_SECRET_KEY!,
 scope: { organizationId: session.organization.id },
})
const operation = await tenantIncld.bulkOperations.create(
 {
  action: "sync_contacts",
  items: contacts.map(contact => ({ id: contact.id })),
  chunkSize: 250,
  metadata: { importId },
 },
 { idempotencyKey: `contact-import:${importId}` },
)

Bulk creation is intentionally not in the browser proxy allowlist. Validate input and authorization in a Server Action or application route, scope the trusted client from the authenticated organization, then return only the new operation ID.

Component reference

Component	Props	Behavior
BulkProgress	operationId? or operation?; cancellable=false; onCancelled?; className?; loading?; error?	Passing operation avoids the initial fetch. Polls while non-terminal and renders optional cancellation.
BulkOperationList	filters?; onSelect?(id); className?; loading?; empty?; error?	Lists operation action, item count, status, and percentage. onSelect receives the string ID, not the operation.
BulkOperationDetails	operationId; className?	Composes cancellable progress, up to 100 chunks, and up to 100 events.

Operation inspector

function BulkOperations() {
 const [selected, setSelected] = useState<string>()
 return (
  <>
   <BulkOperationList
    filters={{ action: "sync_contacts" }}
    onSelect={setSelected}
   />
   {selected && <BulkOperationDetails operationId={selected} />}
  </>
 )
}

Hooks and polling

useBulkOperations(params?: ListBulkOperationsParams)

Lists by status, action, limit, and cursor.

Returns AsyncState<Page<BulkOperation>>

useBulkOperation(id?, pollInterval=2000)

Adds a faster active-operation poll while visible and non-terminal; the provider interval keeps surrounding lists and inspection data current.

Returns AsyncState<BulkOperation | undefined>

useBulkChunks(id?) / useBulkEvents(id?)

Loads the first 100 inspection records.

Returns AsyncState<Page<BulkChunk | BulkEvent>>

useBulkOperationMutation()

Cancels an operation through the trusted proxy and refreshes provider consumers.

Returns {cancel, pending, error}

Terminal states

Status	Meaning
succeeded	Every chunk completed successfully.
completed_with_errors	Delivery is complete and at least one chunk failed permanently.
cancelled	No new queued chunks will be delivered; already-running work may finish.
queued / running	Non-terminal; BulkProgress continues polling.

Generated TypeScript signatures

Interface	Prop	Type	Required
BulkOperationDetailsProps	operationId	string	Yes
BulkOperationDetailsProps	className	string	No
BulkOperationListProps extends AsyncViewProps	filters	ListBulkOperationsParams	No
BulkOperationListProps extends AsyncViewProps	onSelect	(id: string) => void	No
BulkOperationListProps extends AsyncViewProps	className	string	No
BulkProgressProps extends AsyncViewProps	operationId	string	No
BulkProgressProps extends AsyncViewProps	operation	BulkOperation	No
BulkProgressProps extends AsyncViewProps	cancellable	boolean	No
BulkProgressProps extends AsyncViewProps	onCancelled	() => void	No
BulkProgressProps extends AsyncViewProps	className	string	No