@bluecopa/core 0.1.4 → 0.1.5

package/README.md

@@ -1,10 +1,29 @@
 # @bluecopa/core
 
-A comprehensive TypeScript library for interacting with the BlueCopa platform, providing utilities, API clients, and configuration management.
-
-**Current Version:** 0.1.2  
-**Node.js:** >=18.0.0  
-**Dependencies:** axios, lodash  
+The core package provides essential API utilities and functions for data management, workbook handling, dataset operations, and definition execution in the Bluecopa platform.
+
+## Table of Contents
+
+- [Version](#version)
+- [Installation](#installation)
+- [Requirements](#requirements)
+- [Configuration](#configuration)
+- [API Reference](#api-reference)
+  - [Dataset Module](#dataset-module)
+  - [Definition Module](#definition-module)
+  - [File Module](#file-module)
+  - [InputTable Module](#inputtable-module)
+  - [Metric Module](#metric-module)
+  - [User Module](#user-module)
+  - [Workbook Module](#workbook-module)
+  - [Workflow Module](#workflow-module)
+  - [Worksheet Module](#worksheet-module)
+- [Development](#development)
+- [Related Packages](#related-packages)
+
+## Version
+
+Current version: 0.1.4
 
 ## Installation
 
@@ -12,301 +31,141 @@ A comprehensive TypeScript library for interacting with the BlueCopa platform, p
 npm install @bluecopa/core
 ```
 
-## Quick Start
-
-### 1. Configuration
-
-Before using any API functions, you need to configure the library with your credentials:
-
-```typescript
-import { copaSetConfig } from '@bluecopa/core';
-
-copaSetConfig({
-  apiBaseUrl: 'https://your-api-base-url.com/api/v1',
-  accessToken: 'your-access-token',
-  workspaceId: 'your-workspace-id'
-});
-```
-
-### 2. Basic Usage
-
-```typescript
-import { copaApi, copaUtils, copaTailwindConfig } from '@bluecopa/core';
-
-// Use utility functions
-const formattedDate = copaUtils.formatDate(new Date());
+## Requirements
 
-// Make API calls
-const userData = await copaApi.user.getLoggedInUserDetails();
-```
+- Node.js >= 18.0.0
+- Dependencies:
+  - axios (1.11.0) - For HTTP requests
+  - lodash (4.17.21) - For utility functions
 
-## API Reference
 
-### Configuration
+## Configuration
 
-#### `copaSetConfig(config: Partial<Config>)`
+The package uses a singleton-based configuration system to manage API settings. Configure it before making API calls.
 
-Sets the global configuration for the library.
+Import and set the config:
 
 ```typescript
 import { copaSetConfig } from '@bluecopa/core';
 
 copaSetConfig({
-  apiBaseUrl: 'https://api.bluecopa.com/api/v1',
-  accessToken: 'eyJ...',
-  workspaceId: 'workspace123'
+  apiBaseUrl: 'https://api.bluecopa.com', // Base URL for API endpoints
+  accessToken: 'your-access-token',       // Authentication token
+  workspaceId: 'your-workspace-id'        // Current workspace identifier
 });
 ```
 
-#### `copaGetConfig(): Config`
+- `copaSetConfig(partialConfig: Partial<Config>)`: Updates the configuration.
+- `copaGetConfig()`: Retrieves the current configuration.
+- `resetConfig()`: Resets to default empty values.
 
-Retrieves the current configuration.
+The Config interface:
 
 ```typescript
-import { copaGetConfig } from '@bluecopa/core';
-
-const config = copaGetConfig();
-console.log(config.apiBaseUrl);
-```
-
-### API Client (`copaApi`)
-
-The library provides a comprehensive API client with the following modules:
-
-#### User API (`copaApi.user`)
-
-```typescript
-// Get logged-in user details
-const userDetails = await copaApi.user.getLoggedInUserDetails();
+export interface Config {
+  apiBaseUrl: string;
+  accessToken: string;
+  workspaceId: string;
+}
 ```
 
-#### Metric API (`copaApi.metric`)
+## API Reference
 
-```typescript
-// Get metric data
-const metricId = '0UbwCn75pym1N47D89uS';
-const metricData = await copaApi.metric.getData(metricId);
-```
+All API functions are asynchronous and use the shared `apiClient` for HTTP requests. They handle errors by throwing objects with `message` and `status`. Access via `copaApi.moduleName.functionName()`.
 
-#### Dataset API (`copaApi.dataset`)
+### Dataset Module
+- `copaApi.dataset.getData()`: Retrieves specific dataset data by ID or parameters
+- `copaApi.dataset.getDatasets()`: Fetches a list of datasets
+- `copaApi.dataset.getSampleData()`: Gets sample data for datasets
 
-```typescript
-// Get dataset sample data
-const datasetId = '0UvoE3CHwqYqzrbGdgs1_large_transaction_dataset_csv';
-const datasetData = await copaApi.dataset.getSampleData({
-  datasetId,
-  dataFilter: 'all_data'
-});
-```
+See: [`dataset/getData.ts`](src/api/dataset/getData.ts:1), [`dataset/getSampleData.ts`](src/api/dataset/getSampleData.ts:1), [`dataset/getDatasets.ts`](src/api/dataset/getDatasets.ts:1)
 
-#### Input Table API (`copaApi.inputTable`)
+### Definition Module
+- `copaApi.definition.runDefinition()`: Executes a custom definition
+- `copaApi.definition.runPublishedDefinition()`: Runs a published definition
+- `copaApi.definition.runSampleDefinition()`: Executes a sample definition for testing
 
-```typescript
-// Get input table data
-const inputTableData = await copaApi.inputTable.getData({
-  inputTableId: '0Ub41b684ku2i4vftSg4',
-  inputTableViewId: '0Ub41b58wvLgQecoRWww',
-  limitParams: { 
-    limit: 2000, 
-    limitFrom: 'top' 
-  }
-});
-```
+See: [`definition/runPublishedDefinition.ts`](src/api/definition/runPublishedDefinition.ts:1), [`definition/runSampleDefinition.ts`](src/api/definition/runSampleDefinition.ts:1), [`definition/runDefinition.ts`](src/api/definition/runDefinition.ts:1)
 
-#### Other Available APIs
+### File Module
+- `copaApi.files.getFileUrlByFileId(fileId: string)`: Generates a URL for a file by its ID
 
-- `copaApi.workflow` - Workflow operations
-- `copaApi.files` - File operations
-- `copaApi.definition` - Definition management
+See: [`file/getFileUrlByFileId.ts`](src/api/file/getFileUrlByFileId.ts:1)
 
-### Utilities (`copaUtils`)
+### InputTable Module
+- `copaApi.inputTable.getData()`: Retrieves data from an input table
+- `copaApi.inputTable.getInputTables()`: Fetches all input tables
+- `copaApi.inputTable.getTableById(id: string)`: Gets a specific input table by ID
 
-#### Date Utilities
+See: [`inputTable/getData.ts`](src/api/inputTable/getData.ts:1), [`inputTable/getInputTables.ts`](src/api/inputTable/getInputTables.ts:1), [`inputTable/getTableById.ts`](src/api/inputTable/getTableById.ts:1)
 
-```typescript
-import { copaUtils } from '@bluecopa/core';
+### Metric Module
+- `copaApi.metric.getData()`: Fetches metric data
 
-// Format date to ISO string (YYYY-MM-DD)
-const formatted = copaUtils.formatDate(new Date());
-console.log(formatted); // "2023-12-25"
-```
+See: [`metric/getData.ts`](src/api/metric/getData.ts:1)
 
-#### Metric Utilities
+### User Module
+- `copaApi.user.getLoggedInUserDetails()`: Retrieves details of the currently logged-in user
 
-```typescript
-// Get metric definition
-const metricDefinition = copaUtils.getMetricDefinition(metricId);
-```
+See: [`user/getLoggedInUserDetails.ts`](src/api/user/getLoggedInUserDetails.ts:1)
 
-#### Input Table Utilities
+### Workbook Module
+- `copaApi.workbook.getPublishedWorkbookById(id: string)`: Fetches a published workbook by ID
+- `copaApi.workbook.getWorkbooksByType(type: string)`: Retrieves workbooks filtered by type
 
-```typescript
-// Input table definition utilities
-const inputTableDef = copaUtils.inputTableUtils.getDefinition(tableId);
-```
+See: [`workbook/getPublishedWorkbookById.ts`](src/api/workbook/getPublishedWorkbookById.ts:1), [`workbook/getWorkbooksByType.ts`](src/api/workbook/getWorkbooksByType.ts:1)
 
-### Tailwind Configuration (`copaTailwindConfig`)
+### Workflow Module
+- `copaApi.workflow.getWorkflowInstanceStatusById(id: string)`: Checks the status of a workflow instance
+- `copaApi.workflow.triggerHttpWorkflowById(id: string)`: Triggers an HTTP-based workflow
+- `copaApi.workflow.triggerWorkflowById(id: string)`: Triggers a workflow by ID
 
-The library includes a pre-configured Tailwind CSS configuration optimized for BlueCopa applications:
+See: [`workflow/triggerHttpWorkflowById.ts`](src/api/workflow/triggerHttpWorkflowById.ts:1), [`workflow/triggerWorkflowById.ts`](src/api/workflow/triggerWorkflowById.ts:1), [`workflow/getWorkflowInstanceStatusById.ts`](src/api/workflow/getWorkflowInstanceStatusById.ts:1)
 
-```typescript
-import { copaTailwindConfig } from '@bluecopa/core';
+### Worksheet Module
+- `copaApi.worksheet.getWorksheets()`: Fetches all worksheets
+- `copaApi.worksheet.getWorksheetsByType(type: string)`: Retrieves worksheets by type
 
-// Use in your tailwind.config.js
-module.exports = {
-  ...copaTailwindConfig,
-  // Your additional configurations
-};
-```
+See: [`worksheet/getWorksheets.ts`](src/api/worksheet/getWorksheets.ts:1), [`worksheet/getWorksheetsByType.ts`](src/api/worksheet/getWorksheetsByType.ts:1)
 
-## Integration with TanStack Query
+## Examples
 
-The library works seamlessly with TanStack Query for state management and caching:
+### 1. Get Input Tables
+Fetches all input tables from the API.
 
 ```typescript
-import { createQuery } from '@tanstack/svelte-query';
 import { copaApi } from '@bluecopa/core';
 
-// Create a query for user data
-export const createUserDetailsQuery = (enabled = true) => {
-  return createQuery({
-    queryKey: ['user'],
-    queryFn: async () => {
-      return await copaApi.user.getLoggedInUserDetails();
-    },
-    enabled,
-    staleTime: 1000 * 60 * 5, // 5 minutes
-    retry: 2
-  });
-};
-
-// Create a query for metric data
-export const createMetricDataQuery = (metricId: string, enabled = true) => {
-  return createQuery({
-    queryKey: ['metricData', metricId],
-    queryFn: async () => {
-      return await copaApi.metric.getData(metricId);
-    },
-    enabled,
-    staleTime: 1000 * 60 * 5, // 5 minutes
-    retry: 2
-  });
-};
-```
-
-## Complete Example
-
-Here's a complete example of using the library in a Svelte component:
-
-```svelte
-<script lang="ts">
-  import { onMount } from 'svelte';
-  import { 
-    copaSetConfig, 
-    copaApi, 
-    copaUtils 
-  } from '@bluecopa/core';
-  import { createQuery } from '@tanstack/svelte-query';
-
-  let isConfigured = false;
-  let formattedDate = '';
-
-  onMount(async () => {
-    // Configure the library
-    copaSetConfig({
-      apiBaseUrl: `${window.location.origin}/api/v1`,
-      accessToken: 'your-access-token',
-      workspaceId: 'your-workspace-id'
-    });
-
-    isConfigured = true;
-    formattedDate = copaUtils.formatDate(new Date());
-  });
-
-  // Create reactive queries
-  $: userQuery = isConfigured ? createQuery({
-    queryKey: ['user'],
-    queryFn: () => copaApi.user.getLoggedInUserDetails()
-  }) : null;
-
-  $: metricQuery = isConfigured ? createQuery({
-    queryKey: ['metric', 'metricId123'],
-    queryFn: () => copaApi.metric.getData('metricId123')
-  }) : null;
-</script>
-
-<main>
-  <h1>BlueCopa Dashboard</h1>
-  
-  <p>Today's date: {formattedDate}</p>
-  
-  {#if userQuery}
-    {#if $userQuery.isLoading}
-      <p>Loading user data...</p>
-    {:else if $userQuery.isError}
-      <p>Error: {$userQuery.error.message}</p>
-    {:else if $userQuery.isSuccess}
-      <p>Welcome, {$userQuery.data.name}!</p>
-    {/if}
-  {/if}
-</main>
-```
-
-## Error Handling
-
-The library includes built-in error handling. API calls will throw errors that can be caught and handled:
+// Configure first
+copaSetConfig({ apiBaseUrl: 'https://api.example.com', accessToken: 'token', workspaceId: 'ws1' });
 
-```typescript
-try {
-  const userData = await copaApi.user.getLoggedInUserDetails();
-  console.log(userData);
-} catch (error) {
-  console.error('Failed to fetch user data:', error);
-}
+// Use API
+const { getInputTables } = copaApi.inputTable;
+const { getWorkbooksByType } = copaApi.workbook;
 ```
 
-When using with TanStack Query, errors are automatically handled and exposed through the query state:
+### 2. Get Workbooks by Type
+Retrieves workbooks filtered by a specific type.
 
 ```typescript
-const userQuery = createQuery({
-  queryKey: ['user'],
-  queryFn: () => copaApi.user.getLoggedInUserDetails(),
-  retry: 2,
-  retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000)
-});
+import { copaApi } from '@bluecopa/core';
+import type { Worksheet } from "$models/gen/Api";
 
-// Access error state
-if (userQuery.isError) {
-  console.error('Query failed:', userQuery.error);
+try {
+  const workbooks = await copaApi.workbook.getWorkbooksByType('dashboard' as Worksheet["type"]);
+  console.log(workbooks); // Array of Worksheet
+} catch (error: any) {
+  console.error(error.message, error.status);
 }
 ```
 
-## TypeScript Support
-
-The library is written in TypeScript and includes full type definitions:
-
-```typescript
-import type { Config } from '@bluecopa/core';
-
-const config: Config = {
-  apiBaseUrl: 'https://api.example.com',
-  accessToken: 'token',
-  workspaceId: 'workspace'
-};
-```
-
 ## Development
 
-### Building the Library
-
-```bash
-npm run build
-```
-
-### Development Mode
+- Run the build: `npm run build` (in the root or package-specific script)
+- TypeScript configuration: See [tsconfig.json](tsconfig.json)
+- Vite configuration: See [vite.config.ts](vite.config.ts)
 
-```bash
-npm run dev
-```
+## Related Packages
 
-This will build the library in watch mode, automatically rebuilding when files change.
+- [@bluecopa/react](packages/react): React hooks that utilize core APIs
+- [@bluecopa/boilerplate](packages/boilerplate/react): React boilerplate templates for Bluecopa applications

package/dist/api/dataset/getDatasets.d.ts

@@ -0,0 +1,2 @@
+import { Worksheet } from '../../../../models/src/lib/gen/Api';
+export declare const getAllDatasets: () => Promise<Worksheet[]>;

package/dist/api/dataset/index.d.ts

@@ -1,2 +1,3 @@
 export * from './getData';
 export * from './getSampleData';
+export * from './getDatasets';

package/dist/api/index.d.ts

@@ -6,3 +6,5 @@ export * as definition from './definition';
 export * as metric from './metric';
 export * as dataset from './dataset';
 export * as inputTable from './inputTable';
+export * as workbook from './workbook';
+export * as worksheet from './worksheet';

package/dist/api/inputTable/getInputTables.d.ts

@@ -0,0 +1,2 @@
+import { InputTable } from '../../../../models/src/lib/gen/Api';
+export declare const getInputTables: () => Promise<InputTable[]>;

package/dist/api/inputTable/index.d.ts

@@ -1,2 +1,3 @@
 export * from './getData';
 export * from './getTableById';
+export * from './getInputTables';

package/dist/api/workbook/getWorkbooksByType.d.ts

@@ -0,0 +1,2 @@
+import { Worksheet } from '../../../../models/src/lib/gen/Api';
+export declare const getWorkbooksByType: (type: Worksheet["type"]) => Promise<Worksheet[]>;

package/dist/api/workbook/index.d.ts

@@ -0,0 +1,2 @@
+export * from './getWorkbooksByType';
+export * from './getPublishedWorkbookById';

package/dist/api/workflow/getWorkflowInstanceStatusById.d.ts

@@ -0,0 +1,31 @@
+export type WorkflowStatusRequest = ReadonlyArray<{
+    instanceId: string;
+    parentId: string;
+}>;
+export declare enum WorkflowStatus {
+    Succeeded = "Succeeded",
+    Failed = "Failed",
+    Running = "Running",
+    NotFound = "NotFound"
+}
+export type StepInfo = {
+    stepId: string;
+    name: string;
+    stepOutput: Record<string, any>;
+};
+export type WorkflowStatusResponse = {
+    instanceId: string;
+    processName: string;
+    parentId: string;
+    status: WorkflowStatus;
+    message: string;
+    data: {
+        completed: StepInfo[];
+        running: StepInfo[];
+        failed?: StepInfo[];
+    };
+    completedAt: string;
+    error?: string;
+};
+export type WorkflowStatusResponses = ReadonlyArray<WorkflowStatusResponse>;
+export declare const getWorkflowInstanceStatusById: (request: WorkflowStatusRequest) => Promise<WorkflowStatusResponses>;

package/dist/api/workflow/index.d.ts

@@ -1,2 +1,3 @@
-export * from './triggerHttpWorkflow';
-export * from './triggerWorkflow';
+export * from './triggerHttpWorkflowById';
+export * from './triggerWorkflowById';
+export * from './getWorkflowInstanceStatusById';

package/dist/api/workflow/{triggerHttpWorkflow.d.ts → triggerHttpWorkflowById.d.ts}

@@ -17,4 +17,4 @@ export interface TriggerHttpWorkflowResponse {
  * @returns Promise<TriggerHttpWorkflowResponse> The triggered workflow details
  * @throws Error if the request fails
  */
-export declare function triggerHttpWorkflow({ data, triggerId, }: TriggerHttpWorkflowRequest): Promise<TriggerHttpWorkflowResponse>;
+export declare function triggerHttpWorkflowById({ data, triggerId, }: TriggerHttpWorkflowRequest): Promise<TriggerHttpWorkflowResponse>;

package/dist/api/workflow/{triggerWorkflow.d.ts → triggerWorkflowById.d.ts}

@@ -20,4 +20,4 @@ export interface TriggerWorkflowResponse {
  * @returns Promise<TriggerWorkflowResponse> The triggered workflow details
  * @throws Error if the request fails
  */
-export declare function triggerWorkflow({ parentId, triggerBy, }: TriggerWorkflowRequest): Promise<TriggerWorkflowResponse>;
+export declare function triggerWorkflowById({ parentId, triggerBy, }: TriggerWorkflowRequest): Promise<TriggerWorkflowResponse>;

package/dist/api/worksheet/getWorksheetsByType.d.ts

@@ -0,0 +1,2 @@
+import { Worksheet } from '../../../../models/src/lib/gen/Api';
+export declare const getWorksheetsByType: (type: Worksheet["type"]) => Promise<Worksheet[]>;

package/dist/api/worksheet/index.d.ts

@@ -1 +1,2 @@
 export * from './getWorksheets';
+export * from './getWorksheetsByType';