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

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

@@ -0,0 +1,157 @@
+import { createGatewayRequestClient, LucernApiError, randomIdempotencyKey, toQueryString, } from "./coreClient.js";
+import { createListResult, mapGatewayData } from "./sdkSurface.js";
+export { LucernApiError };
+/**
+ * Create the packs client for pack catalog, state, and entitlement operations.
+ * @param config - Gateway transport configuration.
+ * @returns An object with methods to manage pack lifecycle, telemetry, and entitlements.
+ */
+export function createPacksClient(config = {}) {
+    const gateway = createGatewayRequestClient(config);
+    return {
+        /**
+         * List catalog entries for available packs.
+         */
+        async listCatalog() {
+            return gateway.request({
+                path: "/api/platform/v1/packs/catalog",
+            }).then((response) => mapGatewayData(response, (data) => createListResult(Array.isArray(data) ? data : [], "catalog")));
+        },
+        /**
+         * @deprecated Use listCatalog.
+         */
+        async getCatalog() {
+            return this.listCatalog();
+        },
+        /**
+         * Get the discovery catalog for packs.
+         */
+        async getDiscoveryCatalog() {
+            return gateway.request({
+                path: "/api/platform/v1/packs/discovery",
+            });
+        },
+        /**
+         * Get discovery details for a specific pack.
+         */
+        async getDiscoveryDetail(packKey) {
+            return gateway.request({
+                path: `/api/platform/v1/packs/discovery/${encodeURIComponent(packKey)}`,
+            });
+        },
+        /**
+         * List pack states for the current scope.
+         */
+        async listStates(query = {}) {
+            return gateway.request({
+                path: `/api/platform/v1/packs/states${toQueryString(query)}`,
+            }).then((response) => mapGatewayData(response, (data) => createListResult(Array.isArray(data) ? data : [], "states")));
+        },
+        /**
+         * @deprecated Use listStates.
+         */
+        async getStates(query = {}) {
+            return this.listStates(query);
+        },
+        /**
+         * Get health details for a pack.
+         */
+        async getHealth(packKey, query = {}) {
+            return gateway.request({
+                path: `/api/platform/v1/packs/${encodeURIComponent(packKey)}/health${toQueryString(query)}`,
+            });
+        },
+        /**
+         * List pack telemetry entries.
+         */
+        async listTelemetry(query = {}) {
+            return gateway.request({
+                path: `/api/platform/v1/packs/telemetry${toQueryString(query)}`,
+            }).then((response) => mapGatewayData(response, (data) => createListResult(Array.isArray(data) ? data : [], "telemetry")));
+        },
+        /**
+         * @deprecated Use listTelemetry.
+         */
+        async getTelemetry(query = {}) {
+            return this.listTelemetry(query);
+        },
+        /**
+         * Create a pack entitlement.
+         */
+        async createEntitlement(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/packs/entitlements",
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Update a pack entitlement.
+         */
+        async updateEntitlement(input, idempotencyKey) {
+            return this.createEntitlement(input, idempotencyKey);
+        },
+        /**
+         * @deprecated Use createEntitlement or updateEntitlement.
+         */
+        async upsertEntitlement(input, idempotencyKey) {
+            return this.createEntitlement(input, idempotencyKey);
+        },
+        /**
+         * Install a pack.
+         */
+        async install(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/packs/install",
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Enable a pack.
+         */
+        async enable(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/packs/enable",
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Disable a pack.
+         */
+        async disable(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/packs/disable",
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Uninstall a pack.
+         */
+        async uninstall(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/packs/uninstall",
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Upgrade a pack.
+         */
+        async upgrade(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/packs/upgrade",
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+    };
+}

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

@@ -1,8 +1,11 @@
 import { type GatewayClientConfig, type GatewayScope, LucernApiError } from "./coreClient";
 export { LucernApiError };
 export type { GatewayScope, PlatformGatewaySuccess } from "./coreClient";
+/** Configuration for the policy client. */
 export type PolicyClientConfig = GatewayClientConfig;
+/** Permission direction: read access or write access. */
 export type PermissionKind = "read" | "write";
+/** Permission level for a write policy rule. */
 export type WritePolicyPermission = "allow" | "deny" | "review_required";
 type TopicRecord = {
     topicId?: string;
@@ -11,6 +14,7 @@ type TopicRecord = {
     isOwner?: boolean;
     [key: string]: unknown;
 };
+/** Structured explanation of how a policy decision was derived. */
 export type PolicyDecisionExplanation = {
     summary?: string;
     matchedReasonCode?: string;
@@ -22,6 +26,7 @@ export type PolicyDecisionExplanation = {
     }>;
     [key: string]: unknown;
 };
+/** Result of a permission check against the policy engine. */
 export type PermissionDecision = {
     allowed?: boolean;
     decision?: string;
@@ -33,6 +38,7 @@ export type PermissionDecision = {
     traceId?: string | null;
     explanation?: PolicyDecisionExplanation;
 };
+/** A persisted write policy rule controlling mutation access. */
 export type WritePolicyRecord = {
     id?: string;
     topicId?: string;
@@ -48,6 +54,7 @@ export type WritePolicyRecord = {
     resolution?: string;
     [key: string]: unknown;
 };
+/** Input for creating a write policy rule. */
 export type WritePolicyCreateInput = GatewayScope & {
     topicId?: string;
     role: string;
@@ -58,6 +65,7 @@ export type WritePolicyCreateInput = GatewayScope & {
     rationale?: string;
     createdBy?: string;
 };
+/** Input for partially updating an existing write policy rule. */
 export type WritePolicyUpdateInput = GatewayScope & {
     topicId?: string;
     clearTopicId?: boolean;
@@ -70,8 +78,27 @@ export type WritePolicyUpdateInput = GatewayScope & {
     rationale?: string;
     clearRationale?: boolean;
 };
+export type TenantPolicyPermission = {
+    resource: string;
+    actions: string[];
+};
+export type TenantPolicyRecord = {
+    id?: string;
+    tenantId: string;
+    workspaceId?: string;
+    roleName: string;
+    description?: string;
+    permissions: TenantPolicyPermission[];
+    groupBindings: string[];
+    createdAt?: number;
+    updatedAt?: number;
+    createdBy?: string;
+    updatedBy?: string;
+};
 /**
- * Create the policy client for permission checks and grants.
+ * Create the policy client for permission checks, grants, and write policies.
+ * @param config - Gateway transport configuration.
+ * @returns An object with methods to check permissions, manage grants, and manage write policies.
  */
 export declare function createPolicyClient(config?: PolicyClientConfig): {
     /**
@@ -107,6 +134,9 @@ export declare function createPolicyClient(config?: PolicyClientConfig): {
         groupId?: string;
         beliefClusterId?: string;
     }, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<unknown>>;
+    /**
+     * List write policy rules for the current scope.
+     */
     listWritePolicies(query?: GatewayScope & {
         topicId?: string;
         role?: string;
@@ -121,6 +151,9 @@ export declare function createPolicyClient(config?: PolicyClientConfig): {
         policyTraceId: string | null;
         idempotentReplay: boolean;
     }>;
+    /**
+     * Create a write policy rule.
+     */
     createWritePolicy(input: WritePolicyCreateInput, idempotencyKey?: string): Promise<{
         data: {
             id: string | undefined;
@@ -132,6 +165,9 @@ export declare function createPolicyClient(config?: PolicyClientConfig): {
         policyTraceId: string | null;
         idempotentReplay: boolean;
     }>;
+    /**
+     * Update an existing write policy rule by identifier.
+     */
     updateWritePolicy(id: string, input: WritePolicyUpdateInput, idempotencyKey?: string): Promise<{
         data: {
             id: string | undefined;
@@ -143,10 +179,63 @@ export declare function createPolicyClient(config?: PolicyClientConfig): {
         policyTraceId: string | null;
         idempotentReplay: boolean;
     }>;
+    /**
+     * Delete a write policy rule by identifier.
+     */
     deleteWritePolicy(id: string, scope?: GatewayScope, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<{
         id?: string;
         deleted?: boolean;
     }>>;
+    /**
+     * List tenant role policies for the current scope.
+     */
+    listRolePolicies(query?: GatewayScope): Promise<{
+        data: {
+            policies: TenantPolicyRecord[];
+        };
+        success: true;
+        correlationId: string;
+        policyTraceId: string | null;
+        idempotentReplay: boolean;
+    }>;
+    /**
+     * Create a tenant role policy.
+     */
+    createRolePolicy(input: GatewayScope & {
+        roleName: string;
+        description?: string;
+        permissions: TenantPolicyPermission[];
+        groupBindings?: string[];
+    }, idempotencyKey?: string): Promise<{
+        data: {
+            policy: TenantPolicyRecord | null;
+        };
+        success: true;
+        correlationId: string;
+        policyTraceId: string | null;
+        idempotentReplay: boolean;
+    }>;
+    /**
+     * Update a tenant role policy by identifier.
+     */
+    updateRolePolicy(id: string, input: GatewayScope & {
+        roleName: string;
+        description?: string;
+        permissions: TenantPolicyPermission[];
+        groupBindings?: string[];
+    }, idempotencyKey?: string): Promise<{
+        data: {
+            policy: TenantPolicyRecord | null;
+        };
+        success: true;
+        correlationId: string;
+        policyTraceId: string | null;
+        idempotentReplay: boolean;
+    }>;
+    /**
+     * Delete a tenant role policy by identifier.
+     */
+    deleteRolePolicy(id: string, scope?: GatewayScope, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<unknown>>;
     /**
      * Check a permission decision for a topic or project scope.
      */

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

@@ -0,0 +1,277 @@
+import { createGatewayRequestClient, LucernApiError, randomIdempotencyKey, toQueryString, } from "./coreClient.js";
+import { createListResult, mapGatewayData } from "./sdkSurface.js";
+export { LucernApiError };
+function asTopicArray(data) {
+    if (Array.isArray(data)) {
+        return data.filter((row) => Boolean(row) && typeof row === "object");
+    }
+    return [];
+}
+function asWritePolicyRecord(data) {
+    if (!data || typeof data !== "object") {
+        return null;
+    }
+    return data;
+}
+function asWritePolicyArray(data) {
+    if (!Array.isArray(data)) {
+        return [];
+    }
+    return data
+        .map(asWritePolicyRecord)
+        .filter((row) => Boolean(row));
+}
+function asRolePolicyRecord(data) {
+    if (!data || typeof data !== "object") {
+        return null;
+    }
+    return data;
+}
+function asRolePolicyArray(data) {
+    if (!Array.isArray(data)) {
+        return [];
+    }
+    return data
+        .map(asRolePolicyRecord)
+        .filter((row) => Boolean(row));
+}
+/**
+ * Create the policy client for permission checks, grants, and write policies.
+ * @param config - Gateway transport configuration.
+ * @returns An object with methods to check permissions, manage grants, and manage write policies.
+ */
+export function createPolicyClient(config = {}) {
+    const gateway = createGatewayRequestClient(config);
+    return {
+        /**
+         * List policy decisions in the current scope.
+         */
+        async listDecisions(query = {}) {
+            return gateway.request({
+                path: `/api/platform/v1/policy/decisions${toQueryString(query)}`,
+            }).then((response) => mapGatewayData(response, (data) => createListResult(Array.isArray(data) ? data : [], "decisions")));
+        },
+        /**
+         * Create a permission grant.
+         */
+        async grant(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/policy/grant",
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Delete a permission grant by revoking it.
+         */
+        async revoke(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/policy/revoke",
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * List write policy rules for the current scope.
+         */
+        async listWritePolicies(query = {}) {
+            const response = await gateway.request({
+                path: `/api/platform/v1/policy/write-policies${toQueryString(query)}`,
+            });
+            const rawPolicies = response.data && typeof response.data === "object"
+                ? response.data.policies
+                : response.data;
+            return {
+                ...response,
+                data: {
+                    policies: asWritePolicyArray(rawPolicies),
+                },
+            };
+        },
+        /**
+         * Create a write policy rule.
+         */
+        async createWritePolicy(input, idempotencyKey) {
+            const response = await gateway.request({
+                path: "/api/platform/v1/policy/write-policies",
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+            return {
+                ...response,
+                data: {
+                    id: typeof response.data?.id === "string" ? response.data.id : undefined,
+                    created: response.data?.created === true,
+                    policy: asWritePolicyRecord(response.data?.policy),
+                },
+            };
+        },
+        /**
+         * Update an existing write policy rule by identifier.
+         */
+        async updateWritePolicy(id, input, idempotencyKey) {
+            const response = await gateway.request({
+                path: `/api/platform/v1/policy/write-policies/${encodeURIComponent(id)}`,
+                method: "PATCH",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+            return {
+                ...response,
+                data: {
+                    id: typeof response.data?.id === "string" ? response.data.id : undefined,
+                    updated: response.data?.updated === true,
+                    policy: asWritePolicyRecord(response.data?.policy),
+                },
+            };
+        },
+        /**
+         * Delete a write policy rule by identifier.
+         */
+        async deleteWritePolicy(id, scope = {}, idempotencyKey) {
+            return gateway.request({
+                path: `/api/platform/v1/policy/write-policies/${encodeURIComponent(id)}${toQueryString(scope)}`,
+                method: "DELETE",
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * List tenant role policies for the current scope.
+         */
+        async listRolePolicies(query = {}) {
+            const response = await gateway.request({
+                path: `/api/platform/v1/policy/roles${toQueryString(query)}`,
+            });
+            return {
+                ...response,
+                data: {
+                    policies: asRolePolicyArray(response.data?.policies),
+                },
+            };
+        },
+        /**
+         * Create a tenant role policy.
+         */
+        async createRolePolicy(input, idempotencyKey) {
+            const response = await gateway.request({
+                path: "/api/platform/v1/policy/roles",
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+            return {
+                ...response,
+                data: {
+                    policy: asRolePolicyRecord(response.data?.policy),
+                },
+            };
+        },
+        /**
+         * Update a tenant role policy by identifier.
+         */
+        async updateRolePolicy(id, input, idempotencyKey) {
+            const response = await gateway.request({
+                path: `/api/platform/v1/policy/roles/${encodeURIComponent(id)}`,
+                method: "PATCH",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+            return {
+                ...response,
+                data: {
+                    policy: asRolePolicyRecord(response.data?.policy),
+                },
+            };
+        },
+        /**
+         * Delete a tenant role policy by identifier.
+         */
+        async deleteRolePolicy(id, scope = {}, idempotencyKey) {
+            return gateway.request({
+                path: `/api/platform/v1/policy/roles/${encodeURIComponent(id)}${toQueryString(scope)}`,
+                method: "DELETE",
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Check a permission decision for a topic or project scope.
+         */
+        async checkPermission(query) {
+            if (!query.topicId) {
+                throw new Error("topicId is required");
+            }
+            return gateway.request({
+                path: `/api/platform/v1/policy/check${toQueryString(query)}`,
+            });
+        },
+        /**
+         * List accessible topics for a principal.
+         */
+        async listAccessibleTopics(query = {}) {
+            const permission = query.permission ?? "read";
+            const principal = query.principal ?? query.principalId;
+            const response = await gateway.request({
+                path: `/api/platform/v1/policy/topics${toQueryString({
+                    tenantId: query.tenantId,
+                    workspaceId: query.workspaceId,
+                    permission,
+                    includeShared: query.includeShared,
+                    principal,
+                    limit: query.limit,
+                })}`,
+            });
+            return {
+                ...response,
+                data: {
+                    permission,
+                    topics: asTopicArray(response.data?.topics),
+                    total: typeof response.data?.total === "number"
+                        ? response.data.total
+                        : asTopicArray(response.data?.topics).length,
+                    deniedTopics: Array.isArray(response.data?.deniedTopics)
+                        ? response.data.deniedTopics
+                        : [],
+                },
+            };
+        },
+        /**
+         * Filter topic identifiers by permission.
+         */
+        async filterByPermission(input) {
+            const permission = input.permission ?? "read";
+            const principal = input.principal ?? input.principalId;
+            const uniqueTopicIds = [...new Set(input.topicIds ?? [])].filter((topicId) => typeof topicId === "string" && topicId.trim().length > 0);
+            const response = await gateway.request({
+                path: "/api/platform/v1/policy/filter",
+                method: "POST",
+                body: {
+                    tenantId: input.tenantId,
+                    workspaceId: input.workspaceId,
+                    topicIds: uniqueTopicIds,
+                    permission,
+                    principal,
+                },
+            });
+            const allowedTopicIds = Array.isArray(response.data?.allowedTopicIds)
+                ? response.data.allowedTopicIds
+                : [];
+            const deniedTopics = Array.isArray(response.data?.deniedTopics)
+                ? response.data.deniedTopics
+                : [];
+            return {
+                success: true,
+                data: {
+                    permission,
+                    allowedTopicIds,
+                    deniedTopics,
+                    count: typeof response.data?.count === "number"
+                        ? response.data.count
+                        : allowedTopicIds.length,
+                },
+            };
+        },
+    };
+}

package/dist/lib/platform/sdk/promptCatalog.d.ts

@@ -0,0 +1 @@
+export { getPromptCatalogSnapshot } from "../../../lib/langfuse/prompt-catalog";

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

@@ -0,0 +1 @@
+export { getPromptCatalogSnapshot } from "../../../lib/langfuse/prompt-catalog.js";

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

@@ -1,9 +1,12 @@
 import { type GatewayClientConfig } from "./coreClient";
 import type { TopicIdentifierInput, 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 declare function createReportsClient(config?: ReportsClientConfig): {
     /**

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

@@ -0,0 +1,64 @@
+import { createGatewayRequestClient, toQueryString, } from "./coreClient.js";
+import { createListResult, mapGatewayData, resolveTopicId } from "./sdkSurface.js";
+/**
+ * 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 = {}) {
+    const gateway = createGatewayRequestClient(config);
+    return {
+        /**
+         * List report templates.
+         */
+        async listTemplates(args = {}) {
+            return gateway.request({
+                path: `/api/platform/v1/reports/templates${toQueryString({
+                    slug: args.slug,
+                })}`,
+            }).then((response) => mapGatewayData(response, (data) => {
+                const record = data && typeof data === "object"
+                    ? data
+                    : {};
+                const rows = Array.isArray(data)
+                    ? data
+                    : Array.isArray(record.templates)
+                        ? record.templates
+                        : [];
+                return createListResult(rows, "templates");
+            }));
+        },
+        /**
+         * @deprecated Use listTemplates.
+         */
+        async getTemplates(args = {}) {
+            return this.listTemplates(args);
+        },
+        /**
+         * List reports for a topic scope.
+         */
+        async listReports(input, args = {}) {
+            const topicId = resolveTopicId(input);
+            if (!topicId) {
+                throw new Error("topicId is required");
+            }
+            return gateway.request({
+                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) {
+            return gateway.request({
+                path: `/api/platform/v1/reports/${encodeURIComponent(reportId)}`,
+            });
+        },
+    };
+}