@tetrascience-npm/tetrascience-react-ui 0.3.0 → 0.4.0-beta.10.1

package/README.md

@@ -2,6 +2,8 @@
 
 React component library for building TetraScience applications.
 
+[![npm version](https://img.shields.io/npm/v/@tetrascience-npm/tetrascience-react-ui)](https://www.npmjs.com/package/@tetrascience-npm/tetrascience-react-ui) [![CI](https://github.com/tetrascience/ts-lib-ui-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/tetrascience/ts-lib-ui-kit/actions/workflows/ci.yml) 📖 **[Storybook – Live Component Demos](https://ts-lib-ui-kit-storybook.vercel.app/)** | 🛠️ **[Contributing Guide](./CONTRIBUTING.md)**
+
 This library provides:
 
 - **UI Components**: Reusable React components following atomic design principles
@@ -9,6 +11,12 @@ This library provides:
 - **Theming**: Customisable design system with ThemeProvider
 - **TypeScript**: Full type support with exported prop types
 
+## Requirements
+
+- **React 19+**
+- **Node.js 18+**
+- **TypeScript 5.5+** (optional, but recommended)
+
 ## Installation
 
 ```bash
@@ -103,6 +111,177 @@ const token = await jwtManager.getUserToken(req.cookies);
 
 > **Note:** The singleton `jwtManager` reads environment variables when the module is imported. Ensure these are set before importing the module.
 
+### Data App Providers (`server/providers`)
+
+TypeScript equivalents of the Python helpers from `ts-lib-ui-kit-streamlit` for connecting to database providers (Snowflake, Databricks, Athena).
+
+**Getting Provider Configurations:**
+
+```typescript
+import { TDPClient } from '@tetrascience-npm/ts-connectors-sdk';
+import {
+  getProviderConfigurations,
+  buildProvider,
+  jwtManager,
+} from '@tetrascience-npm/tetrascience-react-ui/server';
+
+// Get user's auth token from request (e.g., in Express middleware)
+const userToken = await jwtManager.getTokenFromExpressRequest(req);
+
+// Create TDPClient with the user's auth token
+// Other fields (tdpEndpoint, connectorId, orgSlug) are read from environment variables
+const client = new TDPClient({
+  authToken: userToken,
+  artifactType: 'data-app',
+});
+await client.init();
+
+// Get all configured providers for this data app
+const providers = await getProviderConfigurations(client);
+
+for (const config of providers) {
+  console.log(`Provider: ${config.name} (${config.type})`);
+
+  // Build a database connection from the config
+  const provider = await buildProvider(config);
+  const results = await provider.query('SELECT * FROM my_table LIMIT 10');
+  await provider.close();
+}
+```
+
+**Using Specific Providers:**
+
+```typescript
+import {
+  buildSnowflakeProvider,
+  buildDatabricksProvider,
+  getTdpAthenaProvider,
+  type ProviderConfiguration,
+} from '@tetrascience-npm/tetrascience-react-ui/server';
+
+// Snowflake
+const snowflakeProvider = await buildSnowflakeProvider(config);
+const data = await snowflakeProvider.query('SELECT * FROM users');
+await snowflakeProvider.close();
+
+// Databricks
+const databricksProvider = await buildDatabricksProvider(config);
+const data = await databricksProvider.query('SELECT * FROM events');
+await databricksProvider.close();
+
+// TDP Athena (uses environment configuration)
+const athenaProvider = await getTdpAthenaProvider();
+const data = await athenaProvider.query('SELECT * FROM files');
+await athenaProvider.close();
+```
+
+**Exception Handling:**
+
+```typescript
+import {
+  QueryError,
+  MissingTableError,
+  ProviderConnectionError,
+  InvalidProviderConfigurationError,
+} from '@tetrascience-npm/tetrascience-react-ui/server';
+
+try {
+  const results = await provider.query('SELECT * FROM missing_table');
+} catch (error) {
+  if (error instanceof MissingTableError) {
+    console.error('Table not found:', error.message);
+  } else if (error instanceof QueryError) {
+    console.error('Query failed:', error.message);
+  }
+}
+```
+
+**Environment Variables:**
+
+- `DATA_APP_PROVIDER_CONFIG` - JSON override for local development only
+- `CONNECTOR_ID` - Connector ID for fetching providers from TDP
+- `TDP_ENDPOINT` - TDP API base URL
+- `ORG_SLUG` - Organization slug
+- `ATHENA_S3_OUTPUT_LOCATION` - S3 bucket for Athena query results
+- `AWS_REGION` - AWS region for Athena
+
+> **Note:** Authentication tokens are obtained from the user's JWT via `jwtManager`. The `TS_AUTH_TOKEN` environment variable is only for local development fallback.
+
+### Connector Key/Value Store
+
+The TDP connector key/value store lets data apps persist small pieces of state (user preferences, cached results, last-run timestamps, etc.) without an external database. The `TDPClient` from `@tetrascience-npm/ts-connectors-sdk` provides `getValue`, `getValues`, `saveValue`, and `saveValues` methods.
+
+**Reading and writing values with the user's JWT token:**
+
+```typescript
+import { TDPClient } from '@tetrascience-npm/ts-connectors-sdk';
+import { jwtManager } from '@tetrascience-npm/tetrascience-react-ui/server';
+
+// In an Express route handler:
+app.get('/api/kv/:key', async (req, res) => {
+  // 1. Get the user's JWT from request cookies
+  const userToken = await jwtManager.getTokenFromExpressRequest(req);
+  if (!userToken) return res.status(401).json({ error: 'Not authenticated' });
+
+  // 2. Create a TDPClient authenticated as the user
+  //    (CONNECTOR_ID, TDP_ENDPOINT, ORG_SLUG are read from env vars)
+  const client = new TDPClient({
+    authToken: userToken,
+    artifactType: 'data-app',
+  });
+  await client.init();
+
+  // 3. Read a value
+  const value = await client.getValue(req.params.key);
+  res.json({ key: req.params.key, value });
+});
+
+app.put('/api/kv/:key', async (req, res) => {
+  const userToken = await jwtManager.getTokenFromExpressRequest(req);
+  if (!userToken) return res.status(401).json({ error: 'Not authenticated' });
+
+  const client = new TDPClient({
+    authToken: userToken,
+    artifactType: 'data-app',
+  });
+  await client.init();
+
+  // Write a value (any JSON-serialisable type)
+  await client.saveValue(req.params.key, req.body.value, { secure: false });
+  res.json({ key: req.params.key, saved: true });
+});
+```
+
+**Reading multiple values at once:**
+
+```typescript
+const values = await client.getValues(['theme', 'locale', 'last-run']);
+// values[0] → theme, values[1] → locale, values[2] → last-run
+```
+
+> See the [example app](./examples/vite-themed-app/) for a complete working server with KV store endpoints.
+
+### TDP Search (`server`)
+
+**TdpSearchManager** - Server-side handler for the TdpSearch component. Resolves auth from request cookies (via `jwtManager`), calls TDP `searchEql`, and returns the response so the frontend hook works with minimal wiring.
+
+```typescript
+import { tdpSearchManager } from "@tetrascience-npm/tetrascience-react-ui/server";
+
+// Express: mount a POST route (e.g. /api/search)
+app.post("/api/search", express.json(), async (req, res) => {
+  try {
+    const body = req.body; // SearchEqlRequest (searchTerm, from, size, sort, order, ...)
+    const response = await tdpSearchManager.handleSearchRequest(req, body);
+    res.json(response);
+  } catch (err) {
+    res.status(401).json({ error: err instanceof Error ? err.message : "Search failed" });
+  }
+});
+```
+
+Frontend: use `<TdpSearch columns={...} />` with default `apiEndpoint="/api/search"`, or pass `apiEndpoint` if you use a different path. Auth is taken from cookies (`ts-auth-token` or `ts-token-ref` via `jwtManager`).
+
 ## TypeScript Support
 
 Full TypeScript support with exported types:
@@ -118,8 +297,8 @@ The repository includes example applications in the `examples/` directory:
 
 ```bash
 # Clone the repository
-git clone https://github.com/tetrascience/ts-lib-ui-kit-react.git
-cd ts-lib-ui-kit-react
+git clone https://github.com/tetrascience/ts-lib-ui-kit.git
+cd ts-lib-ui-kit
 
 # Install dependencies
 yarn
@@ -128,13 +307,15 @@ yarn
 yarn workspace vite-themed-app dev
 ```
 
-Visit http://localhost:5173 to see the example app with custom theming.
+Visit <http://localhost:5173> to see the example app with custom theming.
 
 ## Documentation
 
-- [Getting Started Guide](https://github.com/tetrascience/ts-lib-ui-kit-react/blob/main/get_started_1.md) - Step-by-step tutorial
-- [Theming Guide](https://github.com/tetrascience/ts-lib-ui-kit-react/blob/main/THEMING.md) - Customise the design system
-- [Storybook](https://github.com/tetrascience/ts-lib-ui-kit-react/blob/main/DEVELOPERS.md#development-setup) - Clone the repo and run `yarn storybook`
+- [Storybook – Live Component Demos](https://ts-lib-ui-kit-storybook.vercel.app/) - Browse all components with interactive examples
+- [NPM Package](https://www.npmjs.com/package/@tetrascience-npm/tetrascience-react-ui) - Installation and version info
+- [Getting Started Guide](./get_started_1.md) - Step-by-step tutorial
+- [Theming Guide](./THEMING.md) - Customise the design system
+- [Contributing](./CONTRIBUTING.md#development-setup) - Clone the repo and run `yarn storybook`
 
 ## Tech Stack