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

package/src/identityClient.ts

@@ -0,0 +1,278 @@
+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/{dist/lib/platform/sdk/index.d.ts → src/index.ts}

@@ -12,6 +12,7 @@ export * from "./audiencesClient";
 export * from "./auditClient";
 export * from "./beliefsClient";
 export * from "./client";
+export * from "./contextFacade";
 export * from "./contextPackCompiler";
 export * from "./controlObjectOwnership";
 export * from "./coreClient";
@@ -28,11 +29,13 @@ 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";

package/src/learningClient.ts

@@ -0,0 +1,95 @@
+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

@@ -0,0 +1,240 @@
+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);
+    },
+  };
+}