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

package/src/graphClient.ts

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