npm package: @orquesta/react
Description: Official Orquesta SDK for React
Author: orquestadev
Latest version: 1.2.0
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

<p align="left">
  <a href="https://orquesta.dev" target="_blank">
    <img src="https://raw.githubusercontent.com/orquestadev/orquesta-javascript/main/img/banner.png" alt="Orquesta"  height="84">
  </a>
</p>

_Orquesta provides your product teams with no-code collaboration tooling to experiment, operate and monitor LLMs and remote configurations within your SaaS_

![npm](https://img.shields.io/npm/v/%40orquesta%2Freact)

# Orquesta React SDK

## Contents

- [Installation](#installation)
- [Create a client instance](#createclient)
- [Usage](#usage)
- [Reference](#reference)

## Installation

<div id='installation'/>

```bash
npm install @orquesta/react
```

```bash
yarn add @orquesta/react
```

## Creating a client instance

<div id='createclient'/>

_You can get your workspace API key from the settings section in your Orquesta workspace. `https://my.orquesta.dev/<workspace>/settings/developers`_

Initialize the Orquesta client with your API key:

```ts
import { OrquestaProvider } from '@orquesta/react';

export function App() {
  return (
    <OrquestaProvider options={{ api_key: '__API_KEY__', ttl: 3600 }}>
      <App />
    </OrquestaProvider>
  );
}
```

When creating a client instance, the following connection settings can be adjusted:

- `api_key`: string - your workspace API key to use for authentication.
- `ttl?`: number - the time to live in seconds for the local cache. Default is 3600 seconds (1 hour).

## Usage

<div id='usage'/>

> _Important Note: If you want to use the Prompts API reach out to [support@orquesta.cloud](support@orquesta.cloud)_

Orquesta comes with a powerful Remote Configurations API that allows you to dynamically configure and run all your environments and services remotely.

Orquesta supports different types of remote configurations, we recommend to always type the `query` method to help Typescript infer the correct type.

The `useOrquestaRemoteConfig` hook receives an object of type `OrquestaRemoteConfigQuery` as parameter.

_Supported types: `boolean`, `number`, `string`, `json`, `array`_

#### Example: Querying a configuration of type boolean

```ts
const config: OrquestaRemoteConfig<boolean> = useOrquestaRemoteConfig<boolean>({
  key: 'boolean_config',
  default_value: false,
  contenxt: { environments: 'production', role: 'admin' },
  metadata: { timestamp: Date.now() },
});
```

#### Example: Querying a configuration of type string

```ts
const config: OrquestaRemoteConfig<string> = useOrquestaRemoteConfig<string>(
  {
    key: 'string_config',
    default_value: 'string_value',
    contenxt: { environments: 'production', 'country': 'NL },
    metadata: { timestamp: Date.now() },
  }
);
```

#### Example: Querying a configuration of type number

```ts
const config: OrquestaRemoteConfig<number> = useOrquestaRemoteConfig<number>({
  key: 'number_config',
  default_value: 1990,
  contenxt: { environments: 'production', market: 'US', domain: 'ecommerce' },
  metadata: { timestamp: Date.now() },
});
```

#### Example: Querying a configuration of type array

```ts
const config: OrquestaRemoteConfig<string[]> = useOrquestaRemoteConfig<
  string[]
>({
  key: 'array_config',
  default_value: ['value1', 'value2'],
  contenxt: { environments: 'acceptance', isEnable: true },
  metadata: { timestamp: Date.now() },
});
```

#### Example: Querying a configuration of type json

It's recommended to add an interface to the json configuration to help Typescript infer the correct type.

```ts
const config: OrquestaRemoteConfig<object> = useOrquestaRemoteConfig<object>({
  key: 'json_config',
  default_value: { dashboardEnabled: false, theme: 'dark' },
  contenxt: { environments: 'develop', platform: 'mobile' },
  metadata: { timestamp: Date.now() },
});
```

#### Example: Add metrics to your request log

After every query, Orquesta will generate a log with data about the request. You can add metadata to the log by using the `addMetrics` method.

`metadata` is a set of `key-value pairs` that you can use to add custom information to the log.

```ts
config.addMetrics({
  metadata: {
    custom: 'custom_metadata',
    user_clicks: 20,
    selected_option: 'option1',
  },
});
```

<div id='references'/>

## Remote Configurations API

#### `OrquestaRemoteConfigQuery`

| Parameter     | Type                      | Description                                                                                                        | Required |
| ------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------ | -------- |
| key           | `string`                  | Key of remote configuration                                                                                        | Yes      |
| default_value | `T`                       | The value to be returned in case there is a en error during evaluation or the remote configuration does not exists | Yes      |
| context       | `Record<string, unknown>` | Set of key-value pairs from your data model that should be compared against the values in the configuration matrix | No       |
| metadata      | `Record<string, unknown>` | Set of key-value pairs of metadata you want to attach to the request log                                           | No       |

#### `OrquestaRemoteConfig`

| Parameter  | Type                                                      | Description                                                                                                                            |
| ---------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| value      | `Record<string, unknown>`                                 | Set of key-value pairs from your data model that should be compared against the values in the configuration matrix                     |
| type       | `T`                                                       | The value to be returned in case there is a en error during evaluation or the remote configuration does not exists                     |
| trace_id   | `string`                                                  | Key of remote configuration                                                                                                            |
| addMetrics | `(payload: OrquestaRemoteConfigMetrics) => Promise<void>` | A method that report metadata to the request log after the configuration value is returned. At least one of the properties is required |

#### `OrquestaRemoteConfigMetrics`

| Parameter | Type                      | Description                                                              | Required |
| --------- | ------------------------- | ------------------------------------------------------------------------ | -------- |
| metadata  | `Record<string, unknown>` | Set of key-value pairs of metadata you want to attach to the request log | No       |