@lucern/sdk 0.2.0-alpha.1

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

@@ -0,0 +1,274 @@
+import { type GatewayClientConfig, LucernApiError } from "./coreClient";
+import type { LensPerspectiveType, LensPromptTemplateReference, LensStatus, LensTaskTemplate, LensWorkflowTemplate } from "@lucern/contracts/lens-workflow.contract";
+import type { WorkflowAutoFixPolicy, WorkflowProofArtifact, WorkflowStaffingHint } from "@lucern/contracts/workflow-runtime.contract";
+import type { CompleteTaskResponse, CreateTaskResponse, JsonObject, ListTopicsResponse, ListWorktreesResponse, MergeWorktreeResponse, OpenPullRequestResponse, PushWorktreeResponse, SwitchTopicContextResponse, TopicIdentifierInput, UpdateTaskResponse, WorkflowBranchRecord, WorkflowLensRecord, WorkflowWorktreeRecord } from "./types";
+export { LucernApiError };
+export type { PlatformGatewaySuccess } from "./coreClient";
+export type { AddWorktreeResponse, CompleteTaskResponse, CreateBranchResponse, CreateLensResponse, CreateTaskResponse, LensTopicBindingResponse, ListBranchesResponse, ListLensesResponse, ListTopicsResponse, ListWorktreesResponse, MergeWorktreeResponse, OpenPullRequestResponse, PushWorktreeResponse, SwitchTopicContextResponse, UpdateTaskResponse, } from "./types";
+export type WorkflowClientConfig = GatewayClientConfig;
+export type WorkflowBranchStatus = "dormant" | "active" | "archived";
+export type WorkflowLensStatus = LensStatus;
+export type WorkflowLensPerspectiveType = LensPerspectiveType;
+export type WorkflowWorktreeStatus = "planning" | "active" | "paused" | "completed" | "merged" | "failed" | "archived";
+export type WorkflowMergeOutcome = "validated" | "invalidated" | "forked" | "inconclusive";
+export type AddWorktreeInput = {
+    title: string;
+    topicId?: string;
+    /** @deprecated Use topicId. */
+    projectId?: string;
+    branchId?: string;
+    objective?: string;
+    hypothesis?: string;
+    beliefIds?: string[];
+    autoShape?: boolean;
+    domainPackId?: string;
+    executionOrder?: number;
+    dependsOn?: string[];
+    blocks?: string[];
+    gate?: string;
+    proofArtifacts?: WorkflowProofArtifact[];
+    staffingHint?: WorkflowStaffingHint | string;
+    lastReconciledAt?: number;
+    autoFixPolicy?: WorkflowAutoFixPolicy;
+} & TopicIdentifierInput;
+export type MergeInput = {
+    outcomes: Array<{
+        beliefId: string;
+        confidence: number;
+        rationale: string;
+    }>;
+    summary?: string;
+};
+export type UpdateWorktreeTargetsInput = {
+    worktreeId: string;
+    addBeliefIds?: string[];
+    addQuestionIds?: string[];
+    removeBeliefIds?: string[];
+    removeQuestionIds?: string[];
+};
+export type ListTopicsInput = {
+    includeShared?: boolean;
+    limit?: number;
+};
+export type SwitchTopicContextInput = {
+    targetTopicName: string;
+};
+export type CreateTaskInput = {
+    title: string;
+    topicId?: string;
+    /** @deprecated Use topicId. */
+    projectId?: string;
+    taskType?: "research" | "interview" | "analysis" | "data_collection";
+    linkedQuestionId?: string;
+    linkedWorktreeId?: string;
+    linkedBeliefId?: string;
+    description?: string;
+    priority?: "low" | "medium" | "high" | "urgent";
+} & TopicIdentifierInput;
+export type CompleteTaskInput = {
+    outputSummary: string;
+    evidenceCreated?: boolean;
+};
+export type UpdateTaskInput = {
+    title?: string;
+    description?: string;
+    linkedBeliefId?: string;
+    linkedQuestionId?: string;
+    linkedWorktreeId?: string;
+    priority?: "critical" | "high" | "medium" | "low";
+    status?: "todo" | "in_progress" | "blocked" | "done";
+};
+/**
+ * Create the workflow client for lenses, legacy branches, worktrees, context,
+ * and tasks.
+ */
+export declare function createWorkflowClient(config?: WorkflowClientConfig): {
+    /**
+     * List workflow branches for a topic scope.
+     */
+    listBranches(query: {
+        topicId?: string;
+        /** @deprecated Use topicId. */
+        projectId?: string;
+        status?: WorkflowBranchStatus;
+        limit?: number;
+    } & TopicIdentifierInput): Promise<import("./coreClient").PlatformGatewaySuccess<import("./types").ListResult<WorkflowBranchRecord, "branches">>>;
+    /**
+     * Create a workflow branch.
+     */
+    createBranch(input: {
+        name: string;
+        topicId?: string;
+        /** @deprecated Use topicId. */
+        projectId?: string;
+        description?: string;
+        metadata?: JsonObject;
+    } & TopicIdentifierInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<WorkflowBranchRecord>>;
+    /**
+     * List reusable lenses for a workspace or topic scope.
+     */
+    listLenses(query: {
+        workspaceId?: string;
+        topicId?: string;
+        /** @deprecated Use topicId. */
+        projectId?: string;
+        status?: WorkflowLensStatus;
+        perspectiveType?: WorkflowLensPerspectiveType;
+    } & TopicIdentifierInput): Promise<import("./coreClient").PlatformGatewaySuccess<import("./types").ListResult<WorkflowLensRecord, "lenses">>>;
+    /**
+     * Create a reusable workflow lens.
+     */
+    createLens(input: {
+        name: string;
+        workspaceId?: string;
+        topicId?: string;
+        /** @deprecated Use topicId. */
+        projectId?: string;
+        description?: string;
+        perspectiveType: WorkflowLensPerspectiveType;
+        promptTemplates?: LensPromptTemplateReference[];
+        workflowTemplates?: LensWorkflowTemplate[];
+        taskTemplates?: LensTaskTemplate[];
+        filterCriteria?: JsonObject;
+    } & TopicIdentifierInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<WorkflowLensRecord>>;
+    /**
+     * Apply an existing lens to a topic.
+     */
+    applyLensToTopic(input: {
+        lensId: string;
+        topicId?: string;
+        /** @deprecated Use topicId. */
+        projectId?: string;
+        metadata?: JsonObject;
+    } & TopicIdentifierInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<import("./types").WorkflowLensBindingRecord>>;
+    /**
+     * Remove an applied lens from a topic.
+     */
+    removeLensFromTopic(input: {
+        lensId: string;
+        topicId?: string;
+        /** @deprecated Use topicId. */
+        projectId?: string;
+    } & TopicIdentifierInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<import("./types").WorkflowLensBindingRecord>>;
+    /**
+     * List worktrees for a topic scope.
+     */
+    listWorktrees(query: {
+        topicId?: string;
+        /** @deprecated Use topicId. */
+        projectId?: string;
+        branchId?: string;
+        status?: WorkflowWorktreeStatus;
+        track?: string;
+        executionBand?: number;
+        limit?: number;
+    } & TopicIdentifierInput): Promise<import("./coreClient").PlatformGatewaySuccess<import("./types").ListResult<WorkflowWorktreeRecord, "worktrees">>>;
+    /**
+     * List all worktrees across accessible topics.
+     */
+    listAllWorktrees(query?: {
+        status?: WorkflowWorktreeStatus;
+        track?: string;
+        executionBand?: number;
+        limit?: number;
+    }): Promise<import("./coreClient").PlatformGatewaySuccess<ListWorktreesResponse>>;
+    /**
+     * Create a workflow worktree.
+     */
+    createWorktree(input: AddWorktreeInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<WorkflowWorktreeRecord>>;
+    /**
+     * @deprecated Use createWorktree.
+     */
+    addWorktree(input: AddWorktreeInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<WorkflowWorktreeRecord>>;
+    /**
+     * Merge a worktree into the main belief line.
+     */
+    merge(worktreeId: string, input: MergeInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<MergeWorktreeResponse>>;
+    /**
+     * Activate a planning worktree.
+     */
+    activateWorktree(worktreeId: string, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<WorkflowWorktreeRecord>>;
+    /**
+     * Update targeted beliefs/questions for a worktree.
+     */
+    updateWorktreeTargets(input: UpdateWorktreeTargetsInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<WorkflowWorktreeRecord>>;
+    /**
+     * Open a pull request for a worktree.
+     */
+    openPullRequest(worktreeId: string, input: {
+        summary: string;
+        reviewers?: string[];
+        status?: "pending_review" | "changes_requested" | "approved" | "blocked";
+    }, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<OpenPullRequestResponse>>;
+    /**
+     * Push scored worktree findings into another context.
+     */
+    push(worktreeId: string, input: {
+        targetContext: string;
+        beliefIds?: string[];
+        metadata?: JsonObject;
+    }, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<PushWorktreeResponse>>;
+    /**
+     * List accessible topic contexts.
+     */
+    listTopics(query?: ListTopicsInput): Promise<import("./coreClient").PlatformGatewaySuccess<ListTopicsResponse>>;
+    /**
+     * Switch the active context by topic or project name.
+     */
+    switchTopicContext(input: SwitchTopicContextInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<SwitchTopicContextResponse>>;
+    /**
+     * Create a workflow task.
+     */
+    createTask(input: CreateTaskInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<CreateTaskResponse>>;
+    /**
+     * Complete a workflow task.
+     */
+    completeTask(taskId: string, input: CompleteTaskInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<CompleteTaskResponse>>;
+    /**
+     * Update a workflow task.
+     */
+    updateTask(taskId: string, input: UpdateTaskInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<UpdateTaskResponse>>;
+    /**
+     * @deprecated Use createBranch.
+     */
+    createPillar(input: {
+        name: string;
+        topicId?: string;
+        /** @deprecated Use topicId. */
+        projectId?: string;
+        description?: string;
+        metadata?: JsonObject;
+    } & TopicIdentifierInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<WorkflowBranchRecord>>;
+    /**
+     * @deprecated Use addWorktree.
+     */
+    createSprint(input: {
+        title: string;
+        topicId?: string;
+        /** @deprecated Use topicId. */
+        projectId?: string;
+        branchId?: string;
+        hypothesis?: string;
+        beliefIds?: string[];
+    } & TopicIdentifierInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<WorkflowWorktreeRecord>>;
+    /**
+     * @deprecated Use merge.
+     */
+    completeSprint(worktreeId: string, input: MergeInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<MergeWorktreeResponse>>;
+    /**
+     * @deprecated Use openPullRequest.
+     */
+    requestReview(worktreeId: string, input: {
+        summary: string;
+        reviewers?: string[];
+        status?: "pending_review" | "changes_requested" | "approved" | "blocked";
+    }, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<OpenPullRequestResponse>>;
+    /**
+     * @deprecated Use push.
+     */
+    publishFindings(worktreeId: string, input: {
+        targetContext: string;
+        beliefIds?: string[];
+        metadata?: JsonObject;
+    }, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<PushWorktreeResponse>>;
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@lucern/sdk",
+  "version": "0.2.0-alpha.1",
+  "description": "Lucern reasoning platform SDK. Install this one package, provide your API key, and start building in 10 minutes.",
+  "license": "UNLICENSED",
+  "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"
+    }
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsup && tsc --project tsconfig.bundle.json --declaration --emitDeclarationOnly --outDir dist",
+    "build:js": "tsup",
+    "build:dts": "tsc --project tsconfig.bundle.json --declaration --emitDeclarationOnly --outDir dist",
+    "pack:dry-run": "npm pack --dry-run",
+    "typecheck": "tsc --project tsconfig.json --noEmit"
+  },
+  "peerDependencies": {
+    "convex": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "convex": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "tsup": "^8.5.0",
+    "typescript": "^5.7.0"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "keywords": [
+    "lucern",
+    "reasoning",
+    "epistemic",
+    "beliefs",
+    "knowledge-graph",
+    "sdk",
+    "ai",
+    "agents"
+  ]
+}