# @coda/datasources-api

ConnectRPC client and proto definitions for datasource management. Supports full lifecycle operations (CRUD), schema introspection, and refresh management.

## Installation

```jsonc
// package.json
{ "dependencies": { "@coda/datasources-api": "workspace:*" } }
```

## Usage

```ts
import { DatasourceClient } from "@coda/datasources-api";

const ds = new DatasourceClient({ baseUrl: "http://localhost:8080" });

// List datasources
const list = await ds.listDatasources({ tenantId: "t_456" });

// Get schema
const schema = await ds.getSchema({ datasourceId: "ds_123" });
if (schema.ok) {
  for (const table of schema.data.tables) {
    console.log(table.name, table.columns.length, "columns");
  }
}

// Trigger refresh
const refresh = await ds.refreshDatasource({ datasourceId: "ds_123" });
```

## API Reference

### DatasourceClient

| Method                   | Description                              | Default Timeout | Retries |
| ------------------------ | ---------------------------------------- | --------------- | ------- |
| `listDatasources(req)`   | List datasources for a tenant            | 2 s             | Yes (3) |
| `getDatasource(req)`     | Fetch a datasource by ID                 | 2 s             | Yes (3) |
| `getRefreshStatus(req)`  | Check refresh job status                 | 2 s             | Yes (3) |
| `getSchema(req)`         | Get datasource schema (tables + columns) | 2 s             | Yes (3) |
| `createDatasource(req)`  | Create a datasource                      | 2 s             | No      |
| `updateDatasource(req)`  | Update datasource metadata               | 2 s             | No      |
| `deleteDatasource(req)`  | Delete a datasource                      | 2 s             | No      |
| `refreshDatasource(req)` | Trigger a datasource refresh             | 2 s             | No      |

## Configuration

All clients accept `BaseClientConfig` from `@coda/api-common`:

```ts
interface BaseClientConfig {
  baseUrl: string;
  transport?: "connect" | "grpc";
  interceptors?: Interceptor[];
  defaultTimeoutMs?: number;
  onError?: (method: string, err: unknown) => void;
}
```

All methods return `RpcResult<T>` — a discriminated union that never throws. See `@coda/api-common` for details.

## Exported Types

| Type                       | Description                                            |
| -------------------------- | ------------------------------------------------------ |
| `DatasourceClientConfig`   | Client constructor config (extends `BaseClientConfig`) |
| `Datasource`               | Datasource entity                                      |
| `DatasourceType`           | Enum: datasource type                                  |
| `RefreshStatus`            | Enum: refresh job status                               |
| `SchemaTable`              | Table in a datasource schema                           |
| `SchemaColumn`             | Column within a schema table                           |
| `ListDatasourcesResponse`  | Paginated datasource list                              |
| `GetDatasourceResponse`    | Single datasource response                             |
| `GetSchemaResponse`        | Schema introspection result                            |
| `GetRefreshStatusResponse` | Refresh status result                                  |

## Proto sources

`proto/datasources/` — `.proto` files defining the RPC service and message types.

## Generated code

`gen/` — auto-generated TypeScript. Do not edit manually.

## Regenerate

```bash
pnpm buf:generate
```

Requires [Buf CLI](https://buf.build/). Generated output is committed to the repo.