Big News: Socket raises $60M Series C at a $1B valuation to secure software supply chains for AI-driven development.Announcement →

@bluecopa/react

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

@bluecopa/react

Bluecopa react library with TanStack Query integration

latest

npm

Version: 0.1.103

Version published: 3 days ago

Maintainers: 3

Created: 9 months ago

Source

@bluecopa/react

A Comprehensive React Query Integration for Bluecopa

A React library providing opinionated custom hooks for TanStack React Query integration with Bluecopa core API. This package enables efficient data fetching, caching, and synchronization with the Bluecopa platform while maintaining type safety and developer experience.

@bluecopa/react
- A Comprehensive React Query Integration for Bluecopa
- Table of Contents
- Features
- Installation
  - Peer Dependencies
- Usage
- API Documentation
  - useUser(options?)
  - useDataset(datasetId, options?)
  - useDatasetSample(datasetId, options?)
  - useMetric(metricId, options?)
  - useInputTable(inputTableId, options?)
  - useRows(tableId, options?)
  - useGetFileUrlByFileId(fileId, options?)
  - useGetFileByFolderIdAndName(folderId, name, options?)
  - useGetPublishedWorkbookById(workbookId, options?)
  - useGetTableById(tableId, options?)
  - useGetWorkbooksByType(workbookType, options?)
  - useGetWorkflowInstanceStatusById(instanceId, options?)
  - useGetWorksheets(options?)
  - useGetWorksheetsByType(worksheetType, options?)
  - useRunDefinition(definitionId, options?)
  - useRunPublishedDefinition(publishedDefinitionId, options?)
  - useRunSampleDefinition(sampleDefinitionId, options?)
  - useTriggerHttpWorkflow(workflowId, payload, options?)
  - useTriggerWorkflow(workflowId, options?)
  - useWorkbook(workbookId, options?)
  - useWorkflow(workflowId, options?)
  - useWorksheet(worksheetId, options?)
  - Plus domain-grouped hooks for Audit, Chat, Email Engine, Files, Forms, Inbox Items, Input Table mutations, Permissions, Process, Recon, Statement, Task, Templated Pipelines, Templates, TCN, Users (extras), Workbook (mutations), and Workflow (extras) — see sections after useWorksheet.
- Configuration
  - Default Query Configuration
  - Customizable Parameters
- Advanced Usage
  - Error Handling
  - Manual Refetching
- Re-exports
- TypeScript Support
- Development

Features

✅ First-class TypeScript support with strict type definitions
🔁 Seamless integration with TanStack React Query (v5+)
🛡 Comprehensive error handling patterns
⚙ Optimized default query configuration
📦 Re-exports of core TanStack React Query utilities
📊 Sample data preview capabilities
🧩 Customizable query parameters (limit, caching, retries)

Installation

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

Peer Dependencies

This package requires the following in your application:

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

Usage

Query Provider Setup

Wrap your application with the React Query provider:

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

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

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

Boilerplate Integration

For projects using the Bluecopa React boilerplate, use the pre-configured QueryProvider component that handles API configuration automatically:

// 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, // 1 minute
            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>
  );
}

Required Environment Variables:

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

Example .env file:

VITE_BLUECOPA_API_URL=https://develop.bluecopa.com
VITE_BLUECOPA_WORKSPACE_ID=your-workspace-id
VITE_BLUECOPA_API_TOKEN=base64-encoded-json-here

Then wrap your application with this provider:

import QueryProvider from "./providers/query-provider";

function App() {
  return (
    <QueryProvider>
      <YourApp />
    </QueryProvider>
  );
}

This setup automatically configures the API client with your environment-specific settings and applies optimal caching defaults.

Hook Examples

`useUser` - Fetch authenticated user

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

function UserProfile() {
  const { data, isLoading, error } = useUser({
    staleTime: 5 * 60 * 1000, // 5 minutes
    retry: 2,
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return <div>Welcome, {data?.name}!</div>;
}

`useDataset` - Fetch dataset with query controls

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

function DatasetViewer({ datasetId }) {
  const { data, isLoading } = useDataset(datasetId, {
    limit: 500,
    staleTime: 10 * 60 * 1000, // 10 minutes
  });

  if (isLoading) return <div>Loading dataset...</div>;
  return (
    <div>
      {data?.name} ({data?.records?.length} records)
    </div>
  );
}

`useRows` - Fetch input table rows with Supabase-style filtering

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

function TableRows({ tableId }) {
  const { data, isLoading, error } = useRows(tableId, {
    status: "active",
    price: "gte.100",
    limit: 25,
    offset: 0,
  });

  if (isLoading) return <div>Loading rows...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <div>Total: {data?.total_count ?? 0}</div>
      {data?.data?.map((row) => (
        <div key={row._copa_id}>{JSON.stringify(row)}</div>
      ))}
    </div>
  );
}

📖 For detailed documentation on useRows including filtering, pagination, and advanced usage, see docs/useRows.md

`useGetFileByFolderIdAndName` - Look up a filebox file by folder + name

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

function FileBadge({ folderId, fileName }) {
  const { data, isLoading, error } = useGetFileByFolderIdAndName(
    folderId,
    fileName,
    {
      staleTime: 60 * 1000, // 1 minute
      retry: 1,
    },
  );

  if (!folderId || !fileName) return <div>Pick a folder and a file.</div>;
  if (isLoading) return <div>Resolving file…</div>;
  if (error) return <div>Could not find “{fileName}”: {error.message}</div>;
  if (!data) return null;

  return (
    <div>
      <strong>{data.name}</strong> · {data.type} ·{" "}
      <code>{data.blobFileId}</code>
      {data.status === "PUBLISHED" ? " (published)" : " (draft)"}
    </div>
  );
}

The query is auto-disabled until both folderId and name are truthy, so you can safely pass null/undefined while the user is still picking inputs.

API Documentation

`useUser(options?)`

Fetches authenticated user details with query controls.

Parameters:

options (optional): Query options extending TanStack React Query's UseQueryOptions

Returns:

data: User object or undefined
isLoading: Boolean indicating loading state
error: Error object if request failed
refetch: Function to manually trigger refetch

`useDataset(datasetId, options?)`

Fetches dataset data by ID with configurable parameters.

Parameters:

datasetId: ID of the dataset to fetch
options (optional): Query options with:
- limit: Maximum records to fetch
- staleTime: Duration (ms) before data is considered stale

Returns:

data: Dataset object containing name and records
isLoading: Boolean indicating loading state
error: Error object if request failed
refetch: Function to manually trigger refetch

`useDatasetSample(datasetId, options?)`

Fetches a representative sample of dataset data.

Parameters:

datasetId: ID of the dataset
options (optional): Query options with enabled flag

Returns:

data: Object containing sample data
isLoading: Boolean indicating loading state
refetch: Function to manually trigger refetch

`useMetric(metricId, options?)`

Fetches metric data by ID.

Parameters:

metricId: ID of the metric
options (optional): Query options

Returns:

data: Metric object with name and value
isLoading: Boolean indicating loading state
error: Error object if request failed
refetch: Function to manually trigger refetch

`useInputTable(inputTableId, options?)`

Fetches input table data with limit parameters.

Parameters:

inputTableId: ID of the input table
options (optional): Query options with limitParams:
- limit: Maximum rows to fetch
- limitFrom: Direction to apply limit from ('top' or 'bottom')

Returns:

data: Input table object with rows
isLoading: Boolean indicating loading state
error: Error object if request failed
refetch: Function to manually trigger refetch

`useRows(tableId, options?)`

Fetches rows from an input table with Supabase-style filtering, pagination, and sorting. Supports advanced filtering operators and group expressions.

Parameters:

tableId: ID of the input table (string | null | undefined)
options (optional): Query options extending GetRowsOptions and BaseQueryOptions:
- limit: Maximum rows to fetch (1-10000)
- offset: Number of rows to skip
- order: Sort order ('asc' or 'desc')
- order_by: Column name to sort by
- Filter fields: Any column name with Supabase-style operator syntax (e.g., status: 'active', price: 'gte.100', status: 'in.(active,pending)')
- or: Supabase/PostgREST group expression for OR conditions
- and: Supabase/PostgREST group expression for AND conditions
- React Query options: enabled, staleTime, gcTime, retry, retryDelay, onSuccess, onError

Returns:

data: GetRowsResponse object containing:
- data: Array of row objects
- count: Number of rows in current page
- total_count: Total rows available
isLoading: Boolean indicating loading state
error: Error object if request failed
refetch: Function to manually trigger refetch

Example:

const { data, isLoading } = useRows("table-123", {
  status: "active",
  price: "gte.100",
  limit: 25,
  offset: 0,
});

📖 For comprehensive documentation including all supported operators, filtering patterns, and advanced usage, see docs/useRows.md

`useGetFileUrlByFileId(fileId, options?)`

Fetches the URL for a file by its ID.

Parameters:

fileId: ID of the file to fetch URL for
options (optional): Query options extending TanStack React Query's UseQueryOptions

Returns:

data: Object containing file URL
isLoading: Boolean indicating loading state
error: Error object if request failed
refetch: Function to manually trigger refetch

`useGetFileByFolderIdAndName(folderId, name, options?)`

Fetches a filebox file by its parent folder id and exact name. The query is disabled until both folderId and name are truthy.

Parameters:

folderId: Parent folder id (null/undefined disables the query)
name: Exact file name to look up (null/undefined disables the query)
options (optional): Query options extending TanStack React Query's UseQueryOptions

Returns:

data: FileboxFile — file metadata (id, name, type, parentId, blobFileId, status, …)
isLoading: Boolean indicating loading state
error: Error object if request failed
refetch: Function to manually trigger refetch

`useGetPublishedWorkbookById(workbookId, options?)`

Fetches published workbook details by ID.

Parameters:

workbookId: ID of the published workbook
options (optional): Query options

Returns:

data: Published workbook object
isLoading: Boolean indicating loading state
error: Error object if request failed
refetch: Function to manually trigger refetch

`useGetTableById(tableId, options?)`

Fetches table metadata by ID.

Parameters:

tableId: ID of the table
options (optional): Query options

Returns:

data: Table metadata object
isLoading: Boolean indicating loading state
error: Error object if request failed
refetch: Function to manually trigger refetch

`useGetWorkbooksByType(workbookType, options?)`

Fetches workbooks filtered by type.

Parameters:

workbookType: Type of workbooks to fetch
options (optional): Query options

Returns:

data: Array of workbook objects
isLoading: Boolean indicating loading state
error: Error object if request failed
refetch: Function to manually trigger refetch

`useGetWorkflowInstanceStatusById(instanceId, options?)`

Fetches workflow instance status by ID.

Parameters:

instanceId: ID of the workflow instance
options (optional): Query options

Returns:

data: Workflow status object
isLoading: Boolean indicating loading state
error: Error object if request failed
refetch: Function to manually trigger refetch

`useGetWorksheets(options?)`

Fetches all available worksheets.

Parameters:

options (optional): Query options

Returns:

data: Array of worksheet objects
isLoading: Boolean indicating loading state
error: Error object if request failed
refetch: Function to manually trigger refetch

`useGetWorksheetsByType(worksheetType, options?)`

Fetches worksheets filtered by type.

Parameters:

worksheetType: Type of worksheets to fetch
options (optional): Query options

Returns:

data: Array of worksheet objects
isLoading: Boolean indicating loading state
error: Error object if request failed
refetch: Function to manually trigger refetch

`useRunDefinition(definitionId, options?)`

Executes a run definition.

Parameters:

definitionId: ID of the run definition
options (optional): Query options

Returns:

data: Execution result
isLoading: Boolean indicating loading state
error: Error object if request failed
refetch: Function to manually trigger refetch

`useRunPublishedDefinition(publishedDefinitionId, options?)`

Executes a published run definition.

Parameters:

publishedDefinitionId: ID of the published definition
options (optional): Query options

Returns:

data: Execution result
isLoading: Boolean indicating loading state
error: Error object if request failed
refetch: Function to manually trigger refetch

`useRunSampleDefinition(sampleDefinitionId, options?)`

Executes a sample run definition.

Parameters:

sampleDefinitionId: ID of the sample definition
options (optional): Query options

Returns:

data: Sample execution result
isLoading: Boolean indicating loading state
error: Error object if request failed
refetch: Function to manually trigger refetch

`useTriggerHttpWorkflow(workflowId, payload, options?)`

Triggers an HTTP workflow execution.

Parameters:

workflowId: ID of the workflow
payload: Request payload
options (optional): Query options

Returns:

data: Workflow execution response
isLoading: Boolean indicating loading state
error: Error object if request failed
refetch: Function to manually trigger refetch

`useTriggerWorkflow(workflowId, options?)`

Triggers a workflow execution.

Parameters:

workflowId: ID of the workflow
options (optional): Query options

Returns:

data: Workflow execution response
isLoading: Boolean indicating loading state
error: Error object if request failed
refetch: Function to manually trigger refetch

`useWorkbook(workbookId, options?)`

Fetches workbook details by ID.

Parameters:

workbookId: ID of the workbook
options (optional): Query options

Returns:

data: Workbook object
isLoading: Boolean indicating loading state
error: Error object if request failed
refetch: Function to manually trigger refetch

`useWorkflow(workflowId, options?)`

Fetches workflow configuration by ID.

Parameters:

workflowId: ID of the workflow
options (optional): Query options

Returns:

data: Workflow configuration object
isLoading: Boolean indicating loading state
error: Error object if request failed
refetch: Function to manually trigger refetch

`useWorksheet(worksheetId, options?)`

Fetches worksheet details by ID.

Parameters:

worksheetId: ID of the worksheet
options (optional): Query options

Returns:

data: Worksheet object
isLoading: Boolean indicating loading state
error: Error object if request failed
refetch: Function to manually trigger refetch

Mutation hooks below follow TanStack Query's useMutation shape. Their returns include mutate(variables) and mutateAsync(variables) to trigger the action, isPending (loading), data (on success), error, isError, isSuccess, and reset(). The options parameter accepts the standard UseMutationOptions (including onSuccess, onError, onSettled, retry, etc.).

— Audit hooks

`useCreateAuditLog(options?)`

Records an audit log entry.

Parameters:

options (optional): Mutation options. mutate(request: CreateAuditLogRequest) triggers the action.

Returns: Mutation result with data: CreateAuditLogResponse.

`useGetAuditLogs(options?)`

Fetches audit log entries on demand. Implemented as a mutation so the request payload can be passed at call time.

Parameters:

options (optional): Mutation options. mutate(request: GetAuditLogsRequest) triggers the fetch.

Returns: Mutation result with data: AuditLogResponse.

— Chat hooks

`useCreateThread(options?)`

Creates a new chat thread.

Parameters:

options (optional): Mutation options including onSuccess, onError, retry, retryDelay.

Returns: Mutation result with data: copaApi.chat.CreateThreadResponse.

`useGetCommentsByThreadId(threadId, options?)`

Fetches comments for a chat thread. Disabled until threadId is set.

Parameters:

threadId: Thread id (null/undefined disables the query)
options (optional): Query options

Returns: Query result with data: copaApi.chat.GetCommentsByThreadIdResponse.

`usePostComment(options?)`

Posts a new comment to a thread.

Parameters:

options (optional): Mutation options. mutate(request: PostCommentRequest) triggers the post.

Returns: Mutation result with data: copaApi.chat.PostCommentResponse.

`useUpdateComment(options?)`

Updates an existing comment.

Parameters:

options (optional): Mutation options. mutate(request: UpdateCommentRequest) triggers the update.

Returns: Mutation result with data: copaApi.chat.UpdateCommentResponse.

`useDeleteComment(options?)`

Deletes a comment by id.

Parameters:

options (optional): Mutation options. mutate(commentId: string) triggers the delete.

Returns: Mutation result with data: copaApi.chat.DeleteCommentResponse.

`useSubscribeUser(options?)`

Subscribes a user to chat updates.

Parameters:

options (optional): Mutation options. mutate(request: SubscribeUserRequest) triggers the action.

Returns: Mutation result with data: copaApi.chat.SubscribeUserResponse.

`useUnsubscribeUser(options?)`

Unsubscribes a user from chat updates.

Parameters:

options (optional): Mutation options. mutate(request: UnsubscribeUserRequest) triggers the action.

Returns: Mutation result with data: copaApi.chat.UnsubscribeUserResponse.

`useCheckSubscriptionStatus(userId, threadId, options?)`

Checks whether a user is subscribed to a thread.

Parameters:

userId: User id (null/undefined disables the query)
threadId: Thread id (null/undefined disables the query)
options (optional): Query options

Returns: Query result with data: copaApi.chat.CheckSubscriptionStatusResponse.

— Email Engine hooks

`useGetAllConversations(params?, options?)`

Lists email conversations (paginated).

Parameters:

params (optional): GetAllConversationsParams filters
options (optional): Query options

Returns: Query result with data: PageChunkEmailConversation.

`useGetConversation(conversationId, options?)`

Fetches a single email conversation by id.

Parameters:

conversationId: Conversation id (null/undefined disables the query)
options (optional): Query options

Returns: Query result with data: EmailConversation.

`useCreateConversation(options?)`

Creates a new email conversation.

Parameters:

options (optional): Mutation options. mutate(request: CreateConversationRequest) triggers the create.

Returns: Mutation result with data: EmailConversation.

`useReplyToConversation(options?)`

Sends a reply on an email conversation.

Parameters:

options (optional): Mutation options. mutate(request: ReplyToConversationRequest) triggers the reply.

Returns: Mutation result.

`useFilterMessagesBySenderId(params, options?)`

Fetches messages filtered by sender id.

Parameters:

params: FilterOnSenderId — sender id and paging
options (optional): Query options

Returns: Query result with data: PageChunkEmailMessage.

— File hooks (mutations & download)

`useFileUpload(options?)`

Uploads file data to storage and returns the resulting file id/path.

Parameters:

options (optional): Mutation options. mutate(request: FileUploadRequest) triggers the upload.

Returns: Mutation result with data: FileUploadResponse.

`useFileDownload(params, options?)`

Downloads a file by id. Implemented as a query (auto-fetches when params are valid).

Parameters:

params: { fileId: string; contentType: string; method: 'GET' | 'PUT' }
options (optional): Query options

Returns: Query result with the downloaded data.

— Form hooks

`useGetFormById(formId, options?)`

Fetches a form by id.

Parameters:

formId: Form id (null/undefined disables the query)
options (optional): Query options

Returns: Query result with the form definition.

`useGetFormSchema(formInstanceId, formRevision, options?)`

Fetches a form's schema for a given instance + revision.

Parameters:

formInstanceId: Form instance id (null/undefined disables the query)
formRevision: Schema revision (string or number, null/undefined disables the query)
options (optional): Query options

Returns: Query result with the form schema.

`useGetFormData(formId, options?)`

Fetches submitted form data.

Parameters:

formId: Form id (null/undefined disables the query)
options (optional): Query options

Returns: Query result with the form data.

`useCreateOrUpdateForm(options?)`

Creates or updates a form definition.

Parameters:

options (optional): Mutation options. mutate(request: CreateOrUpdateFormRequest) triggers the save.

Returns: Mutation result.

— Inbox Items hooks

`useGetAllInboxItems(params?, options?)`

Lists inbox items.

Parameters:

params (optional): GetAllInboxItemsRequest filters
options (optional): Query options

Returns: Query result with the items array.

`useCreateInboxItemPerUser(options?)`

Creates an inbox item for a specific user.

Parameters:

options (optional): Mutation options. mutate(request) triggers the create.

Returns: Mutation result with the created inbox items.

`useMarkItemAsRead(options?)`

Marks an inbox item as read.

Parameters:

options (optional): Mutation options. mutate(request: MarkItemAsReadRequest) triggers the action.

Returns: Mutation result.

`useMarkItemAsUnread(options?)`

Marks an inbox item as unread.

Parameters:

options (optional): Mutation options. mutate(request: MarkItemAsUnreadRequest) triggers the action.

Returns: Mutation result.

— Input Table mutation hooks

`useInsertRow(options?)`

Inserts a new row into an input table.

Parameters:

options (optional): Mutation options. mutate(request: InsertRowRequest) triggers the insert.

Returns: Mutation result.

`useUpdateRow(options?)`

Updates an existing row in an input table.

Parameters:

options (optional): Mutation options. mutate(request: UpdateRowRequest) triggers the update.

Returns: Mutation result.

`useDeleteRow(options?)`

Deletes a row by id from an input table.

Parameters:

options (optional): Mutation options. mutate(request: DeleteRowRequest) triggers the delete.

Returns: Mutation result.

— Permissions hooks

`useDocumentPermissions(objectId, objectType, options?)`

Fetches permissions for a given document/object.

Parameters:

objectId: Object id (undefined disables the query)
objectType: Object type (e.g. Workbook, Dashboard)
options (optional): Query options

Returns: Query result with data: PermissionsResponse.

— Process hooks

`useGetTriggersBySheet(sheetId, options?)`

Lists process triggers attached to a sheet.

Parameters:

sheetId: Sheet id
options (optional): TanStack UseQueryOptions (omit queryKey/queryFn/enabled)

Returns: Query result with data: ProcessTrigger[].

`useRegisterProcessTrigger(options?)`

Registers a new process trigger.

Parameters:

options (optional): Mutation options. mutate(trigger: ProcessTrigger) triggers the register.

Returns: Mutation result with data: ProcessTrigger.

`useDeleteProcessTrigger(options?)`

Deletes a process trigger by id. Invalidates the corresponding trigger list query.

Parameters:

options (optional): Mutation options. mutate({ id, sheetId? }) triggers the delete.

Returns: Mutation result with data: DeleteProcessTriggerResponse.

`useMarkTaskDone(options?)`

Marks a process task as done.

Parameters:

options (optional): Mutation options. mutate(request: MarkTaskDoneRequest) triggers the action.

Returns: Mutation result.

`useReassignTask(options?)`

Reassigns a process task to a different user.

Parameters:

options (optional): Mutation options. mutate(request: ReassignTaskRequest) triggers the action.

Returns: Mutation result.

— Recon hooks

`useGetAllRecon(options?)`

Lists all recon workflows.

Parameters:

options (optional): Query options

Returns: Query result with data: ReconWorkflow[].

`useRunRecon(options?)`

Triggers a recon workflow run.

Parameters:

options (optional): Mutation options. mutate(request: RunReconRequest) triggers the run.

Returns: Mutation result with data: RunReconResponse.

— Statement hooks

`useGetStatementData(statementId, viewId?, runId?, options?)`

Fetches statement data for a given statement/view/run.

Parameters:

statementId: Statement id (null/undefined disables the query)
viewId (optional): View id
runId (optional): Run id
options (optional): Query options

Returns: Query result with the statement data.

`useGetViewsBySheetId(sheetId, options?)`

Lists statement views for a sheet.

Parameters:

sheetId: Sheet id (null/undefined disables the query)
options (optional): Query options

Returns: Query result with the array of views.

`useGetViewById(viewId, options?)`

Fetches a single statement view by id.

Parameters:

viewId: View id (null/undefined disables the query)
options (optional): Query options

Returns: Query result with the view.

`useGetRunsByViewId(viewId, options?)`

Lists statement runs for a given view.

Parameters:

viewId: View id (null/undefined disables the query)
options (optional): Query options

Returns: Query result with the runs array.

`useGetRunResultById(runId, options?)`

Fetches the result of a statement run.

Parameters:

runId: Run id (null/undefined disables the query)
options (optional): Query options

Returns: Query result with the run result.

`useCreateStatementRun(options?)`

Creates a new statement run.

Parameters:

options (optional): Mutation options. mutate(params: CreateStatementRunParams) triggers the create.

Returns: Mutation result with data: CreateStatementRunResult.

— Task hook

`useGetTaskDetails(taskId, options?)`

Fetches detailed information about a task.

Parameters:

taskId: Task id (null/undefined disables the query)
options (optional): Query options

Returns: Query result with the task details.

— Templated Pipeline hooks

`useGetAllTemplatedPipelines(options?)`

Lists all templated pipelines.

Parameters:

options (optional): Query options

Returns: Query result with data: TemplatedPipelineWorkflow[].

— Template hooks

`useRenderTemplate(options?)`

Renders a template with the provided variables.

Parameters:

options (optional): Mutation options. mutate(request: RenderTemplateRequest) triggers the render.

Returns: Mutation result with data: RenderTemplateResponse.

— TCN hooks

All TCN mutation hooks take their TCN token (and other identifiers) as part of mutate(variables). The options parameter is standard UseMutationOptions.

`useTcnAuthUrl(options?)`

Returns the TCN OAuth authorization URL.

Parameters:

options (optional): Query options

Returns: Query result with data: { url: string }.

`useTcnExchangeCode(options?)`

Exchanges an OAuth code for TCN tokens.

Parameters: mutate({ code }) triggers the exchange.

Returns: Mutation result with data: TcnTokenData.

`useTcnRefreshToken(options?)`

Refreshes a TCN access token.

Parameters: mutate({ refresh_token }).

Returns: Mutation result with data: TcnTokenData.

`useTcnCurrentAgent(options?)`

Fetches the currently signed-in TCN agent.

Parameters: mutate({ token }).

Returns: Mutation result with data: TcnAgentData.

`useTcnAgentSkills(options?)`

Lists skills available to the agent in a hunt group.

Parameters: mutate({ token, huntGroupSid }).

Returns: Mutation result with data: TcnSkillsData.

`useTcnCreateSession(options?)`

Creates a new TCN agent session.

Parameters: mutate({ token, huntGroupSid, skills }).

Returns: Mutation result with data: TcnSessionData.

`useTcnKeepAlive(options?)`

Pings the TCN session to keep it alive.

Parameters: mutate({ token, sessionSid }).

Returns: Mutation result.

`useTcnAgentGetStatus(options?)`

Returns the current agent status.

Parameters: mutate({ token }).

Returns: Mutation result with data: TcnStatusData.

`useTcnAgentSetReady(options?)`

Marks the agent as ready.

Parameters: mutate({ token, sessionSid }).

Returns: Mutation result.

`useTcnAgentPause(options?)`

Pauses the agent.

Parameters: mutate({ token, sessionSid }).

Returns: Mutation result.

`useTcnAgentDisconnect(options?)`

Disconnects the agent.

Parameters: mutate({ token, sessionSid, reason? }).

Returns: Mutation result.

`useTcnConnectedParty(options?)`

Returns the currently connected party for the agent.

Parameters: mutate({ token, sessionSid }).

Returns: Mutation result with data: TcnConnectedParty.

`useTcnAgentPutCallOnHold(options?)`

Puts the agent's current call on hold.

Parameters: mutate({ token, sessionSid, holdType? }).

Returns: Mutation result.

`useTcnAgentGetCallFromHold(options?)`

Resumes the agent's held call.

Parameters: mutate({ token, sessionSid, holdType? }).

Returns: Mutation result.

`useTcnHuntGroupSettings(options?)`

Fetches hunt-group settings for the agent.

Parameters: mutate({ token, huntGroupSid }).

Returns: Mutation result with data: TcnDialSettings.

`useTcnCallData(options?)`

Retrieves data for an active call.

Parameters: mutate({ token, callSid }).

Returns: Mutation result with data: TcnCallData.

`useTcnDialManualPrepare(options?)`

Prepares a manual dial.

Parameters: mutate({ token, sessionSid }).

Returns: Mutation result.

`useTcnManualDialStart(options?)`

Starts a prepared manual dial.

Parameters: mutate({ token, agentSessionSid, huntGroupSid, simpleCallData }).

Returns: Mutation result.

`useTcnProcessManualDial(options?)`

Processes the result of a manual dial.

Parameters: mutate({ token, call }).

Returns: Mutation result.

— User hooks (extras)

`useGetAllUsers(options?)`

Lists all users in the workspace.

Parameters:

options (optional): Query options

Returns: Query result with data: User[].

— Workbook hooks (mutations)

`useGetWorkbookDetails(workbookId, options?)`

Fetches workbook metadata/details.

Parameters:

workbookId: Workbook id (null/undefined disables the query)
options (optional): Query options

Returns: Query result with the workbook details.

`useSaveWorkbook(options?)`

Saves a workbook draft.

Parameters: mutate(request: SaveWorkbookRequest).

Returns: Mutation result.

`usePublishWorkbook(options?)`

Publishes a workbook.

Parameters: mutate(request: PublishWorkbookRequest).

Returns: Mutation result.

— Workflow hooks (extras)

`useGetAllHttpTriggers(options?)`

Lists all HTTP triggers.

Parameters:

options (optional): Query options

Returns: Query result with data: HttpTrigger[].

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

All hooks accept standard TanStack React Query options:

interface QueryOptions {
  enabled?: boolean; // Enable/disable query
  staleTime?: number; // Duration (ms) before data is stale
  gcTime?: number; // Duration (ms) to keep data in cache
  retry?: number | boolean; // Number of retries or disable retries
  onSuccess?: (data: any) => void; // Success callback
  onError?: (error: Error) => void; // Error callback
}

Advanced Usage

Error Handling

useUser({
  onError: (error) => {
    console.error("User fetch failed:", error.message);
    // Custom error recovery logic
  },
});

Manual Refetching

function ManualRefetch() {
  const { data, refetch } = useUser();

  return (
    <div>
      <button onClick={() => refetch()}>Refresh</button>
    </div>
  );
}

Re-exports

This package re-exports core TanStack React Query utilities:

import {
  useQuery,
  useMutation,
  QueryClient,
  QueryClientProvider,
  ReactQueryDevtools,
} from "@bluecopa/react";

TypeScript Support

Fully typed with TypeScript. All hooks provide proper type inference and IntelliSense support. Extend types for custom use cases:

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

interface CustomUser extends User {
  role: string;
  permissions: string[];
}

Development

# Install dependencies
pnpm install

# Build the package
pnpm build

# Run development server
pnpm dev

# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Lint code
pnpm lint

# Format code
pnpm format

Keywords

FAQs

What is @bluecopa/react?

Is @bluecopa/react well maintained?

Package last updated on 10 Jun 2026

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@bluecopa/react

A Comprehensive React Query Integration for Bluecopa

Table of Contents

Features

Installation

Peer Dependencies

Usage

Query Provider Setup

Boilerplate Integration

Hook Examples

useUser - Fetch authenticated user

useDataset - Fetch dataset with query controls

useRows - Fetch input table rows with Supabase-style filtering

useGetFileByFolderIdAndName - Look up a filebox file by folder + name

API Documentation

useUser(options?)

useDataset(datasetId, options?)

useDatasetSample(datasetId, options?)

useMetric(metricId, options?)

useInputTable(inputTableId, options?)

useRows(tableId, options?)

useGetFileUrlByFileId(fileId, options?)

useGetFileByFolderIdAndName(folderId, name, options?)

useGetPublishedWorkbookById(workbookId, options?)

useGetTableById(tableId, options?)

useGetWorkbooksByType(workbookType, options?)

useGetWorkflowInstanceStatusById(instanceId, options?)

useGetWorksheets(options?)

useGetWorksheetsByType(worksheetType, options?)

useRunDefinition(definitionId, options?)

useRunPublishedDefinition(publishedDefinitionId, options?)

useRunSampleDefinition(sampleDefinitionId, options?)

useTriggerHttpWorkflow(workflowId, payload, options?)

useTriggerWorkflow(workflowId, options?)

useWorkbook(workbookId, options?)

useWorkflow(workflowId, options?)

useWorksheet(worksheetId, options?)

useCreateAuditLog(options?)

useGetAuditLogs(options?)

useCreateThread(options?)

useGetCommentsByThreadId(threadId, options?)

usePostComment(options?)

useUpdateComment(options?)

useDeleteComment(options?)

useSubscribeUser(options?)

useUnsubscribeUser(options?)

useCheckSubscriptionStatus(userId, threadId, options?)

useGetAllConversations(params?, options?)

useGetConversation(conversationId, options?)

useCreateConversation(options?)

useReplyToConversation(options?)

useFilterMessagesBySenderId(params, options?)

useFileUpload(options?)

useFileDownload(params, options?)

useGetFormById(formId, options?)

useGetFormSchema(formInstanceId, formRevision, options?)

useGetFormData(formId, options?)

useCreateOrUpdateForm(options?)

useGetAllInboxItems(params?, options?)

useCreateInboxItemPerUser(options?)

useMarkItemAsRead(options?)

useMarkItemAsUnread(options?)

useInsertRow(options?)

useUpdateRow(options?)

useDeleteRow(options?)

useDocumentPermissions(objectId, objectType, options?)

useGetTriggersBySheet(sheetId, options?)

useRegisterProcessTrigger(options?)

useDeleteProcessTrigger(options?)

useMarkTaskDone(options?)

useReassignTask(options?)

useGetAllRecon(options?)

useRunRecon(options?)

useGetStatementData(statementId, viewId?, runId?, options?)

useGetViewsBySheetId(sheetId, options?)

useGetViewById(viewId, options?)

useGetRunsByViewId(viewId, options?)

useGetRunResultById(runId, options?)

useCreateStatementRun(options?)

useGetTaskDetails(taskId, options?)

`useUser` - Fetch authenticated user

`useDataset` - Fetch dataset with query controls

`useRows` - Fetch input table rows with Supabase-style filtering

`useGetFileByFolderIdAndName` - Look up a filebox file by folder + name

`useUser(options?)`

`useDataset(datasetId, options?)`

`useDatasetSample(datasetId, options?)`

`useMetric(metricId, options?)`

`useInputTable(inputTableId, options?)`

`useRows(tableId, options?)`

`useGetFileUrlByFileId(fileId, options?)`

`useGetFileByFolderIdAndName(folderId, name, options?)`

`useGetPublishedWorkbookById(workbookId, options?)`

`useGetTableById(tableId, options?)`

`useGetWorkbooksByType(workbookType, options?)`

`useGetWorkflowInstanceStatusById(instanceId, options?)`

`useGetWorksheets(options?)`

`useGetWorksheetsByType(worksheetType, options?)`

`useRunDefinition(definitionId, options?)`

`useRunPublishedDefinition(publishedDefinitionId, options?)`

`useRunSampleDefinition(sampleDefinitionId, options?)`

`useTriggerHttpWorkflow(workflowId, payload, options?)`

`useTriggerWorkflow(workflowId, options?)`

`useWorkbook(workbookId, options?)`

`useWorkflow(workflowId, options?)`

`useWorksheet(worksheetId, options?)`

`useCreateAuditLog(options?)`

`useGetAuditLogs(options?)`

`useCreateThread(options?)`

`useGetCommentsByThreadId(threadId, options?)`

`usePostComment(options?)`

`useUpdateComment(options?)`

`useDeleteComment(options?)`

`useSubscribeUser(options?)`

`useUnsubscribeUser(options?)`

`useCheckSubscriptionStatus(userId, threadId, options?)`

`useGetAllConversations(params?, options?)`

`useGetConversation(conversationId, options?)`

`useCreateConversation(options?)`

`useReplyToConversation(options?)`

`useFilterMessagesBySenderId(params, options?)`

`useFileUpload(options?)`

`useFileDownload(params, options?)`

`useGetFormById(formId, options?)`

`useGetFormSchema(formInstanceId, formRevision, options?)`

`useGetFormData(formId, options?)`

`useCreateOrUpdateForm(options?)`

`useGetAllInboxItems(params?, options?)`

`useCreateInboxItemPerUser(options?)`

`useMarkItemAsRead(options?)`

`useMarkItemAsUnread(options?)`

`useInsertRow(options?)`

`useUpdateRow(options?)`

`useDeleteRow(options?)`

`useDocumentPermissions(objectId, objectType, options?)`

`useGetTriggersBySheet(sheetId, options?)`

`useRegisterProcessTrigger(options?)`

`useDeleteProcessTrigger(options?)`

`useMarkTaskDone(options?)`

`useReassignTask(options?)`

`useGetAllRecon(options?)`

`useRunRecon(options?)`

`useGetStatementData(statementId, viewId?, runId?, options?)`

`useGetViewsBySheetId(sheetId, options?)`

`useGetViewById(viewId, options?)`

`useGetRunsByViewId(viewId, options?)`

`useGetRunResultById(runId, options?)`

`useCreateStatementRun(options?)`

`useGetTaskDetails(taskId, options?)`

`useGetAllTemplatedPipelines(options?)`

`useRenderTemplate(options?)`

`useTcnAuthUrl(options?)`

`useTcnExchangeCode(options?)`

`useTcnRefreshToken(options?)`

`useTcnCurrentAgent(options?)`

`useTcnAgentSkills(options?)`

`useTcnCreateSession(options?)`

`useTcnKeepAlive(options?)`

`useTcnAgentGetStatus(options?)`

`useTcnAgentSetReady(options?)`