@bluecopa/core 0.1.2

package/README.md

@@ -0,0 +1,312 @@
+# @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  
+
+## Installation
+
+```bash
+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());
+
+// Make API calls
+const userData = await copaApi.user.getLoggedInUserDetails();
+```
+
+## API Reference
+
+### Configuration
+
+#### `copaSetConfig(config: Partial<Config>)`
+
+Sets the global configuration for the library.
+
+```typescript
+import { copaSetConfig } from '@bluecopa/core';
+
+copaSetConfig({
+  apiBaseUrl: 'https://api.bluecopa.com/api/v1',
+  accessToken: 'eyJ...',
+  workspaceId: 'workspace123'
+});
+```
+
+#### `copaGetConfig(): Config`
+
+Retrieves the current configuration.
+
+```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();
+```
+
+#### Metric API (`copaApi.metric`)
+
+```typescript
+// Get metric data
+const metricId = '0UbwCn75pym1N47D89uS';
+const metricData = await copaApi.metric.getData(metricId);
+```
+
+#### Dataset API (`copaApi.dataset`)
+
+```typescript
+// Get dataset sample data
+const datasetId = '0UvoE3CHwqYqzrbGdgs1_large_transaction_dataset_csv';
+const datasetData = await copaApi.dataset.getSampleData({
+  datasetId,
+  dataFilter: 'all_data'
+});
+```
+
+#### Input Table API (`copaApi.inputTable`)
+
+```typescript
+// Get input table data
+const inputTableData = await copaApi.inputTable.getData({
+  inputTableId: '0Ub41b684ku2i4vftSg4',
+  inputTableViewId: '0Ub41b58wvLgQecoRWww',
+  limitParams: { 
+    limit: 2000, 
+    limitFrom: 'top' 
+  }
+});
+```
+
+#### Other Available APIs
+
+- `copaApi.workflow` - Workflow operations
+- `copaApi.files` - File operations
+- `copaApi.definition` - Definition management
+
+### Utilities (`copaUtils`)
+
+#### Date Utilities
+
+```typescript
+import { copaUtils } from '@bluecopa/core';
+
+// Format date to ISO string (YYYY-MM-DD)
+const formatted = copaUtils.formatDate(new Date());
+console.log(formatted); // "2023-12-25"
+```
+
+#### Metric Utilities
+
+```typescript
+// Get metric definition
+const metricDefinition = copaUtils.getMetricDefinition(metricId);
+```
+
+#### Input Table Utilities
+
+```typescript
+// Input table definition utilities
+const inputTableDef = copaUtils.inputTableUtils.getDefinition(tableId);
+```
+
+### Tailwind Configuration (`copaTailwindConfig`)
+
+The library includes a pre-configured Tailwind CSS configuration optimized for BlueCopa applications:
+
+```typescript
+import { copaTailwindConfig } from '@bluecopa/core';
+
+// Use in your tailwind.config.js
+module.exports = {
+  ...copaTailwindConfig,
+  // Your additional configurations
+};
+```
+
+## Integration with TanStack Query
+
+The library works seamlessly with TanStack Query for state management and caching:
+
+```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:
+
+```typescript
+try {
+  const userData = await copaApi.user.getLoggedInUserDetails();
+  console.log(userData);
+} catch (error) {
+  console.error('Failed to fetch user data:', error);
+}
+```
+
+When using with TanStack Query, errors are automatically handled and exposed through the query state:
+
+```typescript
+const userQuery = createQuery({
+  queryKey: ['user'],
+  queryFn: () => copaApi.user.getLoggedInUserDetails(),
+  retry: 2,
+  retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000)
+});
+
+// Access error state
+if (userQuery.isError) {
+  console.error('Query failed:', userQuery.error);
+}
+```
+
+## 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
+
+```bash
+npm run dev
+```
+
+This will build the library in watch mode, automatically rebuilding when files change.

package/dist/api/client.d.ts

@@ -0,0 +1,2 @@
+import { AxiosInstance } from 'axios';
+export declare const apiClient: AxiosInstance;

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

@@ -0,0 +1,5 @@
+export declare const getData: (datasetId: string, options?: {
+    limit?: number;
+}) => Promise<{
+    data: any;
+}>;

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

@@ -0,0 +1,8 @@
+export declare const getSampleData: ({ datasetId, dataFilter, duplicateColGroups, datasetType, }: {
+    datasetId: string;
+    dataFilter: "valid_data" | "invalid_data" | "all_data";
+    duplicateColGroups?: string[];
+    datasetType?: string;
+}) => Promise<{
+    data: any;
+}>;

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

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

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

@@ -0,0 +1,3 @@
+export * from './runPublishedDefinition';
+export * from './runSampleDefinition';
+export * from './runDefinition';

package/dist/api/definition/runDefinition.d.ts

@@ -0,0 +1,9 @@
+import { CancelTokenSource } from 'axios';
+import { Definition, Inputs } from '../../../../models/src/lib/ui-models/definitionModel';
+export declare const runDefinition: (props: {
+    inputs: Inputs;
+    definition: Definition;
+    variable: string;
+    source?: CancelTokenSource;
+    limit?: number;
+}) => Promise<import('axios').AxiosResponse<any, any>>;

package/dist/api/definition/runPublishedDefinition.d.ts

@@ -0,0 +1,11 @@
+import { CancelTokenSource } from 'axios';
+export declare const runPublishedDefinition: (props: {
+    describe: string;
+    sheet: {
+        id: string;
+        lastModifiedDate: string;
+    };
+    variable: string;
+    inputs: object;
+    source?: CancelTokenSource;
+}) => Promise<import('axios').AxiosResponse<any, any>>;

package/dist/api/definition/runSampleDefinition.d.ts

@@ -0,0 +1,6 @@
+export declare const runSampleDefinition: (props: {
+    datasetId: string;
+    dataFilter: "valid_data" | "invalid_data" | "all_data";
+    duplicateColGroups?: string[];
+    datasetType?: string;
+}) => Promise<import('axios').AxiosResponse<any, any>>;

package/dist/api/file/getFileUrlByFileId.d.ts

@@ -0,0 +1,18 @@
+export interface GetFileUrlRequest {
+    key: string;
+    contentType: string;
+    method: 'GET' | 'PUT' | 'POST';
+}
+export interface GetFileUrlResponse {
+    url: string;
+}
+/**
+ * Gets a signed URL for a file by its key
+ * @param params - The file request parameters
+ * @param params.key - The file key/path in storage
+ * @param params.contentType - The content type of the file
+ * @param params.method - The HTTP method (GET, PUT, POST)
+ * @returns Promise<GetFileUrlResponse> The signed URL for the file
+ * @throws Error if the request fails
+ */
+export declare function getFileUrlByFileId({ key, contentType, method, }: GetFileUrlRequest): Promise<GetFileUrlResponse>;

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

@@ -0,0 +1 @@
+export * from './getFileUrlByFileId';

package/dist/api/index.d.ts

@@ -0,0 +1,8 @@
+export { apiClient } from './client';
+export * as user from './user';
+export * as workflow from './workflow';
+export * as files from './file';
+export * as definition from './definition';
+export * as metric from './metric';
+export * as dataset from './dataset';
+export * as inputTable from './inputTable';

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

@@ -0,0 +1,11 @@
+import { LimitOptions, SortOptions } from '../../../../models/src/lib/ui-models/workbookModel';
+export declare const getData: ({ inputTableId: inputTableWorkbookId, inputTableViewId, pageParams, limitParams, sortParams, offsetParam, }: {
+    inputTableId: string;
+    inputTableViewId: string;
+    pageParams?: any;
+    limitParams?: LimitOptions;
+    sortParams?: SortOptions;
+    offsetParam?: number;
+}) => Promise<any[] | {
+    data: any;
+}>;

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

@@ -0,0 +1,2 @@
+import { Workbook } from '../../../../models/src/lib/gen/Api';
+export declare const getTableById: (tableId: string) => Promise<Workbook>;

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

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

package/dist/api/metric/getData.d.ts

@@ -0,0 +1,10 @@
+export declare const getData: (metricSheetId: string, options?: {
+    groupKeys?: string[];
+    isKPI?: boolean;
+    plotAsTrend?: boolean;
+    stringValue?: boolean;
+}) => Promise<{
+    data?: undefined;
+} | {
+    data: object[];
+}>;

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

@@ -0,0 +1 @@
+export * from './getData';

package/dist/api/user/getLoggedInUserDetails.d.ts

@@ -0,0 +1,25 @@
+export interface UserDetails {
+    id: string;
+    email: string;
+    name: string;
+    role: string;
+    workspaceId: string;
+    avatar?: string;
+    preferences?: Record<string, any>;
+    lastLoginAt?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ApiResponse<T> {
+    success: boolean;
+    data: T;
+    message?: string;
+}
+/**
+ * Fetches the logged-in user's details from the API
+ * @returns Promise<{ user: UserDetails }> The user's details
+ * @throws Error if the request fails or user is not authenticated
+ */
+export declare function getLoggedInUserDetails(): Promise<{
+    user: UserDetails;
+}>;

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

@@ -0,0 +1 @@
+export { getLoggedInUserDetails, type UserDetails } from './getLoggedInUserDetails';

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

@@ -0,0 +1,5 @@
+import { Workbook } from '../../../../models/src/lib/gen/Api';
+export declare const getPublishedWorkbookById: ({ type, id, }: {
+    type: string;
+    id: string;
+}) => Promise<Workbook>;

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

@@ -0,0 +1,2 @@
+export * from './triggerHttpWorkflow';
+export * from './triggerWorkflow';

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

@@ -0,0 +1,20 @@
+export interface TriggerHttpWorkflowRequest {
+    data: Record<string, any>;
+    triggerId: string;
+}
+export interface TriggeredWorkflow {
+    workflowId: string;
+    triggerId: string;
+}
+export interface TriggerHttpWorkflowResponse {
+    triggeredWorkflows: TriggeredWorkflow[];
+}
+/**
+ * Triggers an HTTP workflow with the provided data
+ * @param params - The trigger parameters
+ * @param params.triggerId - The ID of the HTTP trigger
+ * @param params.data - The data payload to send to the workflow
+ * @returns Promise<TriggerHttpWorkflowResponse> The triggered workflow details
+ * @throws Error if the request fails
+ */
+export declare function triggerHttpWorkflow({ data, triggerId, }: TriggerHttpWorkflowRequest): Promise<TriggerHttpWorkflowResponse>;

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

@@ -0,0 +1,23 @@
+export interface TriggerWorkflowRequest {
+    parentId: string;
+    triggerBy: string;
+}
+export interface TriggerWorkflowResponse {
+    workbookId: string;
+    triggerBy: string;
+    instanceId: string;
+    triggerId: string;
+    workflowId: string;
+    status: string;
+    triggeredAt: string;
+    message: string;
+}
+/**
+ * Triggers workflow
+ * @param params - The trigger parameters
+ * @param params.parentId - The ID of the workflow to be triggered
+ * @param params.triggerBy - The user who triggered the workflow
+ * @returns Promise<TriggerWorkflowResponse> The triggered workflow details
+ * @throws Error if the request fails
+ */
+export declare function triggerWorkflow({ parentId, triggerBy, }: TriggerWorkflowRequest): Promise<TriggerWorkflowResponse>;

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

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

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

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

package/dist/config.d.ts

@@ -0,0 +1,18 @@
+export interface Config {
+    apiBaseUrl: string;
+    accessToken: string;
+    workspaceId: string;
+}
+declare class ConfigSingleton {
+    private static instance;
+    private config;
+    private constructor();
+    static getInstance(): ConfigSingleton;
+    setConfig(newConfig: Partial<Config>): void;
+    getConfig(): Config;
+    resetConfig(): void;
+}
+export declare function setConfig(newConfig: Partial<Config>): void;
+export declare function getConfig(): Config;
+export declare function resetConfig(): void;
+export { ConfigSingleton };

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { setConfig as copaSetConfig, getConfig as copaGetConfig } from './config';
+export * as copaApi from './api';
+export * as copaUtils from './utils';
+export { default as copaTailwindConfig } from './tailwind/bluecopa.config';