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

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

@@ -2,13 +2,16 @@ import { type GatewayClientConfig, type GatewayScope, LucernApiError } from "./c
 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";
@@ -19,6 +22,8 @@ export type SchemaEntitlementInput = GatewayScope & {
 };
 /**
  * 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 declare function createSchemaClient(config?: SchemaClientConfig): {
     /**

package/dist/lib/platform/sdk/schemaClient.js

@@ -0,0 +1,71 @@
+import { createGatewayRequestClient, LucernApiError, randomIdempotencyKey, toQueryString, } from "./coreClient.js";
+import { createListResult, mapGatewayData } from "./sdkSurface.js";
+export { LucernApiError };
+/**
+ * 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 = {}) {
+    const gateway = createGatewayRequestClient(config);
+    return {
+        /**
+         * List schema packs.
+         */
+        async listPacks(scope = {}) {
+            return gateway.request({
+                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, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/schema/packs",
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Get a schema pack by identifier.
+         */
+        async getPack(packId, scope = {}) {
+            return gateway.request({
+                path: `/api/platform/v1/schema/packs/${encodeURIComponent(packId)}${toQueryString(scope)}`,
+            });
+        },
+        /**
+         * List schema entitlements.
+         */
+        async listEntitlements(scope = {}) {
+            return gateway.request({
+                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, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/schema/entitlements",
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Update a schema entitlement.
+         */
+        async updateEntitlement(input, idempotencyKey) {
+            return this.createEntitlement(input, idempotencyKey);
+        },
+        /**
+         * @deprecated Use createEntitlement or updateEntitlement.
+         */
+        async upsertEntitlement(input, idempotencyKey) {
+            return this.createEntitlement(input, idempotencyKey);
+        },
+    };
+}

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

@@ -32,6 +32,7 @@ export declare function withSdkAliases<T extends AnyRecord>(value: T): T;
  * Normalize a belief/question/evidence write payload to the canonical gateway shape.
  */
 export declare function normalizeNodeWriteInput<T extends JsonObject>(value: T): T;
+export declare function normalizeNodeVerificationStatus(value: unknown): string | undefined;
 /**
  * Build a topic-aware query object.
  */

package/dist/lib/platform/sdk/sdkSurface.js

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

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

@@ -1,12 +1,15 @@
 import { type GatewayClientConfig } from "./coreClient";
 import type { JsonObject, TopicCoverageResponse, TopicIdentifierInput, TopicListResponse, TopicRecord, 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;
@@ -19,6 +22,7 @@ export type TopicCreateInput = TopicIdentifierInput & {
     createdBy?: string;
     metadata?: JsonObject;
 };
+/** Input for updating an existing topic's metadata. All fields are optional. */
 export type TopicUpdateInput = TopicIdentifierInput & {
     name?: string;
     description?: string;
@@ -28,13 +32,40 @@ export type TopicUpdateInput = TopicIdentifierInput & {
     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;
+    }>;
+};
+/**
+ * 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 declare function createTopicsClient(config?: TopicsClientConfig): {
     list(query?: TopicListInput): Promise<import("./coreClient").PlatformGatewaySuccess<TopicListResponse>>;
     get(topicId: string): Promise<import("./coreClient").PlatformGatewaySuccess<TopicRecord>>;
@@ -42,4 +73,6 @@ export declare function createTopicsClient(config?: TopicsClientConfig): {
     update(topicId: string, input: TopicUpdateInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<TopicRecord>>;
     getTree(topicId: string, query?: TopicTreeQuery): Promise<import("./coreClient").PlatformGatewaySuccess<TopicTreeResponse>>;
     getCoverage(topicId: string, query?: TopicCoverageQuery): Promise<import("./coreClient").PlatformGatewaySuccess<TopicCoverageResponse>>;
+    remove(topicId: string, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<Record<string, unknown>>>;
+    bulkCreate(input: TopicBulkCreateInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<Record<string, unknown>>>;
 };

package/dist/lib/platform/sdk/topicsClient.js

@@ -0,0 +1,118 @@
+import { createGatewayRequestClient, randomIdempotencyKey, toQueryString, } from "./coreClient.js";
+import { createListResult, mapGatewayData, resolveTopicId, withTopicAlias, } from "./sdkSurface.js";
+function asRecord(value) {
+    return value && typeof value === "object"
+        ? value
+        : {};
+}
+function cleanString(value) {
+    return typeof value === "string" && value.trim().length > 0
+        ? value.trim()
+        : undefined;
+}
+function normalizeTopicRecord(value) {
+    const record = asRecord(value);
+    const topicId = cleanString(record.topicId) ??
+        cleanString(record.id) ??
+        cleanString(record._id);
+    return withTopicAlias({
+        ...record,
+        ...(topicId ? { topicId } : {}),
+    });
+}
+function normalizeTopicTreeNode(value) {
+    return normalizeTopicRecord(value);
+}
+/**
+ * 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 = {}) {
+    const gateway = createGatewayRequestClient(config);
+    return {
+        async list(query = {}) {
+            const topicId = resolveTopicId(query);
+            return gateway.request({
+                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,
+                };
+            }));
+        },
+        async get(topicId) {
+            return gateway.request({
+                path: `/api/platform/v1/topics/${encodeURIComponent(topicId)}`,
+            }).then((response) => mapGatewayData(response, (data) => normalizeTopicRecord(asRecord(data).topic ?? data)));
+        },
+        async create(input, idempotencyKey) {
+            const topicId = resolveTopicId(input);
+            return gateway.request({
+                path: "/api/platform/v1/topics",
+                method: "POST",
+                body: {
+                    ...input,
+                    ...(topicId ? { topicId } : {}),
+                    type: input.type ?? "theme",
+                },
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            }).then((response) => mapGatewayData(response, (data) => normalizeTopicRecord(data)));
+        },
+        async update(topicId, input, idempotencyKey) {
+            return gateway.request({
+                path: `/api/platform/v1/topics/${encodeURIComponent(topicId)}`,
+                method: "PATCH",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            }).then((response) => mapGatewayData(response, (data) => normalizeTopicRecord(data)));
+        },
+        async getTree(topicId, query = {}) {
+            return gateway.request({
+                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)
+                        : [],
+                };
+            }));
+        },
+        async getCoverage(topicId, query = {}) {
+            return gateway.request({
+                path: `/api/platform/v1/topics/${encodeURIComponent(topicId)}/coverage${toQueryString(query)}`,
+            });
+        },
+        async remove(topicId, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/topics/remove",
+                method: "POST",
+                body: { id: topicId },
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        async bulkCreate(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/topics/bulk",
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+    };
+}