npm package: @rocketlane/rli-core
Description: RLI Core - The Rocketlane CLI Core
Latest version: 1.2.0-beta.3

# @rli-core

A TypeScript library providing core functionality for interacting with the RLI platform API, including key-value storage operations and API service utilities.

## Installation

```bash
npm install @rli-core
```

## Overview

The @rli-core package offers essential utilities for RLI platform integration:

- API Service: Simplified HTTP client for interacting with the RLI API
- Key-Value Store: Persistent storage for both app-specific and global data
- Context Management: Easy access to installation parameters and authentication

```js
const { rliCore } = require('@rli-core');

// Initialize with required context
const core = rliCore({
  context: {
    baseUrl: 'https://api.example.com',
    apiKey: 'your-api-key',
    installation: {
      appId: 123,
      authParams: { /* auth parameters */ },
      iparams: { /* installation parameters */ },
      secureParams: { /* secure parameters */ }
    }
  }
});

// Access core functionality
const { kv, authParams, installationParams, logger } = core;
```

## Working with Key-Value Store

The KV store allows you to store and retrieve data with app-specific or global scope.

### App-Specific KV Store

```js
// Store a value
await kv.setAppValue({
  key: 'user_preferences',
  value: { theme: 'dark', notifications: true },
  ttlInSeconds: 86400, // 24 hours
  setIf: 'not_exist' // Only set if the key doesn't exist
});

// Retrieve a value
const preferences = await kv.getAppValue('user_preferences');

// Delete a value
await kv.deleteAppValue('user_preferences');

// Get all values
const allValues = await kv.getAllAppValues();

// JSON operations
await kv.setAppJsonValue('user_preferences', 'theme', 'light');
await kv.incrementAppJsonValue('stats', 'count');
await kv.pushAppJsonValue('history', 'events', { type: 'login', timestamp: Date.now() });
await kv.removeAppJsonValue('user_preferences', 'notifications');
```

### Global KV Store

```js
// Store a global value
await kv.setGlobalValue({
  key: 'system_settings',
  value: { maintenance: false },
  ttlInSeconds: 3600,
  setIf: 'exist'
});

// Retrieve a global value
const settings = await kv.getGlobalValue('system_settings');

// Delete a global value
await kv.deleteGlobalValue('system_settings');

// Get all global values
const allGlobalValues = await kv.getAllGlobalValues();

// JSON operations
await kv.setGlobalJsonValue('system_settings', 'maintenance', true);
await kv.incrementGlobalJsonValue('global_stats', 'visitor_count');
await kv.pushGlobalJsonValue('audit_log', 'entries', { action: 'config_change', timestamp: Date.now() });
await kv.removeGlobalJsonValue('system_settings', 'deprecated_feature');
```


## API Service

The `MpApiService` is used internally by the KV store, but can also be accessed for custom API calls:


```js
import { mpApiService } from '@rli-core';

// The service is automatically initialized by rliCore()

// Make API requests
const response = await mpApiService.get('/resource/123');
await mpApiService.post('/resource', { name: 'New Resource' });
await mpApiService.put('/resource/123', { name: 'Updated Resource' });
await mpApiService.patch('/resource/123', { status: 'active' });
await mpApiService.delete('/resource/123');
```

## API Reference

### rliCore

```typescript
rliCore({ context: RliCoreContext }) => {
  authParams: Record<string, string>;
  installationParams: Record<string, string>;
  logger: Console;
  kv: MpKvStore;
}
```

### MpKvStore

Key-value storage service with methods for both app-specific and global data.

#### App-Specific Methods

- `setAppValue(request: KVStoreRequest): Promise<void>` - Set a key-value pair for a specific app
- `getAppValue(key: string): Promise<KVResponse | null>` - Get value for a specific key in an app
- `getAllAppValues(): Promise<KVResponse[]>` - Get all key-value pairs for an app
- `deleteAppValue(key: string): Promise<void>` - Delete a specific key-value pair from an app
- `deleteAllAppValues(): Promise<void>` - Delete all key-value pairs for an app
- `patchAppValue(key: string, request: KVPatchRequest): Promise<void>` - Patch a specific key-value in an app
- `incrementAppJsonValue(key: string, attribute: string): Promise<void>` - Increment a numeric value in a JSON object
- `pushAppJsonValue(key: string, attribute: string, value: any): Promise<void>` - Add an item to an array in a JSON object
- `removeAppJsonValue(key: string, attribute: string): Promise<void>` - Remove an attribute from a JSON object
- `setAppJsonValue(key: string, attribute: string, value: any): Promise<void>` - Set an attribute in a JSON object

#### Global Methods

- `setGlobalValue(request: KVStoreRequest): Promise<void>` - Set a global key-value pair
- `getGlobalValue(key: string): Promise<KVResponse | null>` - Get value for a specific global key
- `getAllGlobalValues(): Promise<KVResponse[]>` - Get all global key-value pairs
- `deleteGlobalValue(key: string): Promise<void>` - Delete a specific global key-value pair
- `deleteAllGlobalValues(): Promise<void>` - Delete all global key-value pairs
- `patchGlobalValue(key: string, request: KVPatchRequest): Promise<void>` - Patch a specific global key-value
- `incrementGlobalJsonValue(key: string, attribute: string): Promise<void>` - Increment a numeric value in a global JSON object
- `pushGlobalJsonValue(key: string, attribute: string, value: any): Promise<void>` - Add an item to an array in a global JSON object
- `removeGlobalJsonValue(key: string, attribute: string): Promise<void>` - Remove an attribute from a global JSON object
- `setGlobalJsonValue(key: string, attribute: string, value: any): Promise<void>` - Set an attribute in a global JSON object

### MpApiService

HTTP client for making API requests:

- `init({ apiKey, apiUrl }: InitOptions): void` - Initialize the API service
- `get<T>(url: string): Promise<AxiosResponse<T>>` - Make a GET request
- `post<T, D>(url: string, data: D): Promise<AxiosResponse<T>>` - Make a POST request
- `put<T, D>(url: string, data: D): Promise<AxiosResponse<T>>` - Make a PUT request
- `delete<T>(url: string): Promise<AxiosResponse<T>>` - Make a DELETE request
- `patch<T, D>(url: string, data: D): Promise<AxiosResponse<T>>` - Make a PATCH request

### Types

#### KVStoreRequest

```typescript
{
  key: string;               // The unique identifier for the stored value
  value: any;                // The data to store (can be any JSON-serializable value)
  ttlInSeconds: number;      // Time-to-live in seconds (0 for no expiration)
  setIf: KVStoreSetIf;       // Condition for setting the value ('exist' or 'not_exist')
}
```

#### KVPatchRequest

```typescript
{
  action: KVPatchAction;     // The type of operation ('INCREMENT', 'PUSH', 'REMOVE', or 'SET')
  attribute: string;         // The JSON path to the attribute to modify
  value?: any;               // The value for the operation (not required for 'INCREMENT' or 'REMOVE')
}
```

#### KVResponse

```typescript
{
  key: string;               // The key for the stored value
  value: any;                // The stored data
  scope: KVStoreScope;       // The scope of the value ('APP' or 'GLOBAL')
  expiresAt: number;         // Timestamp when the value will expire (0 for no expiration)
  createdAt: number;         // Timestamp when the value was created
  updatedAt: number;         // Timestamp when the value was last updated
}
```

#### RliCoreContext

```typescript
{
  installation: {
    appId: number;           // The unique identifier for the app
    authParams: Record<string, string>;    // Authentication parameters
    iparams: Record<string, string>;       // Installation parameters
    secureParams: Record<string, string>;  // Secure parameters
  };
  baseUrl: string;           // The base URL for the API
  apiKey: string;            // The API key for authentication
}
```

## License

PROPRIETARY - All Rights Reserved