npm package: @davidovicstefan/swimlane-api-client
Description: Swimlane API client with caching to prevent duplicate API calls across widgets
Author: Stefan Davidovic
Latest version: 1.1.0

# Swimlane API Client

A centralized API client for Swimlane with intelligent caching to prevent duplicate API calls across multiple widgets.

## Features

- 🚀 **Caching**: Prevents duplicate API calls across widgets
- 🔄 **Instance Support**: Works with Swimlane, Turbine, and Shared Cloud
- 🛠️ **Helper Functions**: Utilities for processing API responses
- 📦 **Lightweight**: Only essential API functions, no UI logic
- 🎯 **TypeScript**: Full TypeScript support

## Installation

```bash
npm install @davidovicstefan/swimlane-api-client
```

## Usage

### Basic API Client

```javascript
import { SwimlaneApi } from '@davidovicstefan/swimlane-api-client';

const apiClient = new SwimlaneApi(contextData);

// GET request with caching
const response = await apiClient.GET('application', 'app123');

// POST request
const result = await apiClient.POST('search', searchParams);
```

### Search Functions

```javascript
import { performReferenceSearch, getSearchCount } from '@davidovicstefan/swimlane-api-client';

// Search with automatic caching
const searchResults = await performReferenceSearch(contextData, {
  referencedAppId: 'app123',
  filters: [
    { fieldId: 'title', filterType: 'contains', value: 'test' }
  ],
  offset: 0,
  pageSize: 20,
  columns: ['title', 'status']
});

// Get count with caching
const totalCount = await getSearchCount(contextData, {
  referencedAppId: 'app123',
  filters: [
    { fieldId: 'title', filterType: 'contains', value: 'test' }
  ],
  columns: ['title', 'status']
});
```

### Helper Functions

```javascript
import { 
  constructKeyIdMap, 
  convertRecordValues, 
  stringifyVal 
} from '@davidovicstefan/swimlane-api-client';

// Convert field mapping
const fieldMap = constructKeyIdMap(applicationDefinition);

// Convert API response
const records = convertRecordValues(apiResponse, fieldMap);

// Stringify values
const displayValue = stringifyVal(complexValue);
```

### Cache Management

```javascript
import { apiCache } from '@davidovicstefan/swimlane-api-client';

// Clear all cache
apiCache.clear();

// Clear cache for specific context
apiCache.clearContext(contextData);

// Get cache stats
const stats = apiCache.getStats();
```

## API Reference

### SwimlaneApi

Main API client class with caching support.

#### Constructor
```javascript
new SwimlaneApi(contextData)
```

#### Methods
- `GET(resource, objectId?, orchestrationVersion?, useCache?)` - GET request
- `POST(resource, jsonObject, objectId?, orchestrationVersion?, useCache?)` - POST request
- `PUT(resource, jsonObject, objectId?, orchestrationVersion?)` - PUT request
- `DELETE(resource, objectId?, orchestrationVersion?)` - DELETE request
- `getReferenceData(recordId, targetAppId, referenceIds)` - Get reference data
- `orchestrationRql(version, resource, payload?, useCache?)` - Orchestration RQL

### Search Functions

- `performReferenceSearch(contextData, searchParams)` - Search with caching
- `getSearchCount(contextData, searchParams)` - Get count with caching
- `getApplicationDefinition(contextData, appId)` - Get app definition with caching

### Helper Functions

- `constructKeyIdMap(applicationDefinition)` - Create field mapping
- `convertRecordValues(records, fieldIds)` - Convert API response
- `getFieldMetadata(fieldId, applicationFields)` - Get field metadata
- `stringifyVal(value)` - Convert value to string
- `processSearchTerms(searchTerms, applicationFields)` - Process search terms

## Caching Strategy

The client uses intelligent caching to prevent duplicate API calls:

- **Cache Key**: Generated from context + endpoint + parameters
- **TTL**: 5 minutes default (configurable)
- **Scope**: Per context (account + tenant)
- **Automatic**: GET requests are cached by default
- **Manual**: POST requests can be cached with `useCache: true`

## Context Data

```javascript
const contextData = {
  origin: 'https://your-swimlane-instance.com',
  accountId: 'account123',
  tenantId: 'tenant456',
  token: 'bearer-token',
  tenantPath: 'optional-for-shared-cloud',
  application: {
    id: 'app789',
    fields: [...]
  }
};
```

## License

MIT