@o-zakstam/voltagent-convex 1.1.2 → 1.1.3

package/package.json

@@ -1,46 +1,45 @@
 {
   "name": "@o-zakstam/voltagent-convex",
   "description": "VoltAgent Convex - Convex storage adapter component for VoltAgent",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "type": "module",
-  "main": "dist/index.cjs",
-  "module": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "types": "./dist/client/index.d.ts",
+  "module": "./dist/client/index.js",
   "exports": {
+    "./package.json": "./package.json",
     ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
     },
     "./api": {
-      "import": {
-        "types": "./dist/client/index.d.ts",
-        "default": "./dist/client/index.js"
-      },
-      "require": {
-        "types": "./dist/client/index.d.cts",
-        "default": "./dist/client/index.cjs"
-      }
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
     },
-    "./convex.config": "./convex/convex.config.ts"
+    "./_generated/component.js": {
+      "types": "./dist/component/_generated/component.d.ts"
+    },
+    "./convex.config": {
+      "types": "./dist/component/convex.config.d.ts",
+      "default": "./dist/component/convex.config.js"
+    },
+    "./convex.config.js": {
+      "types": "./dist/component/convex.config.d.ts",
+      "default": "./dist/component/convex.config.js"
+    }
   },
   "files": [
     "dist",
-    "convex"
+    "src"
   ],
   "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "build": "tsc --project ./tsconfig.build.json",
+    "dev:build": "chokidar 'tsconfig*.json' 'src/**/*.ts' -i '**/*.test.ts' -c 'convex codegen --component-dir ./src/component && npm run build' --initial",
     "lint": "biome check .",
     "lint:fix": "biome check . --write",
     "test": "vitest --reporter=hanging-process --reporter=default --typecheck",
     "test:coverage": "vitest run --coverage --typecheck",
-    "prepublishOnly": "npm run build",
+    "prepare": "npm run build",
     "release": "semantic-release"
   },
   "devDependencies": {
@@ -51,9 +50,9 @@
     "@voltagent/core": "^2.0.2",
     "@voltagent/logger": "^2.0.2",
     "ai": "^6.0.0",
+    "chokidar-cli": "^3.0.0",
     "convex": "^1.21.0",
     "semantic-release": "^25.0.2",
-    "tsup": "^8.3.5",
     "typescript": "^5.7.2",
     "vitest": "^3.2.4"
   },

package/src/client/defineVoltAgentAPI.ts

@@ -0,0 +1,365 @@
+/**
+ * VoltAgent API Generator
+ *
+ * This function generates public Convex query/mutation functions that wrap
+ * the VoltAgent component's internal functions. This allows external HTTP
+ * clients to call the functions via ConvexHttpClient.
+ *
+ * Usage:
+ * ```typescript
+ * // convex/voltagent.ts
+ * import { components } from "./_generated/api";
+ * import { defineVoltAgentAPI } from "@voltagent/convex/api";
+ *
+ * export const {
+ *   createConversation,
+ *   getConversation,
+ *   // ... other functions
+ * } = defineVoltAgentAPI(components.voltagent);
+ * ```
+ */
+import {
+  queryGeneric,
+  mutationGeneric,
+  type ApiFromModules,
+} from "convex/server";
+import { v } from "convex/values";
+import type { VoltAgentComponent } from "./types.js";
+
+/**
+ * Define the VoltAgent API functions.
+ *
+ * @param component - The VoltAgent component reference (components.voltagent)
+ * @returns An object containing all VoltAgent API functions
+ */
+export function defineVoltAgentAPI(component: VoltAgentComponent) {
+  // ============================================================================
+  // Conversation Functions
+  // ============================================================================
+
+  const createConversation = mutationGeneric({
+    args: {
+      id: v.string(),
+      resourceId: v.string(),
+      userId: v.string(),
+      title: v.string(),
+      metadata: v.any(),
+    },
+    handler: async (ctx, args) => {
+      return ctx.runMutation(component.conversations.create, args);
+    },
+  });
+
+  const getConversation = queryGeneric({
+    args: { id: v.string() },
+    handler: async (ctx, args) => {
+      return ctx.runQuery(component.conversations.get, args);
+    },
+  });
+
+  const getConversations = queryGeneric({
+    args: { resourceId: v.string() },
+    handler: async (ctx, args) => {
+      return ctx.runQuery(component.conversations.getByResourceId, args);
+    },
+  });
+
+  const getConversationsByUserId = queryGeneric({
+    args: {
+      userId: v.string(),
+      limit: v.optional(v.number()),
+      offset: v.optional(v.number()),
+      orderBy: v.optional(v.string()),
+      orderDirection: v.optional(v.string()),
+    },
+    handler: async (ctx, args) => {
+      return ctx.runQuery(component.conversations.getByUserId, args);
+    },
+  });
+
+  const queryConversations = queryGeneric({
+    args: {
+      userId: v.optional(v.string()),
+      resourceId: v.optional(v.string()),
+      limit: v.optional(v.number()),
+      offset: v.optional(v.number()),
+      orderBy: v.optional(v.string()),
+      orderDirection: v.optional(v.string()),
+    },
+    handler: async (ctx, args) => {
+      return ctx.runQuery(component.conversations.queryConversations, args);
+    },
+  });
+
+  const updateConversation = mutationGeneric({
+    args: {
+      id: v.string(),
+      title: v.optional(v.string()),
+      resourceId: v.optional(v.string()),
+      metadata: v.optional(v.any()),
+    },
+    handler: async (ctx, args) => {
+      return ctx.runMutation(component.conversations.update, args);
+    },
+  });
+
+  const deleteConversation = mutationGeneric({
+    args: { id: v.string() },
+    handler: async (ctx, args) => {
+      return ctx.runMutation(component.conversations.remove, args);
+    },
+  });
+
+  // ============================================================================
+  // Message Functions
+  // ============================================================================
+
+  const addMessage = mutationGeneric({
+    args: {
+      id: v.string(),
+      conversationId: v.string(),
+      userId: v.string(),
+      role: v.string(),
+      parts: v.any(),
+      metadata: v.optional(v.any()),
+    },
+    handler: async (ctx, args) => {
+      return ctx.runMutation(component.messages.add, args);
+    },
+  });
+
+  const addMessages = mutationGeneric({
+    args: {
+      messages: v.array(
+        v.object({
+          id: v.string(),
+          conversationId: v.string(),
+          userId: v.string(),
+          role: v.string(),
+          parts: v.any(),
+          metadata: v.optional(v.any()),
+        }),
+      ),
+    },
+    handler: async (ctx, args) => {
+      return ctx.runMutation(component.messages.addMany, args);
+    },
+  });
+
+  const getMessages = queryGeneric({
+    args: {
+      userId: v.string(),
+      conversationId: v.string(),
+      limit: v.optional(v.number()),
+      before: v.optional(v.string()),
+      after: v.optional(v.string()),
+      roles: v.optional(v.array(v.string())),
+    },
+    handler: async (ctx, args) => {
+      return ctx.runQuery(component.messages.get, args);
+    },
+  });
+
+  const clearMessages = mutationGeneric({
+    args: {
+      userId: v.string(),
+      conversationId: v.optional(v.string()),
+    },
+    handler: async (ctx, args) => {
+      return ctx.runMutation(component.messages.clear, args);
+    },
+  });
+
+  // ============================================================================
+  // Conversation Steps Functions
+  // ============================================================================
+
+  const saveConversationSteps = mutationGeneric({
+    args: {
+      steps: v.array(
+        v.object({
+          id: v.string(),
+          conversationId: v.string(),
+          userId: v.string(),
+          agentId: v.string(),
+          agentName: v.optional(v.string()),
+          operationId: v.optional(v.string()),
+          stepIndex: v.number(),
+          type: v.string(),
+          role: v.string(),
+          content: v.optional(v.string()),
+          arguments: v.optional(v.any()),
+          result: v.optional(v.any()),
+          usage: v.optional(v.any()),
+          subAgentId: v.optional(v.string()),
+          subAgentName: v.optional(v.string()),
+          createdAt: v.optional(v.string()),
+        }),
+      ),
+    },
+    handler: async (ctx, args) => {
+      return ctx.runMutation(component.steps.save, args);
+    },
+  });
+
+  const getConversationSteps = queryGeneric({
+    args: {
+      userId: v.string(),
+      conversationId: v.string(),
+      limit: v.optional(v.number()),
+      operationId: v.optional(v.string()),
+    },
+    handler: async (ctx, args) => {
+      return ctx.runQuery(component.steps.get, args);
+    },
+  });
+
+  // ============================================================================
+  // Working Memory Functions
+  // ============================================================================
+
+  const getWorkingMemory = queryGeneric({
+    args: {
+      conversationId: v.optional(v.string()),
+      userId: v.optional(v.string()),
+      scope: v.string(),
+    },
+    handler: async (ctx, args) => {
+      return ctx.runQuery(component.workingMemory.get, args);
+    },
+  });
+
+  const setWorkingMemory = mutationGeneric({
+    args: {
+      conversationId: v.optional(v.string()),
+      userId: v.optional(v.string()),
+      content: v.string(),
+      scope: v.string(),
+    },
+    handler: async (ctx, args) => {
+      return ctx.runMutation(component.workingMemory.set, args);
+    },
+  });
+
+  const deleteWorkingMemory = mutationGeneric({
+    args: {
+      conversationId: v.optional(v.string()),
+      userId: v.optional(v.string()),
+      scope: v.string(),
+    },
+    handler: async (ctx, args) => {
+      return ctx.runMutation(component.workingMemory.remove, args);
+    },
+  });
+
+  // ============================================================================
+  // Workflow State Functions
+  // ============================================================================
+
+  const getWorkflowState = queryGeneric({
+    args: { executionId: v.string() },
+    handler: async (ctx, args) => {
+      return ctx.runQuery(component.workflows.get, args);
+    },
+  });
+
+  const queryWorkflowRuns = queryGeneric({
+    args: {
+      workflowId: v.optional(v.string()),
+      status: v.optional(v.string()),
+      from: v.optional(v.string()),
+      to: v.optional(v.string()),
+      limit: v.optional(v.number()),
+      offset: v.optional(v.number()),
+    },
+    handler: async (ctx, args) => {
+      return ctx.runQuery(component.workflows.queryRuns, args);
+    },
+  });
+
+  const setWorkflowState = mutationGeneric({
+    args: {
+      executionId: v.string(),
+      workflowId: v.string(),
+      workflowName: v.string(),
+      status: v.string(),
+      input: v.optional(v.any()),
+      context: v.optional(v.any()),
+      suspension: v.optional(v.any()),
+      events: v.optional(v.any()),
+      output: v.optional(v.any()),
+      cancellation: v.optional(v.any()),
+      userId: v.optional(v.string()),
+      conversationId: v.optional(v.string()),
+      metadata: v.optional(v.any()),
+      createdAt: v.string(),
+      updatedAt: v.string(),
+    },
+    handler: async (ctx, args) => {
+      return ctx.runMutation(component.workflows.set, args);
+    },
+  });
+
+  const updateWorkflowState = mutationGeneric({
+    args: {
+      executionId: v.string(),
+      status: v.optional(v.string()),
+      suspension: v.optional(v.any()),
+      events: v.optional(v.any()),
+      output: v.optional(v.any()),
+      cancellation: v.optional(v.any()),
+      metadata: v.optional(v.any()),
+    },
+    handler: async (ctx, args) => {
+      return ctx.runMutation(component.workflows.update, args);
+    },
+  });
+
+  const getSuspendedWorkflowStates = queryGeneric({
+    args: { workflowId: v.string() },
+    handler: async (ctx, args) => {
+      return ctx.runQuery(component.workflows.getSuspended, args);
+    },
+  });
+
+  return {
+    // Conversations
+    createConversation,
+    getConversation,
+    getConversations,
+    getConversationsByUserId,
+    queryConversations,
+    updateConversation,
+    deleteConversation,
+    // Messages
+    addMessage,
+    addMessages,
+    getMessages,
+    clearMessages,
+    // Conversation Steps
+    saveConversationSteps,
+    getConversationSteps,
+    // Working Memory
+    getWorkingMemory,
+    setWorkingMemory,
+    deleteWorkingMemory,
+    // Workflow State
+    getWorkflowState,
+    queryWorkflowRuns,
+    setWorkflowState,
+    updateWorkflowState,
+    getSuspendedWorkflowStates,
+  };
+}
+
+/**
+ * Type for the VoltAgent API when used with ApiFromModules.
+ *
+ * Usage:
+ * ```typescript
+ * import type { VoltAgentAPI } from "@voltagent/convex/api";
+ * ```
+ */
+export type VoltAgentAPI = ApiFromModules<{
+  voltagent: ReturnType<typeof defineVoltAgentAPI>;
+}>["voltagent"];

package/src/client/index.ts

@@ -0,0 +1,8 @@
+/**
+ * VoltAgent Convex Client API
+ *
+ * This module exports the defineVoltAgentAPI function and related types
+ * for creating public wrapper functions around the VoltAgent component.
+ */
+export { defineVoltAgentAPI, type VoltAgentAPI } from "./defineVoltAgentAPI.js";
+export { type VoltAgentComponent } from "./types.js";

package/src/client/types.ts

@@ -0,0 +1,14 @@
+/**
+ * VoltAgent Convex Component API Types
+ *
+ * These types define the structure of the VoltAgent component's API,
+ * allowing type-safe access to component functions.
+ */
+
+import type { ComponentApi } from "../component/_generated/component.js";
+
+/**
+ * The VoltAgent Component API type.
+ * This matches the structure of `components.voltagent` after installing the component.
+ */
+export type VoltAgentComponent = ComponentApi;

package/src/component/_generated/api.ts

@@ -0,0 +1,60 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type * as conversations from "../conversations.js";
+import type * as messages from "../messages.js";
+import type * as steps from "../steps.js";
+import type * as validators from "../validators.js";
+import type * as workflows from "../workflows.js";
+import type * as workingMemory from "../workingMemory.js";
+
+import type {
+  ApiFromModules,
+  FilterApi,
+  FunctionReference,
+} from "convex/server";
+import { anyApi, componentsGeneric } from "convex/server";
+
+const fullApi: ApiFromModules<{
+  conversations: typeof conversations;
+  messages: typeof messages;
+  steps: typeof steps;
+  validators: typeof validators;
+  workflows: typeof workflows;
+  workingMemory: typeof workingMemory;
+}> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
+export const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+> = anyApi as any;
+
+export const components = componentsGeneric() as unknown as {};