@lucern/sdk 0.2.0-alpha.5 → 0.2.0-alpha.7

package/src/adminClient.ts

@@ -0,0 +1,789 @@
+import {
+  createGatewayRequestClient,
+  type GatewayClientConfig,
+  type GatewayScope,
+  LucernApiError,
+  randomIdempotencyKey,
+  toQueryString,
+} from "./coreClient";
+import { createListResult, mapGatewayData } from "./sdkSurface";
+import type { ControlObjectOwnershipContract } from "./controlObjectOwnership";
+import type { JsonObject } from "./types";
+
+export { LucernApiError };
+export type { GatewayScope, PlatformGatewaySuccess } from "./coreClient";
+
+/** Configuration for the admin client. */
+export type AdminClientConfig = GatewayClientConfig;
+
+export type TenantApiKeyRecord = {
+  id?: string;
+  tenantId?: string;
+  workspaceId?: string;
+  label?: string;
+  keyPrefix?: string;
+  hashedKey?: string;
+  scopes?: string[];
+  status?: string;
+  expiresAt?: number;
+  lastUsedAt?: number;
+  revokedAt?: number;
+  revokedBy?: string;
+  createdBy?: string;
+  createdAt?: number;
+  updatedAt?: number;
+};
+
+export type TenantVaultSecretRecord = {
+  id?: string;
+  tenantId?: string;
+  workspaceId?: string;
+  name?: string;
+  description?: string;
+  lastRotated?: number;
+  createdBy?: string;
+  updatedBy?: string;
+  createdAt?: number;
+  updatedAt?: number;
+};
+
+export type TenantAuthPolicyMode = "open" | "invite_only" | "sso_required";
+export type TenantTopicVisibility = "private" | "tenant" | "public";
+export type TenantFeatureFlags = Record<string, boolean>;
+export type TenantModelSlotOverrides = Record<string, string>;
+
+export type TenantConfigRecord = {
+  tenantId: string;
+  authPolicyMode: TenantAuthPolicyMode;
+  defaultSessionTTL: number;
+  defaultTopicVisibility: TenantTopicVisibility;
+  featureFlags: TenantFeatureFlags;
+  maxWorkspaceCount: number;
+  defaultModelSlotOverrides: TenantModelSlotOverrides;
+  updatedAt?: number;
+  updatedBy?: string;
+};
+
+export type TenantModelRoutingSlotRecord = {
+  slot: string;
+  category?: string;
+  description?: string;
+  modelKey: string;
+  promptName?: string;
+  temperature?: number;
+  maxTokens?: number;
+  enabled?: boolean;
+};
+
+export type TenantModelRoutingModelRecord = {
+  key: string;
+  name?: string;
+  modelId?: string;
+  provider?: string;
+  enabled?: boolean;
+  recommended?: boolean;
+  notes?: string;
+};
+
+export type TenantModelRoutingBindingRecord = {
+  slot: string;
+  providerId: string;
+  secretRef: string;
+  label?: string;
+  keyHint?: string;
+};
+
+export type TenantModelRouteOverrideStatus =
+  | "inherit"
+  | "active"
+  | "blocked_missing_model"
+  | "blocked_missing_binding";
+
+export type TenantModelRouteBindingState = "ready" | "missing";
+export type TenantModelRouteSource = "platform_default" | "tenant_override";
+
+export type TenantModelRouteRow = {
+  slot: string;
+  category: string;
+  description?: string;
+  promptName?: string;
+  slotEnabled: boolean;
+  platformModelKey: string;
+  platformModelName?: string;
+  platformProviderId?: string;
+  overrideModelKey?: string;
+  overrideModelName?: string;
+  overrideProviderId?: string;
+  effectiveModelKey: string;
+  effectiveModelName?: string;
+  effectiveProviderId?: string;
+  effectiveSource: TenantModelRouteSource;
+  overrideStatus: TenantModelRouteOverrideStatus;
+  bindingState: TenantModelRouteBindingState;
+  bindingLabel?: string;
+  bindingKeyHint?: string;
+  bindingSecretRef?: string;
+};
+
+export type TenantModelRoutingSummary = {
+  totalSlots: number;
+  promptBoundSlots: number;
+  activeOverrides: number;
+  blockedOverrides: number;
+  readyBindings: number;
+};
+
+export type TenantModelRoutingSnapshot = {
+  tenantId: string;
+  defaultModelSlotOverrides: Record<string, string>;
+  slots: TenantModelRoutingSlotRecord[];
+  models: TenantModelRoutingModelRecord[];
+  bindings: TenantModelRoutingBindingRecord[];
+  rows: TenantModelRouteRow[];
+  summary: TenantModelRoutingSummary;
+  notes: string[];
+};
+
+function asTenantApiKeyRecord(data: unknown): TenantApiKeyRecord | null {
+  if (!data || typeof data !== "object") {
+    return null;
+  }
+  return data as TenantApiKeyRecord;
+}
+
+function asTenantApiKeyArray(data: unknown): TenantApiKeyRecord[] {
+  if (!Array.isArray(data)) {
+    return [];
+  }
+  return data
+    .map(asTenantApiKeyRecord)
+    .filter((row): row is TenantApiKeyRecord => Boolean(row));
+}
+
+function asTenantVaultSecretRecord(
+  data: unknown
+): TenantVaultSecretRecord | null {
+  if (!data || typeof data !== "object") {
+    return null;
+  }
+  return data as TenantVaultSecretRecord;
+}
+
+function asTenantVaultSecretArray(data: unknown): TenantVaultSecretRecord[] {
+  if (!Array.isArray(data)) {
+    return [];
+  }
+  return data
+    .map(asTenantVaultSecretRecord)
+    .filter((row): row is TenantVaultSecretRecord => Boolean(row));
+}
+
+/**
+ * Create the admin client for tenant, workspace, and membership administration.
+ * @param config - Gateway transport configuration.
+ * @returns An object with methods to manage tenants, workspaces, and memberships.
+ */
+export function createAdminClient(config: AdminClientConfig = {}) {
+  const gateway = createGatewayRequestClient(config);
+
+  return {
+    /**
+     * List tenants visible to the current principal.
+     */
+    async listTenants(
+      query: {
+        status?: "active" | "disabled" | "archived";
+        limit?: number;
+      } = {}
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/tenants${toQueryString(query)}`,
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          createListResult(
+            Array.isArray(data) ? data : [],
+            "tenants"
+          )
+        )
+      );
+    },
+
+    /**
+     * Create a tenant.
+     */
+    async createTenant(
+      input: {
+        key: string;
+        slug?: string;
+        name: string;
+        status?: "active" | "disabled" | "archived";
+        metadata?: JsonObject;
+      },
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: "/api/platform/v1/tenants",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Get the control-object ownership contract.
+     */
+    async getControlObjectOwnership() {
+      return gateway.request<ControlObjectOwnershipContract>({
+        path: "/api/platform/v1/admin/control-ownership",
+      });
+    },
+
+    /**
+     * @deprecated Use getControlObjectOwnership.
+     */
+    async getControlObjectOwnershipContract() {
+      return gateway.request<ControlObjectOwnershipContract>({
+        path: "/api/platform/v1/admin/control-ownership",
+      });
+    },
+
+    /**
+     * List workspaces for the current admin scope.
+     */
+    async listWorkspaces(
+      query: GatewayScope & {
+        status?: "active" | "archived";
+        limit?: number;
+      } = {}
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/workspaces${toQueryString(query)}`,
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          createListResult(
+            Array.isArray(data) ? data : [],
+            "workspaces"
+          )
+        )
+      );
+    },
+
+    /**
+     * Create a workspace.
+     */
+    async createWorkspace(
+      input: GatewayScope & {
+        workspaceId?: string;
+        key?: string;
+        slug?: string;
+        name?: string;
+        status?: "active" | "archived";
+        defaultProjectVisibility?:
+          | "private"
+          | "team"
+          | "firm"
+          | "external"
+          | "public";
+        restore?: boolean;
+        metadata?: JsonObject;
+      },
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: "/api/platform/v1/workspaces",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * List memberships for the current admin scope.
+     */
+    async listMemberships(
+      query: GatewayScope & {
+        principalId?: string;
+        status?: "active" | "revoked" | "expired";
+        limit?: number;
+      } = {}
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/memberships${toQueryString(query)}`,
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          createListResult(
+            Array.isArray(data) ? data : [],
+            "memberships"
+          )
+        )
+      );
+    },
+
+    /**
+     * Create a membership.
+     */
+    async createMembership(
+      input: GatewayScope & {
+        membershipId?: string;
+        principalId: string;
+        role:
+          | "platform_admin"
+          | "tenant_admin"
+          | "workspace_admin"
+          | "editor"
+          | "viewer"
+          | "auditor"
+          | "service_agent";
+        status?: "active" | "revoked" | "expired";
+        source?: "bootstrap" | "manual" | "sync" | "invitation";
+      },
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: "/api/platform/v1/memberships",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Update a membership.
+     */
+    async updateMembership(
+      input: GatewayScope & {
+        membershipId?: string;
+        principalId: string;
+        role:
+          | "platform_admin"
+          | "tenant_admin"
+          | "workspace_admin"
+          | "editor"
+          | "viewer"
+          | "auditor"
+          | "service_agent";
+        status?: "active" | "revoked" | "expired";
+        source?: "bootstrap" | "manual" | "sync" | "invitation";
+      },
+      idempotencyKey?: string
+    ) {
+      return this.createMembership(input, idempotencyKey);
+    },
+
+    /**
+     * @deprecated Use createMembership or updateMembership.
+     */
+    async upsertMembership(
+      input: GatewayScope & {
+        membershipId?: string;
+        principalId: string;
+        role:
+          | "platform_admin"
+          | "tenant_admin"
+          | "workspace_admin"
+          | "editor"
+          | "viewer"
+          | "auditor"
+          | "service_agent";
+        status?: "active" | "revoked" | "expired";
+        source?: "bootstrap" | "manual" | "sync" | "invitation";
+      },
+      idempotencyKey?: string
+    ) {
+      return this.createMembership(input, idempotencyKey);
+    },
+
+    /**
+     * List tenant API keys in the current admin scope.
+     */
+    async listTenantApiKeys(
+      scope: GatewayScope & {
+        status?: "active" | "revoked" | "expired";
+      }
+    ) {
+      const response = await gateway.request<{ keys?: unknown[] }>({
+        path: `/api/platform/v1/tenant-api-keys${toQueryString(scope)}`,
+      });
+
+      return {
+        ...response,
+        data: {
+          keys: asTenantApiKeyArray(response.data?.keys),
+        },
+      };
+    },
+
+    /**
+     * Create a tenant API key.
+     */
+    async createTenantApiKey(
+      input: GatewayScope & {
+        label?: string;
+        scopes: string[];
+        expiresAt?: number;
+      },
+      idempotencyKey?: string
+    ) {
+      const response = await gateway.request<{
+        key?: unknown;
+        plaintextKey?: string;
+      }>({
+        path: "/api/platform/v1/tenant-api-keys",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+
+      return {
+        ...response,
+        data: {
+          key: asTenantApiKeyRecord(response.data?.key),
+          plaintextKey:
+            typeof response.data?.plaintextKey === "string"
+              ? response.data.plaintextKey
+              : undefined,
+        },
+      };
+    },
+
+    /**
+     * Revoke a tenant API key.
+     */
+    async revokeTenantApiKey(
+      keyId: string,
+      input: GatewayScope & { reason?: string } = {},
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/tenant-api-keys/${encodeURIComponent(keyId)}/revoke`,
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * List tenant vault secrets.
+     */
+    async listTenantVaultSecrets(scope: GatewayScope) {
+      const response = await gateway.request<{ secrets?: unknown[] }>({
+        path: `/api/platform/v1/tenant-vault-secrets${toQueryString(scope)}`,
+      });
+
+      return {
+        ...response,
+        data: {
+          secrets: asTenantVaultSecretArray(response.data?.secrets),
+        },
+      };
+    },
+
+    /**
+     * Create a tenant vault secret.
+     */
+    async createTenantVaultSecret(
+      input: GatewayScope & {
+        name: string;
+        description?: string;
+        value: string;
+      },
+      idempotencyKey?: string
+    ) {
+      const response = await gateway.request<{ secret?: unknown }>({
+        path: "/api/platform/v1/tenant-vault-secrets",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+
+      return {
+        ...response,
+        data: {
+          secret: asTenantVaultSecretRecord(response.data?.secret),
+        },
+      };
+    },
+
+    /**
+     * Update a tenant vault secret.
+     */
+    async updateTenantVaultSecret(
+      secretId: string,
+      input: GatewayScope & {
+        name: string;
+        description?: string;
+        value?: string;
+      },
+      idempotencyKey?: string
+    ) {
+      const response = await gateway.request<{ secret?: unknown }>({
+        path: `/api/platform/v1/tenant-vault-secrets/${encodeURIComponent(secretId)}`,
+        method: "PATCH",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+
+      return {
+        ...response,
+        data: {
+          secret: asTenantVaultSecretRecord(response.data?.secret),
+        },
+      };
+    },
+
+    /**
+     * Delete a tenant vault secret.
+     */
+    async deleteTenantVaultSecret(
+      secretId: string,
+      scope: GatewayScope,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/tenant-vault-secrets/${encodeURIComponent(
+          secretId
+        )}${toQueryString(scope)}`,
+        method: "DELETE",
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * List tenant provider secrets.
+     */
+    async listTenantSecrets(
+      scope: GatewayScope & {
+        providerId?: string;
+        status?: "active" | "revoked";
+      }
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/tenant-secrets${toQueryString(scope)}`,
+      });
+    },
+
+    /**
+     * Upsert a tenant provider secret.
+     */
+    async upsertTenantSecret(
+      input: GatewayScope & {
+        providerId: string;
+        apiKey: string;
+        label?: string;
+        modelSlotIds?: string[];
+        passThroughOnly?: boolean;
+        metadata?: JsonObject;
+      },
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: "/api/platform/v1/tenant-secrets",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Revoke a tenant provider secret.
+     */
+    async revokeTenantSecret(
+      secretRef: string,
+      input: GatewayScope & { reason?: string },
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/tenant-secrets/${encodeURIComponent(secretRef)}/revoke`,
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Get tenant configuration.
+     */
+    async getTenantConfig(scope: GatewayScope & { tenantId: string }) {
+      return gateway.request<TenantConfigRecord>({
+        path: `/api/platform/v1/tenant-config${toQueryString(scope)}`,
+      });
+    },
+
+    /**
+     * Get tenant model routing.
+     */
+    async getTenantModelRouting(scope: GatewayScope & { tenantId: string }) {
+      return gateway.request<TenantModelRoutingSnapshot>({
+        path: `/api/platform/v1/tenant-config/model-routing${toQueryString(scope)}`,
+      });
+    },
+
+    /**
+     * Upsert tenant configuration.
+     */
+    async upsertTenantConfig(
+      input: GatewayScope & Omit<TenantConfigRecord, "updatedAt" | "updatedBy">,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<TenantConfigRecord>({
+        path: "/api/platform/v1/tenant-config",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * List groups.
+     */
+    async listGroups(scope: GatewayScope & { limit?: number } = {}) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/groups${toQueryString(scope)}`,
+      });
+    },
+
+    /**
+     * Create a group.
+     */
+    async createGroup(
+      input: GatewayScope & {
+        name: string;
+        groupKey?: string;
+        groupType?: string;
+        description?: string;
+      },
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: "/api/platform/v1/groups",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Update a group.
+     */
+    async updateGroup(
+      groupId: string,
+      input: GatewayScope & {
+        name?: string;
+        description?: string;
+        workspaceId?: string;
+        clearWorkspaceId?: boolean;
+      },
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/groups/${encodeURIComponent(groupId)}`,
+        method: "PATCH",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Delete a group.
+     */
+    async deleteGroup(
+      groupId: string,
+      input: GatewayScope = {},
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/groups/${encodeURIComponent(groupId)}${toQueryString(input)}`,
+        method: "DELETE",
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * List group members.
+     */
+    async listGroupMembers(query: GatewayScope & { groupId: string }) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/groups/members${toQueryString(query)}`,
+      });
+    },
+
+    /**
+     * Add a group member.
+     */
+    async addGroupMember(
+      input: GatewayScope & {
+        groupId: string;
+        principalId: string;
+      },
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: "/api/platform/v1/groups/members",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Remove a group member.
+     */
+    async removeGroupMember(
+      input: GatewayScope & { groupId: string; principalId: string },
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/groups/members${toQueryString(input)}`,
+        method: "DELETE",
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * List pack-to-group assignments.
+     */
+    async listPackGroupAssignments(
+      query: GatewayScope & {
+        groupId?: string;
+        status?: string;
+      } = {}
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/groups/packs${toQueryString(query)}`,
+      });
+    },
+
+    /**
+     * Assign a pack to a group.
+     */
+    async assignPackToGroup(
+      input: GatewayScope & {
+        groupId: string;
+        packKey: string;
+        packVersion?: string;
+      },
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: "/api/platform/v1/groups/packs",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Remove a pack from a group.
+     */
+    async removePackFromGroup(
+      input: GatewayScope & { groupId: string; packKey: string },
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/groups/packs${toQueryString(input)}`,
+        method: "DELETE",
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+  };
+}