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

package/src/reportsClient.ts

@@ -0,0 +1,99 @@
+import {
+  createGatewayRequestClient,
+  type GatewayClientConfig,
+  toQueryString,
+} from "./coreClient";
+import { createListResult, mapGatewayData, resolveTopicId } from "./sdkSurface";
+import type {
+  TopicIdentifierInput,
+  ProjectReportsResponse,
+  ReportTemplatesResponse,
+  ReportWithSectionsResponse,
+} from "./types";
+
+/** Configuration for the reports client. */
+export type ReportsClientConfig = GatewayClientConfig;
+export type {
+  ProjectReportsResponse,
+  ReportTemplatesResponse,
+  ReportWithSectionsResponse,
+} from "./types";
+
+/**
+ * Create the reports client for report templates and generated reports.
+ * @param config - Gateway transport configuration.
+ * @returns An object with methods to list templates, list reports, and get a report.
+ */
+export function createReportsClient(config: ReportsClientConfig = {}) {
+  const gateway = createGatewayRequestClient(config);
+
+  return {
+    /**
+     * List report templates.
+     */
+    async listTemplates(args: { slug?: string } = {}) {
+      return gateway.request<ReportTemplatesResponse>({
+        path: `/api/platform/v1/reports/templates${toQueryString({
+          slug: args.slug,
+        })}`,
+      }).then((response) =>
+        mapGatewayData(response, (data) => {
+          const record =
+            data && typeof data === "object"
+              ? (data as Record<string, unknown>)
+              : {};
+          const rows = Array.isArray(data)
+            ? data
+            : Array.isArray(record.templates)
+              ? record.templates
+              : [];
+          return createListResult(rows, "templates") as ReportTemplatesResponse;
+        })
+      );
+    },
+
+    /**
+     * @deprecated Use listTemplates.
+     */
+    async getTemplates(args: { slug?: string } = {}) {
+      return this.listTemplates(args);
+    },
+
+    /**
+     * List reports for a topic scope.
+     */
+    async listReports(
+      input: TopicIdentifierInput,
+      args: { summary?: boolean } = {}
+    ) {
+      const topicId = resolveTopicId(input);
+      if (!topicId) {
+        throw new Error("topicId is required");
+      }
+      return gateway.request<ProjectReportsResponse>({
+        path: `/api/platform/v1/reports/topics/${encodeURIComponent(topicId)}${toQueryString(
+          {
+            summary:
+              typeof args.summary === "boolean"
+                ? args.summary
+                  ? "true"
+                  : "false"
+                : undefined,
+          }
+        )}`,
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          createListResult(Array.isArray(data) ? data : [], "reports")
+        )
+      );
+    },
+    /**
+     * Get a generated report.
+     */
+    async getReport(reportId: string) {
+      return gateway.request<ReportWithSectionsResponse>({
+        path: `/api/platform/v1/reports/${encodeURIComponent(reportId)}`,
+      });
+    },
+  };
+}

package/src/schemaClient.ts

@@ -0,0 +1,129 @@
+import {
+  createGatewayRequestClient,
+  type GatewayClientConfig,
+  type GatewayScope,
+  LucernApiError,
+  randomIdempotencyKey,
+  toQueryString,
+} from "./coreClient";
+import { createListResult, mapGatewayData } from "./sdkSurface";
+import type { JsonObject } from "./types";
+
+export { LucernApiError };
+export type { GatewayScope, PlatformGatewaySuccess } from "./coreClient";
+
+/** Configuration for the schema client. */
+export type SchemaClientConfig = GatewayClientConfig;
+
+/** Input for installing a schema pack into a tenant scope. */
+export type SchemaPackInstallInput = GatewayScope & {
+  packKey: string;
+  version?: string;
+  autoEnable?: boolean;
+  metadata?: JsonObject;
+};
+
+/** Input for creating or updating a schema entitlement record. */
+export type SchemaEntitlementInput = GatewayScope & {
+  packKey: string;
+  status: "active" | "disabled" | "revoked";
+  allowedLifecycles?: Array<"active" | "beta" | "experimental">;
+  minVersion?: string;
+  maxVersion?: string;
+  metadata?: JsonObject;
+};
+
+/**
+ * Create the schema client for pack catalog and entitlement operations.
+ * @param config - Gateway transport configuration.
+ * @returns An object with methods to manage schema packs and entitlements.
+ */
+export function createSchemaClient(config: SchemaClientConfig = {}) {
+  const gateway = createGatewayRequestClient(config);
+
+  return {
+    /**
+     * List schema packs.
+     */
+    async listPacks(scope: GatewayScope = {}) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/schema/packs${toQueryString(scope)}`,
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          createListResult(Array.isArray(data) ? data : [], "packs")
+        )
+      );
+    },
+
+    /**
+     * Install a schema pack.
+     */
+    async installPack(input: SchemaPackInstallInput, idempotencyKey?: string) {
+      return gateway.request<unknown>({
+        path: "/api/platform/v1/schema/packs",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Get a schema pack by identifier.
+     */
+    async getPack(packId: string, scope: GatewayScope = {}) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/schema/packs/${encodeURIComponent(packId)}${toQueryString(
+          scope
+        )}`,
+      });
+    },
+
+    /**
+     * List schema entitlements.
+     */
+    async listEntitlements(scope: GatewayScope & { packKey?: string } = {}) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/schema/entitlements${toQueryString(scope)}`,
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          createListResult(Array.isArray(data) ? data : [], "entitlements")
+        )
+      );
+    },
+
+    /**
+     * Create a schema entitlement.
+     */
+    async createEntitlement(
+      input: SchemaEntitlementInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: "/api/platform/v1/schema/entitlements",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Update a schema entitlement.
+     */
+    async updateEntitlement(
+      input: SchemaEntitlementInput,
+      idempotencyKey?: string
+    ) {
+      return this.createEntitlement(input, idempotencyKey);
+    },
+
+    /**
+     * @deprecated Use createEntitlement or updateEntitlement.
+     */
+    async upsertEntitlement(
+      input: SchemaEntitlementInput,
+      idempotencyKey?: string
+    ) {
+      return this.createEntitlement(input, idempotencyKey);
+    },
+  };
+}

package/src/sdkSurface.ts

@@ -0,0 +1,190 @@
+import type { PlatformGatewaySuccess } from "./coreClient";
+import type { JsonObject, ListResult } from "./types";
+
+type TopicScopedValue = {
+  topicId?: string;
+};
+
+type TextScopedValue = {
+  text?: string;
+  canonicalText?: string;
+};
+
+type AnyRecord = Record<string, unknown>;
+
+function asRecord(value: unknown): AnyRecord {
+  return value && typeof value === "object" ? (value as AnyRecord) : {};
+}
+
+function cleanString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0
+    ? value.trim()
+    : undefined;
+}
+
+function normalizeVerificationStatus(value: unknown): string | undefined {
+  const status = cleanString(value);
+  if (!status) {
+    return undefined;
+  }
+  if (status === "verified") {
+    return "human_verified";
+  }
+  if (status === "rejected") {
+    return "contradicted";
+  }
+  return status;
+}
+
+function cloneWith<T extends AnyRecord>(value: T, patch: AnyRecord): T {
+  return { ...value, ...patch } as T;
+}
+
+/**
+ * Resolve the canonical topic identifier.
+ */
+export function resolveTopicId(value: TopicScopedValue): string | undefined {
+  return cleanString(value.topicId);
+}
+
+/**
+ * Resolve the canonical text field from text-first or legacy canonicalText-first inputs.
+ */
+export function resolveText(value: TextScopedValue): string | undefined {
+  return cleanString(value.text) ?? cleanString(value.canonicalText);
+}
+
+/**
+ * Attach the topicId to a record.
+ */
+export function withTopicAlias<T extends AnyRecord>(value: T): T {
+  const topicId = cleanString(value.topicId) ?? undefined;
+  if (!topicId) {
+    return value;
+  }
+  return cloneWith(value, { topicId });
+}
+
+/**
+ * Attach the text/canonicalText alias pair to a record.
+ */
+export function withTextAlias<T extends AnyRecord>(value: T): T {
+  const text =
+    cleanString(value.text) ?? cleanString(value.canonicalText) ?? undefined;
+  if (!text) {
+    return value;
+  }
+  return cloneWith(value, { text, canonicalText: text });
+}
+
+/**
+ * Attach topic and text aliases to SDK node-like records.
+ */
+export function withSdkAliases<T extends AnyRecord>(value: T): T {
+  return withTopicAlias(withTextAlias(value));
+}
+
+/**
+ * Normalize a belief/question/evidence write payload to the canonical gateway shape.
+ */
+export function normalizeNodeWriteInput<T extends JsonObject>(value: T): T {
+  const topicId = resolveTopicId(value);
+  const text = resolveText(value);
+  const verificationStatus = normalizeVerificationStatus(value.verificationStatus);
+  const next = { ...value } as JsonObject;
+
+  if (topicId) {
+    next.topicId = topicId;
+  }
+  if (text) {
+    next.text = text;
+    next.canonicalText = text;
+  }
+  if (verificationStatus) {
+    next.verificationStatus = verificationStatus;
+  }
+
+  return next as T;
+}
+
+export function normalizeNodeVerificationStatus(value: unknown) {
+  return normalizeVerificationStatus(value);
+}
+
+/**
+ * Build a topic-aware query object.
+ */
+export function normalizeTopicQuery<T extends JsonObject>(value: T): T {
+  const topicId = cleanString(value.topicId);
+  if (!topicId) {
+    return value;
+  }
+  return { ...value, topicId } as T;
+}
+
+/**
+ * Extract list items from array or list-envelope payloads.
+ */
+export function asListItems<T>(data: unknown, legacyKey?: string): T[] {
+  if (Array.isArray(data)) {
+    return data as T[];
+  }
+
+  const record = asRecord(data);
+  if (Array.isArray(record.items)) {
+    return record.items as T[];
+  }
+  if (legacyKey && Array.isArray(record[legacyKey])) {
+    return record[legacyKey] as T[];
+  }
+
+  return [];
+}
+
+/**
+ * Standardize list data to { items, total } while retaining an optional legacy array key.
+ */
+export function createListResult<T, LegacyKey extends string>(
+  items: T[],
+  legacyKey?: LegacyKey
+): ListResult<T, LegacyKey> {
+  const result = {
+    items,
+    total: items.length,
+  } as ListResult<T, LegacyKey>;
+
+  if (legacyKey) {
+    (result as Record<string, unknown>)[legacyKey] = items;
+  }
+
+  return result;
+}
+
+/**
+ * Map a gateway success envelope's data while preserving the transport metadata.
+ */
+export function mapGatewayData<T, U>(
+  response: PlatformGatewaySuccess<T>,
+  mapper: (data: T) => U
+): PlatformGatewaySuccess<U> {
+  return {
+    ...response,
+    data: mapper(response.data),
+  };
+}
+
+/**
+ * Apply SDK aliases across all items in a list-like payload.
+ */
+export function mapAliasedList<
+  TItem extends AnyRecord,
+  LegacyKey extends string,
+>(
+  data: unknown,
+  legacyKey?: LegacyKey
+): ListResult<TItem, LegacyKey> {
+  const items = asListItems<TItem>(data, legacyKey).map((item) =>
+    withSdkAliases(item)
+  );
+  return createListResult(items, legacyKey);
+}

package/src/topicsClient.ts

@@ -0,0 +1,243 @@
+import {
+  createGatewayRequestClient,
+  type GatewayClientConfig,
+  randomIdempotencyKey,
+  toQueryString,
+} from "./coreClient";
+import {
+  createListResult,
+  mapGatewayData,
+  resolveTopicId,
+  withTopicAlias,
+} from "./sdkSurface";
+import type {
+  JsonObject,
+  TopicCoverageResponse,
+  TopicIdentifierInput,
+  TopicListResponse,
+  TopicRecord,
+  TopicTreeNode,
+  TopicTreeResponse,
+} from "./types";
+
+/** Configuration for the topics client. Inherits gateway transport settings. */
+export type TopicsClientConfig = GatewayClientConfig;
+
+/** Filters for listing topics within a scope. */
+export type TopicListInput = TopicIdentifierInput & {
+  ontologyId?: string;
+  parentTopicId?: string;
+  status?: string;
+  type?: string;
+};
+
+/** Input for creating a new topic. Name is required; all other fields are optional. */
+export type TopicCreateInput = TopicIdentifierInput & {
+  name: string;
+  description?: string;
+  type?: string;
+  parentTopicId?: string;
+  ontologyId?: string;
+  tenantId?: string;
+  workspaceId?: string;
+  visibility?: "private" | "team" | "firm" | "external" | "public";
+  createdBy?: string;
+  metadata?: JsonObject;
+};
+
+/** Input for updating an existing topic's metadata. All fields are optional. */
+export type TopicUpdateInput = TopicIdentifierInput & {
+  name?: string;
+  description?: string;
+  type?: string;
+  ontologyId?: string;
+  clearOntologyId?: boolean;
+  status?: "active" | "archived" | "watching";
+  visibility?: "private" | "team" | "firm" | "external" | "public";
+};
+
+/** Options for retrieving the topic hierarchy. */
+export type TopicTreeQuery = {
+  maxDepth?: number;
+};
+
+/** Options for retrieving belief/question/evidence coverage across a topic tree. */
+export type TopicCoverageQuery = {
+  includeDescendants?: boolean;
+  maxDepth?: number;
+};
+
+/** Input for batch-creating topics. */
+export type TopicBulkCreateInput = {
+  topics: Array<
+    TopicIdentifierInput & {
+      globalId?: string;
+      name: string;
+      description?: string;
+      type: string;
+      parentTopicId?: string;
+      depth?: number;
+      path?: string[];
+      tenantId?: string;
+      workspaceId?: string;
+      graphScopeProjectId?: string;
+      status?: "active" | "archived" | "watching";
+      visibility?: "private" | "team" | "firm" | "external" | "public";
+      metadata?: JsonObject;
+      createdBy?: string;
+    }
+  >;
+};
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object"
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function cleanString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0
+    ? value.trim()
+    : undefined;
+}
+
+function normalizeTopicRecord(value: unknown): TopicRecord {
+  const record = asRecord(value);
+  const topicId =
+    cleanString(record.topicId) ??
+    cleanString(record.id) ??
+    cleanString(record._id);
+
+  return withTopicAlias({
+    ...record,
+    ...(topicId ? { topicId } : {}),
+  }) as TopicRecord;
+}
+
+function normalizeTopicTreeNode(value: unknown): TopicTreeNode {
+  return normalizeTopicRecord(value) as TopicTreeNode;
+}
+
+/**
+ * Create the topics client for managing hierarchical knowledge containers.
+ *
+ * @param config - Gateway transport configuration.
+ * @returns An object with `list`, `get`, `create`, `update`, `getTree`, and `getCoverage` methods.
+ */
+export function createTopicsClient(config: TopicsClientConfig = {}) {
+  const gateway = createGatewayRequestClient(config);
+
+  return {
+    async list(query: TopicListInput = {}) {
+      const topicId = resolveTopicId(query);
+      return gateway.request<TopicListResponse>({
+        path: `/api/platform/v1/topics${toQueryString({
+          ...(topicId ? { topicId } : {}),
+          ontologyId: query.ontologyId,
+          parentTopicId: query.parentTopicId,
+          status: query.status,
+          type: query.type,
+        })}`,
+      }).then((response) =>
+        mapGatewayData(response, (data) => {
+          const record = asRecord(data);
+          const items = Array.isArray(record.topics)
+            ? record.topics.map(normalizeTopicRecord)
+            : [];
+
+          return {
+            ...createListResult(items, "topics"),
+            ...record,
+            topics: items,
+            total:
+              typeof record.total === "number" ? record.total : items.length,
+          } as TopicListResponse;
+        })
+      );
+    },
+
+    async get(topicId: string) {
+      return gateway.request<TopicRecord>({
+        path: `/api/platform/v1/topics/${encodeURIComponent(topicId)}`,
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          normalizeTopicRecord(asRecord(data).topic ?? data)
+        )
+      );
+    },
+
+    async create(input: TopicCreateInput, idempotencyKey?: string) {
+      const topicId = resolveTopicId(input);
+      return gateway.request<TopicRecord>({
+        path: "/api/platform/v1/topics",
+        method: "POST",
+        body: {
+          ...input,
+          ...(topicId ? { topicId } : {}),
+          type: input.type ?? "theme",
+        } as JsonObject,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      }).then((response) =>
+        mapGatewayData(response, (data) => normalizeTopicRecord(data))
+      );
+    },
+
+    async update(
+      topicId: string,
+      input: TopicUpdateInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<TopicRecord>({
+        path: `/api/platform/v1/topics/${encodeURIComponent(topicId)}`,
+        method: "PATCH",
+        body: input as JsonObject,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      }).then((response) =>
+        mapGatewayData(response, (data) => normalizeTopicRecord(data))
+      );
+    },
+
+    async getTree(topicId: string, query: TopicTreeQuery = {}) {
+      return gateway.request<TopicTreeResponse>({
+        path: `/api/platform/v1/topics/${encodeURIComponent(topicId)}/tree${toQueryString(
+          query
+        )}`,
+      }).then((response) =>
+        mapGatewayData(response, (data) => {
+          const record = asRecord(data);
+          return {
+            tree: Array.isArray(record.tree)
+              ? record.tree.map(normalizeTopicTreeNode)
+              : [],
+          } as TopicTreeResponse;
+        })
+      );
+    },
+
+    async getCoverage(topicId: string, query: TopicCoverageQuery = {}) {
+      return gateway.request<TopicCoverageResponse>({
+        path: `/api/platform/v1/topics/${encodeURIComponent(topicId)}/coverage${toQueryString(
+          query
+        )}`,
+      });
+    },
+
+    async remove(topicId: string, idempotencyKey?: string) {
+      return gateway.request<Record<string, unknown>>({
+        path: "/api/platform/v1/topics/remove",
+        method: "POST",
+        body: { id: topicId },
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    async bulkCreate(input: TopicBulkCreateInput, idempotencyKey?: string) {
+      return gateway.request<Record<string, unknown>>({
+        path: "/api/platform/v1/topics/bulk",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+  };
+}