@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.

Table of Contents

• @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
  • 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