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

package/src/reportsClient.ts

@@ -1,99 +0,0 @@
-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

@@ -1,129 +0,0 @@
-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

@@ -1,190 +0,0 @@
-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

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