@bluecopa/react 0.1.3 → 0.1.5

package/README.md

@@ -1,183 +1,593 @@
-# @bluecopa/reactjs
-
-A React.js wrapper for TanStack React Query with Bluecopa core integration.
+# @bluecopa/react [![npm version](https://img.shields.io/npm/v/@bluecopa/react)](https://www.npmjs.com/package/@bluecopa/react) [![License](https://img.shields.io/npm/l/@bluecopa/react)](https://github.com/bluecopa/blui/blob/main/packages/react/LICENSE)
+
+## 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  ](#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)
+    - [`useGetFileUrlByFileId(fileId, options?)`](#usegetfileurlbyfileidfileid-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)
+  - [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
+
+- ✅ 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
 
 ```bash
-npm install @bluecopa/reactjs @bluecopa/core @tanstack/react-query
+npm install @bluecopa/react
+# or with pnpm
+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
 ```
 
 ## Usage
 
-### 1. Setup the Provider
+### Query Provider Setup
 
-Wrap your app with the `BlueCopaQueryProvider`:
+Wrap your application with the React Query provider:
 
 ```tsx
-import React from 'react';
-import { BlueCopaQueryProvider } from '@bluecopa/reactjs';
-import { ApiClient } from '@bluecopa/core';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 
-const apiClient = new ApiClient({
-  baseURL: 'https://api.example.com',
-  // other config options
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 60 * 1000, // 1 minute
+      refetchOnWindowFocus: false,
+    },
+  },
 });
 
 function App() {
   return (
-    <BlueCopaQueryProvider 
-      config={{
-        apiClient,
-        defaultStaleTime: 5 * 60 * 1000, // 5 minutes
-        defaultCacheTime: 10 * 60 * 1000, // 10 minutes
-        enableDevtools: true,
-      }}
-    >
-      <YourAppComponents />
-    </BlueCopaQueryProvider>
+    <QueryClientProvider client={queryClient}>
+      <YourApp />
+      <ReactQueryDevtools initialIsOpen={false} />
+    </QueryClientProvider>
   );
 }
 ```
 
-### 2. Using Queries
+### Boilerplate Integration
+
+For projects using the Bluecopa React boilerplate, use the pre-configured `QueryProvider` component that handles API configuration automatically:
 
 ```tsx
-import React from 'react';
-import { useQuery } from '@bluecopa/reactjs';
-
-function UserProfile({ userId }: { userId: string }) {
-  const { data, isLoading, error } = useQuery({
-    queryKey: {
-      scope: 'users',
-      endpoint: `/users/${userId}`,
+// 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,
+      },
     },
-    staleTime: 5 * 60 * 1000,
-  });
+  }));
+
+  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 || "",
+    });
+  }, []);
 
-  if (isLoading) return <div>Loading...</div>;
-  if (error) return <div>Error: {error.message}</div>;
-
-  return <div>User: {data?.name}</div>;
+  return (
+    <QueryClientProvider client={queryClient}>
+      {children}
+      <ReactQueryDevtools initialIsOpen={false} />
+    </QueryClientProvider>
+  );
 }
 ```
 
-### 3. Using Mutations
+**Required Environment Variables:**
 
-```tsx
-import React from 'react';
-import { usePost, usePut } from '@bluecopa/reactjs';
+| 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=` |
 
-function CreateUser() {
-  const createUser = usePost('/users', {
-    onSuccess: (data) => {
-      console.log('User created:', data);
-    },
-    onError: (error) => {
-      console.error('Failed to create user:', error);
-    },
-  });
+**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
+```
 
-  const handleSubmit = (userData: any) => {
-    createUser.mutate(userData);
-  };
+Then wrap your application with this provider:
 
+```tsx
+import QueryProvider from './providers/query-provider';
+
+function App() {
   return (
-    <form onSubmit={handleSubmit}>
-      {/* form fields */}
-      <button 
-        type="submit" 
-        disabled={createUser.isPending}
-      >
-        {createUser.isPending ? 'Creating...' : 'Create User'}
-      </button>
-    </form>
+    <QueryProvider>
+      <YourApp />
+    </QueryProvider>
   );
 }
 ```
 
-### 4. Using Infinite Queries
+This setup automatically configures the API client with your environment-specific settings and applies optimal caching defaults.
+
+### Hook Examples
+
+#### `useUser` - Fetch authenticated user
 
 ```tsx
-import React from 'react';
-import { useInfiniteQuery } from '@bluecopa/reactjs';
-
-function UserList() {
-  const {
-    data,
-    fetchNextPage,
-    hasNextPage,
-    isFetchingNextPage,
-    isLoading,
-  } = useInfiniteQuery({
-    queryKey: {
-      scope: 'users',
-      endpoint: '/users',
-      params: { limit: 10 },
-    },
-    getNextPageParam: (lastPage) => lastPage.nextPage,
-  });
+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>;
+}
+```
 
-  return (
-    <div>
-      {data?.pages.map((page, i) => (
-        <div key={i}>
-          {page.data.map((user: any) => (
-            <div key={user.id}>{user.name}</div>
-          ))}
-        </div>
-      ))}
-      {hasNextPage && (
-        <button
-          onClick={() => fetchNextPage()}
-          disabled={isFetchingNextPage}
-        >
-          {isFetchingNextPage ? 'Loading more...' : 'Load More'}
-        </button>
-      )}
-    </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>;
 }
 ```
 
-## API Reference
+## 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
+
+### `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
+
+### `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
+
+ 
+## Configuration
+
+### Default Query Configuration
+
+```tsx
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      retry: 3,
+      staleTime: 1000 * 60 * 5, // 5 minutes
+      gcTime: 1000 * 60 * 10, // 10 minutes
+    },
+  },
+});
+```
+
+### Customizable Parameters
 
-### BlueCopaQueryProvider
+All hooks accept standard TanStack React Query options:
 
-The main provider component that sets up React Query with Bluecopa core integration.
+```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
+}
+```
 
-#### Props
+## Advanced Usage
 
-- `config?: BlueCopaQueryConfig` - Configuration options
+### Error Handling
 
-#### BlueCopaQueryConfig
+```tsx
+useUser({
+  onError: (error) => {
+    console.error('User fetch failed:', error.message);
+    // Custom error recovery logic
+  }
+});
+```
+
+### Manual Refetching
 
-```typescript
-interface BlueCopaQueryConfig {
-  apiClient?: ApiClient;
-  queryClient?: QueryClient;
-  defaultStaleTime?: number;
-  defaultCacheTime?: number;
-  defaultRetry?: number | boolean;
-  enableDevtools?: boolean;
+```tsx
+function ManualRefetch() {
+  const { data, refetch } = useUser();
+  
+  return (
+    <div>
+      <button onClick={() => refetch()}>Refresh</button>
+    </div>
+  );
 }
 ```
 
-### Hooks
+## Re-exports
 
-#### useQuery
+This package re-exports core TanStack React Query utilities:
 
-Enhanced version of TanStack's useQuery with Bluecopa integration.
+```ts
+import { 
+  useQuery,
+  useMutation,
+  QueryClient,
+  QueryClientProvider,
+  ReactQueryDevtools 
+} from '@bluecopa/react';
+```
 
-#### useMutation, usePost, usePut, usePatch, useDelete
+## TypeScript Support
 
-Enhanced mutation hooks with built-in HTTP method support.
+Fully typed with TypeScript. All hooks provide proper type inference and IntelliSense support. Extend types for custom use cases:
 
-#### useInfiniteQuery
+```ts
+import { User } from '@bluecopa/react';
 
-Enhanced infinite query hook for pagination.
+interface CustomUser extends User {
+  role: string;
+  permissions: string[];
+}
+```
 
 ## Development
 
@@ -188,13 +598,18 @@ pnpm install
 # Build the package
 pnpm build
 
-# Run in development mode (watch)
+# Run development server
 pnpm dev
 
 # Run tests
 pnpm test
-```
 
-## License
+# Run tests in watch mode
+pnpm test:watch
 
-MIT
+# Lint code
+pnpm lint
+
+# Format code
+pnpm format
+```