@bluecopa/copa-lib - npm Package Compare versions

Comparing version 0.1.0 to 0.1.1

README.md

+# @bluecopa/copa-lib
+
+A comprehensive TypeScript library for interacting with the BlueCopa platform, providing utilities, API clients, and configuration management.
+
+## Installation
+
+```bash
+npm install @bluecopa/copa-lib
+```
+
+## Quick Start
+
+### 1. Configuration
+
+Before using any API functions, you need to configure the library with your credentials:
+
+```typescript
+import { copaSetConfig } from '@bluecopa/copa-lib';
+
+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/copa-lib';
+
+// 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/copa-lib';
+
+copaSetConfig({
+  apiBaseUrl: 'https://api.bluecopa.com/api/v1',
+  accessToken: 'eyJ...',
+  workspaceId: 'workspace123'
+});
+```
+
+#### `copaGetConfig(): Config`
+
+Retrieves the current configuration.
+
+```typescript
+import { copaGetConfig } from '@bluecopa/copa-lib';
+
+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
+- `copaApi.workbook` - Workbook operations
+- `copaApi.worksheet` - Worksheet operations
+
+### Utilities (`copaUtils`)
+
+#### Date Utilities
+
+```typescript
+import { copaUtils } from '@bluecopa/copa-lib';
+
+// 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/copa-lib';
+
+// 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/copa-lib';
+
+// 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/copa-lib';
+  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/copa-lib';
+
+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.json

 {
   "name": "@bluecopa/copa-lib",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
@@ -28,4 +28,5 @@ "main": "dist/index.es.js",
   "dependencies": {
-    "axios": "^1.11.0"
+    "axios": "^1.11.0",
+    "lodash": "^4.17.21"
   }
 }

New alerts

Unpublished package

Supply chain risk

Package version was not found on the registry. It may exist on a different registry and need to be configured to pull from that registry.

Found 1 instance in 1 package

Fixed alerts

No README

Quality

Package does not have a README. This may indicate a failed publish or a low quality package.

Found 1 instance in 1 package

Unpublished package

Supply chain risk

Package version was not found on the registry. It may exist on a different registry and need to be configured to pull from that registry.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

2373882

0.3%

Number of package files

4

33.33%

Number of medium quality alerts

0

-100%

Number of lines in readme file

313

Infinity%

Worsened metrics

Dependency count

2

100%

Dependency changes

• + Added

  lodash@^4.17.21

• + Added

  lodash@4.18.1
  (transitive)