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

package/src/graphClient.ts

@@ -0,0 +1,529 @@
+import {
+  createGatewayRequestClient,
+  type GatewayClientConfig,
+  LucernApiError,
+  randomIdempotencyKey,
+  toQueryString,
+} from "./coreClient";
+import {
+  mapAliasedList,
+  mapGatewayData,
+  normalizeNodeWriteInput,
+  normalizeNodeVerificationStatus,
+  normalizeTopicQuery,
+  withSdkAliases,
+} from "./sdkSurface";
+import type {
+  CreateEdgeResponse,
+  CreateNodeResponse,
+  DeleteEdgeResponse,
+  GraphAnalyticsMetric,
+  GraphAnalyticsResponse,
+  GraphNeighborhoodResponse,
+  GraphPathResponse,
+  JsonObject,
+  ListResult,
+  PlatformGraphEdge,
+  PlatformGraphNode,
+  QueryEdgesResponse,
+  QueryNodesResponse,
+  TextAliasInput,
+  TopicIdentifierInput,
+  UpdateNodeResponse,
+} from "./types";
+
+export { LucernApiError };
+export type { GatewayScope, PlatformGatewaySuccess } from "./coreClient";
+export type {
+  CreateEdgeResponse,
+  CreateNodeResponse,
+  DeleteEdgeResponse,
+  GraphAnalyticsMetric,
+  GraphAnalyticsResponse,
+  GraphNeighborhoodResponse,
+  GraphPathResponse,
+  ListResult,
+  QueryEdgesResponse,
+  QueryNodesResponse,
+  UpdateNodeResponse,
+} from "./types";
+
+/** Configuration for the graph client. */
+export type GraphClientConfig = GatewayClientConfig;
+
+/** Filter parameters for listing graph nodes. */
+export type ListNodesInput = {
+  nodeId?: string;
+  globalId?: string;
+  topicId?: string;
+  nodeType?: string;
+  limit?: number;
+} & TopicIdentifierInput;
+
+/** Paginated list response containing graph nodes. */
+export type ListNodesResponse = ListResult<PlatformGraphNode, "nodes">;
+
+/** @deprecated Use ListNodesInput. */
+export type QueryNodesInput = ListNodesInput;
+
+/** Input for creating a new graph node. */
+export type CreateNodeInput = {
+  text?: string;
+  /** @deprecated Use text. */
+  canonicalText?: string;
+  nodeType: string;
+  topicId?: string;
+  content?: string;
+  contentHash?: string;
+  globalId?: string;
+  sourceType?: string;
+  subtype?: string;
+  title?: string;
+  confidence?: number;
+  status?: string;
+  tags?: string[];
+  metadata?: JsonObject;
+  verificationStatus?: string;
+} & TextAliasInput &
+  TopicIdentifierInput;
+
+/** Input for updating an existing graph node. */
+export type UpdateNodeInput = {
+  nodeId: string;
+  text?: string;
+  canonicalText?: string;
+  content?: string;
+  contentHash?: string;
+  title?: string;
+  subtype?: string;
+  confidence?: number;
+  status?: string;
+  tags?: string[];
+  metadata?: JsonObject;
+  verificationStatus?: string;
+} & TextAliasInput;
+
+/** Input for retrieving a single graph node by canonical identifier. */
+export type GetNodeInput = {
+  nodeId?: string;
+  globalId?: string;
+};
+
+/** Filter parameters for listing graph edges. */
+export type ListEdgesInput = {
+  edgeId?: string;
+  topicId?: string;
+  fromNodeId?: string;
+  toNodeId?: string;
+  edgeType?: string;
+  limit?: number;
+} & TopicIdentifierInput;
+
+/** Paginated list response containing graph edges. */
+export type ListEdgesResponse = ListResult<PlatformGraphEdge, "edges">;
+
+/** @deprecated Use ListEdgesInput. */
+export type QueryEdgesInput = ListEdgesInput;
+
+/** Input for creating a typed edge between two graph nodes. */
+export type CreateEdgeInput = {
+  fromNodeId: string;
+  toNodeId: string;
+  edgeType: string;
+  globalId?: string;
+  topicId?: string;
+  confidence?: number;
+  weight?: number;
+  context?: string;
+  derivationType?: string;
+} & TopicIdentifierInput;
+
+/** Filter for selecting edges to delete. */
+export type DeleteEdgeInput = {
+  edgeId?: string;
+  fromNodeId?: string;
+  toNodeId?: string;
+  edgeType?: string;
+};
+
+/** Input for batch-creating multiple graph nodes. */
+export type BatchCreateNodesInput = {
+  nodes: Array<CreateNodeInput>;
+};
+
+/** Input for superseding an existing graph node with a new version. */
+export type SupersedeNodeInput = {
+  oldNodeId?: string;
+  nodeId?: string;
+  newGlobalId?: string;
+  newCanonicalText?: string;
+  text?: string;
+  canonicalText?: string;
+  newContentHash?: string;
+  reason?: string;
+};
+
+/** Input for updating a node's verification state. */
+export type VerifyNodeInput = {
+  nodeId?: string;
+  id?: string;
+  verificationStatus: string;
+  confidence?: number;
+};
+
+/** Input for permanently deleting a node via admin-only API. */
+export type HardDeleteNodeInput = {
+  nodeId?: string;
+  id?: string;
+  reason: string;
+  allowBeliefHardDelete?: boolean;
+};
+
+/** Input for retrieving the local neighborhood around a graph node. */
+export type NeighborhoodInput = {
+  globalId?: string;
+  globalIds?: string;
+  maxDepth?: number;
+};
+
+/** Input for finding the shortest path between two graph nodes. */
+export type PathInput = {
+  fromGlobalId: string;
+  toGlobalId: string;
+  maxDepth?: number;
+};
+
+/** Input for retrieving a specific graph analytics metric. */
+export type AnalyticsInput = {
+  metric?: GraphAnalyticsMetric;
+  limit?: number;
+};
+
+/** Input for traversing the graph from a starting node. */
+export type TraverseInput = {
+  startNode: string;
+  direction?: string;
+  maxDepth?: number;
+  topicId?: string;
+} & TopicIdentifierInput;
+
+/** Input for structural analysis of a topic graph. */
+export type AnalyzeInput = {
+  topicId?: string;
+  metric?: GraphAnalyticsMetric;
+  limit?: number;
+} & TopicIdentifierInput;
+
+/** Input for detecting confirmation-bias patterns in a topic graph. */
+export type BiasInput = {
+  topicId?: string;
+  threshold?: number;
+  limit?: number;
+} & TopicIdentifierInput;
+
+/** Input for finding beliefs without sufficient testing questions. */
+export type GapsInput = {
+  topicId?: string;
+  minConfidence?: number;
+} & TopicIdentifierInput;
+
+/** Input for cross-resource search within a topic scope. */
+export type SearchInput = {
+  q?: string;
+  query?: string;
+  topicId?: string;
+  types?: string[];
+  status?: string;
+  minConfidence?: number;
+  limit?: number;
+  cursor?: string;
+} & TopicIdentifierInput;
+
+/**
+ * Create the low-level graph client for nodes, edges, and graph analytics.
+ * @param config - Gateway transport configuration.
+ * @returns An object with methods for CRUD on nodes/edges plus analytics, traversal, and search.
+ */
+export function createGraphClient(config: GraphClientConfig = {}) {
+  const gateway = createGatewayRequestClient(config);
+
+  return {
+    /**
+     * List graph nodes matching the provided filters.
+     */
+    async listNodes(query: ListNodesInput) {
+      return gateway.request<ListNodesResponse>({
+        path: `/api/platform/v1/graph/nodes${toQueryString(
+          normalizeTopicQuery(query)
+        )}`,
+      }).then((response) =>
+        mapGatewayData(response, (data) => mapAliasedList<PlatformGraphNode, "nodes">(data, "nodes"))
+      );
+    },
+
+    /**
+     * @deprecated Use listNodes.
+     */
+    async queryNodes(query: QueryNodesInput) {
+      return this.listNodes(query);
+    },
+
+    /**
+     * Retrieve a single graph node by nodeId or globalId.
+     */
+    async getNode(query: GetNodeInput) {
+      return gateway.request<PlatformGraphNode>({
+        path: `/api/platform/v1/graph/nodes${toQueryString(query)}`,
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          withSdkAliases(data as Record<string, unknown>) as PlatformGraphNode
+        )
+      );
+    },
+
+    /**
+     * Create a graph node.
+     */
+    async createNode(input: CreateNodeInput, idempotencyKey?: string) {
+      return gateway.request<CreateNodeResponse>({
+        path: "/api/platform/v1/graph/nodes",
+        method: "POST",
+        body: normalizeNodeWriteInput(input),
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          withSdkAliases(data as Record<string, unknown>) as CreateNodeResponse
+        )
+      );
+    },
+
+    /**
+     * Update a graph node.
+     */
+    async updateNode(input: UpdateNodeInput, idempotencyKey?: string) {
+      return gateway.request<UpdateNodeResponse>({
+        path: "/api/platform/v1/graph/nodes",
+        method: "PUT",
+        body: normalizeNodeWriteInput(input as UpdateNodeInput & JsonObject),
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          withSdkAliases(data as Record<string, unknown>) as UpdateNodeResponse
+        )
+      );
+    },
+
+    /**
+     * Batch create graph nodes through the admin route surface.
+     */
+    async batchCreateNodes(
+      input: BatchCreateNodesInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<Record<string, unknown>>({
+        path: "/api/platform/v1/graph/nodes/batch",
+        method: "POST",
+        body: {
+          nodes: input.nodes.map((node) => normalizeNodeWriteInput(node)),
+        } as JsonObject,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Supersede an existing graph node with a new canonical version.
+     */
+    async supersedeNode(input: SupersedeNodeInput, idempotencyKey?: string) {
+      return gateway.request<Record<string, unknown>>({
+        path: "/api/platform/v1/graph/nodes/supersede",
+        method: "POST",
+        body: input as JsonObject,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Update a node's verification status.
+     */
+    async verifyNode(input: VerifyNodeInput, idempotencyKey?: string) {
+      const verificationStatus =
+        normalizeNodeVerificationStatus(input.verificationStatus) ??
+        input.verificationStatus;
+      return gateway.request<Record<string, unknown>>({
+        path: "/api/platform/v1/graph/nodes/verify",
+        method: "POST",
+        body: {
+          ...input,
+          verificationStatus,
+        } as JsonObject,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Permanently delete a node via the admin-only hard-delete route.
+     */
+    async hardDeleteNode(input: HardDeleteNodeInput, idempotencyKey?: string) {
+      return gateway.request<Record<string, unknown>>({
+        path: "/api/platform/v1/graph/nodes/hard-delete",
+        method: "POST",
+        body: input as JsonObject,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * List graph edges matching the provided filters.
+     */
+    async listEdges(query: ListEdgesInput) {
+      return gateway.request<ListEdgesResponse>({
+        path: `/api/platform/v1/graph/edges${toQueryString(
+          normalizeTopicQuery(query)
+        )}`,
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          mapAliasedList<PlatformGraphEdge, "edges">(data, "edges")
+        )
+      );
+    },
+
+    /**
+     * @deprecated Use listEdges.
+     */
+    async queryEdges(query: QueryEdgesInput) {
+      return this.listEdges(query);
+    },
+
+    /**
+     * Create a graph edge.
+     */
+    async createEdge(input: CreateEdgeInput, idempotencyKey?: string) {
+      return gateway.request<CreateEdgeResponse>({
+        path: "/api/platform/v1/graph/edges",
+        method: "POST",
+        body: normalizeTopicQuery(input as CreateEdgeInput & JsonObject),
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Delete one or more edges matching the provided filter.
+     */
+    async deleteEdge(query: DeleteEdgeInput, idempotencyKey?: string) {
+      return gateway.request<DeleteEdgeResponse>({
+        path: `/api/platform/v1/graph/edges${toQueryString(query)}`,
+        method: "DELETE",
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Retrieve a graph neighborhood around a root node.
+     */
+    async neighborhood(query: NeighborhoodInput) {
+      return gateway.request<GraphNeighborhoodResponse>({
+        path: `/api/platform/v1/graph/neighborhood${toQueryString(query)}`,
+      });
+    },
+
+    /**
+     * Traverse the graph from a starting node.
+     */
+    async traverse(query: TraverseInput) {
+      return gateway.request<Record<string, unknown>>({
+        path: "/api/platform/v1/graph/traverse",
+        method: "POST",
+        body: normalizeTopicQuery(query as TraverseInput & JsonObject),
+      });
+    },
+
+    /**
+     * Analyze graph structure for a topic.
+     */
+    async analyze(query: AnalyzeInput = {}) {
+      const normalized = normalizeTopicQuery(query as AnalyzeInput & JsonObject);
+      return gateway.request<Record<string, unknown>>({
+        path: `/api/platform/v1/graph/analyze${toQueryString({
+          topicId:
+            typeof normalized.topicId === "string" ? normalized.topicId : undefined,
+          metric:
+            typeof normalized.metric === "string" ? normalized.metric : undefined,
+          limit:
+            typeof normalized.limit === "number" ? normalized.limit : undefined,
+        })}`,
+      });
+    },
+
+    /**
+     * Detect confirmation-bias patterns for a topic graph.
+     */
+    async bias(query: BiasInput = {}) {
+      const normalized = normalizeTopicQuery(query as BiasInput & JsonObject);
+      return gateway.request<Record<string, unknown>>({
+        path: `/api/platform/v1/graph/bias${toQueryString({
+          topicId:
+            typeof normalized.topicId === "string" ? normalized.topicId : undefined,
+          threshold:
+            typeof normalized.threshold === "number"
+              ? normalized.threshold
+              : undefined,
+          limit:
+            typeof normalized.limit === "number" ? normalized.limit : undefined,
+        })}`,
+      });
+    },
+
+    /**
+     * Find graph gaps for beliefs that still need testing.
+     */
+    async gaps(query: GapsInput) {
+      const normalized = normalizeTopicQuery(query as GapsInput & JsonObject);
+      return gateway.request<Record<string, unknown>>({
+        path: `/api/platform/v1/graph/gaps${toQueryString({
+          topicId:
+            typeof normalized.topicId === "string" ? normalized.topicId : undefined,
+          minConfidence:
+            typeof normalized.minConfidence === "number"
+              ? normalized.minConfidence
+              : undefined,
+        })}`,
+      });
+    },
+
+    /**
+     * Search across graph resources within a topic.
+     */
+    async search(query: SearchInput) {
+      return gateway.request<Record<string, unknown>>({
+        path: "/api/platform/v1/search",
+        method: "POST",
+        body: normalizeTopicQuery(query as SearchInput & JsonObject),
+      });
+    },
+
+    /**
+     * Retrieve a graph neighborhood around a root node.
+     */
+    async getNeighborhood(query: NeighborhoodInput) {
+      return this.neighborhood(query);
+    },
+
+    /**
+     * Retrieve the shortest known path between two graph nodes.
+     */
+    async getPath(query: PathInput) {
+      return gateway.request<GraphPathResponse>({
+        path: `/api/platform/v1/graph/path${toQueryString(query)}`,
+      });
+    },
+
+    /**
+     * Retrieve graph analytics for the requested metric.
+     */
+    async getAnalytics(query: AnalyticsInput = {}) {
+      return gateway.request<GraphAnalyticsResponse>({
+        path: `/api/platform/v1/graph/analytics${toQueryString(query)}`,
+      });
+    },
+  };
+}