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

package/src/identityClient.ts

@@ -1,278 +0,0 @@
-import {
-  createGatewayRequestClient,
-  type GatewayClientConfig,
-  type GatewayScope,
-  type PlatformGatewaySuccess,
-  LucernApiError,
-  randomIdempotencyKey,
-  toQueryString,
-} from "./coreClient";
-import { createListResult, mapGatewayData } from "./sdkSurface";
-import type { JsonObject, SdkPrincipalContext } from "./types";
-
-/** Summary of the currently authenticated principal and their scopes. */
-export type IdentitySummary = SdkPrincipalContext;
-
-/** Gateway response wrapping an identity summary payload. */
-export type IdentityWhoamiResponse = PlatformGatewaySuccess<IdentitySummary>;
-
-function createIdentityWhoamiClient(
-  config: GatewayClientConfig = {}
-) {
-  const gateway = createGatewayRequestClient(config);
-
-  return {
-    async whoami(): Promise<IdentityWhoamiResponse> {
-      return gateway.request<SdkPrincipalContext>({
-        path: "/api/platform/v1/identity/whoami",
-      });
-    },
-  };
-}
-
-export { LucernApiError };
-export type { GatewayScope, PlatformGatewaySuccess } from "./coreClient";
-
-/** Configuration for the identity client. */
-export type IdentityClientConfig = GatewayClientConfig;
-
-export type ClerkUserSearchResult = {
-  clerkId: string;
-  email: string | null;
-  firstName: string | null;
-  lastName: string | null;
-  displayName: string | null;
-  imageUrl: string | null;
-};
-
-/**
- * Create the identity client for principals and API keys.
- * @param config - Gateway transport configuration.
- * @returns An object with methods for whoami, principal management, and key management.
- */
-export function createIdentityClient(config: IdentityClientConfig = {}) {
-  const gateway = createGatewayRequestClient(config);
-  const whoamiClient = createIdentityWhoamiClient(config);
-
-  const requestPrincipalWrite = (
-    method: "POST" | "PATCH",
-    input: GatewayScope & {
-      principalId: string;
-      principalType: "user" | "group" | "service" | "external_viewer";
-      clerkId?: string;
-      email?: string;
-      displayName?: string;
-      status?: "active" | "disabled" | "revoked";
-      metadata?: JsonObject;
-    },
-    idempotencyKey?: string
-  ) =>
-    gateway.request<unknown>({
-      path: "/api/platform/v1/identity/principals",
-      method,
-      body: input,
-      idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
-    });
-
-  return {
-    /**
-     * Resolve the current authenticated identity summary.
-     */
-    async whoami() {
-      return whoamiClient.whoami().then((response) =>
-        mapGatewayData(response, (data) => ({
-          principalId: data.principalId,
-          principalType: data.principalType,
-          tenantId: data.tenantId ?? null,
-          workspaceId: data.workspaceId ?? null,
-          scopes: Array.isArray(data.scopes) ? data.scopes : [],
-          roles: Array.isArray(data.roles) ? data.roles : [],
-          isPlatformAdmin: data.isPlatformAdmin === true,
-          isTenantAdmin: data.isTenantAdmin === true,
-          isWorkspaceAdmin: data.isWorkspaceAdmin === true,
-          authMode: data.authMode,
-          sessionId: data.sessionId,
-          delegatedBy: data.delegatedBy,
-          expiresAt: data.expiresAt,
-        }))
-      );
-    },
-
-    /**
-     * List principals in the current identity scope.
-     */
-    async listPrincipals(
-      query: GatewayScope & {
-        status?: string;
-        principalType?: string;
-        query?: string;
-        limit?: number;
-      } = {}
-    ) {
-      return gateway.request<unknown>({
-        path: `/api/platform/v1/identity/principals${toQueryString(query)}`,
-      }).then((response) =>
-        mapGatewayData(response, (data) =>
-          createListResult(
-            Array.isArray(data) ? data : [],
-            "principals"
-          )
-        )
-      );
-    },
-
-    /**
-     * Create a principal.
-     */
-    async createPrincipal(
-      input: GatewayScope & {
-        principalId: string;
-        principalType: "user" | "group" | "service" | "external_viewer";
-        clerkId?: string;
-        email?: string;
-        displayName?: string;
-        status?: "active" | "disabled" | "revoked";
-        metadata?: JsonObject;
-      },
-      idempotencyKey?: string
-    ) {
-      return requestPrincipalWrite("POST", input, idempotencyKey);
-    },
-
-    /**
-     * Update a principal.
-     */
-    async updatePrincipal(
-      input: GatewayScope & {
-        principalId: string;
-        principalType: "user" | "group" | "service" | "external_viewer";
-        clerkId?: string;
-        email?: string;
-        displayName?: string;
-        status?: "active" | "disabled" | "revoked";
-        metadata?: JsonObject;
-      },
-      idempotencyKey?: string
-    ) {
-      return requestPrincipalWrite("PATCH", input, idempotencyKey);
-    },
-
-    /**
-     * @deprecated Use createPrincipal or updatePrincipal.
-     */
-    async upsertPrincipal(
-      input: GatewayScope & {
-        principalId: string;
-        principalType: "user" | "group" | "service" | "external_viewer";
-        clerkId?: string;
-        email?: string;
-        displayName?: string;
-        status?: "active" | "disabled" | "revoked";
-        metadata?: JsonObject;
-      },
-      idempotencyKey?: string
-    ) {
-      return requestPrincipalWrite("PATCH", input, idempotencyKey);
-    },
-
-    /**
-     * List keys in the current identity scope.
-     */
-    async listKeys(
-      query: GatewayScope & {
-        principalId?: string;
-        status?: string;
-        limit?: number;
-      } = {}
-    ) {
-      return gateway.request<unknown>({
-        path: `/api/platform/v1/identity/keys${toQueryString(query)}`,
-      }).then((response) =>
-        mapGatewayData(response, (data) =>
-          createListResult(Array.isArray(data) ? data : [], "keys")
-        )
-      );
-    },
-
-    /**
-     * Create an API key.
-     */
-    async createKey(
-      input: GatewayScope & {
-        principalId: string;
-        keyId?: string;
-        token?: string;
-        scopes?: string[];
-        environment?: "sandbox" | "production";
-        expiresInDays?: number;
-        rateLimitTier?: "free" | "developer" | "partner";
-        metadata?: JsonObject;
-      },
-      idempotencyKey?: string
-    ) {
-      return gateway.request<unknown>({
-        path: "/api/platform/v1/identity/keys",
-        method: "POST",
-        body: input,
-        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
-      });
-    },
-
-    /**
-     * Rotate an API key.
-     */
-    async rotateKey(
-      keyId: string,
-      input: {
-        replacementKeyId?: string;
-        replacementToken?: string;
-        replacementExpiresInDays?: number;
-        gracePeriodHours?: number;
-      } = {},
-      idempotencyKey?: string
-    ) {
-      return gateway.request<unknown>({
-        path: `/api/platform/v1/identity/keys/${encodeURIComponent(keyId)}/rotate`,
-        method: "POST",
-        body: input,
-        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
-      });
-    },
-
-    /**
-     * Delete an API key by revoking it.
-     */
-    async deleteKey(
-      keyId: string,
-      input: { reason?: string } = {},
-      idempotencyKey?: string
-    ) {
-      return gateway.request<unknown>({
-        path: `/api/platform/v1/identity/keys/${encodeURIComponent(keyId)}/revoke`,
-        method: "POST",
-        body: input,
-        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
-      });
-    },
-
-    /**
-     * @deprecated Use deleteKey.
-     */
-    async revokeKey(
-      keyId: string,
-      input: { reason?: string } = {},
-      idempotencyKey?: string
-    ) {
-      return this.deleteKey(keyId, input, idempotencyKey);
-    },
-
-    /**
-     * Search Clerk users by email or display attributes.
-     */
-    async searchClerkUsers(q: string) {
-      return gateway.request<ClerkUserSearchResult[]>({
-        path: `/api/platform/v1/identity/clerk-users${toQueryString({ q })}`,
-      });
-    },
-  };
-}

package/src/index.ts

@@ -1,49 +0,0 @@
-/**
- * @lucern/sdk — The reasoning operating system for AI-native applications.
- *
- * This is the main entry point. It re-exports all client factories,
- * types, contracts, and utilities from domain modules.
- *
- * @packageDocumentation
- */
-export * from "./adminClient";
-export * from "./answersClient";
-export * from "./audiencesClient";
-export * from "./auditClient";
-export * from "./beliefsClient";
-export * from "./client";
-export * from "./contextFacade";
-export * from "./contextPackCompiler";
-export * from "./controlObjectOwnership";
-export * from "./coreClient";
-export * from "./contextClient";
-export * from "./contracts/api-enums.contract";
-export * from "./contracts/auth-session.contract";
-export { MAX_ENTITY_LIMIT } from "./contracts/contextPack";
-export * from "./contracts/lensFilter";
-export * from "./contracts/lensWorkflow";
-export * from "./contracts/mcpTools";
-export * from "./contracts/prompt";
-export * from "./contracts/workflowRuntime";
-export * from "./domainContext";
-export * from "./customTools";
-export * from "./decisionsClient";
-export * from "./events";
-export * from "./eventsCore";
-export * from "./graphClient";
-export * from "./harnessClient";
-export * from "./identityClient";
-export * from "./learningClient";
-export * from "./mcpParityClient";
-export * from "./mcpParitySurface";
-export * from "./ontologyClient";
-export * from "./packRuntime";
-export * from "./packsClient";
-export * from "./policyClient";
-export * from "./reportsClient";
-export * from "./schemaClient";
-export * from "./sdkSurface";
-export * from "./topicsClient";
-export * from "./types";
-export * from "./version";
-export * from "./workflowClient";

package/src/learningClient.ts

@@ -1,95 +0,0 @@
-import {
-  createGatewayRequestClient,
-  type GatewayClientConfig,
-  toQueryString,
-} from "./coreClient";
-import { createListResult, mapGatewayData, normalizeTopicQuery } from "./sdkSurface";
-import type { TopicIdentifierInput } from "./types";
-
-/** Configuration for the learning client. */
-export type LearningClientConfig = GatewayClientConfig;
-
-/**
- * Create the learning client for execution telemetry reads.
- * @param config - Gateway transport configuration.
- * @returns An object with methods to list executions and retrieve stats.
- */
-export function createLearningClient(config: LearningClientConfig = {}) {
-  const gateway = createGatewayRequestClient(config);
-
-  return {
-    /**
-     * List recent execution records.
-     */
-    async listRecentExecutions(
-      args: {
-        namespace?: string;
-        topicId?: string;
-        audienceMode?: string;
-        success?: boolean;
-        limit?: number;
-      } & TopicIdentifierInput = {}
-    ) {
-      return gateway.request<unknown>({
-        path: `/api/platform/v1/learning/executions/recent${toQueryString({
-          ...normalizeTopicQuery(args),
-          namespace: args.namespace,
-          audienceMode: args.audienceMode,
-          success:
-            typeof args.success === "boolean"
-              ? args.success
-                ? "true"
-                : "false"
-              : undefined,
-          limit:
-            typeof args.limit === "number" && Number.isFinite(args.limit)
-              ? String(args.limit)
-              : undefined,
-        })}`,
-      }).then((response) =>
-        mapGatewayData(response, (data) =>
-          createListResult(Array.isArray(data) ? data : [], "executions")
-        )
-      );
-    },
-
-    /**
-     * @deprecated Use listRecentExecutions.
-     */
-    async getRecentExecutions(
-      args: {
-        namespace?: string;
-        topicId?: string;
-        audienceMode?: string;
-        success?: boolean;
-        limit?: number;
-      } & TopicIdentifierInput = {}
-    ) {
-      return this.listRecentExecutions(args);
-    },
-
-    /**
-     * Get aggregate execution statistics.
-     */
-    async getExecutionStats(
-      args: {
-        namespace?: string;
-        topicId?: string;
-        audienceMode?: string;
-        hours?: number;
-      } & TopicIdentifierInput = {}
-    ) {
-      return gateway.request<unknown>({
-        path: `/api/platform/v1/learning/executions/stats${toQueryString({
-          ...normalizeTopicQuery(args),
-          namespace: args.namespace,
-          audienceMode: args.audienceMode,
-          hours:
-            typeof args.hours === "number" && Number.isFinite(args.hours)
-              ? String(args.hours)
-              : undefined,
-        })}`,
-      });
-    },
-  };
-}

package/src/mcpParityClient.ts

@@ -1,240 +0,0 @@
-import {
-  createGatewayRequestClient,
-  type GatewayClientConfig,
-  randomIdempotencyKey,
-  type PlatformGatewaySuccess,
-} from "./coreClient";
-import type { JsonObject } from "./types";
-
-/** Configuration for the MCP parity client. Inherits gateway transport settings. */
-export type McpParityClientConfig = GatewayClientConfig;
-
-type ToolArgs = JsonObject;
-
-type ToolResult<T = unknown> = Promise<PlatformGatewaySuccess<T>>;
-
-function withSdkSessionId(args: ToolArgs | undefined, sessionId: string): ToolArgs {
-  return {
-    ...(args ?? {}),
-    __sdkSessionId: sessionId,
-  };
-}
-
-/**
- * Thin typed bridge for MCP-only SDK parity methods.
- *
- * These methods map 1:1 to the Lucern MCP handlers and execute through the
- * platform gateway so the SDK can cover the full control-plane surface.
- */
-export function createMcpParityClient(config: McpParityClientConfig = {}) {
-  const gateway = createGatewayRequestClient(config);
-  const sessionId = crypto.randomUUID();
-
-  function executeRead<T = unknown>(
-    toolName: string,
-    args?: ToolArgs
-  ): ToolResult<T> {
-    return gateway.request<T>({
-      path: `/api/platform/v1/mcp-tools/${encodeURIComponent(toolName)}`,
-      method: "POST",
-      body: withSdkSessionId(args, sessionId),
-    });
-  }
-
-  function executeMutation<T = unknown>(
-    toolName: string,
-    args?: ToolArgs,
-    idempotencyKey?: string
-  ): ToolResult<T> {
-    return gateway.request<T>({
-      path: `/api/platform/v1/mcp-tools/${encodeURIComponent(toolName)}`,
-      method: "POST",
-      body: withSdkSessionId(args, sessionId),
-      idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
-    });
-  }
-
-  return {
-    sessionId,
-
-    listTopics(args: ToolArgs = {}) {
-      return executeRead("list_topics", args);
-    },
-    createTopic(args: ToolArgs, idempotencyKey?: string) {
-      return executeMutation("create_topic", args, idempotencyKey);
-    },
-    getTopic(args: ToolArgs) {
-      return executeRead("get_topic", args);
-    },
-    getTopicTree(args: ToolArgs) {
-      return executeRead("get_topic_tree", args);
-    },
-
-    activateWorktree(args: ToolArgs, idempotencyKey?: string) {
-      return executeMutation("activate_worktree", args, idempotencyKey);
-    },
-    updateWorktreeMetadata(args: ToolArgs, idempotencyKey?: string) {
-      return executeMutation("update_worktree_metadata", args, idempotencyKey);
-    },
-    updateWorktreeTargets(args: ToolArgs, idempotencyKey?: string) {
-      return executeMutation("update_worktree_targets", args, idempotencyKey);
-    },
-    listAllWorktrees(args: ToolArgs = {}) {
-      return executeRead("list_all_worktrees", args);
-    },
-    pipelineSnapshot(args: ToolArgs) {
-      return executeRead("pipeline_snapshot", args);
-    },
-    recordScopeLearning(args: ToolArgs, idempotencyKey?: string) {
-      return executeMutation("record_scope_learning", args, idempotencyKey);
-    },
-    discover(args: ToolArgs) {
-      return executeRead("discover", args);
-    },
-    analyzeTopicDensity(args: ToolArgs) {
-      return executeRead("analyze_topic_density", args);
-    },
-    applyAutoBranching(args: ToolArgs, idempotencyKey?: string) {
-      return executeMutation("apply_auto_branching", args, idempotencyKey);
-    },
-    seedBeliefLattice(args: ToolArgs = {}, idempotencyKey?: string) {
-      return executeMutation("seed_belief_lattice", args, idempotencyKey);
-    },
-    getLatticeCoverage(args: ToolArgs = {}) {
-      return executeRead("get_lattice_coverage", args);
-    },
-    matchEntityType(args: ToolArgs) {
-      return executeRead("match_entity_type", args);
-    },
-    discoverEntityConnections(args: ToolArgs) {
-      return executeRead("discover_entity_connections", args);
-    },
-    triggerBeliefReview(args: ToolArgs, idempotencyKey?: string) {
-      return executeMutation("trigger_belief_review", args, idempotencyKey);
-    },
-
-    listOntologies(args: ToolArgs = {}) {
-      return executeRead("list_ontologies", args);
-    },
-    getOntology(args: ToolArgs) {
-      return executeRead("get_ontology", args);
-    },
-    applyOntology(args: ToolArgs, idempotencyKey?: string) {
-      return executeMutation("apply_ontology", args, idempotencyKey);
-    },
-    createOntology(args: ToolArgs, idempotencyKey?: string) {
-      return executeMutation("create_ontology", args, idempotencyKey);
-    },
-    updateOntology(args: ToolArgs, idempotencyKey?: string) {
-      return executeMutation("update_ontology", args, idempotencyKey);
-    },
-    archiveOntology(args: ToolArgs, idempotencyKey?: string) {
-      return executeMutation("archive_ontology", args, idempotencyKey);
-    },
-    createOntologyVersion(args: ToolArgs, idempotencyKey?: string) {
-      return executeMutation("create_ontology_version", args, idempotencyKey);
-    },
-    publishOntologyVersion(args: ToolArgs, idempotencyKey?: string) {
-      return executeMutation("publish_ontology_version", args, idempotencyKey);
-    },
-    deprecateOntologyVersion(args: ToolArgs, idempotencyKey?: string) {
-      return executeMutation(
-        "deprecate_ontology_version",
-        args,
-        idempotencyKey
-      );
-    },
-    resolveEffectiveOntology(args: ToolArgs) {
-      return executeRead("resolve_effective_ontology", args);
-    },
-
-    registerSession(args: ToolArgs = {}, idempotencyKey?: string) {
-      return executeMutation("register_session", args, idempotencyKey);
-    },
-    heartbeatSession(args: ToolArgs = {}, idempotencyKey?: string) {
-      return executeMutation("heartbeat_session", args, idempotencyKey);
-    },
-    endSession(args: ToolArgs = {}, idempotencyKey?: string) {
-      return executeMutation("end_session", args, idempotencyKey);
-    },
-    listActiveSessions(args: ToolArgs = {}) {
-      return executeRead("list_active_sessions", args);
-    },
-    sendAgentMessage(args: ToolArgs, idempotencyKey?: string) {
-      return executeMutation("send_agent_message", args, idempotencyKey);
-    },
-    broadcastMessage(args: ToolArgs, idempotencyKey?: string) {
-      return executeMutation("broadcast_message", args, idempotencyKey);
-    },
-    getAgentInbox(args: ToolArgs = {}) {
-      return executeRead("get_agent_inbox", args);
-    },
-    claimFiles(args: ToolArgs, idempotencyKey?: string) {
-      return executeMutation("claim_files", args, idempotencyKey);
-    },
-
-    listTasks(args: ToolArgs) {
-      return executeRead("list_tasks", args);
-    },
-    createAnswer(args: ToolArgs, idempotencyKey?: string) {
-      return executeMutation("create_answer", args, idempotencyKey);
-    },
-    getAnswer(args: ToolArgs) {
-      return executeRead("get_answer", args);
-    },
-    flagContradiction(args: ToolArgs, idempotencyKey?: string) {
-      return executeMutation("flag_contradiction", args, idempotencyKey);
-    },
-
-    ingestObservation(args: ToolArgs, idempotencyKey?: string) {
-      return executeMutation("ingest_observation", args, idempotencyKey);
-    },
-    getObservationContext(args: ToolArgs) {
-      return executeRead("get_observation_context", args);
-    },
-
-    getCodeContext(args: ToolArgs) {
-      return executeRead("get_code_context", args);
-    },
-    getChangeHistory(args: ToolArgs) {
-      return executeRead("get_change_history", args);
-    },
-    recordAttempt(args: ToolArgs, idempotencyKey?: string) {
-      return executeMutation("record_attempt", args, idempotencyKey);
-    },
-    getFailureLog(args: ToolArgs) {
-      return executeRead("get_failure_log", args);
-    },
-
-    createEpistemicContract(args: ToolArgs, idempotencyKey?: string) {
-      return executeMutation(
-        "create_epistemic_contract",
-        args,
-        idempotencyKey
-      );
-    },
-    evaluateContract(args: ToolArgs, idempotencyKey?: string) {
-      return executeMutation("evaluate_contract", args, idempotencyKey);
-    },
-    getContractStatus(args: ToolArgs) {
-      return executeRead("get_contract_status", args);
-    },
-
-    checkPermission(args: ToolArgs) {
-      return executeRead("check_permission", args);
-    },
-    filterByPermission(args: ToolArgs) {
-      return executeRead("filter_by_permission", args);
-    },
-
-    manageWritePolicy(args: ToolArgs, idempotencyKey?: string) {
-      return args.action === "set"
-        ? executeMutation("manage_write_policy", args, idempotencyKey)
-        : executeRead("manage_write_policy", args);
-    },
-
-    generateSessionHandoff(args: ToolArgs) {
-      return executeRead("generate_session_handoff", args);
-    },
-  };
-}