@tetrascience-npm/tetrascience-react-ui 0.4.0-beta.1.1 → 0.4.0-beta.11.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
@@ -121,10 +129,10 @@ import {
 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',
-  orgSlug: process.env.ORG_SLUG,
 });
 await client.init();
 
@@ -199,6 +207,81 @@ try {
 
 > **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:
@@ -210,7 +293,7 @@ import type { ButtonProps, BarGraphProps, BarDataSeries } from '@tetrascience-np
 
 ## Examples
 
-The repository includes example applications in the `examples/` directory:
+This repository uses component driven development with storybook.js. To see the examples run the following.
 
 ```bash
 # Clone the repository
@@ -220,14 +303,16 @@ cd ts-lib-ui-kit
 # Install dependencies
 yarn
 
-# Run the themed example app
-yarn workspace vite-themed-app dev
+# Run the storybook
+yarn dev
 ```
 
-Visit <http://localhost:5173> to see the example app with custom theming.
+Visit <http://localhost:6006>.
 
 ## Documentation
 
+- [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`

package/dist/athena.d.ts

@@ -0,0 +1,167 @@
+import { AthenaClient as AthenaClient_2 } from '@aws-sdk/client-athena';
+import { awsSdkClientAthena } from '@aws-sdk/client-athena';
+
+/**
+ * Athena Data Provider
+ *
+ * TypeScript equivalent of AthenaProvider from
+ * ts-lib-ui-kit-streamlit/tetrascience/data_app_providers/provider.py
+ *
+ * @remarks
+ * This provider requires the `@aws-sdk/client-athena` package to be installed.
+ * It is an optional peer dependency - install it only if you need Athena support:
+ * ```bash
+ * npm install @aws-sdk/client-athena
+ * # or
+ * yarn add @aws-sdk/client-athena
+ * ```
+ */
+declare type AthenaClient = AthenaClient_2;
+
+/**
+ * Athena data provider
+ */
+export declare class AthenaProvider {
+    private client;
+    private sdk;
+    private workgroup;
+    private database;
+    private outputLocation?;
+    /**
+     * Initialize the Athena data provider
+     *
+     * @param client - AWS Athena client
+     * @param sdk - AWS Athena SDK module (for accessing command classes)
+     * @param workgroup - Athena workgroup to use
+     * @param database - Default database/schema
+     * @param outputLocation - Optional S3 output location
+     */
+    constructor(client: AthenaClient, sdk: AthenaSDK, workgroup: string, database: string, outputLocation?: string);
+    /**
+     * Query the Athena database
+     *
+     * @param sqlQuery - SQL query to execute
+     * @param _params - Parameters to pass to the query (currently not used - Athena doesn't support parameterized queries)
+     * @returns Promise resolving to array of row objects
+     *
+     * @remarks
+     * **Security Note:** AWS Athena does not support parameterized queries.
+     * Unlike traditional databases, there is no native way to use bind parameters
+     * with Athena. Callers are responsible for properly sanitizing any user input
+     * before constructing the SQL query string. This is a known limitation of the
+     * Athena service, not a design flaw in this implementation.
+     */
+    query(sqlQuery: string, _params?: Record<string, unknown>): Promise<Array<Record<string, unknown>>>;
+    /**
+     * Wait for query to complete
+     */
+    private waitForQueryCompletion;
+    /**
+     * Fetch all results from a completed query
+     */
+    private fetchAllResults;
+    /**
+     * Close the Athena client (no-op for AWS SDK clients)
+     */
+    close(): Promise<void>;
+}
+
+declare type AthenaSDK = awsSdkClientAthena;
+
+/**
+ * Get the TDP Athena provider
+ *
+ * Creates an Athena provider using TDP environment configuration
+ *
+ * @returns Promise resolving to Athena data provider
+ * @throws {InvalidProviderConfigurationError} If @aws-sdk/client-athena is not installed
+ * @throws {Error} If ATHENA_S3_OUTPUT_LOCATION is not set when using the 'primary' workgroup
+ */
+export declare function getTdpAthenaProvider(): Promise<AthenaProvider>;
+
+/**
+ * Raised when the provider configuration is invalid
+ */
+export declare class InvalidProviderConfigurationError extends ProviderError {
+    constructor(message: string);
+}
+
+/**
+ * Raised when a table is missing in the database
+ */
+export declare class MissingTableError extends ProviderError {
+    constructor(message: string);
+}
+
+/**
+ * Data App Provider Types
+ *
+ * TypeScript equivalents of the Python ProviderConfiguration Pydantic models
+ * from ts-lib-ui-kit-streamlit/tetrascience/data_app_providers/provider_typing.py
+ */
+/**
+ * Configuration model for data providers.
+ *
+ * This interface represents the configuration needed to connect to various
+ * database providers (Snowflake, Databricks, Athena, Benchling, etc.)
+ * attached to a data app.
+ */
+export declare interface ProviderConfiguration {
+    /** Human-readable name of the provider */
+    name: string;
+    /** Provider type (snowflake, databricks, benchling, custom, etc.) */
+    type: string;
+    /** Optional URL to the provider's icon */
+    iconUrl?: string;
+    /** Dictionary containing connection details and credentials */
+    fields: Record<string, string | undefined>;
+}
+
+/**
+ * Raised when connecting to a provider fails
+ */
+export declare class ProviderConnectionError extends ProviderError {
+    constructor(message: string);
+}
+
+/**
+ * Provider Exceptions
+ *
+ * TypeScript equivalents of the Python exceptions from
+ * ts-lib-ui-kit-streamlit/tetrascience/data_app_providers/exceptions.py
+ */
+/**
+ * Base class for provider errors
+ */
+export declare class ProviderError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Raised when a query fails
+ */
+export declare class QueryError extends ProviderError {
+    constructor(message: string);
+}
+
+/**
+ * Standardized query result from data providers.
+ *
+ * This interface provides a consistent shape for query results across
+ * all provider types (Snowflake, Databricks, Athena), with optional
+ * metadata for API responses.
+ */
+export declare interface QueryResult {
+    /** Array of row objects returned by the query */
+    data: Array<Record<string, unknown>>;
+    /** Number of rows returned */
+    rowCount: number;
+    /** Name of the provider that executed the query */
+    provider?: string;
+    /** Whether this is mock/demo data */
+    mock?: boolean;
+    /** Optional message (e.g., for errors or warnings) */
+    message?: string;
+}
+
+export { }

package/dist/databricks.d.ts

@@ -0,0 +1,129 @@
+import { DBSQLClient as DBSQLClient_2 } from '@databricks/sql';
+import { default as default_2 } from '@databricks/sql/dist/contracts/IDBSQLSession';
+
+/**
+ * Build a Databricks data provider from the configuration
+ *
+ * @param config - Provider configuration
+ * @returns Promise resolving to Databricks data provider
+ * @throws {InvalidProviderConfigurationError} If @databricks/sql is not installed or config is invalid
+ */
+export declare function buildDatabricksProvider(config: ProviderConfiguration): Promise<DatabricksProvider>;
+
+/**
+ * Databricks data provider
+ */
+export declare class DatabricksProvider {
+    private client;
+    private session;
+    /**
+     * Initialize the Databricks data provider
+     *
+     * @param client - Databricks SQL client
+     * @param session - Databricks SQL session
+     */
+    constructor(client: DBSQLClient, session: IDBSQLSession);
+    /**
+     * Query the Databricks database
+     *
+     * @param sqlQuery - SQL query to execute
+     * @param _params - Parameters to pass to the query (currently not used)
+     * @returns Promise resolving to array of row objects
+     */
+    query(sqlQuery: string, _params?: Record<string, unknown>): Promise<Array<Record<string, unknown>>>;
+    /**
+     * Close the Databricks connection
+     */
+    close(): Promise<void>;
+}
+
+declare type DBSQLClient = DBSQLClient_2;
+
+declare type IDBSQLSession = default_2;
+
+/**
+ * Raised when the provider configuration is invalid
+ */
+export declare class InvalidProviderConfigurationError extends ProviderError {
+    constructor(message: string);
+}
+
+/**
+ * Raised when a table is missing in the database
+ */
+export declare class MissingTableError extends ProviderError {
+    constructor(message: string);
+}
+
+/**
+ * Data App Provider Types
+ *
+ * TypeScript equivalents of the Python ProviderConfiguration Pydantic models
+ * from ts-lib-ui-kit-streamlit/tetrascience/data_app_providers/provider_typing.py
+ */
+/**
+ * Configuration model for data providers.
+ *
+ * This interface represents the configuration needed to connect to various
+ * database providers (Snowflake, Databricks, Athena, Benchling, etc.)
+ * attached to a data app.
+ */
+export declare interface ProviderConfiguration {
+    /** Human-readable name of the provider */
+    name: string;
+    /** Provider type (snowflake, databricks, benchling, custom, etc.) */
+    type: string;
+    /** Optional URL to the provider's icon */
+    iconUrl?: string;
+    /** Dictionary containing connection details and credentials */
+    fields: Record<string, string | undefined>;
+}
+
+/**
+ * Raised when connecting to a provider fails
+ */
+export declare class ProviderConnectionError extends ProviderError {
+    constructor(message: string);
+}
+
+/**
+ * Provider Exceptions
+ *
+ * TypeScript equivalents of the Python exceptions from
+ * ts-lib-ui-kit-streamlit/tetrascience/data_app_providers/exceptions.py
+ */
+/**
+ * Base class for provider errors
+ */
+export declare class ProviderError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Raised when a query fails
+ */
+export declare class QueryError extends ProviderError {
+    constructor(message: string);
+}
+
+/**
+ * Standardized query result from data providers.
+ *
+ * This interface provides a consistent shape for query results across
+ * all provider types (Snowflake, Databricks, Athena), with optional
+ * metadata for API responses.
+ */
+export declare interface QueryResult {
+    /** Array of row objects returned by the query */
+    data: Array<Record<string, unknown>>;
+    /** Number of rows returned */
+    rowCount: number;
+    /** Name of the provider that executed the query */
+    provider?: string;
+    /** Whether this is mock/demo data */
+    mock?: boolean;
+    /** Optional message (e.g., for errors or warnings) */
+    message?: string;
+}
+
+export { }

package/dist/exceptions-DN25pCDi.cjs

@@ -0,0 +1,2 @@
+"use strict";class o extends Error{constructor(r){super(r),this.name="ProviderError"}}class s extends o{constructor(r){super(r),this.name="MissingTableError"}}class n extends o{constructor(r){super(r),this.name="QueryError"}}class i extends o{constructor(r){super(r),this.name="ProviderConnectionError"}}class t extends o{constructor(r){super(r),this.name="InvalidProviderConfigurationError"}}exports.InvalidProviderConfigurationError=t;exports.MissingTableError=s;exports.ProviderConnectionError=i;exports.ProviderError=o;exports.QueryError=n;
+//# sourceMappingURL=exceptions-DN25pCDi.cjs.map

package/dist/exceptions-DN25pCDi.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"exceptions-DN25pCDi.cjs","sources":["../src/server/providers/exceptions.ts"],"sourcesContent":["/**\n * Provider Exceptions\n *\n * TypeScript equivalents of the Python exceptions from\n * ts-lib-ui-kit-streamlit/tetrascience/data_app_providers/exceptions.py\n */\n\n/**\n * Base class for provider errors\n */\nexport class ProviderError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"ProviderError\";\n  }\n}\n\n/**\n * Raised when a table is missing in the database\n */\nexport class MissingTableError extends ProviderError {\n  constructor(message: string) {\n    super(message);\n    this.name = \"MissingTableError\";\n  }\n}\n\n/**\n * Raised when a query fails\n */\nexport class QueryError extends ProviderError {\n  constructor(message: string) {\n    super(message);\n    this.name = \"QueryError\";\n  }\n}\n\n/**\n * Raised when connecting to a provider fails\n */\nexport class ProviderConnectionError extends ProviderError {\n  constructor(message: string) {\n    super(message);\n    this.name = \"ProviderConnectionError\";\n  }\n}\n\n/**\n * Raised when the provider configuration is invalid\n */\nexport class InvalidProviderConfigurationError extends ProviderError {\n  constructor(message: string) {\n    super(message);\n    this.name = \"InvalidProviderConfigurationError\";\n  }\n}\n\n"],"names":["ProviderError","message","MissingTableError","QueryError","ProviderConnectionError","InvalidProviderConfigurationError"],"mappings":"aAUO,MAAMA,UAAsB,KAAM,CACvC,YAAYC,EAAiB,CAC3B,MAAMA,CAAO,EACb,KAAK,KAAO,eACd,CACF,CAKO,MAAMC,UAA0BF,CAAc,CACnD,YAAYC,EAAiB,CAC3B,MAAMA,CAAO,EACb,KAAK,KAAO,mBACd,CACF,CAKO,MAAME,UAAmBH,CAAc,CAC5C,YAAYC,EAAiB,CAC3B,MAAMA,CAAO,EACb,KAAK,KAAO,YACd,CACF,CAKO,MAAMG,UAAgCJ,CAAc,CACzD,YAAYC,EAAiB,CAC3B,MAAMA,CAAO,EACb,KAAK,KAAO,yBACd,CACF,CAKO,MAAMI,UAA0CL,CAAc,CACnE,YAAYC,EAAiB,CAC3B,MAAMA,CAAO,EACb,KAAK,KAAO,mCACd,CACF"}

package/dist/exceptions-jCQ6h5C8.js

@@ -0,0 +1,33 @@
+class o extends Error {
+  constructor(r) {
+    super(r), this.name = "ProviderError";
+  }
+}
+class e extends o {
+  constructor(r) {
+    super(r), this.name = "MissingTableError";
+  }
+}
+class n extends o {
+  constructor(r) {
+    super(r), this.name = "QueryError";
+  }
+}
+class t extends o {
+  constructor(r) {
+    super(r), this.name = "ProviderConnectionError";
+  }
+}
+class i extends o {
+  constructor(r) {
+    super(r), this.name = "InvalidProviderConfigurationError";
+  }
+}
+export {
+  i as I,
+  e as M,
+  t as P,
+  n as Q,
+  o as a
+};
+//# sourceMappingURL=exceptions-jCQ6h5C8.js.map

package/dist/exceptions-jCQ6h5C8.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exceptions-jCQ6h5C8.js","sources":["../src/server/providers/exceptions.ts"],"sourcesContent":["/**\n * Provider Exceptions\n *\n * TypeScript equivalents of the Python exceptions from\n * ts-lib-ui-kit-streamlit/tetrascience/data_app_providers/exceptions.py\n */\n\n/**\n * Base class for provider errors\n */\nexport class ProviderError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"ProviderError\";\n  }\n}\n\n/**\n * Raised when a table is missing in the database\n */\nexport class MissingTableError extends ProviderError {\n  constructor(message: string) {\n    super(message);\n    this.name = \"MissingTableError\";\n  }\n}\n\n/**\n * Raised when a query fails\n */\nexport class QueryError extends ProviderError {\n  constructor(message: string) {\n    super(message);\n    this.name = \"QueryError\";\n  }\n}\n\n/**\n * Raised when connecting to a provider fails\n */\nexport class ProviderConnectionError extends ProviderError {\n  constructor(message: string) {\n    super(message);\n    this.name = \"ProviderConnectionError\";\n  }\n}\n\n/**\n * Raised when the provider configuration is invalid\n */\nexport class InvalidProviderConfigurationError extends ProviderError {\n  constructor(message: string) {\n    super(message);\n    this.name = \"InvalidProviderConfigurationError\";\n  }\n}\n\n"],"names":["ProviderError","message","MissingTableError","QueryError","ProviderConnectionError","InvalidProviderConfigurationError"],"mappings":"AAUO,MAAMA,UAAsB,MAAM;AAAA,EACvC,YAAYC,GAAiB;AAC3B,UAAMA,CAAO,GACb,KAAK,OAAO;AAAA,EACd;AACF;AAKO,MAAMC,UAA0BF,EAAc;AAAA,EACnD,YAAYC,GAAiB;AAC3B,UAAMA,CAAO,GACb,KAAK,OAAO;AAAA,EACd;AACF;AAKO,MAAME,UAAmBH,EAAc;AAAA,EAC5C,YAAYC,GAAiB;AAC3B,UAAMA,CAAO,GACb,KAAK,OAAO;AAAA,EACd;AACF;AAKO,MAAMG,UAAgCJ,EAAc;AAAA,EACzD,YAAYC,GAAiB;AAC3B,UAAMA,CAAO,GACb,KAAK,OAAO;AAAA,EACd;AACF;AAKO,MAAMI,UAA0CL,EAAc;AAAA,EACnE,YAAYC,GAAiB;AAC3B,UAAMA,CAAO,GACb,KAAK,OAAO;AAAA,EACd;AACF;"}