# @coda/admin-api

ConnectRPC clients and proto definitions for the platform admin service. Covers access control, tenant management, user identity, roles, policies, sessions, and cache operations.

## Installation

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

## Clients

### AccessClient

Permission checks and tenant resolution. All methods are idempotent reads with automatic retry.

| Method               | Description                                      | Retries |
| -------------------- | ------------------------------------------------ | ------- |
| `check(req)`         | Check a single permission for a user             | Yes (3) |
| `checkBatch(req)`    | Check multiple permissions in one call           | Yes (3) |
| `getEffective(req)`  | Get all effective permissions for a user         | Yes (3) |
| `resolveTenant(req)` | Resolve a tenant by slug, ID, identity, or email | Yes (3) |

Default timeout: **200 ms**.

```ts
import { AccessClient } from "@coda/admin-api";

const access = new AccessClient({ baseUrl: "http://localhost:8091" });

const result = await access.check({
  userId: "u_123",
  tenantId: "t_456",
  permission: "datasource:read",
});

if (result.ok) {
  console.log(result.data.allowed); // true | false
} else {
  console.error(result.reason); // "timeout" | "unavailable" | ...
}
```

### PlatformClient

Tenant CRUD and lifecycle management.

| Method                  | Description                                    | Retries |
| ----------------------- | ---------------------------------------------- | ------- |
| `getTenant(req)`        | Fetch a tenant by ID                           | Yes (3) |
| `listTenants(req)`      | List tenants (paginated, filterable by status) | Yes (3) |
| `createTenant(req)`     | Create a new tenant                            | No      |
| `updateTenant(req)`     | Update tenant metadata                         | No      |
| `suspendTenant(req)`    | Suspend a tenant (with reason)                 | No      |
| `reactivateTenant(req)` | Reactivate a suspended tenant                  | No      |

Default timeout: **500 ms**.

```ts
import { PlatformClient } from "@coda/admin-api";

const platform = new PlatformClient({ baseUrl: "http://localhost:8091" });
const result = await platform.listTenants({ page: { pageSize: 20 } });
if (result.ok) console.log(result.data.tenants);
```

### IdentityClient

User management and super-admin grants.

| Method                  | Description                        | Retries |
| ----------------------- | ---------------------------------- | ------- |
| `getUser(req)`          | Fetch a user within a tenant       | Yes (3) |
| `listUsers(req)`        | List users in a tenant (paginated) | Yes (3) |
| `listSuperAdmins(req)`  | List all super-admin users         | Yes (3) |
| `suspendUser(req)`      | Suspend a user (with reason)       | No      |
| `reactivateUser(req)`   | Reactivate a suspended user        | No      |
| `deactivateUser(req)`   | Permanently deactivate a user      | No      |
| `grantSuperAdmin(req)`  | Grant super-admin privileges       | No      |
| `revokeSuperAdmin(req)` | Revoke super-admin privileges      | No      |

Default timeout: **500 ms**.

```ts
import { IdentityClient } from "@coda/admin-api";

const identity = new IdentityClient({ baseUrl: "http://localhost:8091" });
const result = await identity.getUser({ tenantId: "t_456", userId: "u_123" });
if (result.ok) console.log(result.data.email);
```

## Configuration

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

```ts
interface BaseClientConfig {
  baseUrl: string; // Service URL
  transport?: "connect" | "grpc"; // Wire format (default: "connect")
  interceptors?: Interceptor[]; // ConnectRPC interceptors
  defaultTimeoutMs?: number; // Override default timeout
  onError?: (method: string, err: unknown) => void; // Error hook
}
```

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

## Exported Types

This package re-exports all proto-generated types and schemas for:

- **Access:** `CheckRequest`, `CheckResponse`, `CheckBatchRequest`, `GetEffectiveRequest`, `ResolveTenantRequest`, etc.
- **Roles:** `CreateRoleRequest`, `ListRolesResponse`, `SetRolePermissionsRequest`, etc.
- **Policies:** `GrantPermissionRequest`, `DenyPermissionRequest`, `PolicyCondition`, etc.
- **Tenants:** `CreateTenantRequest`, `ListTenantsResponse`, `TenantInfo`, `TenantStatus`, etc.
- **Identity:** `ListUsersRequest`, `GetUserRequest`, `SuperAdminInfo`, `SuperAdminLevel`, etc.
- **Sessions:** `SessionInfo`, `ListSessionsRequest`, `CreateStepUpChallengeRequest`, etc.
- **Cache:** `ListCacheRequest`, `BustCacheRequest`, `BludgeonCacheRequest`, `CacheType`, etc.

## Service Definitions

Exported for use with raw ConnectRPC clients or server implementations:

`AccessService`, `RoleService`, `PolicyService`, `TenantService`, `IdentityService`, `SessionService`, `CacheService`

## Proto sources

`proto/admin/` — `.proto` files defining the RPC services 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.