@lucern/sdk 0.3.0-alpha.8 → 0.3.0-alpha.9

package/dist/clientHelpers.d.ts

@@ -1,10 +1,29 @@
-import { PlatformGraphEdge, PlatformGraphNode } from './types.js';
+import { JsonObject, PlatformGraphEdge, PlatformGraphNode } from './types.js';
 import './contracts/workflow-runtime.contract.js';
 import './contracts/lens-workflow.contract.js';
 import './contracts/lens-filter.contract.js';
 
 type NodeLike = PlatformGraphNode;
 type EdgeLike = PlatformGraphEdge;
+type CustomToolInput = JsonObject;
+type BeliefsRefineInput = string | {
+    text: string;
+    rationale?: string;
+};
+type BeliefsArchiveInput = {
+    reason?: string;
+    rationale?: string;
+} | string;
+declare function normalizeCustomNamespace(namespace: string): string;
+declare function normalizeCustomToolPayload(input: unknown): CustomToolInput;
+declare function resolveCustomToolFullName(name: string): string;
+declare function buildBeliefsRefinePayload(textOrInput: BeliefsRefineInput, rationale?: string): {
+    text: string;
+    rationale?: string;
+};
+declare function buildBeliefsArchivePayload(input?: BeliefsArchiveInput): {
+    reason?: string;
+} | undefined;
 declare function asNodeArray(data: unknown): NodeLike[];
 declare function asEdgeArray(data: unknown): EdgeLike[];
 declare function requireTopicId(args: {
@@ -26,4 +45,4 @@ declare function requireBaseRate(args: {
 }): number;
 declare function sdkQueryString(input: Record<string, unknown>): string;
 
-export { type EdgeLike, type NodeLike, asEdgeArray, asNodeArray, matchesAuditNodeReference, requireBaseRate, requireText, requireTopicId, requireTopicOrProjectId, sdkQueryString };
+export { type BeliefsArchiveInput, type BeliefsRefineInput, type CustomToolInput, type EdgeLike, type NodeLike, asEdgeArray, asNodeArray, buildBeliefsArchivePayload, buildBeliefsRefinePayload, matchesAuditNodeReference, normalizeCustomNamespace, normalizeCustomToolPayload, requireBaseRate, requireText, requireTopicId, requireTopicOrProjectId, resolveCustomToolFullName, sdkQueryString };

package/dist/clientHelpers.js

@@ -29,6 +29,21 @@ function asListItems(data, legacyKey) {
 }
 
 // src/clientHelpers.ts
+function normalizeCustomNamespace(namespace) {
+  return namespace.trim() || "custom";
+}
+function normalizeCustomToolPayload(input) {
+  return input && typeof input === "object" && !Array.isArray(input) ? input : {};
+}
+function resolveCustomToolFullName(name) {
+  return name.includes(".") ? name : `custom.${name}`;
+}
+function buildBeliefsRefinePayload(textOrInput, rationale) {
+  return typeof textOrInput === "string" ? { text: textOrInput, rationale } : { text: textOrInput.text, rationale: textOrInput.rationale };
+}
+function buildBeliefsArchivePayload(input) {
+  return typeof input === "string" ? { reason: input } : input ? { reason: input.reason ?? input.rationale } : void 0;
+}
 function asNodeArray(data) {
   const rows = asListItems(data, "nodes");
   if (rows.length > 0) {
@@ -117,6 +132,6 @@ function sdkQueryString(input) {
   return serialized ? `?${serialized}` : "";
 }
 
-export { asEdgeArray, asNodeArray, matchesAuditNodeReference, requireBaseRate, requireText, requireTopicId, requireTopicOrProjectId, sdkQueryString };
+export { asEdgeArray, asNodeArray, buildBeliefsArchivePayload, buildBeliefsRefinePayload, matchesAuditNodeReference, normalizeCustomNamespace, normalizeCustomToolPayload, requireBaseRate, requireText, requireTopicId, requireTopicOrProjectId, resolveCustomToolFullName, sdkQueryString };
 //# sourceMappingURL=clientHelpers.js.map
 //# sourceMappingURL=clientHelpers.js.map

package/dist/clientHelpers.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/sdkSurface.ts","../src/clientHelpers.ts"],"names":[],"mappings":"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","file":"clientHelpers.js","sourcesContent":["import type { PlatformGatewaySuccess } from \"./coreClient\";\nimport type { JsonObject, ListResult } from \"./types\";\n\ntype TopicScopedValue = {\n  topicId?: string;\n};\n\ntype TextScopedValue = {\n  text?: string;\n  canonicalText?: string;\n};\n\ntype AnyRecord = Record<string, unknown>;\n\nexport function isRecord(value: unknown): value is AnyRecord {\n  return Boolean(value) && typeof value === \"object\" && !Array.isArray(value);\n}\n\nexport function asRecord(value: unknown): AnyRecord {\n  return isRecord(value) ? value : {};\n}\n\nfunction cleanString(value: unknown): string | undefined {\n  return typeof value === \"string\" && value.trim().length > 0\n    ? value.trim()\n    : undefined;\n}\n\nfunction normalizeVerificationStatus(value: unknown): string | undefined {\n  const status = cleanString(value);\n  if (!status) {\n    return undefined;\n  }\n  if (status === \"verified\") {\n    return \"human_verified\";\n  }\n  if (status === \"rejected\") {\n    return \"contradicted\";\n  }\n  return status;\n}\n\nfunction cloneWith<T extends AnyRecord>(value: T, patch: AnyRecord): T {\n  return { ...value, ...patch } as T;\n}\n\n/**\n * Resolve the canonical topic identifier.\n */\nexport function resolveTopicId(value: TopicScopedValue): string | undefined {\n  return cleanString(value.topicId);\n}\n\n/**\n * Resolve the canonical text field from text-first or legacy canonicalText-first inputs.\n */\nexport function resolveText(value: TextScopedValue): string | undefined {\n  return cleanString(value.text) ?? cleanString(value.canonicalText);\n}\n\n/**\n * Attach the topicId to a record.\n */\nexport function withTopicAlias<T extends AnyRecord>(value: T): T {\n  const topicId = cleanString(value.topicId) ?? undefined;\n  if (!topicId) {\n    return value;\n  }\n  return cloneWith(value, { topicId });\n}\n\n/**\n * Attach the text/canonicalText alias pair to a record.\n */\nexport function withTextAlias<T extends AnyRecord>(value: T): T {\n  const text =\n    cleanString(value.text) ?? cleanString(value.canonicalText) ?? undefined;\n  if (!text) {\n    return value;\n  }\n  return cloneWith(value, { text, canonicalText: text });\n}\n\n/**\n * Attach topic and text aliases to SDK node-like records.\n */\nexport function withSdkAliases<T extends AnyRecord>(value: T): T {\n  return withTopicAlias(withTextAlias(value));\n}\n\n/**\n * Normalize a belief/question/evidence write payload to the canonical gateway shape.\n */\nexport function normalizeNodeWriteInput<T extends JsonObject>(value: T): T {\n  const topicId = resolveTopicId(value);\n  const text = resolveText(value);\n  const verificationStatus = normalizeVerificationStatus(value.verificationStatus);\n  const next = { ...value } as JsonObject;\n\n  if (topicId) {\n    next.topicId = topicId;\n  }\n  if (text) {\n    next.text = text;\n    next.canonicalText = text;\n  }\n  if (verificationStatus) {\n    next.verificationStatus = verificationStatus;\n  }\n\n  return next as T;\n}\n\nexport const normalizeNodeVerificationStatus = normalizeVerificationStatus;\n\n/**\n * Build a topic-aware query object.\n */\nexport function normalizeTopicQuery<T extends JsonObject>(value: T): T {\n  const topicId = cleanString(value.topicId);\n  if (!topicId) {\n    return value;\n  }\n  return { ...value, topicId } as T;\n}\n\n/**\n * Extract list items from array or list-envelope payloads.\n */\nexport function asListItems<T>(data: unknown, legacyKey?: string): T[] {\n  if (Array.isArray(data)) {\n    return data;\n  }\n\n  const record = asRecord(data);\n  if (Array.isArray(record.items)) {\n    return record.items;\n  }\n  if (legacyKey && Array.isArray(record[legacyKey])) {\n    return record[legacyKey];\n  }\n\n  return [];\n}\n\n/**\n * Standardize list data to { items, total } while retaining an optional legacy array key.\n */\nexport function createListResult<T, LegacyKey extends string>(\n  items: T[],\n  legacyKey?: LegacyKey\n): ListResult<T, LegacyKey> {\n  const result = {\n    items,\n    total: items.length,\n  } as ListResult<T, LegacyKey>;\n\n  if (legacyKey) {\n    return {\n      ...result,\n      [legacyKey]: items,\n    } as ListResult<T, LegacyKey>;\n  }\n\n  return result;\n}\n\n/**\n * Map a gateway success envelope's data while preserving the transport metadata.\n */\nexport function mapGatewayData<T, U>(\n  response: PlatformGatewaySuccess<T>,\n  mapper: (data: T) => U\n): PlatformGatewaySuccess<U> {\n  return {\n    ...response,\n    data: mapper(response.data),\n  };\n}\n\n/**\n * Apply SDK aliases across all items in a list-like payload.\n */\nexport function mapAliasedList<\n  TItem extends AnyRecord,\n  LegacyKey extends string,\n>(\n  data: unknown,\n  legacyKey?: LegacyKey\n): ListResult<TItem, LegacyKey> {\n  const items = asListItems<TItem>(data, legacyKey).map((item) =>\n    withSdkAliases(item)\n  );\n  return createListResult(items, legacyKey);\n}\n","import { asListItems, resolveText, resolveTopicId } from \"./sdkSurface\";\nimport type { PlatformGraphEdge, PlatformGraphNode } from \"./types\";\n\nexport type NodeLike = PlatformGraphNode;\nexport type EdgeLike = PlatformGraphEdge;\n\nexport function asNodeArray(data: unknown): NodeLike[] {\n  const rows = asListItems<NodeLike>(data, \"nodes\");\n  if (rows.length > 0) {\n    return rows.filter(\n      (value): value is NodeLike => Boolean(value) && typeof value === \"object\"\n    );\n  }\n  if (data && typeof data === \"object\") {\n    return [data as NodeLike];\n  }\n  return [];\n}\n\nexport function asEdgeArray(data: unknown): EdgeLike[] {\n  const rows = asListItems<EdgeLike>(data, \"edges\");\n  if (rows.length > 0) {\n    return rows.filter(\n      (value): value is EdgeLike => Boolean(value) && typeof value === \"object\"\n    );\n  }\n  if (data && typeof data === \"object\") {\n    return [data as EdgeLike];\n  }\n  return [];\n}\n\nexport function requireTopicId(args: { topicId?: string }): string {\n  const topicId = resolveTopicId(args);\n  if (!topicId) {\n    throw new Error(\"topicId is required\");\n  }\n  return topicId;\n}\n\nexport function requireTopicOrProjectId(args: {\n  topicId?: string;\n  projectId?: string;\n}): string {\n  const topicId =\n    args.topicId?.trim() || args.projectId?.trim() || undefined;\n  if (!topicId) {\n    throw new Error(\"topicId is required\");\n  }\n  return topicId;\n}\n\nconst AUDIT_NODE_REFERENCE_KEY_PATTERN =\n  /(^|_)(id|nodeid|beliefid|resourceid|targetid|sourceid|subjectid|globalid|entityid|recordid|fromnodeid|tonodeid|linkednodeid|linkedbeliefid|nodeids|beliefids|resourceids)$/i;\n\nexport function matchesAuditNodeReference(\n  value: unknown,\n  nodeId: string\n): boolean {\n  if (Array.isArray(value)) {\n    return value.some((entry) => matchesAuditNodeReference(entry, nodeId));\n  }\n\n  if (!value || typeof value !== \"object\") {\n    return false;\n  }\n\n  return Object.entries(value as Record<string, unknown>).some(([key, entry]) => {\n    if (\n      typeof entry === \"string\" &&\n      entry === nodeId &&\n      AUDIT_NODE_REFERENCE_KEY_PATTERN.test(key)\n    ) {\n      return true;\n    }\n\n    if (\n      Array.isArray(entry) &&\n      AUDIT_NODE_REFERENCE_KEY_PATTERN.test(key) &&\n      entry.some((item) => item === nodeId)\n    ) {\n      return true;\n    }\n\n    return matchesAuditNodeReference(entry, nodeId);\n  });\n}\n\nexport function requireText(args: {\n  text?: string;\n  canonicalText?: string;\n  formulation?: string;\n  newFormulation?: string;\n}): string {\n  const text = resolveText(args);\n  if (!text) {\n    throw new Error(\"text is required\");\n  }\n  return text;\n}\n\nexport function requireBaseRate(args: { baseRate?: number }): number {\n  const baseRate =\n    typeof args.baseRate === \"number\" && Number.isFinite(args.baseRate)\n      ? args.baseRate\n      : 0.5;\n  if (baseRate < 0 || baseRate > 1) {\n    throw new Error(\"baseRate must be within [0, 1].\");\n  }\n  return baseRate;\n}\n\nexport function sdkQueryString(input: Record<string, unknown>): string {\n  const params = new URLSearchParams();\n  for (const [key, value] of Object.entries(input)) {\n    if (value === undefined || value === null) {\n      continue;\n    }\n    if (Array.isArray(value)) {\n      if (value.length > 0) {\n        params.set(key, value.join(\",\"));\n      }\n      continue;\n    }\n    params.set(key, String(value));\n  }\n  const serialized = params.toString();\n  return serialized ? `?${serialized}` : \"\";\n}\n"]}
+{"version":3,"sources":["../src/sdkSurface.ts","../src/clientHelpers.ts"],"names":[],"mappings":"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","file":"clientHelpers.js","sourcesContent":["import type { PlatformGatewaySuccess } from \"./coreClient\";\nimport type { JsonObject, ListResult } from \"./types\";\n\ntype TopicScopedValue = {\n  topicId?: string;\n};\n\ntype TextScopedValue = {\n  text?: string;\n  canonicalText?: string;\n};\n\ntype AnyRecord = Record<string, unknown>;\n\nexport function isRecord(value: unknown): value is AnyRecord {\n  return Boolean(value) && typeof value === \"object\" && !Array.isArray(value);\n}\n\nexport function asRecord(value: unknown): AnyRecord {\n  return isRecord(value) ? value : {};\n}\n\nfunction cleanString(value: unknown): string | undefined {\n  return typeof value === \"string\" && value.trim().length > 0\n    ? value.trim()\n    : undefined;\n}\n\nfunction normalizeVerificationStatus(value: unknown): string | undefined {\n  const status = cleanString(value);\n  if (!status) {\n    return undefined;\n  }\n  if (status === \"verified\") {\n    return \"human_verified\";\n  }\n  if (status === \"rejected\") {\n    return \"contradicted\";\n  }\n  return status;\n}\n\nfunction cloneWith<T extends AnyRecord>(value: T, patch: AnyRecord): T {\n  return { ...value, ...patch } as T;\n}\n\n/**\n * Resolve the canonical topic identifier.\n */\nexport function resolveTopicId(value: TopicScopedValue): string | undefined {\n  return cleanString(value.topicId);\n}\n\n/**\n * Resolve the canonical text field from text-first or legacy canonicalText-first inputs.\n */\nexport function resolveText(value: TextScopedValue): string | undefined {\n  return cleanString(value.text) ?? cleanString(value.canonicalText);\n}\n\n/**\n * Attach the topicId to a record.\n */\nexport function withTopicAlias<T extends AnyRecord>(value: T): T {\n  const topicId = cleanString(value.topicId) ?? undefined;\n  if (!topicId) {\n    return value;\n  }\n  return cloneWith(value, { topicId });\n}\n\n/**\n * Attach the text/canonicalText alias pair to a record.\n */\nexport function withTextAlias<T extends AnyRecord>(value: T): T {\n  const text =\n    cleanString(value.text) ?? cleanString(value.canonicalText) ?? undefined;\n  if (!text) {\n    return value;\n  }\n  return cloneWith(value, { text, canonicalText: text });\n}\n\n/**\n * Attach topic and text aliases to SDK node-like records.\n */\nexport function withSdkAliases<T extends AnyRecord>(value: T): T {\n  return withTopicAlias(withTextAlias(value));\n}\n\n/**\n * Normalize a belief/question/evidence write payload to the canonical gateway shape.\n */\nexport function normalizeNodeWriteInput<T extends JsonObject>(value: T): T {\n  const topicId = resolveTopicId(value);\n  const text = resolveText(value);\n  const verificationStatus = normalizeVerificationStatus(value.verificationStatus);\n  const next = { ...value } as JsonObject;\n\n  if (topicId) {\n    next.topicId = topicId;\n  }\n  if (text) {\n    next.text = text;\n    next.canonicalText = text;\n  }\n  if (verificationStatus) {\n    next.verificationStatus = verificationStatus;\n  }\n\n  return next as T;\n}\n\nexport const normalizeNodeVerificationStatus = normalizeVerificationStatus;\n\n/**\n * Build a topic-aware query object.\n */\nexport function normalizeTopicQuery<T extends JsonObject>(value: T): T {\n  const topicId = cleanString(value.topicId);\n  if (!topicId) {\n    return value;\n  }\n  return { ...value, topicId } as T;\n}\n\n/**\n * Extract list items from array or list-envelope payloads.\n */\nexport function asListItems<T>(data: unknown, legacyKey?: string): T[] {\n  if (Array.isArray(data)) {\n    return data;\n  }\n\n  const record = asRecord(data);\n  if (Array.isArray(record.items)) {\n    return record.items;\n  }\n  if (legacyKey && Array.isArray(record[legacyKey])) {\n    return record[legacyKey];\n  }\n\n  return [];\n}\n\n/**\n * Standardize list data to { items, total } while retaining an optional legacy array key.\n */\nexport function createListResult<T, LegacyKey extends string>(\n  items: T[],\n  legacyKey?: LegacyKey\n): ListResult<T, LegacyKey> {\n  const result = {\n    items,\n    total: items.length,\n  } as ListResult<T, LegacyKey>;\n\n  if (legacyKey) {\n    return {\n      ...result,\n      [legacyKey]: items,\n    } as ListResult<T, LegacyKey>;\n  }\n\n  return result;\n}\n\n/**\n * Map a gateway success envelope's data while preserving the transport metadata.\n */\nexport function mapGatewayData<T, U>(\n  response: PlatformGatewaySuccess<T>,\n  mapper: (data: T) => U\n): PlatformGatewaySuccess<U> {\n  return {\n    ...response,\n    data: mapper(response.data),\n  };\n}\n\n/**\n * Apply SDK aliases across all items in a list-like payload.\n */\nexport function mapAliasedList<\n  TItem extends AnyRecord,\n  LegacyKey extends string,\n>(\n  data: unknown,\n  legacyKey?: LegacyKey\n): ListResult<TItem, LegacyKey> {\n  const items = asListItems<TItem>(data, legacyKey).map((item) =>\n    withSdkAliases(item)\n  );\n  return createListResult(items, legacyKey);\n}\n","import { asListItems, resolveText, resolveTopicId } from \"./sdkSurface\";\nimport type { JsonObject, PlatformGraphEdge, PlatformGraphNode } from \"./types\";\n\nexport type NodeLike = PlatformGraphNode;\nexport type EdgeLike = PlatformGraphEdge;\nexport type CustomToolInput = JsonObject;\nexport type BeliefsRefineInput =\n  | string\n  | { text: string; rationale?: string };\nexport type BeliefsArchiveInput = { reason?: string; rationale?: string } | string;\n\nexport function normalizeCustomNamespace(namespace: string): string {\n  return namespace.trim() || \"custom\";\n}\n\nexport function normalizeCustomToolPayload(input: unknown): CustomToolInput {\n  return input && typeof input === \"object\" && !Array.isArray(input)\n    ? (input as CustomToolInput)\n    : {};\n}\n\nexport function resolveCustomToolFullName(name: string): string {\n  return name.includes(\".\") ? name : `custom.${name}`;\n}\n\nexport function buildBeliefsRefinePayload(\n  textOrInput: BeliefsRefineInput,\n  rationale?: string\n): { text: string; rationale?: string } {\n  return typeof textOrInput === \"string\"\n    ? { text: textOrInput, rationale }\n    : { text: textOrInput.text, rationale: textOrInput.rationale };\n}\n\nexport function buildBeliefsArchivePayload(\n  input?: BeliefsArchiveInput\n): { reason?: string } | undefined {\n  return typeof input === \"string\"\n    ? { reason: input }\n    : input\n      ? { reason: input.reason ?? input.rationale }\n      : undefined;\n}\n\nexport function asNodeArray(data: unknown): NodeLike[] {\n  const rows = asListItems<NodeLike>(data, \"nodes\");\n  if (rows.length > 0) {\n    return rows.filter(\n      (value): value is NodeLike => Boolean(value) && typeof value === \"object\"\n    );\n  }\n  if (data && typeof data === \"object\") {\n    return [data as NodeLike];\n  }\n  return [];\n}\n\nexport function asEdgeArray(data: unknown): EdgeLike[] {\n  const rows = asListItems<EdgeLike>(data, \"edges\");\n  if (rows.length > 0) {\n    return rows.filter(\n      (value): value is EdgeLike => Boolean(value) && typeof value === \"object\"\n    );\n  }\n  if (data && typeof data === \"object\") {\n    return [data as EdgeLike];\n  }\n  return [];\n}\n\nexport function requireTopicId(args: { topicId?: string }): string {\n  const topicId = resolveTopicId(args);\n  if (!topicId) {\n    throw new Error(\"topicId is required\");\n  }\n  return topicId;\n}\n\nexport function requireTopicOrProjectId(args: {\n  topicId?: string;\n  projectId?: string;\n}): string {\n  const topicId =\n    args.topicId?.trim() || args.projectId?.trim() || undefined;\n  if (!topicId) {\n    throw new Error(\"topicId is required\");\n  }\n  return topicId;\n}\n\nconst AUDIT_NODE_REFERENCE_KEY_PATTERN =\n  /(^|_)(id|nodeid|beliefid|resourceid|targetid|sourceid|subjectid|globalid|entityid|recordid|fromnodeid|tonodeid|linkednodeid|linkedbeliefid|nodeids|beliefids|resourceids)$/i;\n\nexport function matchesAuditNodeReference(\n  value: unknown,\n  nodeId: string\n): boolean {\n  if (Array.isArray(value)) {\n    return value.some((entry) => matchesAuditNodeReference(entry, nodeId));\n  }\n\n  if (!value || typeof value !== \"object\") {\n    return false;\n  }\n\n  return Object.entries(value as Record<string, unknown>).some(([key, entry]) => {\n    if (\n      typeof entry === \"string\" &&\n      entry === nodeId &&\n      AUDIT_NODE_REFERENCE_KEY_PATTERN.test(key)\n    ) {\n      return true;\n    }\n\n    if (\n      Array.isArray(entry) &&\n      AUDIT_NODE_REFERENCE_KEY_PATTERN.test(key) &&\n      entry.some((item) => item === nodeId)\n    ) {\n      return true;\n    }\n\n    return matchesAuditNodeReference(entry, nodeId);\n  });\n}\n\nexport function requireText(args: {\n  text?: string;\n  canonicalText?: string;\n  formulation?: string;\n  newFormulation?: string;\n}): string {\n  const text = resolveText(args);\n  if (!text) {\n    throw new Error(\"text is required\");\n  }\n  return text;\n}\n\nexport function requireBaseRate(args: { baseRate?: number }): number {\n  const baseRate =\n    typeof args.baseRate === \"number\" && Number.isFinite(args.baseRate)\n      ? args.baseRate\n      : 0.5;\n  if (baseRate < 0 || baseRate > 1) {\n    throw new Error(\"baseRate must be within [0, 1].\");\n  }\n  return baseRate;\n}\n\nexport function sdkQueryString(input: Record<string, unknown>): string {\n  const params = new URLSearchParams();\n  for (const [key, value] of Object.entries(input)) {\n    if (value === undefined || value === null) {\n      continue;\n    }\n    if (Array.isArray(value)) {\n      if (value.length > 0) {\n        params.set(key, value.join(\",\"));\n      }\n      continue;\n    }\n    params.set(key, String(value));\n  }\n  const serialized = params.toString();\n  return serialized ? `?${serialized}` : \"\";\n}\n"]}

package/dist/contradictions/index.d.ts

@@ -54,6 +54,7 @@ import '../learningClient.js';
 import '../reportsClient.js';
 import '../sourcesClient.js';
 import '../workflowClient.js';
+import '../clientHelpers.js';
 
 type ContradictionsClientConfig = LucernClientConfig;
 type ContradictionsClient = ReturnType<typeof createContradictionsClient>;

package/dist/contradictions/index.js

@@ -6262,6 +6262,21 @@ function createSchemaClient(config = {}) {
 }
 
 // src/clientHelpers.ts
+function normalizeCustomNamespace(namespace) {
+  return namespace.trim() || "custom";
+}
+function normalizeCustomToolPayload(input) {
+  return input && typeof input === "object" && !Array.isArray(input) ? input : {};
+}
+function resolveCustomToolFullName(name) {
+  return name.includes(".") ? name : `custom.${name}`;
+}
+function buildBeliefsRefinePayload(textOrInput, rationale) {
+  return typeof textOrInput === "string" ? { text: textOrInput, rationale } : { text: textOrInput.text, rationale: textOrInput.rationale };
+}
+function buildBeliefsArchivePayload(input) {
+  return typeof input === "string" ? { reason: input } : input ? { reason: input.reason ?? input.rationale } : void 0;
+}
 function asNodeArray(data) {
   const rows = asListItems(data, "nodes");
   if (rows.length > 0) {
@@ -6639,7 +6654,7 @@ function createToolRegistryClient(config = {}) {
 }
 
 // src/version.ts
-var LUCERN_SDK_VERSION = "0.3.0-alpha.8";
+var LUCERN_SDK_VERSION = "0.3.0-alpha.9";
 
 // src/workflowClient.ts
 function normalizeLensQuery(value) {
@@ -7160,11 +7175,11 @@ function createLucernClient(config = {}) {
     }
   }
   const invokeCustomTool = async (fullName, input = {}) => {
-    const payload = input && typeof input === "object" && !Array.isArray(input) ? input : {};
+    const payload = normalizeCustomToolPayload(input);
     return invokeRegisteredCustomTool(fullName, payload, { source: "sdk" });
   };
   const getCustomNamespace = (namespace) => {
-    const normalized = namespace.trim() || "custom";
+    const normalized = normalizeCustomNamespace(namespace);
     const cached = customNamespaceCache.get(normalized);
     if (cached) {
       return cached;
@@ -7624,10 +7639,7 @@ function createLucernClient(config = {}) {
         return beliefsFacade.get(nodeId).then(exposeGatewayData);
       },
       refine(nodeId, textOrInput, rationale) {
-        const payload = typeof textOrInput === "string" ? { text: textOrInput, rationale } : {
-          text: textOrInput.text,
-          rationale: textOrInput.rationale
-        };
+        const payload = buildBeliefsRefinePayload(textOrInput, rationale);
         return beliefsFacade.refine(nodeId, payload).then(exposeGatewayData);
       },
       updateConfidence(nodeId, input) {
@@ -7665,7 +7677,7 @@ function createLucernClient(config = {}) {
         }).then(exposeGatewayData);
       },
       archive(nodeId, input) {
-        const payload = typeof input === "string" ? { reason: input } : input ? { reason: input.reason ?? input.rationale } : void 0;
+        const payload = buildBeliefsArchivePayload(input);
         return beliefsFacade.archive(nodeId, payload).then(exposeGatewayData);
       },
       list(args) {
@@ -8705,7 +8717,7 @@ function createLucernClient(config = {}) {
       list: listRegisteredCustomTools,
       clear: clearRegisteredCustomTools,
       invoke(name, input = {}) {
-        const fullName = name.includes(".") ? name : `custom.${name}`;
+        const fullName = resolveCustomToolFullName(name);
         return invokeCustomTool(fullName, input);
       },
       namespace: getCustomNamespace