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

package/src/policyClient.ts

@@ -0,0 +1,572 @@
+import {
+  createGatewayRequestClient,
+  type GatewayClientConfig,
+  type GatewayScope,
+  LucernApiError,
+  randomIdempotencyKey,
+  toQueryString,
+} from "./coreClient";
+import { createListResult, mapGatewayData } from "./sdkSurface";
+
+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;
+  name?: string;
+  type?: string;
+  isOwner?: boolean;
+  [key: string]: unknown;
+};
+
+/** Structured explanation of how a policy decision was derived. */
+export type PolicyDecisionExplanation = {
+  summary?: string;
+  matchedReasonCode?: string;
+  steps?: Array<{
+    stage?: string;
+    outcome?: string;
+    reasonCode?: string;
+    detail?: string;
+  }>;
+  [key: string]: unknown;
+};
+
+/** Result of a permission check against the policy engine. */
+export type PermissionDecision = {
+  allowed?: boolean;
+  decision?: string;
+  reasonCode?: string;
+  principalId?: string;
+  topicId?: string;
+  permission?: string;
+  policyVersion?: string;
+  traceId?: string | null;
+  explanation?: PolicyDecisionExplanation;
+};
+
+/** A persisted write policy rule controlling mutation access. */
+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;
+};
+
+/** Input for creating a write policy rule. */
+export type WritePolicyCreateInput = GatewayScope & {
+  topicId?: string;
+  role: string;
+  toolCategory: string;
+  permission: WritePolicyPermission;
+  maxWritesPerSession?: number;
+  enabled?: boolean;
+  rationale?: string;
+  createdBy?: string;
+};
+
+/** Input for partially updating an existing write policy rule. */
+export type WritePolicyUpdateInput = GatewayScope & {
+  topicId?: string;
+  clearTopicId?: boolean;
+  role?: string;
+  toolCategory?: string;
+  permission?: WritePolicyPermission;
+  maxWritesPerSession?: number;
+  clearMaxWritesPerSession?: boolean;
+  enabled?: boolean;
+  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;
+};
+
+type AccessibleTopicsResponse = {
+  permission: PermissionKind;
+  topics: TopicRecord[];
+  total: number;
+  deniedTopics: Array<{
+    topicId: string;
+    reasonCode: string;
+  }>;
+};
+
+type FilterByPermissionResponse = {
+  permission: PermissionKind;
+  allowedTopicIds: string[];
+  deniedTopics: Array<{
+    topicId: string;
+    reasonCode: string;
+  }>;
+  count: number;
+};
+
+function asTopicArray(data: unknown): TopicRecord[] {
+  if (Array.isArray(data)) {
+    return data.filter(
+      (row): row is TopicRecord => Boolean(row) && typeof row === "object"
+    );
+  }
+  return [];
+}
+
+function asWritePolicyRecord(data: unknown): WritePolicyRecord | null {
+  if (!data || typeof data !== "object") {
+    return null;
+  }
+  return data as WritePolicyRecord;
+}
+
+function asWritePolicyArray(data: unknown): WritePolicyRecord[] {
+  if (!Array.isArray(data)) {
+    return [];
+  }
+  return data
+    .map(asWritePolicyRecord)
+    .filter((row): row is WritePolicyRecord => Boolean(row));
+}
+
+function asRolePolicyRecord(data: unknown): TenantPolicyRecord | null {
+  if (!data || typeof data !== "object") {
+    return null;
+  }
+  return data as TenantPolicyRecord;
+}
+
+function asRolePolicyArray(data: unknown): TenantPolicyRecord[] {
+  if (!Array.isArray(data)) {
+    return [];
+  }
+  return data
+    .map(asRolePolicyRecord)
+    .filter((row): row is TenantPolicyRecord => 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: PolicyClientConfig = {}) {
+  const gateway = createGatewayRequestClient(config);
+
+  return {
+    /**
+     * List policy decisions in the current scope.
+     */
+    async listDecisions(
+      query: GatewayScope & {
+        action?: string;
+        decision?: string;
+        traceId?: string;
+        principalId?: string;
+        topicId?: string;
+        limit?: number;
+      } = {}
+    ) {
+      return gateway.request<unknown>({
+        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: GatewayScope & {
+        topicId: string;
+        permission: PermissionKind;
+        principal?: string;
+        principalId?: string;
+        groupId?: string;
+        beliefClusterId?: string;
+        expiresAt?: number;
+      },
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: "/api/platform/v1/policy/grant",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Delete a permission grant by revoking it.
+     */
+    async revoke(
+      input: GatewayScope & {
+        topicId: string;
+        principal?: string;
+        principalId?: string;
+        groupId?: string;
+        beliefClusterId?: string;
+      },
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: "/api/platform/v1/policy/revoke",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * List write policy rules for the current scope.
+     */
+    async listWritePolicies(
+      query: GatewayScope & {
+        topicId?: string;
+        role?: string;
+        toolCategory?: string;
+        enabled?: boolean;
+      } = {}
+    ) {
+      const response = await gateway.request<{ policies?: unknown[] }>({
+        path: `/api/platform/v1/policy/write-policies${toQueryString(query)}`,
+      });
+      const rawPolicies =
+        response.data && typeof response.data === "object"
+          ? (response.data as { policies?: unknown[] }).policies
+          : response.data;
+
+      return {
+        ...response,
+        data: {
+          policies: asWritePolicyArray(rawPolicies),
+        },
+      };
+    },
+
+    /**
+     * Create a write policy rule.
+     */
+    async createWritePolicy(
+      input: WritePolicyCreateInput,
+      idempotencyKey?: string
+    ) {
+      const response = await gateway.request<{
+        id?: string;
+        created?: boolean;
+        policy?: unknown;
+      }>({
+        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: string,
+      input: WritePolicyUpdateInput,
+      idempotencyKey?: string
+    ) {
+      const response = await gateway.request<{
+        id?: string;
+        updated?: boolean;
+        policy?: unknown;
+      }>({
+        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: string,
+      scope: GatewayScope = {},
+      idempotencyKey?: string
+    ) {
+      return gateway.request<{ id?: string; deleted?: boolean }>({
+        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: GatewayScope = {}) {
+      const response = await gateway.request<{ policies?: unknown[] }>({
+        path: `/api/platform/v1/policy/roles${toQueryString(query)}`,
+      });
+
+      return {
+        ...response,
+        data: {
+          policies: asRolePolicyArray(response.data?.policies),
+        },
+      };
+    },
+
+    /**
+     * Create a tenant role policy.
+     */
+    async createRolePolicy(
+      input: GatewayScope & {
+        roleName: string;
+        description?: string;
+        permissions: TenantPolicyPermission[];
+        groupBindings?: string[];
+      },
+      idempotencyKey?: string
+    ) {
+      const response = await gateway.request<{ policy?: unknown }>({
+        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: string,
+      input: GatewayScope & {
+        roleName: string;
+        description?: string;
+        permissions: TenantPolicyPermission[];
+        groupBindings?: string[];
+      },
+      idempotencyKey?: string
+    ) {
+      const response = await gateway.request<{ policy?: unknown }>({
+        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: string,
+      scope: GatewayScope = {},
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        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: GatewayScope & {
+        topicId?: string;
+        permission?: PermissionKind;
+        principal?: string;
+        principalId?: string;
+        beliefClusterId?: string;
+      }
+    ) {
+      if (!query.topicId) {
+        throw new Error("topicId is required");
+      }
+      return gateway.request<PermissionDecision>({
+        path: `/api/platform/v1/policy/check${toQueryString(query)}`,
+      });
+    },
+
+    /**
+     * List accessible topics for a principal.
+     */
+    async listAccessibleTopics(
+      query: GatewayScope & {
+        permission?: PermissionKind;
+        includeShared?: boolean;
+        principal?: string;
+        principalId?: string;
+        limit?: number;
+      } = {}
+    ) {
+      const permission = query.permission ?? "read";
+      const principal = query.principal ?? query.principalId;
+      const response = await gateway.request<{
+        permission?: PermissionKind;
+        topics?: unknown[];
+        total?: number;
+        deniedTopics?: Array<{
+          topicId: string;
+          reasonCode: string;
+        }>;
+      }>({
+        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
+            : [],
+        } satisfies AccessibleTopicsResponse,
+      };
+    },
+
+    /**
+     * Filter topic identifiers by permission.
+     */
+    async filterByPermission(
+      input: GatewayScope & {
+        topicIds?: string[];
+        permission?: PermissionKind;
+        principal?: string;
+        principalId?: string;
+      }
+    ) {
+      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<{
+        permission?: PermissionKind;
+        allowedTopicIds?: string[];
+        deniedTopics?: Array<{
+          topicId: string;
+          reasonCode: string;
+        }>;
+        count?: number;
+      }>({
+        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,
+        } satisfies FilterByPermissionResponse,
+      };
+    },
+  };
+}

package/src/realtime/index.ts

@@ -0,0 +1,51 @@
+import { ConvexHttpClient } from "convex/browser";
+import type { ConvexReactClientOptions as LucernConvexReactClientOptions } from "convex/react";
+import {
+  ConvexReactClient,
+  useAction,
+  useConvex,
+  useMutation,
+  useQuery,
+} from "convex/react";
+
+/**
+ * Re-export the server-safe ref surface so existing client consumers keep a
+ * single import site. Server code must import from `@lucern/sdk/realtime/refs`
+ * instead, because this module statically pulls in `convex/react` which is
+ * incompatible with the Next.js Edge runtime React shim.
+ */
+export { subscriptionRefs, platformApi, type AnyApi } from "./refs";
+
+/**
+ * Opt-in realtime hook surface. These preserve native Convex semantics while
+ * moving the transport boundary behind an SDK subpath export.
+ */
+export const useLucernSubscription: typeof useQuery = useQuery;
+export const useLucernMutation: typeof useMutation = useMutation;
+export const useLucernAction: typeof useAction = useAction;
+export const useLucernRealtimeClient: typeof useConvex = useConvex;
+
+export type LucernRealtimeClient = ConvexReactClient;
+export type LucernHttpClient = ConvexHttpClient;
+
+/**
+ * Construct the Convex realtime client that host apps wire into their provider
+ * tree. Keeping this here lets HTTP-only consumers avoid importing the
+ * realtime surface altogether.
+ */
+export function createLucernRealtimeClient(
+  address: string,
+  options?: LucernConvexReactClientOptions
+): LucernRealtimeClient {
+  return new ConvexReactClient(address, options);
+}
+
+/**
+ * Construct the HTTP-only Convex client behind the SDK boundary so app code
+ * does not import `convex/browser` directly.
+ */
+export function createLucernHttpClient(address: string): LucernHttpClient {
+  return new ConvexHttpClient(address);
+}
+
+export type { LucernConvexReactClientOptions };

package/src/realtime/refs.ts

@@ -0,0 +1,17 @@
+import { type AnyApi, anyApi } from "convex/server";
+
+/**
+ * Server-safe realtime ref surface.
+ *
+ * Keep this module free of any import that transitively pulls `convex/react`
+ * or `convex/browser`. Edge-runtime routes and server adapters import from
+ * `@lucern/sdk/realtime/refs` so Next.js never bundles the Convex React client
+ * (which imports React hooks that are not available in the Edge runtime shim).
+ *
+ * Client consumers should continue importing from `@lucern/sdk/realtime`.
+ */
+export const subscriptionRefs: AnyApi = anyApi;
+
+export const platformApi = subscriptionRefs;
+
+export type { AnyApi };