@bluecopa/copa-lib

@bluecopa/copa-lib

A comprehensive TypeScript library for interacting with the BlueCopa platform, providing utilities, API clients, and configuration management.

Installation

npm install @bluecopa/copa-lib

Quick Start

1. Configuration

Before using any API functions, you need to configure the library with your credentials:

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

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.

import { copaSetConfig } from '@bluecopa/copa-lib';

copaSetConfig({
  apiBaseUrl: 'https://api.bluecopa.com/api/v1',
  accessToken: 'eyJ...',
  workspaceId: 'workspace123'
});

copaGetConfig(): Config

Retrieves the current configuration.

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)

// Get logged-in user details
const userDetails = await copaApi.user.getLoggedInUserDetails();

Metric API (copaApi.metric)

// Get metric data
const metricId = '0UbwCn75pym1N47D89uS';
const metricData = await copaApi.metric.getData(metricId);

Dataset API (copaApi.dataset)

// 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)

// 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

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

// Get metric definition
const metricDefinition = copaUtils.getMetricDefinition(metricId);

Input Table Utilities

// 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:

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:

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:

<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:

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:

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:

import type { Config } from '@bluecopa/copa-lib';

const config: Config = {
  apiBaseUrl: 'https://api.example.com',
  accessToken: 'token',
  workspaceId: 'workspace'
};

Development

Building the Library

npm run build

Development Mode

npm run dev

This will build the library in watch mode, automatically rebuilding when files change.