@lucern/sdk 0.3.0-alpha.17 → 0.3.0-alpha.2

package/dist/graphClient.d.ts

@@ -1,9 +1,7 @@
 import { GatewayClientConfig, PlatformGatewaySuccess } from './coreClient.js';
 export { GatewayScope, LucernApiError } from './coreClient.js';
-import { TopicIdentifierInput, JsonObject, TextAliasInput, GraphAnalyticsMetric, ListResult, PlatformGraphEdge, PlatformGraphNode, DeleteEdgeResponse, GraphNeighborhoodResponse, GraphPathResponse, GraphAnalyticsResponse } from './types.js';
+import { TopicIdentifierInput, JsonObject, TextAliasInput, GraphAnalyticsMetric, ListResult, PlatformGraphNode, PlatformGraphEdge, DeleteEdgeResponse, GraphNeighborhoodResponse, GraphPathResponse, GraphAnalyticsResponse } from './types.js';
 export { CreateEdgeResponse, CreateNodeResponse, QueryEdgesResponse, QueryNodesResponse, UpdateNodeResponse } from './types.js';
-import './authContext.js';
-import './contracts/auth-session.contract.js';
 import './contracts/workflow-runtime.contract.js';
 import './contracts/lens-workflow.contract.js';
 import './contracts/lens-filter.contract.js';
@@ -84,7 +82,6 @@ type CreateEdgeInput = {
     confidence?: number;
     weight?: number;
     context?: string;
-    reasoningMethod?: string;
     derivationType?: string;
 } & TopicIdentifierInput;
 /** Filter for selecting edges to delete. */
@@ -185,6 +182,10 @@ declare function createGraphClient(config?: GraphClientConfig): {
      * List graph nodes matching the provided filters.
      */
     listNodes(query: ListNodesInput): Promise<PlatformGatewaySuccess<ListResult<PlatformGraphNode, "nodes">>>;
+    /**
+     * @deprecated Use listNodes.
+     */
+    queryNodes(query: QueryNodesInput): Promise<PlatformGatewaySuccess<ListResult<PlatformGraphNode, "nodes">>>;
     /**
      * Retrieve a single graph node by nodeId or globalId.
      */
@@ -217,6 +218,10 @@ declare function createGraphClient(config?: GraphClientConfig): {
      * List graph edges matching the provided filters.
      */
     listEdges(query: ListEdgesInput): Promise<PlatformGatewaySuccess<ListResult<PlatformGraphEdge, "edges">>>;
+    /**
+     * @deprecated Use listEdges.
+     */
+    queryEdges(query: QueryEdgesInput): Promise<PlatformGatewaySuccess<ListResult<PlatformGraphEdge, "edges">>>;
     /**
      * Create a graph edge.
      */
@@ -249,6 +254,10 @@ declare function createGraphClient(config?: GraphClientConfig): {
      * Search across graph resources within a topic.
      */
     search(query: SearchInput): Promise<PlatformGatewaySuccess<Record<string, unknown>>>;
+    /**
+     * Retrieve a graph neighborhood around a root node.
+     */
+    getNeighborhood(query: NeighborhoodInput): Promise<PlatformGatewaySuccess<GraphNeighborhoodResponse>>;
     /**
      * Retrieve the shortest known path between two graph nodes.
      */
@@ -257,10 +266,6 @@ declare function createGraphClient(config?: GraphClientConfig): {
      * Retrieve graph analytics for the requested metric.
      */
     getAnalytics(query?: AnalyticsInput): Promise<PlatformGatewaySuccess<GraphAnalyticsResponse>>;
-} & {
-    queryNodes: (query: ListNodesInput) => Promise<PlatformGatewaySuccess<ListResult<PlatformGraphNode, "nodes">>>;
-    queryEdges: (query: ListEdgesInput) => Promise<PlatformGatewaySuccess<ListResult<PlatformGraphEdge, "edges">>>;
-    getNeighborhood: (query: NeighborhoodInput) => Promise<PlatformGatewaySuccess<GraphNeighborhoodResponse>>;
 };
 
 export { type AnalyticsInput, type AnalyzeInput, type BatchCreateNodesInput, type BiasInput, type CreateEdgeInput, type CreateNodeInput, type DeleteEdgeInput, DeleteEdgeResponse, type GapsInput, type GetNodeInput, GraphAnalyticsMetric, GraphAnalyticsResponse, type GraphClientConfig, GraphNeighborhoodResponse, GraphPathResponse, type HardDeleteNodeInput, type ListEdgesInput, type ListEdgesResponse, type ListNodesInput, type ListNodesResponse, ListResult, type NeighborhoodInput, type PathInput, PlatformGatewaySuccess, type QueryEdgesInput, type QueryNodesInput, type SearchInput, type SupersedeNodeInput, type TraverseInput, type UpdateNodeInput, type VerifyNodeInput, createGraphClient };

package/dist/graphClient.js

@@ -1,170 +1,3 @@
-// src/authContext.ts
-var LucernSdkAuthContextError = class extends Error {
-  reason;
-  constructor(reason, message) {
-    super(message);
-    this.name = "LucernSdkAuthContextError";
-    this.reason = reason;
-  }
-};
-function cleanString(value) {
-  const normalized = value?.trim();
-  return normalized ? normalized : void 0;
-}
-function cleanStringList(values) {
-  if (!values) {
-    return [];
-  }
-  return values.map((value) => value.trim()).filter(
-    (value, index, list) => value.length > 0 && list.indexOf(value) === index
-  );
-}
-function requireString(value, reason, label) {
-  const normalized = cleanString(value);
-  if (!normalized) {
-    throw new LucernSdkAuthContextError(
-      reason,
-      `Canonical Lucern SDK auth context is missing ${label}.`
-    );
-  }
-  return normalized;
-}
-function requirePrincipalType(principalType) {
-  if (!principalType) {
-    throw new LucernSdkAuthContextError(
-      "principal_missing",
-      "Canonical Lucern SDK auth context is missing principalType."
-    );
-  }
-  return principalType;
-}
-function requireAuthMode(authMode) {
-  if (!authMode) {
-    throw new LucernSdkAuthContextError(
-      "principal_missing",
-      "Canonical Lucern SDK auth context is missing authMode."
-    );
-  }
-  return authMode;
-}
-function ensurePermitMatch(args) {
-  const actual = cleanString(args.actual);
-  if (actual && actual !== args.expected) {
-    throw new LucernSdkAuthContextError(
-      "policy_denied",
-      `Canonical Lucern SDK auth context has conflicting Permit ${args.field}.`
-    );
-  }
-}
-function normalizeCanonicalLucernAuthContext(input) {
-  if (!input) {
-    throw new LucernSdkAuthContextError(
-      "principal_missing",
-      "Canonical Lucern SDK auth context is required."
-    );
-  }
-  if (input.policyDecision === "deny") {
-    throw new LucernSdkAuthContextError(
-      "policy_denied",
-      "Canonical Lucern SDK auth context carries a denied policy decision."
-    );
-  }
-  const principalId = requireString(
-    input.principalId,
-    "principal_missing",
-    "principalId"
-  );
-  const tenantId = requireString(input.tenantId, "tenant_missing", "tenantId");
-  const workspaceId = requireString(
-    input.workspaceId,
-    "workspace_missing",
-    "workspaceId"
-  );
-  const roles = cleanStringList(input.roles);
-  const scopes = cleanStringList(input.scopes);
-  const principalType = requirePrincipalType(input.principalType);
-  const authMode = requireAuthMode(input.authMode);
-  const roleBasedInteractiveAuth = authMode === "interactive_user" && roles.length > 0;
-  if (roles.length === 0 || scopes.length === 0 && !roleBasedInteractiveAuth) {
-    throw new LucernSdkAuthContextError(
-      "membership_missing",
-      "Canonical Lucern SDK auth context requires non-empty roles and scopes."
-    );
-  }
-  const subject = cleanString(input.permit?.subject) ?? principalId;
-  const tenant = cleanString(input.permit?.tenant) ?? tenantId;
-  const workspace = cleanString(input.permit?.workspace) ?? workspaceId;
-  ensurePermitMatch({
-    field: "subject",
-    expected: principalId,
-    actual: subject
-  });
-  ensurePermitMatch({ field: "tenant", expected: tenantId, actual: tenant });
-  ensurePermitMatch({
-    field: "workspace",
-    expected: workspaceId,
-    actual: workspace
-  });
-  const context = input.permit?.context ? { ...input.permit.context } : void 0;
-  return {
-    clerkId: cleanString(input.clerkId),
-    principalId,
-    tenantId,
-    workspaceId,
-    principalType,
-    authMode,
-    roles,
-    scopes,
-    delegationChain: input.delegationChain ? [...input.delegationChain] : [],
-    policyTraceId: cleanString(input.policyTraceId),
-    correlationId: cleanString(input.correlationId),
-    membershipId: cleanString(input.membershipId),
-    permit: {
-      subject,
-      tenant,
-      workspace,
-      resource: cleanString(input.permit?.resource),
-      action: cleanString(input.permit?.action),
-      relation: cleanString(input.permit?.relation),
-      context
-    }
-  };
-}
-function createCanonicalAuthHeaders(authContext) {
-  const headers = {
-    "x-lucern-principal-id": authContext.principalId,
-    "x-lucern-principal-type": authContext.principalType,
-    "x-lucern-tenant": authContext.tenantId,
-    "x-lucern-tenant-id": authContext.tenantId,
-    "x-lucern-workspace": authContext.workspaceId,
-    "x-lucern-workspace-id": authContext.workspaceId,
-    "x-lucern-auth-mode": authContext.authMode,
-    "x-lucern-roles": authContext.roles.join(","),
-    "x-lucern-scopes": authContext.scopes.join(","),
-    "x-lucern-permit-context": JSON.stringify(authContext.permit)
-  };
-  if (authContext.clerkId) {
-    headers["x-lucern-clerk-id"] = authContext.clerkId;
-    headers["x-lucern-user-id"] = authContext.clerkId;
-  }
-  if (authContext.delegationChain.length > 0) {
-    headers["x-lucern-delegation-chain"] = JSON.stringify(
-      authContext.delegationChain
-    );
-  }
-  if (authContext.policyTraceId) {
-    headers["x-lucern-policy-trace-id"] = authContext.policyTraceId;
-  }
-  if (authContext.correlationId) {
-    headers["x-correlation-id"] = authContext.correlationId;
-    headers["x-lucern-correlation-id"] = authContext.correlationId;
-  }
-  if (authContext.membershipId) {
-    headers["x-lucern-membership-id"] = authContext.membershipId;
-  }
-  return headers;
-}
-
 // src/coreClient.ts
 var LucernApiError = class extends Error {
   code;
@@ -232,7 +65,9 @@ function generatePortableRequestId() {
     8
   ).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10).join("")}`;
 }
-var randomIdempotencyKey = generatePortableRequestId;
+function randomIdempotencyKey() {
+  return generatePortableRequestId();
+}
 function isRetryableStatus(status) {
   return status >= 500 || status === 408 || status === 429;
 }
@@ -297,11 +132,8 @@ function timeoutError(timeoutMs) {
   error.name = "AbortError";
   return error;
 }
-function isRecord(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
 function readPolicySummaryFromDetails(details) {
-  if (!isRecord(details)) {
+  if (!details || typeof details !== "object" || Array.isArray(details)) {
     return null;
   }
   const directSummary = details.summary;
@@ -309,11 +141,11 @@ function readPolicySummaryFromDetails(details) {
     return directSummary.trim();
   }
   const policy = details.policy;
-  if (!isRecord(policy)) {
+  if (!policy || typeof policy !== "object" || Array.isArray(policy)) {
     return null;
   }
   const explanation = policy.explanation;
-  if (!isRecord(explanation)) {
+  if (!explanation || typeof explanation !== "object" || Array.isArray(explanation)) {
     return null;
   }
   const nestedSummary = explanation.summary;
@@ -322,59 +154,16 @@ function readPolicySummaryFromDetails(details) {
   }
   return null;
 }
-async function resolveConfiguredAuthContext(authContext) {
-  if (typeof authContext === "function") {
-    return await authContext();
-  }
-  return authContext;
-}
-function mergeHeaderRecord(base, addition) {
-  const headers = new Headers(base);
-  for (const [key, value] of Object.entries(addition)) {
-    const existing = headers.get(key);
-    if (existing !== null && existing !== value) {
-      throw new LucernSdkAuthContextError(
-        "policy_denied",
-        `Canonical Lucern SDK auth context conflicts with existing ${key} header.`
-      );
-    }
-    headers.set(key, value);
-  }
-  return Object.fromEntries(headers.entries());
-}
-function cleanHeaderValue(value) {
-  const normalized = value?.trim();
-  return normalized ? normalized : void 0;
-}
 function createGatewayRequestClient(config = {}) {
   const fetchImpl = config.fetchImpl ?? fetch;
   const baseUrl = config.baseUrl?.replace(/\/+$/, "") ?? "";
   const maxRetries = config.maxRetries ?? 2;
   const requestIdFactory = config.requestIdFactory ?? (() => generatePortableRequestId());
   async function resolveAuthHeaders() {
-    const provided = config.getAuthHeaders ? await config.getAuthHeaders() : {};
-    const headers = new Headers(provided);
-    const setIfAbsent = (name, value) => {
-      const normalized = cleanHeaderValue(value);
-      if (normalized && !headers.has(name)) {
-        headers.set(name, normalized);
-      }
-    };
-    setIfAbsent("x-lucern-key", config.apiKey);
-    setIfAbsent("x-lucern-session-token", config.userToken);
-    setIfAbsent("x-lucern-environment", config.environment);
-    setIfAbsent("x-lucern-clerk-id", config.clerkId);
-    setIfAbsent("x-lucern-user-id", config.userId ?? config.clerkId);
-    setIfAbsent("x-lucern-deployment-host", config.deploymentHost);
-    const base = Object.fromEntries(headers.entries());
-    const authContextInput = await resolveConfiguredAuthContext(
-      config.authContext
-    );
-    if (!authContextInput && !config.requireCanonicalAuthContext) {
-      return base;
+    if (!config.getAuthHeaders) {
+      return {};
     }
-    const authContext = normalizeCanonicalLucernAuthContext(authContextInput);
-    return mergeHeaderRecord(base, createCanonicalAuthHeaders(authContext));
+    return await config.getAuthHeaders();
   }
   async function fetchWithTimeout(url, init, timeoutMs) {
     const controller = new AbortController();
@@ -395,11 +184,11 @@ function createGatewayRequestClient(config = {}) {
     if (!text) {
       return null;
     }
-    const parsed = tryParseGatewayEnvelopeJson(text);
-    if (!parsed.ok) {
+    try {
+      return JSON.parse(text);
+    } catch {
       return null;
     }
-    return isRecord(parsed.value) ? parsed.value : null;
   }
   function resolveTimeoutMs(method, requestTimeoutMs) {
     if (typeof requestTimeoutMs === "number") {
@@ -411,31 +200,16 @@ function createGatewayRequestClient(config = {}) {
     }
     return config.timeoutMs ?? 15e3;
   }
-  function tryParseGatewayEnvelopeJson(text) {
-    const trimmed = text.trim();
-    if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) {
-      return { ok: false, reason: "non-json" };
-    }
-    try {
-      return { ok: true, value: JSON.parse(trimmed) };
-    } catch (error) {
-      if (error instanceof SyntaxError) {
-        return { ok: false, reason: "invalid-json", error };
-      }
-      throw error;
-    }
-  }
   function buildApiError(args) {
     const failure = args.failure;
-    const legacyError = failure && isRecord(failure.error) ? failure.error : failure?.legacyError;
+    const legacyError = failure && typeof failure.error === "object" && failure.error !== null ? failure.error : failure?.legacyError;
     const correlationId = failure?.correlationId ?? args.response.headers.get("x-lucern-correlation-id")?.trim() ?? args.requestId;
     const policyTraceId = failure?.policyTraceId ?? args.response.headers.get("x-lucern-policy-trace-id")?.trim() ?? null;
     const details = failure?.details ?? legacyError?.details;
     const policySummary = readPolicySummaryFromDetails(details);
-    const failureMessage = typeof failure?.error === "string" ? failure.error : legacyError?.message;
     return new LucernApiError({
       code: failure?.code ?? legacyError?.code ?? fallbackErrorCode(args.response.status),
-      message: policySummary ?? failureMessage ?? (args.response.ok ? "Platform API returned an invalid success payload." : "Platform API request failed."),
+      message: policySummary ?? (typeof failure?.error === "string" ? failure.error : legacyError?.message ?? (args.response.ok ? "Platform API returned an invalid success payload." : "Platform API request failed.")),
       status: args.response.status,
       invariant: failure?.invariant,
       suggestion: failure?.suggestion,
@@ -561,17 +335,14 @@ function createGatewayRequestClient(config = {}) {
 }
 
 // src/sdkSurface.ts
-function isRecord2(value) {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
 function asRecord(value) {
-  return isRecord2(value) ? value : {};
+  return value && typeof value === "object" ? value : {};
 }
-function cleanString2(value) {
+function cleanString(value) {
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
 }
 function normalizeVerificationStatus(value) {
-  const status = cleanString2(value);
+  const status = cleanString(value);
   if (!status) {
     return void 0;
   }
@@ -587,20 +358,20 @@ function cloneWith(value, patch) {
   return { ...value, ...patch };
 }
 function resolveTopicId(value) {
-  return cleanString2(value.topicId);
+  return cleanString(value.topicId);
 }
 function resolveText(value) {
-  return cleanString2(value.text) ?? cleanString2(value.canonicalText);
+  return cleanString(value.text) ?? cleanString(value.canonicalText);
 }
 function withTopicAlias(value) {
-  const topicId = cleanString2(value.topicId) ?? void 0;
+  const topicId = cleanString(value.topicId) ?? void 0;
   if (!topicId) {
     return value;
   }
   return cloneWith(value, { topicId });
 }
 function withTextAlias(value) {
-  const text = cleanString2(value.text) ?? cleanString2(value.canonicalText) ?? void 0;
+  const text = cleanString(value.text) ?? cleanString(value.canonicalText) ?? void 0;
   if (!text) {
     return value;
   }
@@ -626,9 +397,11 @@ function normalizeNodeWriteInput(value) {
   }
   return next;
 }
-var normalizeNodeVerificationStatus = normalizeVerificationStatus;
+function normalizeNodeVerificationStatus(value) {
+  return normalizeVerificationStatus(value);
+}
 function normalizeTopicQuery(value) {
-  const topicId = cleanString2(value.topicId);
+  const topicId = cleanString(value.topicId);
   if (!topicId) {
     return value;
   }
@@ -653,10 +426,7 @@ function createListResult(items, legacyKey) {
     total: items.length
   };
   if (legacyKey) {
-    return {
-      ...result,
-      [legacyKey]: items
-    };
+    result[legacyKey] = items;
   }
   return result;
 }
@@ -676,7 +446,7 @@ function mapAliasedList(data, legacyKey) {
 // src/graphClient.ts
 function createGraphClient(config = {}) {
   const gateway = createGatewayRequestClient(config);
-  const client = {
+  return {
     /**
      * List graph nodes matching the provided filters.
      */
@@ -689,6 +459,12 @@ function createGraphClient(config = {}) {
         (response) => mapGatewayData(response, (data) => mapAliasedList(data, "nodes"))
       );
     },
+    /**
+     * @deprecated Use listNodes.
+     */
+    async queryNodes(query) {
+      return this.listNodes(query);
+    },
     /**
      * Retrieve a single graph node by nodeId or globalId.
      */
@@ -799,6 +575,12 @@ function createGraphClient(config = {}) {
         )
       );
     },
+    /**
+     * @deprecated Use listEdges.
+     */
+    async queryEdges(query) {
+      return this.listEdges(query);
+    },
     /**
      * Create a graph edge.
      */
@@ -886,6 +668,12 @@ function createGraphClient(config = {}) {
         body: normalizeTopicQuery(query)
       });
     },
+    /**
+     * Retrieve a graph neighborhood around a root node.
+     */
+    async getNeighborhood(query) {
+      return this.neighborhood(query);
+    },
     /**
      * Retrieve the shortest known path between two graph nodes.
      */
@@ -903,11 +691,6 @@ function createGraphClient(config = {}) {
       });
     }
   };
-  return Object.assign(client, {
-    queryNodes: client.listNodes,
-    queryEdges: client.listEdges,
-    getNeighborhood: client.neighborhood
-  });
 }
 
 export { LucernApiError, createGraphClient };