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

package/examples/shared.ts

@@ -0,0 +1,318 @@
+import { randomUUID } from "node:crypto";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import {
+  createGatewayRequestClient,
+  createLucernClient,
+  LucernApiError,
+} from "../src/index.js";
+
+type AnyRecord = Record<string, unknown>;
+
+export type ExampleEnv = {
+  apiKey: string;
+  baseTopicId: string;
+  baseUrl: string;
+  environment: "production" | "sandbox";
+};
+
+export type ExampleContext = {
+  env: ExampleEnv;
+  gateway: ReturnType<typeof createGatewayRequestClient>;
+  lucern: ReturnType<typeof createLucernClient>;
+};
+
+function asRecord(value: unknown): AnyRecord {
+  return value && typeof value === "object" ? (value as AnyRecord) : {};
+}
+
+function normalizeEnvironment(
+  value: string | undefined
+): "production" | "sandbox" {
+  const normalized = value?.trim().toLowerCase();
+  if (
+    normalized === "sandbox" ||
+    normalized === "preview" ||
+    normalized === "development"
+  ) {
+    return "sandbox";
+  }
+  return "production";
+}
+
+function readEnv(...names: string[]): string | undefined {
+  for (const name of names) {
+    const value = process.env[name];
+    if (typeof value === "string" && value.trim().length > 0) {
+      return value.trim();
+    }
+  }
+  return;
+}
+
+function requireEnv(label: string, ...names: string[]): string {
+  const value = readEnv(...names);
+  if (!value) {
+    throw new Error(
+      `Missing required env var for ${label}: ${names.join(" or ")}`
+    );
+  }
+  return value;
+}
+
+function parseMcpPayload(result: unknown): unknown {
+  const record = asRecord(result);
+  const content = Array.isArray(record.content) ? record.content : [];
+  const first = content[0];
+  const text =
+    typeof asRecord(first).text === "string"
+      ? String(asRecord(first).text)
+      : "";
+  if (!text) {
+    return result;
+  }
+
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return text;
+  }
+}
+
+export function slugify(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48);
+}
+
+export function loadExampleEnv(): ExampleEnv {
+  return {
+    apiKey: requireEnv("API key", "LUCERN_API_KEY", "LUCERN_KEY"),
+    baseTopicId: requireEnv(
+      "base topic",
+      "LUCERN_TOPIC_ID",
+      "LUCERN_PROJECT_ID"
+    ),
+    baseUrl: requireEnv(
+      "deployment URL",
+      "LUCERN_BASE_URL",
+      "LUCERN_API_BASE_URL"
+    ),
+    environment: normalizeEnvironment(
+      readEnv("LUCERN_ENVIRONMENT", "LUCERN_API_ENVIRONMENT")
+    ),
+  };
+}
+
+export function createExampleContext(): ExampleContext {
+  const env = loadExampleEnv();
+  const getAuthHeaders = async () => ({
+    "x-lucern-environment": env.environment,
+    "x-lucern-key": env.apiKey,
+  });
+
+  return {
+    env,
+    gateway: createGatewayRequestClient({
+      baseUrl: env.baseUrl,
+      getAuthHeaders,
+    }),
+    lucern: createLucernClient({
+      apiKey: env.apiKey,
+      baseUrl: env.baseUrl,
+      environment: env.environment,
+    }),
+  };
+}
+
+export function listItems<T = AnyRecord>(
+  value: unknown,
+  legacyKey?: string
+): T[] {
+  if (Array.isArray(value)) {
+    return value as T[];
+  }
+
+  const record = asRecord(value);
+  if (Array.isArray(record.items)) {
+    return record.items as T[];
+  }
+  if (legacyKey && Array.isArray(record[legacyKey])) {
+    return record[legacyKey] as T[];
+  }
+  return [];
+}
+
+export function readStringField(
+  value: unknown,
+  keys: string[]
+): string | undefined {
+  const record = asRecord(value);
+  for (const key of keys) {
+    const candidate = record[key];
+    if (typeof candidate === "string" && candidate.trim().length > 0) {
+      return candidate.trim();
+    }
+  }
+  return;
+}
+
+export function requireStringField(
+  value: unknown,
+  keys: string[],
+  label: string
+): string {
+  const resolved = readStringField(value, keys);
+  if (!resolved) {
+    throw new Error(`Unable to resolve ${label} from response payload.`);
+  }
+  return resolved;
+}
+
+export function summarizeError(error: unknown): AnyRecord {
+  if (error instanceof LucernApiError) {
+    return {
+      type: error.name,
+      code: error.code,
+      status: error.status,
+      message: error.message,
+      invariant: error.invariant ?? null,
+      suggestion: error.suggestion ?? null,
+      correlationId: error.correlationId ?? null,
+      policyTraceId: error.policyTraceId ?? null,
+    };
+  }
+
+  if (error instanceof Error) {
+    return {
+      type: error.name,
+      message: error.message,
+    };
+  }
+
+  return {
+    type: "UnknownError",
+    message: String(error),
+  };
+}
+
+export function printJson(payload: unknown): void {
+  console.log(JSON.stringify(payload, null, 2));
+}
+
+export async function createExampleTopic(
+  context: ExampleContext,
+  label: string
+): Promise<{
+  name: string;
+  parentTopicId: string;
+  raw: unknown;
+  topicId: string;
+}> {
+  const suffix = `${slugify(label)}-${randomUUID().slice(0, 8)}`;
+  const response = await context.gateway.request<AnyRecord>({
+    path: "/api/platform/v1/topics",
+    method: "POST",
+    body: {
+      description: `Created by lucern/packages/sdk/examples/${slugify(label)}.ts`,
+      name: `SDK Example ${suffix}`,
+      parentTopicId: context.env.baseTopicId,
+      type: "project",
+    },
+  });
+
+  const topicId = requireStringField(
+    response.data,
+    ["topicId", "_id", "id"],
+    "topicId"
+  );
+
+  return {
+    topicId,
+    name: readStringField(response.data, ["name"]) ?? `SDK Example ${suffix}`,
+    parentTopicId: context.env.baseTopicId,
+    raw: response.data,
+  };
+}
+
+export async function callHostedMcpTool(
+  context: ExampleContext,
+  name: string,
+  args: Record<string, unknown>
+): Promise<{
+  endpoint: string;
+  ok: boolean;
+  payload: unknown;
+  raw: unknown;
+}> {
+  const endpoint = new URL("/api/platform/mcp", context.env.baseUrl);
+  const transport = new StreamableHTTPClientTransport(endpoint, {
+    requestInit: {
+      headers: {
+        "x-lucern-environment": context.env.environment,
+        "x-lucern-key": context.env.apiKey,
+      },
+    },
+  });
+  const client = new Client({
+    name: `sdk-example-${slugify(name)}`,
+    version: "0.1.0",
+  });
+
+  try {
+    await client.connect(transport);
+    const result = await client.callTool({
+      name,
+      arguments: args,
+    });
+
+    return {
+      endpoint: endpoint.toString(),
+      ok: result.isError !== true,
+      payload: parseMcpPayload(result),
+      raw: result,
+    };
+  } catch (error) {
+    return {
+      endpoint: endpoint.toString(),
+      ok: false,
+      payload: summarizeError(error),
+      raw: null,
+    };
+  } finally {
+    // biome-ignore lint/suspicious/noEmptyBlockStatements: intentional swallow on cleanup
+    await client.close().catch(() => {});
+    // biome-ignore lint/suspicious/noEmptyBlockStatements: intentional swallow on cleanup
+    await transport.close().catch(() => {});
+  }
+}
+
+export async function runExample(
+  name: string,
+  executor: (context: ExampleContext) => Promise<AnyRecord>
+): Promise<void> {
+  const startedAt = Date.now();
+  const context = createExampleContext();
+
+  try {
+    const result = await executor(context);
+    printJson({
+      example: name,
+      status: "ok",
+      durationMs: Date.now() - startedAt,
+      environment: context.env.environment,
+      ...result,
+    });
+  } catch (error) {
+    printJson({
+      example: name,
+      status: "error",
+      durationMs: Date.now() - startedAt,
+      environment: context.env.environment,
+      error: summarizeError(error),
+    });
+    process.exit(1);
+  }
+}

package/examples/strict-public-types.ts

@@ -0,0 +1,143 @@
+import type {
+  AudienceGrantInput,
+  CreateBeliefInput,
+  CreateEdgeInput,
+  CreateNodeInput,
+  HarnessAgentWriteInput,
+  HarnessRunReportInput,
+  PackInstallInput,
+  PlatformBeliefRecord,
+  PlatformGraphEdge,
+  PlatformGraphNode,
+  WorkflowWorktreeRecord,
+} from "../src";
+
+type HasUnknownStringIndex<T> = string extends keyof T
+  ? unknown extends T[string]
+    ? true
+    : false
+  : false;
+
+type AssertFalse<T extends false> = T;
+
+type _platformBeliefRecordHasNoUnknownIndex = AssertFalse<
+  HasUnknownStringIndex<PlatformBeliefRecord>
+>;
+type _platformGraphNodeHasNoUnknownIndex = AssertFalse<
+  HasUnknownStringIndex<PlatformGraphNode>
+>;
+type _platformGraphEdgeHasNoUnknownIndex = AssertFalse<
+  HasUnknownStringIndex<PlatformGraphEdge>
+>;
+type _workflowWorktreeRecordHasNoUnknownIndex = AssertFalse<
+  HasUnknownStringIndex<WorkflowWorktreeRecord>
+>;
+type _createBeliefInputHasNoUnknownIndex = AssertFalse<
+  HasUnknownStringIndex<CreateBeliefInput>
+>;
+type _createNodeInputHasNoUnknownIndex = AssertFalse<
+  HasUnknownStringIndex<CreateNodeInput>
+>;
+type _createEdgeInputHasNoUnknownIndex = AssertFalse<
+  HasUnknownStringIndex<CreateEdgeInput>
+>;
+type _packInstallInputHasNoUnknownIndex = AssertFalse<
+  HasUnknownStringIndex<PackInstallInput>
+>;
+type _audienceGrantInputHasNoUnknownIndex = AssertFalse<
+  HasUnknownStringIndex<AudienceGrantInput>
+>;
+type _harnessAgentWriteInputHasNoUnknownIndex = AssertFalse<
+  HasUnknownStringIndex<HarnessAgentWriteInput>
+>;
+type _harnessRunReportInputHasNoUnknownIndex = AssertFalse<
+  HasUnknownStringIndex<HarnessRunReportInput>
+>;
+
+const createBeliefInput: CreateBeliefInput = {
+  canonicalText: "Strict SDK public types compile against JSON metadata.",
+  topicId: "topic_123",
+  metadata: {
+    source: "sdk",
+    tags: ["strict", "types"],
+    nested: {
+      enabled: true,
+    },
+  },
+};
+
+const createNodeInput: CreateNodeInput = {
+  canonicalText: "Belief node",
+  nodeType: "belief",
+  metadata: {
+    scope: "sdk",
+  },
+};
+
+const createEdgeInput: CreateEdgeInput = {
+  fromNodeId: "node_a",
+  toNodeId: "node_b",
+  edgeType: "tests",
+  weight: 0.75,
+};
+
+const packInstallInput: PackInstallInput = {
+  tenantId: "tenant_123",
+  packKey: "strict-types",
+  metadata: {
+    actor: "sdk",
+  },
+};
+
+const audienceGrantInput: AudienceGrantInput = {
+  audienceKey: "developers",
+  principalId: "principal_123",
+  metadata: {
+    source: "sdk",
+  },
+};
+
+const harnessAgentInput: HarnessAgentWriteInput = {
+  tenantId: "tenant_123",
+  agentKey: "sdk-audit",
+  displayName: "SDK Audit",
+  description: "Compile-time type contract audit",
+  version: "0.0.1",
+  executionAdapter: "sdk_invocation",
+  parameterSchema: {
+    type: "object",
+  },
+  exampleInvocations: [
+    {
+      input: {
+        query: "strict types",
+      },
+      expectedOutput: {
+        ok: true,
+      },
+    },
+  ],
+};
+
+const harnessRunReportInput: HarnessRunReportInput = {
+  reportingToken: "token_123",
+  type: "tool_call",
+  toolName: "search_beliefs",
+  input: {
+    query: "strict types",
+  },
+  result: {
+    success: true,
+  },
+};
+
+// Export type-check fixtures so the compiler verifies them without void expressions
+export {
+  createBeliefInput,
+  createNodeInput,
+  createEdgeInput,
+  packInstallInput,
+  audienceGrantInput,
+  harnessAgentInput,
+  harnessRunReportInput,
+};

package/examples/worktree-lifecycle.ts

@@ -0,0 +1,79 @@
+import {
+  createExampleTopic,
+  listItems,
+  requireStringField,
+  runExample,
+  slugify,
+} from "./shared.js";
+
+runExample("worktree-lifecycle", async (context) => {
+  const topic = await createExampleTopic(context, "worktree-lifecycle");
+
+  const branchName = `sdk-example-${slugify(topic.name)}-${Date.now()}`;
+  const branch = await context.lucern.worktrees.createBranch({
+    description: "Branch for the SDK worktree lifecycle example.",
+    name: branchName,
+    topicId: topic.topicId,
+  });
+  const branchId = requireStringField(
+    branch.data,
+    ["branchId", "nodeId"],
+    "branchId"
+  );
+
+  const belief = await context.lucern.beliefs.create({
+    text: "A short-lived worktree lets SDK adopters test a belief without mutating scored state.",
+    topicId: topic.topicId,
+  });
+  const beliefId = requireStringField(
+    belief.data,
+    ["nodeId", "globalId"],
+    "beliefId"
+  );
+
+  const worktree = await context.lucern.worktrees.create({
+    beliefIds: [beliefId],
+    branchId,
+    gate: "gate:sdk-example-worktree",
+    hypothesis:
+      "A lightweight worktree example makes the draft-to-merge lifecycle concrete.",
+    objective: "Demonstrate worktree creation from the public SDK surface.",
+    title: "SDK Example Worktree Lifecycle",
+    topicId: topic.topicId,
+  });
+  const worktreeId = requireStringField(
+    worktree.data,
+    ["worktreeId", "nodeId"],
+    "worktreeId"
+  );
+
+  const activation = await context.lucern.worktrees.activate(worktreeId);
+
+  const listed = await context.lucern.worktrees.list({
+    topicId: topic.topicId,
+  });
+  const visibleWorktrees = listItems<Record<string, unknown>>(
+    listed.data,
+    "worktrees"
+  )
+    .filter((entry) => entry.worktreeId === worktreeId)
+    .map((entry) => ({
+      status: typeof entry.status === "string" ? entry.status : null,
+      title: typeof entry.title === "string" ? entry.title : null,
+      worktreeId:
+        typeof entry.worktreeId === "string" ? entry.worktreeId : worktreeId,
+    }));
+
+  return {
+    activation: activation.data,
+    branch: {
+      branchId,
+      name: branchName,
+    },
+    topic,
+    worktree: {
+      visibleWorktrees,
+      worktreeId,
+    },
+  };
+});

package/package.json

@@ -1,70 +1,27 @@
 {
   "name": "@lucern/sdk",
-  "version": "0.2.0-alpha.5",
-  "description": "Lucern reasoning platform SDK. Install this one package, provide your API key, and start building in 10 minutes.",
-  "license": "UNLICENSED",
+  "version": "0.2.0-alpha.7",
   "type": "module",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/packages/sdk/src/index.d.ts",
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "exports": {
-    ".": {
-      "types": "./dist/packages/sdk/src/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./realtime": {
-      "types": "./dist/packages/sdk/src/realtime/index.d.ts",
-      "import": "./dist/realtime.js"
-    },
-    "./realtime/refs": {
-      "types": "./dist/packages/sdk/src/realtime/refs.d.ts",
-      "import": "./dist/realtime-refs.js"
-    }
+  "publishConfig": {
+    "access": "restricted"
   },
-  "sideEffects": false,
-  "engines": {
-    "node": ">=18.0.0"
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./contracts/*": "./src/contracts/*.ts",
+    "./*": "./src/*.ts"
   },
   "scripts": {
-    "build": "bash -lc 'cd ../.. && npx tsx scripts/build-sdk-package.ts'",
-    "build:js": "tsup",
-    "build:dts": "tsc --project tsconfig.bundle.json --declaration --emitDeclarationOnly --outDir dist",
-    "pack:dry-run": "npm pack --dry-run",
-    "prepack": "npm run build",
-    "typecheck": "tsc --project tsconfig.json --noEmit"
-  },
-  "dependencies": {},
-  "peerDependencies": {
-    "convex": ">=1.0.0",
-    "react": "^18.0.0 || ^19.0.0-0 || ^19.0.0"
+    "build": "tsup src/index.ts --format esm --dts",
+    "typecheck": "tsc --noEmit"
   },
-  "peerDependenciesMeta": {
-    "convex": {
-      "optional": true
-    },
-    "react": {
-      "optional": true
-    }
+  "dependencies": {
+    "@lucern/contracts": "workspace:*",
+    "@lucern/reasoning-kernel": "workspace:*",
+    "zod": "^3.25.76"
   },
   "devDependencies": {
-    "tsup": "^8.5.0",
     "typescript": "^5.7.0"
-  },
-  "publishConfig": {
-    "access": "restricted"
-  },
-  "keywords": [
-    "lucern",
-    "reasoning",
-    "epistemic",
-    "beliefs",
-    "knowledge-graph",
-    "sdk",
-    "ai",
-    "agents"
-  ]
+  }
 }

package/src/README.md

@@ -0,0 +1,6 @@
+# @lucern/sdk
+
+Official TypeScript SDK for the Lucern reasoning platform.
+
+Generated from and validated against `@lucern/contracts`.
+Migrates from `front-end/lucern/packages/sdk/`.