@lucern/sdk 0.2.0-alpha.1

package/dist/packages/sdk/src/mcpParitySurface.d.ts

@@ -0,0 +1,8 @@
+export type McpParityMethod = {
+    toolName: string;
+    methodPath: string;
+    kind: "read" | "mutation";
+};
+export declare const SDK_MCP_PARITY_METHODS: readonly McpParityMethod[];
+export declare const SDK_MCP_PARITY_METHOD_PATHS: string[];
+export declare const SDK_MCP_PARITY_TOOL_NAMES: string[];

package/dist/packages/sdk/src/ontologyClient.d.ts

@@ -0,0 +1,115 @@
+import { type GatewayClientConfig, type GatewayScope } from "./coreClient";
+import type { JsonObject } from "./types";
+export type OntologyClientConfig = GatewayClientConfig;
+export type OntologyBindingInput = GatewayScope & {
+    ontologyId: string;
+    topicId: string;
+};
+export type OntologyDefinitionInput = GatewayScope & {
+    ontologyKey: string;
+    name: string;
+    description?: string;
+    tenantId?: string;
+    tier?: "platform" | "pack" | "tenant";
+};
+export type OntologyDefinitionUpdateInput = GatewayScope & {
+    name?: string;
+    description?: string;
+    status?: "draft" | "active" | "deprecated";
+};
+export type OntologyVersionInput = GatewayScope & {
+    version: string;
+    entityTypes: Array<{
+        value: string;
+        label: string;
+        description?: string;
+        schema?: JsonObject;
+        subtypes?: Array<{
+            value: string;
+            label: string;
+            description?: string;
+        }>;
+    }>;
+    edgeTypes: Array<{
+        value: string;
+        label: string;
+        description?: string;
+        sourceTypes?: string[];
+        targetTypes?: string[];
+        constraintSeverity?: "warn" | "info";
+    }>;
+    releaseNotes?: string;
+};
+/**
+ * Create the ontology client for ontology definitions and versions.
+ */
+export declare function createOntologyClient(config?: OntologyClientConfig): {
+    list(filters?: GatewayScope & {
+        tenantId?: string;
+        tier?: string;
+        status?: string;
+    }): Promise<import("./coreClient").PlatformGatewaySuccess<{
+        ontologies: any[];
+        total: number;
+        items: any[];
+        definitions: any[];
+    }>>;
+    get(id: string): Promise<import("./coreClient").PlatformGatewaySuccess<unknown>>;
+    bind(input: OntologyBindingInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<unknown>>;
+    /**
+     * List ontology definitions.
+     */
+    listDefinitions(filters?: GatewayScope & {
+        tenantId?: string;
+        tier?: string;
+        status?: string;
+    }): Promise<import("./coreClient").PlatformGatewaySuccess<{
+        ontologies: any[];
+        total: number;
+        items: any[];
+        definitions: any[];
+    }>>;
+    /**
+     * Get an ontology definition.
+     */
+    getDefinition(id: string): Promise<import("./coreClient").PlatformGatewaySuccess<unknown>>;
+    /**
+     * Create an ontology definition.
+     */
+    createDefinition(input: OntologyDefinitionInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<unknown>>;
+    /**
+     * Update an ontology definition.
+     */
+    updateDefinition(id: string, input: OntologyDefinitionUpdateInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<unknown>>;
+    /**
+     * Archive an ontology definition.
+     */
+    archiveDefinition(id: string, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<unknown>>;
+    /**
+     * List versions for an ontology definition.
+     */
+    listVersions(ontologyId: string, filters?: GatewayScope & {
+        status?: string;
+    }): Promise<import("./coreClient").PlatformGatewaySuccess<import("./types").ListResult<any, "versions">>>;
+    /**
+     * Create an ontology version.
+     */
+    createVersion(ontologyId: string, input: OntologyVersionInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<unknown>>;
+    /**
+     * Publish an ontology version.
+     */
+    publishVersion(ontologyId: string, versionId: string, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<unknown>>;
+    /**
+     * Deprecate an ontology version.
+     */
+    deprecateVersion(ontologyId: string, versionId: string, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<unknown>>;
+    /**
+     * List topics directly bound to a specific ontology definition.
+     * Uses the topics gateway with ontologyId filter.
+     */
+    listTopics(ontologyId: string): Promise<import("./coreClient").PlatformGatewaySuccess<import("./types").ListResult<any, "topics">>>;
+    /**
+     * @deprecated Use listTopics.
+     */
+    listTopicsByOntology(ontologyId: string): Promise<import("./coreClient").PlatformGatewaySuccess<import("./types").ListResult<any, "topics">>>;
+};

package/dist/packages/sdk/src/packsClient.d.ts

@@ -0,0 +1,101 @@
+import { type GatewayClientConfig, type GatewayScope, LucernApiError } from "./coreClient";
+import type { JsonObject } from "./types";
+export { LucernApiError };
+export type { GatewayScope, PlatformGatewaySuccess } from "./coreClient";
+export type PacksClientConfig = GatewayClientConfig;
+export type PackInstallInput = GatewayScope & {
+    packKey: string;
+    version?: string;
+    autoEnable?: boolean;
+    metadata?: JsonObject;
+};
+export type PackEnableInput = GatewayScope & {
+    packKey: string;
+    metadata?: JsonObject;
+};
+export type PackDisableInput = GatewayScope & {
+    packKey: string;
+    force?: boolean;
+    metadata?: JsonObject;
+};
+export type PackUpgradeInput = GatewayScope & {
+    packKey: string;
+    mode: "prepare" | "canary" | "commit" | "rollback";
+    targetVersion?: string;
+    metadata?: JsonObject;
+};
+export type PackEntitlementInput = GatewayScope & {
+    packKey: string;
+    status: "active" | "disabled" | "revoked";
+    allowedLifecycles?: Array<"active" | "beta" | "experimental">;
+    minVersion?: string;
+    maxVersion?: string;
+    metadata?: JsonObject;
+};
+/**
+ * Create the packs client for pack catalog, state, and entitlement operations.
+ */
+export declare function createPacksClient(config?: PacksClientConfig): {
+    /**
+     * List catalog entries for available packs.
+     */
+    listCatalog(): Promise<import("./coreClient").PlatformGatewaySuccess<import("./types").ListResult<any, "catalog">>>;
+    /**
+     * @deprecated Use listCatalog.
+     */
+    getCatalog(): Promise<import("./coreClient").PlatformGatewaySuccess<import("./types").ListResult<any, "catalog">>>;
+    /**
+     * List pack states for the current scope.
+     */
+    listStates(query?: GatewayScope): Promise<import("./coreClient").PlatformGatewaySuccess<import("./types").ListResult<any, "states">>>;
+    /**
+     * @deprecated Use listStates.
+     */
+    getStates(query?: GatewayScope): Promise<import("./coreClient").PlatformGatewaySuccess<import("./types").ListResult<any, "states">>>;
+    /**
+     * Get health details for a pack.
+     */
+    getHealth(packKey: string, query?: GatewayScope): Promise<import("./coreClient").PlatformGatewaySuccess<unknown>>;
+    /**
+     * List pack telemetry entries.
+     */
+    listTelemetry(query?: GatewayScope & {
+        lookbackHours?: number;
+        limit?: number;
+    }): Promise<import("./coreClient").PlatformGatewaySuccess<import("./types").ListResult<any, "telemetry">>>;
+    /**
+     * @deprecated Use listTelemetry.
+     */
+    getTelemetry(query?: GatewayScope & {
+        lookbackHours?: number;
+        limit?: number;
+    }): Promise<import("./coreClient").PlatformGatewaySuccess<import("./types").ListResult<any, "telemetry">>>;
+    /**
+     * Create a pack entitlement.
+     */
+    createEntitlement(input: PackEntitlementInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<unknown>>;
+    /**
+     * Update a pack entitlement.
+     */
+    updateEntitlement(input: PackEntitlementInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<unknown>>;
+    /**
+     * @deprecated Use createEntitlement or updateEntitlement.
+     */
+    upsertEntitlement(input: PackEntitlementInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<unknown>>;
+    /**
+     * Install a pack.
+     */
+    install(input: PackInstallInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<unknown>>;
+    /**
+     * Enable a pack.
+     */
+    enable(input: PackEnableInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<unknown>>;
+    /**
+     * Disable a pack.
+     */
+    disable(input: PackDisableInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<unknown>>;
+    /**
+     * Upgrade a pack.
+     */
+    upgrade(input: PackUpgradeInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<unknown>>;
+};

package/dist/packages/sdk/src/policyClient.d.ts

@@ -0,0 +1,204 @@
+import { type GatewayClientConfig, type GatewayScope, LucernApiError } from "./coreClient";
+export { LucernApiError };
+export type { GatewayScope, PlatformGatewaySuccess } from "./coreClient";
+export type PolicyClientConfig = GatewayClientConfig;
+export type PermissionKind = "read" | "write";
+export type WritePolicyPermission = "allow" | "deny" | "review_required";
+type TopicRecord = {
+    topicId?: string;
+    name?: string;
+    type?: string;
+    isOwner?: boolean;
+    [key: string]: unknown;
+};
+export type PolicyDecisionExplanation = {
+    summary?: string;
+    matchedReasonCode?: string;
+    steps?: Array<{
+        stage?: string;
+        outcome?: string;
+        reasonCode?: string;
+        detail?: string;
+    }>;
+    [key: string]: unknown;
+};
+export type PermissionDecision = {
+    allowed?: boolean;
+    decision?: string;
+    reasonCode?: string;
+    principalId?: string;
+    topicId?: string;
+    permission?: string;
+    policyVersion?: string;
+    traceId?: string | null;
+    explanation?: PolicyDecisionExplanation;
+};
+export type WritePolicyRecord = {
+    id?: string;
+    topicId?: string;
+    role?: string;
+    toolCategory?: string;
+    permission?: WritePolicyPermission;
+    maxWritesPerSession?: number;
+    enabled?: boolean;
+    rationale?: string;
+    createdAt?: number;
+    updatedAt?: number;
+    createdBy?: string;
+    resolution?: string;
+    [key: string]: unknown;
+};
+export type WritePolicyCreateInput = GatewayScope & {
+    topicId?: string;
+    role: string;
+    toolCategory: string;
+    permission: WritePolicyPermission;
+    maxWritesPerSession?: number;
+    enabled?: boolean;
+    rationale?: string;
+    createdBy?: string;
+};
+export type WritePolicyUpdateInput = GatewayScope & {
+    topicId?: string;
+    clearTopicId?: boolean;
+    role?: string;
+    toolCategory?: string;
+    permission?: WritePolicyPermission;
+    maxWritesPerSession?: number;
+    clearMaxWritesPerSession?: boolean;
+    enabled?: boolean;
+    rationale?: string;
+    clearRationale?: boolean;
+};
+/**
+ * Create the policy client for permission checks and grants.
+ */
+export declare function createPolicyClient(config?: PolicyClientConfig): {
+    /**
+     * List policy decisions in the current scope.
+     */
+    listDecisions(query?: GatewayScope & {
+        action?: string;
+        decision?: string;
+        traceId?: string;
+        principalId?: string;
+        topicId?: string;
+        limit?: number;
+    }): Promise<import("./coreClient").PlatformGatewaySuccess<import("./types").ListResult<any, "decisions">>>;
+    /**
+     * Create a permission grant.
+     */
+    grant(input: GatewayScope & {
+        topicId: string;
+        permission: PermissionKind;
+        principal?: string;
+        principalId?: string;
+        groupId?: string;
+        beliefClusterId?: string;
+        expiresAt?: number;
+    }, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<unknown>>;
+    /**
+     * Delete a permission grant by revoking it.
+     */
+    revoke(input: GatewayScope & {
+        topicId: string;
+        principal?: string;
+        principalId?: string;
+        groupId?: string;
+        beliefClusterId?: string;
+    }, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<unknown>>;
+    listWritePolicies(query?: GatewayScope & {
+        topicId?: string;
+        role?: string;
+        toolCategory?: string;
+        enabled?: boolean;
+    }): Promise<{
+        data: {
+            policies: WritePolicyRecord[];
+        };
+        success: true;
+        correlationId: string;
+        policyTraceId: string | null;
+        idempotentReplay: boolean;
+    }>;
+    createWritePolicy(input: WritePolicyCreateInput, idempotencyKey?: string): Promise<{
+        data: {
+            id: string | undefined;
+            created: boolean;
+            policy: WritePolicyRecord | null;
+        };
+        success: true;
+        correlationId: string;
+        policyTraceId: string | null;
+        idempotentReplay: boolean;
+    }>;
+    updateWritePolicy(id: string, input: WritePolicyUpdateInput, idempotencyKey?: string): Promise<{
+        data: {
+            id: string | undefined;
+            updated: boolean;
+            policy: WritePolicyRecord | null;
+        };
+        success: true;
+        correlationId: string;
+        policyTraceId: string | null;
+        idempotentReplay: boolean;
+    }>;
+    deleteWritePolicy(id: string, scope?: GatewayScope, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<{
+        id?: string;
+        deleted?: boolean;
+    }>>;
+    /**
+     * Check a permission decision for a topic or project scope.
+     */
+    checkPermission(query: GatewayScope & {
+        topicId?: string;
+        permission?: PermissionKind;
+        principal?: string;
+        principalId?: string;
+        beliefClusterId?: string;
+    }): Promise<import("./coreClient").PlatformGatewaySuccess<PermissionDecision>>;
+    /**
+     * List accessible topics for a principal.
+     */
+    listAccessibleTopics(query?: GatewayScope & {
+        permission?: PermissionKind;
+        includeShared?: boolean;
+        principal?: string;
+        principalId?: string;
+        limit?: number;
+    }): Promise<{
+        data: {
+            permission: PermissionKind;
+            topics: TopicRecord[];
+            total: number;
+            deniedTopics: {
+                topicId: string;
+                reasonCode: string;
+            }[];
+        };
+        success: true;
+        correlationId: string;
+        policyTraceId: string | null;
+        idempotentReplay: boolean;
+    }>;
+    /**
+     * Filter topic identifiers by permission.
+     */
+    filterByPermission(input: GatewayScope & {
+        topicIds?: string[];
+        permission?: PermissionKind;
+        principal?: string;
+        principalId?: string;
+    }): Promise<{
+        success: boolean;
+        data: {
+            permission: PermissionKind;
+            allowedTopicIds: string[];
+            deniedTopics: {
+                topicId: string;
+                reasonCode: string;
+            }[];
+            count: number;
+        };
+    }>;
+};

package/dist/packages/sdk/src/reportsClient.d.ts

@@ -0,0 +1,31 @@
+import { type GatewayClientConfig } from "./coreClient";
+import type { TopicIdentifierInput, ReportTemplatesResponse, ReportWithSectionsResponse } from "./types";
+export type ReportsClientConfig = GatewayClientConfig;
+export type { ProjectReportsResponse, ReportTemplatesResponse, ReportWithSectionsResponse, } from "./types";
+/**
+ * Create the reports client for report templates and generated reports.
+ */
+export declare function createReportsClient(config?: ReportsClientConfig): {
+    /**
+     * List report templates.
+     */
+    listTemplates(args?: {
+        slug?: string;
+    }): Promise<import("./coreClient").PlatformGatewaySuccess<ReportTemplatesResponse>>;
+    /**
+     * @deprecated Use listTemplates.
+     */
+    getTemplates(args?: {
+        slug?: string;
+    }): Promise<import("./coreClient").PlatformGatewaySuccess<ReportTemplatesResponse>>;
+    /**
+     * List reports for a topic scope.
+     */
+    listReports(input: TopicIdentifierInput, args?: {
+        summary?: boolean;
+    }): Promise<import("./coreClient").PlatformGatewaySuccess<import("./types").ListResult<any, "reports">>>;
+    /**
+     * Get a generated report.
+     */
+    getReport(reportId: string): Promise<import("./coreClient").PlatformGatewaySuccess<ReportWithSectionsResponse>>;
+};

package/dist/packages/sdk/src/schemaClient.d.ts

@@ -0,0 +1,54 @@
+import { type GatewayClientConfig, type GatewayScope, LucernApiError } from "./coreClient";
+import type { JsonObject } from "./types";
+export { LucernApiError };
+export type { GatewayScope, PlatformGatewaySuccess } from "./coreClient";
+export type SchemaClientConfig = GatewayClientConfig;
+export type SchemaPackInstallInput = GatewayScope & {
+    packKey: string;
+    version?: string;
+    autoEnable?: boolean;
+    metadata?: JsonObject;
+};
+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.
+ */
+export declare function createSchemaClient(config?: SchemaClientConfig): {
+    /**
+     * List schema packs.
+     */
+    listPacks(scope?: GatewayScope): Promise<import("./coreClient").PlatformGatewaySuccess<import("./types").ListResult<any, "packs">>>;
+    /**
+     * Install a schema pack.
+     */
+    installPack(input: SchemaPackInstallInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<unknown>>;
+    /**
+     * Get a schema pack by identifier.
+     */
+    getPack(packId: string, scope?: GatewayScope): Promise<import("./coreClient").PlatformGatewaySuccess<unknown>>;
+    /**
+     * List schema entitlements.
+     */
+    listEntitlements(scope?: GatewayScope & {
+        packKey?: string;
+    }): Promise<import("./coreClient").PlatformGatewaySuccess<import("./types").ListResult<any, "entitlements">>>;
+    /**
+     * Create a schema entitlement.
+     */
+    createEntitlement(input: SchemaEntitlementInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<unknown>>;
+    /**
+     * Update a schema entitlement.
+     */
+    updateEntitlement(input: SchemaEntitlementInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<unknown>>;
+    /**
+     * @deprecated Use createEntitlement or updateEntitlement.
+     */
+    upsertEntitlement(input: SchemaEntitlementInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<unknown>>;
+};

package/dist/packages/sdk/src/sdkSurface.d.ts

@@ -0,0 +1,56 @@
+import type { PlatformGatewaySuccess } from "./coreClient";
+import type { JsonObject, ListResult } from "./types";
+type TopicScopedValue = {
+    topicId?: string;
+    projectId?: string;
+};
+type TextScopedValue = {
+    text?: string;
+    canonicalText?: string;
+};
+type AnyRecord = Record<string, unknown>;
+/**
+ * Resolve the canonical topic identifier from topic-first or legacy project-first inputs.
+ */
+export declare function resolveTopicId(value: TopicScopedValue): string | undefined;
+/**
+ * Resolve the canonical text field from text-first or legacy canonicalText-first inputs.
+ */
+export declare function resolveText(value: TextScopedValue): string | undefined;
+/**
+ * Attach the topicId/projectId alias pair to a record.
+ */
+export declare function withTopicAlias<T extends AnyRecord>(value: T): T;
+/**
+ * Attach the text/canonicalText alias pair to a record.
+ */
+export declare function withTextAlias<T extends AnyRecord>(value: T): T;
+/**
+ * Attach topic and text aliases to SDK node-like records.
+ */
+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;
+/**
+ * Build a topic-aware query object while preserving the legacy projectId alias.
+ */
+export declare function normalizeTopicQuery<T extends JsonObject>(value: T): T;
+/**
+ * Extract list items from array or list-envelope payloads.
+ */
+export declare function asListItems<T>(data: unknown, legacyKey?: string): T[];
+/**
+ * Standardize list data to { items, total } while retaining an optional legacy array key.
+ */
+export declare function createListResult<T, LegacyKey extends string>(items: T[], legacyKey?: LegacyKey): ListResult<T, LegacyKey>;
+/**
+ * Map a gateway success envelope's data while preserving the transport metadata.
+ */
+export declare function mapGatewayData<T, U>(response: PlatformGatewaySuccess<T>, mapper: (data: T) => U): PlatformGatewaySuccess<U>;
+/**
+ * Apply SDK aliases across all items in a list-like payload.
+ */
+export declare function mapAliasedList<TItem extends AnyRecord, LegacyKey extends string>(data: unknown, legacyKey?: LegacyKey): ListResult<TItem, LegacyKey>;
+export {};

package/dist/packages/sdk/src/topicsClient.d.ts

@@ -0,0 +1,45 @@
+import { type GatewayClientConfig } from "./coreClient";
+import type { JsonObject, TopicCoverageResponse, TopicIdentifierInput, TopicListResponse, TopicRecord, TopicTreeResponse } from "./types";
+export type TopicsClientConfig = GatewayClientConfig;
+export type TopicListInput = TopicIdentifierInput & {
+    ontologyId?: string;
+    parentTopicId?: string;
+    status?: string;
+    type?: string;
+};
+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;
+};
+export type TopicUpdateInput = TopicIdentifierInput & {
+    name?: string;
+    description?: string;
+    type?: string;
+    ontologyId?: string;
+    clearOntologyId?: boolean;
+    status?: "active" | "archived" | "watching";
+    visibility?: "private" | "team" | "firm" | "external" | "public";
+};
+export type TopicTreeQuery = {
+    maxDepth?: number;
+};
+export type TopicCoverageQuery = {
+    includeDescendants?: boolean;
+    maxDepth?: number;
+};
+export declare function createTopicsClient(config?: TopicsClientConfig): {
+    list(query?: TopicListInput): Promise<import("./coreClient").PlatformGatewaySuccess<TopicListResponse>>;
+    get(topicId: string): Promise<import("./coreClient").PlatformGatewaySuccess<TopicRecord>>;
+    create(input: TopicCreateInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<TopicRecord>>;
+    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>>;
+};