@bluecopa/react 0.1.116 → 0.1.118

package/README.md

@@ -2,97 +2,72 @@
 
 ## 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.
+A React library of opinionated hooks that wrap [`@bluecopa/core`](https://www.npmjs.com/package/@bluecopa/core) with TanStack React Query — efficient data fetching, caching, and mutations against the Bluecopa platform, fully typed.
 
 ## Table of Contents
 
-- [@bluecopa/react ](#bluecopareact--)
-  - [A Comprehensive React Query Integration for Bluecopa](#a-comprehensive-react-query-integration-for-bluecopa)
-  - [Table of Contents](#table-of-contents)
-  - [Features](#features)
-  - [Installation](#installation)
-    - [Peer Dependencies](#peer-dependencies)
-  - [Usage](#usage)
-    - [Query Provider Setup](#query-provider-setup)
-    - [Boilerplate Integration](#boilerplate-integration)
-    - [Hook Examples](#hook-examples)
-      - [`useUser` - Fetch authenticated user](#useuser---fetch-authenticated-user)
-      - [`useDataset` - Fetch dataset with query controls](#usedataset---fetch-dataset-with-query-controls)
-  - [API Documentation](#api-documentation)
-    - [`useUser(options?)`](#useuseroptions)
-    - [`useDataset(datasetId, options?)`](#usedatasetdatasetid-options)
-    - [`useDatasetSample(datasetId, options?)`](#usedatasetsampledatasetid-options)
-    - [`useMetric(metricId, options?)`](#usemetricmetricid-options)
-    - [`useInputTable(inputTableId, options?)`](#useinputtableinputtableid-options)
-    - [`useRows(tableId, options?)`](#userowstableid-options)
-    - [`useGetFileUrlByFileId(fileId, options?)`](#usegetfileurlbyfileidfileid-options)
-    - [`useGetFileByFolderIdAndName(folderId, name, options?)`](#usegetfilebyfolderidandnamefolderid-name-options)
-    - [`useGetPublishedWorkbookById(workbookId, options?)`](#usegetpublishedworkbookbyidworkbookid-options)
-    - [`useGetTableById(tableId, options?)`](#usegettablebyidtableid-options)
-    - [`useGetWorkbooksByType(workbookType, options?)`](#usegetworkbooksbytypeworkbooktype-options)
-    - [`useGetWorkflowInstanceStatusById(instanceId, options?)`](#usegetworkflowinstancestatusbyidinstanceid-options)
-    - [`useGetWorksheets(options?)`](#usegetworksheetsoptions)
-    - [`useGetWorksheetsByType(worksheetType, options?)`](#usegetworksheetsbytypeworksheettype-options)
-    - [`useRunDefinition(definitionId, options?)`](#userundefinitiondefinitionid-options)
-    - [`useRunPublishedDefinition(publishedDefinitionId, options?)`](#userunpublisheddefinitionpublisheddefinitionid-options)
-    - [`useRunSampleDefinition(sampleDefinitionId, options?)`](#userunsampledefinitionsampledefinitionid-options)
-    - [`useTriggerHttpWorkflow(workflowId, payload, options?)`](#usetriggerhttpworkflowworkflowid-payload-options)
-    - [`useTriggerWorkflow(workflowId, options?)`](#usetriggerworkflowworkflowid-options)
-    - [`useWorkbook(workbookId, options?)`](#useworkbookworkbookid-options)
-    - [`useWorkflow(workflowId, options?)`](#useworkflowworkflowid-options)
-    - [`useWorksheet(worksheetId, options?)`](#useworksheetworksheetid-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](#configuration)
-    - [Default Query Configuration](#default-query-configuration)
-    - [Customizable Parameters](#customizable-parameters)
-  - [Advanced Usage](#advanced-usage)
-    - [Error Handling](#error-handling)
-    - [Manual Refetching](#manual-refetching)
-  - [Re-exports](#re-exports)
-  - [TypeScript Support](#typescript-support)
-  - [Development](#development)
+- [Features](#features)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Query Provider Setup](#query-provider-setup)
+  - [Boilerplate Integration](#boilerplate-integration)
+  - [Hook Examples](#hook-examples)
+- [Detailed Reference — Common Hooks](#detailed-reference--common-hooks)
+- [Complete Hook Reference](#complete-hook-reference)
+- [Configuration](#configuration)
+- [Advanced Usage](#advanced-usage)
+- [Re-exports](#re-exports)
+- [TypeScript Support](#typescript-support)
+- [Development](#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)
+- ✅ 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
 
 ```bash
 npm install @bluecopa/react
-# or with pnpm
+# or
 pnpm add @bluecopa/react
 ```
 
 ### Peer Dependencies
 
-This package requires the following in your application:
-
 ```bash
 npm install react@^18.0.0 react-dom@^18.0.0
 ```
 
+Also install TanStack React Query if you set up the `QueryClient` yourself:
+
+```bash
+npm install @tanstack/react-query
+```
+
 ## Usage
 
 ### Query Provider Setup
 
-Wrap your application with the React Query provider:
+Wrap your application with the React Query provider and configure the core SDK once:
 
 ```tsx
 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, // 1 minute
-      refetchOnWindowFocus: false,
-    },
+    queries: { staleTime: 60 * 1000, refetchOnWindowFocus: false },
   },
 });
 
@@ -100,15 +75,16 @@ function App() {
   return (
     <QueryClientProvider client={queryClient}>
       <YourApp />
-      <ReactQueryDevtools initialIsOpen={false} />
     </QueryClientProvider>
   );
 }
 ```
 
+`copaSetConfig`, `copaGetConfig`, and the `reactQuery` / `ReactQueryDevtools` namespaces are re-exported from `@bluecopa/react` (see [Re-exports](#re-exports)).
+
 ### Boilerplate Integration
 
-For projects using the Bluecopa React boilerplate, use the pre-configured `QueryProvider` component that handles API configuration automatically:
+For projects generated by [`create-bluecopa-react-app`](https://www.npmjs.com/package/create-bluecopa-react-app), use a pre-configured `QueryProvider` that wires config from env vars:
 
 ```tsx
 // src/providers/query-provider.tsx
@@ -126,10 +102,7 @@ export default function QueryProvider({
     () =>
       new QueryClient({
         defaultOptions: {
-          queries: {
-            staleTime: 60 * 1000, // 1 minute
-            refetchOnWindowFocus: false,
-          },
+          queries: { staleTime: 60 * 1000, refetchOnWindowFocus: false },
         },
       }),
   );
@@ -140,7 +113,6 @@ export default function QueryProvider({
       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);
@@ -164,1233 +136,492 @@ export default function QueryProvider({
 }
 ```
 
-**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:
-
-```tsx
-import QueryProvider from "./providers/query-provider";
+**Environment Variables:**
 
-function App() {
-  return (
-    <QueryProvider>
-      <YourApp />
-    </QueryProvider>
-  );
-}
-```
+| 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=`    |
 
-This setup automatically configures the API client with your environment-specific settings and applies optimal caching defaults.
+> **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
 
-#### `useUser` - Fetch authenticated user
-
 ```tsx
 import { useUser } from "@bluecopa/react";
 
 function UserProfile() {
   const { data, isLoading, error } = useUser({
-    staleTime: 5 * 60 * 1000, // 5 minutes
+    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>;
 }
 ```
 
-#### `useDataset` - Fetch dataset with query controls
-
-```tsx
-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
-
 ```tsx
 import { useRows } from "@bluecopa/react";
 
 function TableRows({ tableId }) {
-  const { data, isLoading, error } = useRows(tableId, {
+  const { data, isLoading } = 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>
-  );
+  return <div>Total: {data?.total_count ?? 0}</div>;
 }
 ```
 
-📖 **For detailed documentation on `useRows` including filtering, pagination, and advanced usage, see [docs/useRows.md](./docs/useRows.md)**
-
-#### `useGetFileByFolderIdAndName` - Look up a filebox file by folder + name
-
-```tsx
-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>
-  );
-}
-```
+📖 For `useRows` filtering, pagination, and operator details, see [docs/useRows.md](./docs/useRows.md).
 
-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.
+## Detailed Reference — Common Hooks
 
-## API Documentation
+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 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
+Fetches the authenticated user. `options` extends `UseQueryOptions`.
 
 ### `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
+Fetches a dataset by id. `options` accepts `limit` and standard query options.
 
 ### `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
+Fetches a representative sample of dataset rows. Supports `enabled`.
 
 ### `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
+Fetches computed metric data by id.
 
-### `useInputTable(inputTableId, options?)`
+### `useInputTable(inputTableId, inputTableViewId, 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
+Fetches an input table for a given view. `options` accepts `limitParams` (`limit`, `limitFrom: 'top' | 'bottom'`).
 
 ### `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:**
-
-```tsx
-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](./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.
+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](./docs/useRows.md).
 
-**Parameters:**
+### `useGetWorkbooksByType(type, options?)`
 
-- `options` (optional): Mutation options. `mutate(request: ReplyToConversationRequest)` triggers the reply.
+Lists workbooks of a given type.
 
-**Returns:** Mutation result.
+### `useTriggerWorkflow(options?)` / `useTriggerHttpWorkflow(options?)`
 
-### `useFilterMessagesBySenderId(params, options?)`
+Mutations that trigger a workflow (or HTTP-trigger workflow) run. Call `mutate(variables)`.
 
-Fetches messages filtered by sender id.
+### `useSaveWorkbook(options?)` / `usePublishWorkbook(options?)`
 
-**Parameters:**
+Mutations to save a draft or publish a workbook.
 
-- `params`: `FilterOnSenderId` — sender id and paging
-- `options` (optional): Query options
+## Complete Hook Reference
 
-**Returns:** Query result with `data: PageChunkEmailMessage`.
+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.
 
-_— File hooks (mutations & download)_
+### User & Teams
 
-### `useFileUpload(options?)`
+- `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.
 
-Uploads file data to storage and returns the resulting file id/path.
+### Dataset
 
-**Parameters:**
+- `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.
 
-- `options` (optional): Mutation options. `mutate(request: FileUploadRequest)` triggers the upload.
+### Datasets Hub
 
-**Returns:** Mutation result with `data: FileUploadResponse`.
+- `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.
 
-### `useFileDownload(params, options?)`
+### Virtual Datasets Hub
 
-Downloads a file by id. Implemented as a query (auto-fetches when params are valid).
+- `useListVirtualDatasets(query?, options?)` — query (hub) — list virtual datasets.
+- `useGetVirtualDataset(virtualDatasetId, options?)` — query (hub) — one virtual dataset.
+- `useCreateVirtualDataset(options?)` — mutation (hub) — create a virtual dataset.
 
-**Parameters:**
+### Metric
 
-- `params`: `{ fileId: string; contentType: string; method: 'GET' | 'PUT' }`
-- `options` (optional): Query options
+- `useMetric(metricId, options?)` — query — a metric by id.
 
-**Returns:** Query result with the downloaded data.
+### Input Table
 
-_— Form hooks_
+- `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.
 
-### `useGetFormById(formId, options?)`
+### Input Tables Hub
 
-Fetches a form by id.
+- `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.
 
-**Parameters:**
+### Workbook
 
-- `formId`: Form id (null/undefined disables the query)
-- `options` (optional): Query options
+- `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.
 
-**Returns:** Query result with the form definition.
+### Workbooks Hub
 
-### `useGetFormSchema(formInstanceId, formRevision, options?)`
+- `useListWorkbooks(query?, options?)` — query (hub) — list workbooks.
+- `useGetWorkbook(workbookId, options?)` — query (hub) — one workbook.
 
-Fetches a form's schema for a given instance + revision.
+### Worksheet / Views
 
-**Parameters:**
+- `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.
 
-- `formInstanceId`: Form instance id (null/undefined disables the query)
-- `formRevision`: Schema revision (string or number, null/undefined disables the query)
-- `options` (optional): Query options
+### Workflow
 
-**Returns:** Query result with the form schema.
+- `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.
 
-### `useGetFormData(formId, options?)`
+### Workflows Hub
 
-Fetches submitted form data.
+- `useListWorkflows(query?, options?)` — query (hub) — list workflows.
+- `useGetWorkflow(workflowId, options?)` — query (hub) — one workflow.
+- `useSaveWorkflow(options?)` — mutation (hub) — save/update a workflow.
 
-**Parameters:**
+### HTTP Triggers Hub
 
-- `formId`: Form id (null/undefined disables the query)
-- `options` (optional): Query options
+- `useListHttpTriggers(query?, options?)` — query (hub) — list HTTP triggers.
+- `useGetHttpTrigger(triggerId, options?)` — query (hub) — one HTTP trigger.
 
-**Returns:** Query result with the form data.
+### Definitions (Pipeline runs)
 
-### `useCreateOrUpdateForm(options?)`
+- `useRunDefinition(options?)` — mutation — run a definition.
+- `useRunPublishedDefinition(options?)` — mutation — run a published definition.
+- `useRunSampleDefinition(options?)` — mutation — run a definition against a sample.
 
-Creates or updates a form definition.
+### Recon (v1)
 
-**Parameters:**
+- `useRunRecon(options?)` — mutation — run a reconciliation.
+- `useGetAllRecon(options?)` — query — all recon workflows.
 
-- `options` (optional): Mutation options. `mutate(request: CreateOrUpdateFormRequest)` triggers the save.
+### Recon V2
 
-**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[]`.
+- `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
 
@@ -1410,16 +641,15 @@ const queryClient = new QueryClient({
 
 ### Customizable Parameters
 
-All hooks accept standard TanStack React Query options:
+Query hooks accept the full TanStack React Query `UseQueryOptions` type. The most commonly used are a small subset of what's available:
 
 ```ts
-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
+// Subset of UseQueryOptions — see TanStack Query docs for the complete list
+interface CommonQueryOptions {
+  enabled?: boolean;
+  staleTime?: number;
+  gcTime?: number;
+  retry?: number | boolean;
 }
 ```
 
@@ -1427,77 +657,52 @@ interface QueryOptions {
 
 ### Error Handling
 
+Errors are normalised to `{ message, status }` by the core SDK:
+
 ```tsx
-useUser({
-  onError: (error) => {
-    console.error("User fetch failed:", error.message);
-    // Custom error recovery logic
-  },
-});
+const { error } = useUser();
+if (error) console.error(error.message);
 ```
 
 ### Manual Refetching
 
 ```tsx
 function ManualRefetch() {
-  const { data, refetch } = useUser();
-
-  return (
-    <div>
-      <button onClick={() => refetch()}>Refresh</button>
-    </div>
-  );
+  const { refetch } = useUser();
+  return <button onClick={() => refetch()}>Refresh</button>;
 }
 ```
 
 ## Re-exports
 
-This package re-exports core TanStack React Query utilities:
+`@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`](https://www.npmjs.com/package/@bluecopa/core) — `copaSetConfig`, `copaGetConfig`, `copaApi`, `hubClient`, `copaInputTableDb`, `copaUtils`, and shared types.
 
 ```ts
 import {
-  useQuery,
-  useMutation,
-  QueryClient,
-  QueryClientProvider,
+  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 with TypeScript. All hooks provide proper type inference and IntelliSense support. Extend types for custom use cases:
-
-```ts
-import { User } from "@bluecopa/react";
-
-interface CustomUser extends User {
-  role: string;
-  permissions: string[];
-}
-```
+Fully typed. All hooks provide type inference and IntelliSense; shared types are exported from the package root.
 
 ## Development
 
 ```bash
-# 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
+pnpm build          # Vite build (pnpm build:umd for the UMD bundle)
+pnpm dev            # watch build
+pnpm test           # Vitest
+pnpm test:watch     # Vitest watch
 ```