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

package/{dist/lib/platform/sdk/answersClient.d.ts → src/answersClient.ts}

@@ -1,16 +1,29 @@
-import { type GatewayClientConfig } from "./coreClient";
+import {
+  createGatewayRequestClient,
+  type GatewayClientConfig,
+} from "./coreClient";
+
 /** Configuration for the answers client. */
 export type AnswersClientConfig = GatewayClientConfig;
+
 /**
  * Create the answers client for retrieving question answers.
  * @param config - Gateway transport configuration.
  * @returns An object with a `get` method to fetch the answer for a question.
  */
-export declare function createAnswersClient(config?: AnswersClientConfig): {
+export function createAnswersClient(config: AnswersClientConfig = {}) {
+  const gateway = createGatewayRequestClient(config);
+
+  return {
     /**
      * Get the current answer for a question.
      * @param questionId - The question node identifier.
      * @returns The answer record for the given question.
      */
-    get(questionId: string): Promise<import("./coreClient").PlatformGatewaySuccess<Record<string, unknown>>>;
-};
+    async get(questionId: string) {
+      return gateway.request<Record<string, unknown>>({
+        path: `/api/platform/v1/questions/${encodeURIComponent(questionId)}/answer`,
+      });
+    },
+  };
+}

package/src/audiencesClient.ts

@@ -0,0 +1,209 @@
+import {
+  createGatewayRequestClient,
+  type GatewayClientConfig,
+  type GatewayScope,
+  randomIdempotencyKey,
+  toQueryString,
+} from "./coreClient";
+import { createListResult, mapGatewayData } from "./sdkSurface";
+import type { JsonObject } from "./types";
+
+/** Configuration for the audiences client. */
+export type AudiencesClientConfig = GatewayClientConfig;
+
+/** Input for creating or updating an audience registry entry. */
+export type AudienceRegistryInput = GatewayScope & {
+  audienceKey: string;
+  audienceLabel: string;
+  audienceClass: "internal" | "restricted_external" | "public";
+  status?: "active" | "disabled" | "archived";
+  description?: string;
+  metadata?: JsonObject;
+};
+
+/** Input for creating an audience access grant. */
+export type AudienceGrantInput = GatewayScope & {
+  audienceKey: string;
+  audienceClass?: "internal" | "restricted_external" | "public";
+  principalId?: string;
+  groupId?: string;
+  expiresAt?: number;
+  metadata?: JsonObject;
+};
+
+/** Input for revoking an audience grant by its identifier. */
+export type AudienceGrantRevokeInput = GatewayScope & {
+  grantId: string;
+};
+
+/**
+ * Create the audiences client for registry entries and grants.
+ * @param config - Gateway transport configuration.
+ * @returns An object with methods to manage audience registry entries and grants.
+ */
+export function createAudiencesClient(config: AudiencesClientConfig = {}) {
+  const gateway = createGatewayRequestClient(config);
+
+  return {
+    /**
+     * List audience registry entries.
+     */
+    async listRegistry(
+      query: GatewayScope & {
+        effective?: boolean;
+        status?: "active" | "disabled" | "archived";
+      } = {}
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/audiences/registry${toQueryString({
+          ...query,
+          effective:
+            typeof query.effective === "boolean"
+              ? query.effective
+                ? "true"
+                : "false"
+              : undefined,
+          status: query.status,
+        })}`,
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          createListResult(
+            Array.isArray(data) ? data : [],
+            "registryEntries"
+          )
+        )
+      );
+    },
+
+    /**
+     * @deprecated Use listRegistry.
+     */
+    async getRegistry(
+      query: GatewayScope & {
+        effective?: boolean;
+        status?: "active" | "disabled" | "archived";
+      } = {}
+    ) {
+      return this.listRegistry(query);
+    },
+
+    /**
+     * Create an audience registry entry.
+     */
+    async createRegistryEntry(
+      input: AudienceRegistryInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: "/api/platform/v1/audiences/registry",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Update an audience registry entry.
+     */
+    async updateRegistryEntry(
+      input: AudienceRegistryInput,
+      idempotencyKey?: string
+    ) {
+      return this.createRegistryEntry(input, idempotencyKey);
+    },
+
+    /**
+     * @deprecated Use createRegistryEntry or updateRegistryEntry.
+     */
+    async upsertRegistry(
+      input: AudienceRegistryInput,
+      idempotencyKey?: string
+    ) {
+      return this.createRegistryEntry(input, idempotencyKey);
+    },
+
+    /**
+     * List audience grants.
+     */
+    async listGrants(
+      query: GatewayScope & {
+        audienceKey?: string;
+        principalId?: string;
+        groupId?: string;
+        status?: "active" | "revoked" | "expired";
+      } = {}
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/audiences/grants${toQueryString({
+          ...query,
+          audienceKey: query.audienceKey,
+          principalId: query.principalId,
+          groupId: query.groupId,
+          status: query.status,
+        })}`,
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          createListResult(Array.isArray(data) ? data : [], "grants")
+        )
+      );
+    },
+
+    /**
+     * @deprecated Use listGrants.
+     */
+    async getGrants(
+      query: GatewayScope & {
+        audienceKey?: string;
+        principalId?: string;
+        groupId?: string;
+        status?: "active" | "revoked" | "expired";
+      } = {}
+    ) {
+      return this.listGrants(query);
+    },
+
+    /**
+     * Create an audience grant.
+     */
+    async createGrant(input: AudienceGrantInput, idempotencyKey?: string) {
+      return gateway.request<unknown>({
+        path: "/api/platform/v1/audiences/grants",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * @deprecated Use createGrant.
+     */
+    async grant(input: AudienceGrantInput, idempotencyKey?: string) {
+      return this.createGrant(input, idempotencyKey);
+    },
+
+    /**
+     * Delete an audience grant by revoking it.
+     */
+    async deleteGrant(
+      input: AudienceGrantRevokeInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: "/api/platform/v1/audiences/grants/revoke",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * @deprecated Use deleteGrant.
+     */
+    async revokeGrant(
+      input: AudienceGrantRevokeInput,
+      idempotencyKey?: string
+    ) {
+      return this.deleteGrant(input, idempotencyKey);
+    },
+  };
+}

package/src/auditClient.ts

@@ -0,0 +1,50 @@
+import {
+  createGatewayRequestClient,
+  type GatewayClientConfig,
+  type GatewayScope,
+  LucernApiError,
+  toQueryString,
+} from "./coreClient";
+import { createListResult, mapGatewayData, normalizeTopicQuery } from "./sdkSurface";
+import type { TopicIdentifierInput } from "./types";
+
+export { LucernApiError };
+export type { GatewayScope, PlatformGatewaySuccess } from "./coreClient";
+
+/** Configuration for the audit client. */
+export type AuditClientConfig = GatewayClientConfig;
+
+/**
+ * Create the audit client for transport-level audit event reads.
+ * @param config - Gateway transport configuration.
+ * @returns An object with methods to list audit events.
+ */
+export function createAuditClient(config: AuditClientConfig = {}) {
+  const gateway = createGatewayRequestClient(config);
+
+  return {
+    /**
+     * List audit events for the current scope.
+     */
+    async listEvents(
+      query: GatewayScope & {
+        action?: string;
+        decision?: string;
+        traceId?: string;
+        principalId?: string;
+        topicId?: string;
+        limit?: number;
+      } & TopicIdentifierInput = {}
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/audit/events${toQueryString(
+          normalizeTopicQuery(query)
+        )}`,
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          createListResult(Array.isArray(data) ? data : [], "events")
+        )
+      );
+    },
+  };
+}

package/src/beliefsClient.ts

@@ -0,0 +1,319 @@
+import {
+  createGatewayRequestClient,
+  type GatewayClientConfig,
+  LucernApiError,
+  randomIdempotencyKey,
+} from "./coreClient";
+import { normalizeNodeWriteInput } from "./sdkSurface";
+import type {
+  CreateBeliefResponse,
+  ForkBeliefResponse,
+  JsonObject,
+  ModulateConfidenceResponse,
+} from "./types";
+
+export { LucernApiError };
+export type { PlatformGatewaySuccess } from "./coreClient";
+export type {
+  CreateBeliefResponse,
+  ForkBeliefResponse,
+  ModulateConfidenceResponse,
+} from "./types";
+
+/** Configuration for the beliefs client. Inherits gateway transport settings. */
+export type BeliefsClientConfig = GatewayClientConfig;
+
+/**
+ * Input for creating a new belief within a topic scope.
+ *
+ * Use `text` as the canonical belief statement.
+ * `canonicalText` remains available as a legacy alias for backwards compatibility.
+ * Beliefs start as unscored drafts and can be scored via confidence modulation.
+ */
+export type CreateBeliefInput = {
+  topicId?: string;
+  /** Preferred belief statement alias. */
+  text?: string;
+  /** @deprecated Use text. */
+  canonicalText?: string;
+  layer?: "L1" | "L2" | "L3" | "L4";
+  domain?: string;
+  sourceType?: "human" | "ai" | "agent" | "imported";
+  content?: string;
+  contentHash?: string;
+  globalId?: string;
+  title?: string;
+  subtype?: string;
+  confidence?: number;
+  tags?: string[];
+  metadata?: JsonObject;
+  verificationStatus?: "unverified" | "verified" | "rejected";
+};
+
+/**
+ * Input for recording a confidence change on a belief.
+ * Confidence modulation is append-only — each call adds a new credence history entry.
+ */
+export type ModulateConfidenceInput = {
+  confidence: number;
+  trigger?:
+    | "evidence_added"
+    | "evidence_removed"
+    | "contradiction_detected"
+    | "contradiction_resolved"
+    | "manual"
+    | "decay"
+    | "agent_assessment"
+    | "merge_outcome"
+    | "worktree_outcome"
+    | "worktree_completed";
+  rationale: string;
+  certainty?: number;
+};
+
+/**
+ * Input for forking a scored belief into a new formulation.
+ * Scored beliefs are immutable — fork to evolve understanding.
+ */
+export type ForkBeliefInput = {
+  newFormulation: string;
+  forkReason?:
+    | "refinement"
+    | "contradiction_response"
+    | "scope_change"
+    | "confidence_collapse"
+    | "manual";
+  rationale?: string;
+};
+
+/** Input for changing a belief's lifecycle status. */
+export type UpdateBeliefStatusInput = {
+  id?: string;
+  nodeId?: string;
+  beliefId?: string;
+  status: "active" | "superseded" | "archived";
+  reason?: string;
+};
+
+/** Input for updating a belief's rationale without refining its text. */
+export type UpdateBeliefRationaleInput = {
+  id?: string;
+  nodeId?: string;
+  beliefId?: string;
+  rationale?: string;
+};
+
+/** Input for creating a belief-to-belief reasoning edge. */
+export type LinkBeliefsInput = {
+  fromNodeId: string;
+  toNodeId: string;
+  edgeType: string;
+  weight?: number;
+  context?: string;
+};
+
+/** Input for unlinking a belief from an attached evidence item. */
+export type UnlinkBeliefEvidenceInput = {
+  beliefNodeId?: string;
+  beliefId?: string;
+  nodeId?: string;
+  insightId?: string;
+  evidenceId?: string;
+};
+
+/** Input for updating a belief's criticality classification. */
+export type UpdateBeliefCriticalityInput = {
+  id?: string;
+  nodeId?: string;
+  beliefId?: string;
+  criticality:
+    | "blocking"
+    | "important"
+    | "supporting"
+    | "essential"
+    | "nice_to_have";
+};
+
+/** Input for bulk-updating multiple beliefs' criticality. */
+export type BatchUpdateBeliefCriticalityInput = {
+  updates: Array<{
+    beliefId: string;
+    criticality:
+      | "blocking"
+      | "important"
+      | "supporting"
+      | "essential"
+      | "nice_to_have";
+    ifFalseImpact?: string;
+    triagePriority?: number;
+    reasoning?: string;
+    dependentBeliefIds?: string[];
+    blockedByBeliefIds?: string[];
+  }>;
+};
+
+/** Input for moving beliefs into a different topic scope. */
+export type ReassignBeliefsTopicInput = {
+  beliefNodeIds?: string[];
+  beliefIds?: string[];
+  targetTopicId: string;
+  reason?: string;
+};
+
+/**
+ * Create the beliefs client for belief lifecycle operations.
+ *
+ * @param config - Gateway transport configuration.
+ * @returns An object with `createBelief`, `modulateConfidence`, and `forkBelief` methods.
+ */
+export function createBeliefsClient(config: BeliefsClientConfig = {}) {
+  const gateway = createGatewayRequestClient(config);
+
+  return {
+    /**
+     * Create a belief within a topic scope.
+     */
+    async createBelief(input: CreateBeliefInput, idempotencyKey?: string) {
+      return gateway.request<CreateBeliefResponse>({
+        path: "/api/platform/v1/beliefs",
+        method: "POST",
+        body: normalizeNodeWriteInput(input),
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Record a confidence change for an existing belief.
+     */
+    async modulateConfidence(
+      beliefId: string,
+      input: ModulateConfidenceInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<ModulateConfidenceResponse>({
+        path: `/api/platform/v1/beliefs/${encodeURIComponent(beliefId)}/confidence`,
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Fork a scored belief into a new formulation.
+     */
+    async forkBelief(
+      beliefId: string,
+      input: ForkBeliefInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<ForkBeliefResponse>({
+        path: `/api/platform/v1/beliefs/${encodeURIComponent(beliefId)}/fork`,
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Update a belief's lifecycle status.
+     */
+    async updateBeliefStatus(
+      input: UpdateBeliefStatusInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<Record<string, unknown>>({
+        path: "/api/platform/v1/beliefs/update-status",
+        method: "POST",
+        body: input as JsonObject,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Update a belief's rationale without changing its text.
+     */
+    async updateBeliefRationale(
+      input: UpdateBeliefRationaleInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<Record<string, unknown>>({
+        path: "/api/platform/v1/beliefs/update-rationale",
+        method: "POST",
+        body: input as JsonObject,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Create a typed relationship between two beliefs.
+     */
+    async linkBeliefs(input: LinkBeliefsInput, idempotencyKey?: string) {
+      return gateway.request<Record<string, unknown>>({
+        path: "/api/platform/v1/beliefs/link",
+        method: "POST",
+        body: input as JsonObject,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Remove an evidence attachment from a belief.
+     */
+    async unlinkBeliefEvidence(
+      input: UnlinkBeliefEvidenceInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<Record<string, unknown>>({
+        path: "/api/platform/v1/beliefs/unlink-evidence",
+        method: "POST",
+        body: input as JsonObject,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Update a belief's criticality metadata.
+     */
+    async updateBeliefCriticality(
+      input: UpdateBeliefCriticalityInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<Record<string, unknown>>({
+        path: "/api/platform/v1/beliefs/update-criticality",
+        method: "POST",
+        body: input as JsonObject,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Update multiple beliefs' criticality in one mutation.
+     */
+    async batchUpdateBeliefCriticality(
+      input: BatchUpdateBeliefCriticalityInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<Record<string, unknown>>({
+        path: "/api/platform/v1/beliefs/batch-update-criticality",
+        method: "POST",
+        body: input as JsonObject,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Reassign beliefs to a different topic scope.
+     */
+    async reassignBeliefsTopic(
+      input: ReassignBeliefsTopicInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<Record<string, unknown>>({
+        path: "/api/platform/v1/beliefs/reassign-topic",
+        method: "POST",
+        body: input as JsonObject,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+  };
+}