@bluecopa/react

A Comprehensive React Query Integration for Bluecopa

A React library of opinionated hooks that wrap @bluecopa/core with TanStack React Query — efficient data fetching, caching, and mutations against the Bluecopa platform, fully typed.

Table of Contents

• Features
• Installation
• Usage
  • Query Provider Setup
  • Boilerplate Integration
  • Hook Examples
• Detailed Reference — Common Hooks
• Complete Hook Reference
• Configuration
• Advanced Usage
• Re-exports
• TypeScript Support
• Development

Features

• ✅ First-class TypeScript with strict types
• 🔁 TanStack React Query v5 integration (queries, mutations, and headless controllers)
• 🛡 Consistent error handling — errors normalise to { message, status }
• ⚙ Sensible default query configuration
• 📦 Re-exports core TanStack React Query utilities and devtools
• 🧩 Coverage across every Bluecopa domain: datasets, input tables, workbooks, worksheets, pipelines, recon (v1 + v2), solutions, versioning, inbox, process/process-tree, TCN, and the curated api/hub

Installation

npm install @bluecopa/react
# or
pnpm add @bluecopa/react

Peer Dependencies

npm install react@^18.0.0 react-dom@^18.0.0

Also install TanStack React Query if you set up the QueryClient yourself:

npm install @tanstack/react-query

Usage

Query Provider Setup

Wrap your application with the React Query provider and configure the core SDK once:

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { copaSetConfig } from "@bluecopa/react";

copaSetConfig({
  apiBaseUrl: "https://develop.bluecopa.com/api/v1",
  workspaceId: "my-workspace-id",
  accessToken: "my-access-token",
});

const queryClient = new QueryClient({
  defaultOptions: {
    queries: { staleTime: 60 * 1000, refetchOnWindowFocus: false },
  },
});

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <YourApp />
    </QueryClientProvider>
  );
}

copaSetConfig, copaGetConfig, and the reactQuery / ReactQueryDevtools namespaces are re-exported from @bluecopa/react (see Re-exports).

Boilerplate Integration

For projects generated by create-bluecopa-react-app, use a pre-configured QueryProvider that wires config from env vars:

// src/providers/query-provider.tsx
import { ReactQueryDevtools, reactQuery, copaSetConfig } from "@bluecopa/react";
import { useEffect, useState } from "react";

const { QueryClient, QueryClientProvider } = reactQuery;

export default function QueryProvider({
  children,
}: {
  children: React.ReactNode;
}) {
  const [queryClient] = useState(
    () =>
      new QueryClient({
        defaultOptions: {
          queries: { staleTime: 60 * 1000, refetchOnWindowFocus: false },
        },
      }),
  );

  useEffect(() => {
    let copaUser: any = {};
    try {
      const copaToken = import.meta.env.VITE_BLUECOPA_API_TOKEN
        ? atob(import.meta.env.VITE_BLUECOPA_API_TOKEN)
        : "{}";
      copaUser = JSON.parse(copaToken);
    } catch (error) {
      console.warn("Failed to parse VITE_BLUECOPA_API_TOKEN:", error);
    }

    copaSetConfig({
      apiBaseUrl:
        import.meta.env.VITE_BLUECOPA_API_URL ||
        "https://develop.bluecopa.com/api/v1",
      workspaceId: import.meta.env.VITE_BLUECOPA_WORKSPACE_ID || "",
      accessToken: copaUser?.accessToken || "",
    });
  }, []);

  return (
    <QueryClientProvider client={queryClient}>
      {children}
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  );
}

Environment Variables:

| Variable | Description | Example | | ---------------------------- | --------------------------------------------------- | ------------------------------------- | | VITE_BLUECOPA_API_URL | Base URL for the Bluecopa API (include /api/v1) | https://develop.bluecopa.com/api/v1 | | VITE_BLUECOPA_WORKSPACE_ID | Your workspace identifier | my-workspace-123 | | VITE_BLUECOPA_API_TOKEN | Base64-encoded JSON string containing accessToken | eyJhY2Nlc3NUb2tlbiI6IjEyMzQ1In0= |

Security: any VITE_* variable is inlined into the browser bundle at build time, and Base64 is encoding, not encryption. VITE_BLUECOPA_API_TOKEN must be a scoped, non-secret client credential (least-privilege, with a rotation plan) — never a long-lived or privileged secret.

Hook Examples

import { useUser } from "@bluecopa/react";

function UserProfile() {
  const { data, isLoading, error } = useUser({
    staleTime: 5 * 60 * 1000,
    retry: 2,
  });
  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  return <div>Welcome, {data?.name}!</div>;
}

import { useRows } from "@bluecopa/react";

function TableRows({ tableId }) {
  const { data, isLoading } = useRows(tableId, {
    status: "active",
    price: "gte.100",
    limit: 25,
    offset: 0,
  });
  if (isLoading) return <div>Loading rows...</div>;
  return <div>Total: {data?.total_count ?? 0}</div>;
}

📖 For useRows filtering, pagination, and operator details, see docs/useRows.md.

Detailed Reference — Common Hooks

Query hooks return { data, isLoading, error, refetch, ... } (TanStack useQuery). Mutation hooks return { mutate, mutateAsync, isPending, data, error, isError, isSuccess, reset } (TanStack useMutation) and accept UseMutationOptions (onSuccess, onError, onSettled, retry, …).

useUser(options?)

Fetches the authenticated user. options extends UseQueryOptions.

useDataset(datasetId, options?)

Fetches a dataset by id. options accepts limit and standard query options.

useDatasetSample(datasetId, options?)

Fetches a representative sample of dataset rows. Supports enabled.

useMetric(metricId, options?)

Fetches computed metric data by id.

useInputTable(inputTableId, inputTableViewId, options?)

Fetches an input table for a given view. options accepts limitParams (limit, limitFrom: 'top' | 'bottom').

useRows(tableId, options?)

Fetches input-table rows with Supabase/PostgREST-style filtering, paging, and sorting. options merges filter fields (e.g. status: 'active', price: 'gte.100', status: 'in.(a,b)'), or/and group expressions, limit, offset, order, order_by, and query options. Returns { data, count, total_count }. See docs/useRows.md.

useGetWorkbooksByType(type, options?)

Lists workbooks of a given type.

useTriggerWorkflow(options?) / useTriggerHttpWorkflow(options?)

Mutations that trigger a workflow (or HTTP-trigger workflow) run. Call mutate(variables).

useSaveWorkbook(options?) / usePublishWorkbook(options?)

Mutations to save a draft or publish a workbook.

Complete Hook Reference

Every exported hook, grouped by domain. Legend: query = read (useQuery), mutation = write (useMutation), controller = composite/headless hook combining queries, mutations, and local state. Hooks suffixed with (hub) target the curated /blui-api surface.

User & Teams

• useUser(options?) — query — current authenticated user.
• useUserDetails(options?) — query — alias of useUser.
• useGetAllUsers(options?) — query — all users in the workspace.
• useGetAllTeams(options?) — query — all teams in the workspace.

Dataset

• useDataset(datasetId, options?) — query — a dataset by id.
• useGetDatasets() — query — all datasets.
• useDatasetSample(datasetId, options?) — query — a sample of dataset rows.
• useGetVirtualDatasets() — query — all virtual datasets.

Datasets Hub

• useDatasetSchema(datasetId, options?) — query (hub) — a dataset's schema.
• useSearchDatasets(query, options?) — query (hub) — search datasets by text.
• useDatasetStats(datasetId, columns?, options?) — query (hub) — column statistics.

Virtual Datasets Hub

• useListVirtualDatasets(query?, options?) — query (hub) — list virtual datasets.
• useGetVirtualDataset(virtualDatasetId, options?) — query (hub) — one virtual dataset.
• useCreateVirtualDataset(options?) — mutation (hub) — create a virtual dataset.

Metric

• useMetric(metricId, options?) — query — a metric by id.

Input Table

• useInputTable(inputTableId, inputTableViewId, options?) — query — an input table for a view.
• useGetInputTables() — query — all input tables.
• useGetTableById(tableId, options?) — query — a table by id.
• useRows(tableId, options?) — query — rows for a table (filters/paging/sorting).
• useInsertRow(options?) — mutation — insert a row.
• useUpdateRow(options?) — mutation — update a row.
• useDeleteRow(options?) — mutation — delete a row.

Input Tables Hub

• useListInputTables(query?, options?) — query (hub) — list input tables.
• useGetInputTable(inputTableId, options?) — query (hub) — one input table.
• useInputTableSchema(ref, options?) — query (hub) — an input table's schema.
• useReadInputTableRows(ref, options?) — query (hub) — read rows.
• useInsertInputTableRows(ref, options?) — mutation (hub) — bulk-insert rows.
• useUpdateInputTableRows(ref, options?) — mutation (hub) — bulk-update rows.
• useDeleteInputTableRows(ref, options?) — mutation (hub) — bulk-delete rows.
• useCreateInputTable(options?) — mutation (hub) — create an input table.
• useDeleteInputTable(ref, options?) — mutation (hub) — delete an input table.

Workbook

• useGetWorkbookDetails(workbookId, options?) — query — full workbook details.
• useGetWorkbooksByType(type, options?) — query — workbooks of a type.
• useGetPublishedWorkbookById(type, id, options?) — query — a published workbook.
• useSaveWorkbook(options?) — mutation — save/update a workbook.
• usePublishWorkbook(options?) — mutation — publish a workbook.
• useDeleteWorkbook(options?) — mutation — delete a workbook.
• useCreateWorkbook(options?) — mutation — create a workbook.

Workbooks Hub

• useListWorkbooks(query?, options?) — query (hub) — list workbooks.
• useGetWorkbook(workbookId, options?) — query (hub) — one workbook.

Worksheet / Views

• useGetWorksheets(worksheetIds, options?) — query — worksheets by ids.
• useGetWorksheetsByType(type, options?) — query — worksheets of a type.
• useGetViewById(viewId, options?) — query — a view by id.
• useGetViewsBySheetId(sheetId, options?) — query — views for a sheet.
• useGetRunsByViewId(viewId, options?) — query — runs for a view.
• useGetRunResultById(runId, options?) — query — a run result by id.

Workflow

• useTriggerWorkflow(options?) — mutation — trigger a workflow run.
• useTriggerHttpWorkflow(options?) — mutation — trigger an HTTP-trigger workflow.
• useGetWorkflowInstanceStatusById(options?) — mutation — workflow instance status (request-based).
• useGetAllHttpTriggers(options?) — query — all HTTP triggers.

Workflows Hub

• useListWorkflows(query?, options?) — query (hub) — list workflows.
• useGetWorkflow(workflowId, options?) — query (hub) — one workflow.
• useSaveWorkflow(options?) — mutation (hub) — save/update a workflow.

HTTP Triggers Hub

• useListHttpTriggers(query?, options?) — query (hub) — list HTTP triggers.
• useGetHttpTrigger(triggerId, options?) — query (hub) — one HTTP trigger.

Definitions (Pipeline runs)

• useRunDefinition(options?) — mutation — run a definition.
• useRunPublishedDefinition(options?) — mutation — run a published definition.
• useRunSampleDefinition(options?) — mutation — run a definition against a sample.

Recon (v1)

• useRunRecon(options?) — mutation — run a reconciliation.
• useGetAllRecon(options?) — query — all recon workflows.

Recon V2

• useCreateReconV2(options?) — mutation — create a workflow.
• useUpdateReconV2(options?) — mutation — update a workflow.
• useDeleteReconV2(options?) — mutation — delete a workflow.
• useRunReconV2(options?) — mutation — run a workflow.
• useGetAllReconV2(options?) — query — all workflows.
• useGetReconV2Runs(workflowId, options?) — query — runs for a workflow.
• useReconV2Templates(options?) — query — template catalog.
• useGetReconV2RunResult(runId, options?) — query — a run's result.
• useGetReconV2SmartResult(params, options?) — query — smart-match results.
• useStartReconV2Profile(options?) — mutation — start a profiling job.
• useGetReconV2ProfileResult(workflowId, side?, options?) — query — profile results.
• useStartReconV2Clean(options?) — mutation — start a clean job.
• useGetReconV2CleanResult(workflowId, side?, options?) — query — clean results.
• useGetReconV2Diff(runId, workflowId, prevRunId, options?) — query — diff between runs.
• useGetReconV2Explanation(runId, workflowId, options?) — query — AI explanation for a run.
• useReconV2RunStatus(runId, options?) — controller — poll a run's status.
• useGetReconV2Workflow(id, options?) — query — a single workflow.
• useReconV2List(filter?, options?) — controller — list with filtering state.
• useReconV2Detail(id, options?) — controller — load/manage a workflow's detail.
• useReconV2Editor() — controller — create/update editor.
• useReconV2RunController(workflowId, options?) — controller — trigger + track a run.
• useReconV2Results({ runId, workflowId, exceptionType, ruleFilter, orderBy }) — controller — fetch/filter run results.

Statement

• useGetStatementData(statementId, viewId?, runId?, options?) — query — statement data.
• useCreateStatementRun(options?) — mutation — create a statement run.

Chat

• useCreateThread(options?) — mutation — create a thread.
• useGetCommentsByThreadId(threadId, options?) — query — comments for a thread.
• usePostComment(options?) — mutation — post a comment.
• useUpdateComment(options?) — mutation — update a comment.
• useDeleteComment(options?) — mutation — delete a comment.
• useSubscribeUser(options?) — mutation — subscribe a user to a thread.
• useUnsubscribeUser(options?) — mutation — unsubscribe a user.
• useCheckSubscriptionStatus(userId, threadId, options?) — query — subscription status.

Email Engine

• useGetAllConversations(params?, options?) — query — list conversations (paged).
• useGetConversation(conversationId, options?) — query — one conversation.
• useCreateConversation(options?) — mutation — create a conversation.
• useReplyToConversation(options?) — mutation — reply to a conversation.
• useFilterMessagesBySenderId(params, options?) — query — messages by sender id.
• useSearchMessages(options?) — mutation — search messages (request-based).

Files

• useFileUpload(options?) — mutation — upload a file.
• useFileDownload({ fileId, contentType, method }) — query — download a file.
• useGetFileById(id, options?) — query — a filebox file by id.
• useGetFileByFolderIdAndName(folderId, name, options?) — query — a file by folder + name.
• useGetFileUrlByFileId(key, contentType, method, options?) — query — presigned URL for a file.

Forms

• useGetFormSchema(formInstanceId, formRevision, options?) — query — a form schema.
• useGetFormData(formId, options?) — query — submitted form data.
• useGetFormById(formId, options?) — query — a form by id.
• useCreateOrUpdateForm(options?) — mutation — create/update a form.

Audit

• useGetAuditLogs(options?) — mutation — fetch audit logs (request-based).
• useCreateAuditLog(options?) — mutation — create an audit log entry.

Task

• useGetTaskDetails(taskId, options?) — query — task details.
• useMarkTaskDone(options?) — mutation — mark a task done.
• useReassignTask(options?) — mutation — reassign a task.

Templated Pipeline & Templates

• useGetAllTemplatedPipelines(options?) — query — all templated pipelines.
• useRenderTemplate(options?) — mutation — render a template.

Process (triggers & schedules)

• useGetTriggersBySheet(sheetId, options?) — query — triggers for a sheet.
• useRegisterProcessTrigger(options?) — mutation — register a trigger.
• useDeleteProcessTrigger(options?) — mutation — delete a trigger.
• usePauseSchedule(options?) — mutation — pause a schedule.
• useResumeSchedule(options?) — mutation — resume a schedule.
• useGetScheduleStatus(triggerId, scheduleName, options?) — query — schedule status.
• useExecuteNow(options?) — mutation — execute a schedule immediately.

Process Triggers Hub

• useRegisterTrigger(options?) — mutation (hub) — register a trigger.
• useDeleteTrigger(options?) — mutation (hub) — delete a trigger.
• useExecuteTriggerNow(options?) — mutation (hub) — execute a trigger now.
• usePauseTrigger(options?) — mutation (hub) — pause a trigger.
• useResumeTrigger(options?) — mutation (hub) — resume a trigger.
• useSkipTrigger(options?) — mutation (hub) — skip next execution.
• useTriggerScheduleStatus(triggerId, options?) — query (hub) — trigger schedule status.
• useUpcomingSchedules(triggerId, options?) — query (hub) — upcoming scheduled runs.
• useTriggersBySheet(sheetId, options?) — query (hub) — triggers for a sheet.

Process Sheets Hub

• useSheetRuns(sheetId, options?) — query (hub) — runs for a process sheet.
• useSheetRunStatus(sheetId, options?) — query (hub) — a sheet's run status.

Process Tree

• useCreateOrUpdateProcessTreeTrigger(options?) — mutation — create/update a trigger.
• useExecuteProcessTreeTrigger(options?) — mutation — execute a trigger.
• useTerminateProcessTreePipelines(options?) — mutation — terminate running pipelines.
• useLogProcessTreeRun(options?) — mutation — log a run.
• useUpdateProcessTreeRunContext(options?) — mutation — update a run's context.
• useDeleteProcessTreeTrigger(options?) — mutation — delete a trigger.
• useGetProcessTreeTrigger(id, options?) — query — a trigger by id.
• useGetProcessTreeTriggersBySheetId(sheetId, options?) — query — triggers for a sheet.
• useGetProcessTreeRunsBySheetId(sheetId, options?) — query — runs for a sheet.
• useGetProcessTreeRunsBySheetIdPaginated(sheetId, query?, options?) — query — runs for a sheet (paged).
• useGetProcessTreeRunByInstanceId(instanceId, options?) — query — a run by instance id.

Custom Authorization

• useCustomAuthzModel(options?) — query — the custom authz model.
• useRegisterCustomAuthzModel(options?) — mutation — register a model.
• useUpdateCustomObjectPermissions(options?) — mutation — update object permissions.
• useBulkUpdateCustomObjectPermissions(options?) — mutation — bulk-update permissions.
• useCheckCustomPermissions(options?) — mutation — check permissions.
• useBulkCheckCustomPermissions(options?) — mutation — bulk-check permissions.

Permissions

• useDocumentPermissions(objectId, objectType, options?) — query — permissions for a document/object.

Inbox (v1)

• useGetAllInboxItems(params?, options?) — query — all inbox items (paged).
• useMarkItemAsRead(options?) — mutation — mark an item read.
• useMarkItemAsUnread(options?) — mutation — mark an item unread.
• useCreateInboxItemPerUser(options?) — mutation — create an item per user.

Inbox V2 / TaskQueue

• useListInboxTypes(options?) — query — inbox item types.
• useGetInboxType(id, options?) — query — one item type.
• useCreateInboxType(options?) — mutation — create an item type.
• useUpdateInboxType(options?) — mutation — update an item type.
• useDeleteInboxType(options?) — mutation — delete an item type.
• useListMyInboxItems(params?) — query — the current user's items (paged).
• useGetInboxItem(id, options?) — query — one item.
• useCreateInboxItem(options?) — mutation — create items.
• useUpdateInboxItem(options?) — mutation — update an item.
• useMarkInboxItemsRead(options?) / useMarkInboxItemsUnread(options?) — mutation — mark items read/unread.
• useSnoozeInboxItem(options?) / useDismissInboxItem(options?) — mutation — snooze/dismiss.
• useClaimInboxItem(options?) / useCompleteInboxItem(options?) / useReleaseInboxItem(options?) — mutation — claim/complete/release.
• useCancelInboxItem(options?) / useReassignInboxItem(options?) — mutation — cancel/reassign.
• useCompleteInboxItemsByKey(options?) / useCancelInboxItemsByKey(options?) — mutation — complete/cancel by key.

TCN (Telephony)

• useTcnAuthUrl(options?) — query — OAuth authorization URL.
• useTcnExchangeCode(options?) / useTcnRefreshToken(options?) — mutation — token exchange/refresh.
• useTcnCurrentAgent(options?) — mutation — current agent (token-based).
• useTcnAgentSkills(options?) — mutation — agent hunt-group skills.
• useTcnCreateSession(options?) / useTcnKeepAlive(options?) — mutation — session lifecycle.
• useTcnAgentGetStatus(options?) / useTcnAgentSetReady(options?) / useTcnAgentPause(options?) / useTcnAgentDisconnect(options?) — mutation — agent state.
• useTcnHuntGroupSettings(options?) — mutation — hunt-group settings.
• useTcnConnectedParty(options?) / useTcnCallData(options?) — mutation — connected party / call data.
• useTcnAgentPutCallOnHold(options?) / useTcnAgentGetCallFromHold(options?) — mutation — hold control.
• useTcnDialManualPrepare(options?) / useTcnManualDialStart(options?) / useTcnProcessManualDial(options?) / useTcnFtpManualDialReport(options?) — mutation — manual dialing.

Databox

• useGetDataboxFolder(folderId, options?) — query — a databox folder.
• useGetDataboxFolderFiles(folderId, options?) — query — files in a folder.
• useGetDataboxFolderDatasets(folderId, options?) — query — datasets in a folder.
• useGetDataboxFolderDuplicates(folderId, options?) — query — duplicates in a folder.
• useGetDatasetExceptions(datasetId, options?) — query — exceptions for a dataset.
• useGetDatasetDuplicates(datasetId, group?, options?) — query — duplicates for a dataset.
• useGetDataboxFolderSchema(folderId, options?) — query — a folder's schema.
• useGetDataboxSchemaHistory(folderId, options?) — query — a folder's schema history.
• useGetDataboxTrashFiles(folderId, options?) — query — trashed files in a folder.
• useGetDataboxFile(fileId, options?) — query — a databox file.
• useGetDataboxFileStatus(fileId, options?) — query — a file's status.
• useGetDataboxFileRuns(fileId, options?) — query — runs for a file.
• useGetDataboxFileDownloadUrl(fileId, options?) — query — a file's download URL.
• useDropFileToDatabox(options?) — mutation — drop/upload a file into a folder.
• useRunDataboxFolder(options?) — mutation — run folder processing.
• useUpdateDataboxFolderSchema(options?) — mutation — update a folder's schema.
• useTrashDataboxFiles(options?) — mutation — move files to trash.
• useRestoreDataboxFile(options?) — mutation — restore a trashed file.
• usePermanentDeleteDataboxFiles(options?) — mutation — permanently delete files.

Ingestion Authoring

• useCreateDatabox(options?) — mutation — create a databox.
• useCreateFileboxFolder(options?) — mutation — create a filebox folder.
• useListDataboxes(options?) — query — list databoxes.
• useListFileboxFolders(options?) — query — list filebox folders.

Connections Authoring

• useCreateSftpConnection(options?) — mutation — create an SFTP connection.
• useCreateEmailConnection(options?) — mutation — create an email connection.
• useCreateBlobConnection(options?) — mutation — create a blob-storage connection.
• useTestConnection(kind, id, options?) — query — test a connection.
• useListConnections(kind, options?) — query — list connections of a kind.

Export Configs Hub

• useListExportConfigs(query?, options?) — query (hub) — list export configs.
• useGetExportConfig(configId, options?) — query (hub) — one export config.
• useCreateExportConfig(options?) — mutation (hub) — create an export config.
• useUpdateExportConfig(configId, options?) — mutation (hub) — update an export config.
• useRunExportConfig(configId, options?) — mutation (hub) — run an export config.

Dashboards Hub

• useListDashboards(query?, options?) — query (hub) — list dashboards.
• useGetDashboard(dashboardId, options?) — query (hub) — one dashboard.
• useCreateDashboard(options?) — mutation (hub) — create a dashboard.
• useAddDashboardWidget(dashboardId, options?) — mutation (hub) — add a widget.
• useUpdateDashboardWidget(dashboardId, widgetId, options?) — mutation (hub) — update a widget.
• useRemoveDashboardWidget(dashboardId, widgetId, options?) — mutation (hub) — remove a widget.

External Apps Authoring

• useCreateExternalApp(options?) — mutation — create an external app.
• useSetExternalAppEnv(workbookId, options?) — mutation — set env variables.
• useSetExternalAppSchemaMap(workbookId, options?) — mutation — set schema mapping.
• useSetExternalAppAccessControl(workbookId, options?) — mutation — set access control.
• useValidateExternalAppUrl(options?) — mutation — validate an external app URL.

Solutions

• useSolutionList(options?) — controller — list solutions.
• useSolutionPicker() — controller — solution/branch selection state.
• useSetSolutionSeedData(solutionId, options?) — mutation — set seed data.
• useCreateSolution(options?) — mutation — create a solution.
• usePackagableComponents(options?) — query — packagable components.
• useAddSolutionObjects(solutionId, options?) — mutation — add objects to a solution.
• useValidateSolution(solutionId, options?) — mutation — validate a solution package.
• usePublishSolution(solutionId, options?) — mutation — publish a solution.
• usePublishJob(jobId?, options?) — query — track a publish job's status (disabled until jobId is set).

Versioning

• useListBranches(solutionId?, branchType?, options?) — query — list branches.
• useListCommits(solutionId?, branch?, branchType?, options?) — query — list commits.
• useListTags(solutionId?, options?) — query — list tags.
• useCommitChanges(options?) — mutation — commit changes.
• useMergeBranches(options?) — mutation — merge branches.
• usePushBranch(options?) — mutation — push a branch.
• useCreateBranch(options?) — mutation — create a branch.

Pipeline

• usePipelineList(filter?, options?) — controller — list pipelines with filtering.
• usePipelineRuns(pipelineId, options?) — controller — runs for a pipeline.
• useLastSuccessfulPipelineRun(pipelineId, options?) — controller — the last successful run.
• usePipelineRunDetail(pipelineId, runId, options?) — controller — a run's detail.
• usePipelineOverview(pipelineId?, options?) — controller — pipeline overview.
• usePipelineOutputSample(pipelineId?) — controller — fetch/trigger an output sample.
• useGetPipeline(pipelineId, options?) — query — a pipeline.
• useGetPipelineRunStatus(pipelineId, options?) — query — a pipeline's run status.
• useSavePipeline(options?) — mutation — save a pipeline.
• useRunPipeline(options?) — mutation — run a pipeline.

Working Paper

• useWorkingPaperList(options?) — controller — list working papers.
• useWorkingPaper(workingPaperId, options?) — controller — load a working paper.
• useCreateWorkingPaper() — mutation — create a working paper.
• useWorkingPaperInputTableSheet(config, viewsOptions?, rowsOptions?) — controller — input-table sheet within a working paper.
• useFxDefinitionSheet(init?) — controller — FX/formula definition sheet with local state.

Period Management — Fiscal Calendars

• useListFiscalCalendars(fiscalYear?, options?) — query — list fiscal calendars.
• useGetFiscalCalendar(id, options?) — query — a fiscal calendar.
• useCreateFiscalCalendar(options?) — mutation — create a fiscal calendar.
• useUpdateFiscalCalendar(options?) — mutation — update a fiscal calendar.
• useDeleteFiscalCalendar(options?) — mutation — delete a fiscal calendar.

Period Management — Holiday Calendars

• useListHolidayCalendars(year?, options?) — query — list holiday calendars.
• useGetHolidayCalendar(id, options?) — query — a holiday calendar.
• useCreateHolidayCalendar(options?) — mutation — create a holiday calendar.
• useUpdateHolidayCalendar(options?) — mutation — update a holiday calendar.
• useDeleteHolidayCalendar(options?) — mutation — delete a holiday calendar.
• useListHolidays(id, options?) — query — holidays in a calendar.
• useImportHolidays(options?) — mutation — import holidays into a calendar.

Configuration

Default Query Configuration

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      retry: 3,
      staleTime: 1000 * 60 * 5, // 5 minutes
      gcTime: 1000 * 60 * 10, // 10 minutes
    },
  },
});

Customizable Parameters

Query hooks accept the full TanStack React Query UseQueryOptions type. The most commonly used are a small subset of what's available:

// Subset of UseQueryOptions — see TanStack Query docs for the complete list
interface CommonQueryOptions {
  enabled?: boolean;
  staleTime?: number;
  gcTime?: number;
  retry?: number | boolean;
}

Advanced Usage

Error Handling

Errors are normalised to { message, status } by the core SDK:

const { error } = useUser();
if (error) console.error(error.message);

Manual Refetching

function ManualRefetch() {
  const { refetch } = useUser();
  return <button onClick={() => refetch()}>Refresh</button>;
}

Re-exports

@bluecopa/react re-exports:

• reactQuery — the entire TanStack React Query API under one namespace (reactQuery.useQuery, reactQuery.QueryClient, reactQuery.QueryClientProvider, …).
• ReactQueryDevtools — the devtools component.
• Everything from @bluecopa/core — copaSetConfig, copaGetConfig, copaApi, hubClient, copaInputTableDb, copaUtils, and shared types.

import {
  reactQuery, // namespaced TanStack React Query
  ReactQueryDevtools,
  copaSetConfig, // from @bluecopa/core
  copaGetConfig, // from @bluecopa/core
  copaApi, // from @bluecopa/core
} from "@bluecopa/react";

const { QueryClient, QueryClientProvider, useQuery } = reactQuery;

TypeScript Support

Fully typed. All hooks provide type inference and IntelliSense; shared types are exported from the package root.

Development

pnpm install
pnpm build          # Vite build (pnpm build:umd for the UMD bundle)
pnpm dev            # watch build
pnpm test           # Vitest
pnpm test:watch     # Vitest watch