convex-devtools 0.1.0

package/README.md

@@ -0,0 +1,332 @@
+# Convex DevTools
+
+<p align="center">
+  <img src="https://img.shields.io/npm/v/convex-devtools" alt="npm version">
+  <img src="https://img.shields.io/npm/l/convex-devtools" alt="license">
+  <img src="https://img.shields.io/npm/dt/convex-devtools" alt="downloads">
+</p>
+
+A standalone development tool for testing Convex queries, mutations, and actions with identity mocking, request saving, and auto-reloading schema discovery.
+
+> ⚠️ **WARNING**: This tool is intended for **local development only**. It requires admin access to your Convex deployment.
+
+## Features
+
+- 🔍 **Function Explorer** - Browse all your Convex queries, mutations, and actions in a tree view
+- 🎭 **Identity Mocking** - Test functions as different users with custom roles and claims
+- 💾 **Request Collections** - Save and organize requests like Postman
+- 📜 **History** - View and replay previous function calls
+- 🔄 **Auto-reload** - Schema updates automatically when your Convex files change
+- 📤 **Import/Export** - Share collections with your team
+
+## Quick Start
+
+### Installation
+
+```bash
+# Install globally
+npm install -g convex-devtools
+
+# Or with pnpm
+pnpm add -g convex-devtools
+
+# Or with yarn
+yarn global add convex-devtools
+
+# Or run directly with npx (no installation required)
+npx convex-devtools
+```
+
+### Setup
+
+1. Navigate to your Convex project directory
+
+2. Add the following to your `.env.local` file:
+
+```env
+CONVEX_DEVTOOLS_ENABLED=true
+CONVEX_URL=https://your-deployment.convex.cloud
+CONVEX_DEPLOY_KEY=prod:your-deploy-key-here
+```
+
+3. Get your deploy key from the [Convex Dashboard](https://dashboard.convex.dev) under **Settings → Deploy Keys**.
+
+### Running
+
+```bash
+# Run in your Convex project directory
+convex-devtools
+
+# Or specify a different directory
+convex-devtools --dir /path/to/your/project
+
+# Run on a custom port
+convex-devtools --port 3000
+
+# Don't auto-open browser
+convex-devtools --no-open
+```
+
+The tool will automatically open in your browser at `http://localhost:5173`.
+
+## CLI Options
+
+| Option                | Description                      | Default |
+| --------------------- | -------------------------------- | ------- |
+| `-p, --port <number>` | Port for the devtools server     | `5173`  |
+| `-d, --dir <path>`    | Path to Convex project directory | `.`     |
+| `--no-open`           | Don't open browser automatically | -       |
+| `-V, --version`       | Display version number           | -       |
+| `-h, --help`          | Display help information         | -       |
+
+## Identity Mocking
+
+The Identity Builder allows you to test functions as different users. You can set:
+
+- **Subject** - The user's unique identifier (e.g., Clerk user ID)
+- **Name/Email** - Display information
+- **Roles** - Array of role strings (e.g., `["super_admin", "shop_admin"]`)
+- **User Local ID** - Your app's internal user document ID
+- **Custom Claims** - Any additional JWT claims your app uses
+
+### Example Identity
+
+```json
+{
+  "subject": "clerk_user_123",
+  "name": "Test Admin",
+  "email": "admin@example.com",
+  "roles": ["super_admin"],
+  "user_local_id": "k975abc123def456"
+}
+```
+
+## Collections
+
+Save requests to collections for easy access:
+
+1. Select a function and configure its arguments
+2. Click the save icon in the request panel
+3. Choose or create a collection
+4. Give the request a descriptive name
+
+### Export/Import
+
+- Click the export icon to download your collections as JSON
+- Click the import icon to load collections from a JSON file
+- Share collections with your team via version control
+
+### Export Format
+
+The export format is a simple JSON structure:
+
+```json
+{
+  "version": "1.0",
+  "exportedAt": "2025-01-29T10:00:00.000Z",
+  "collections": [
+    {
+      "id": "abc123",
+      "name": "Product Tests",
+      "requests": [
+        {
+          "id": "def456",
+          "name": "List all products",
+          "functionPath": "products/products:list",
+          "functionType": "query",
+          "args": "{}",
+          "identity": null,
+          "savedAt": "2025-01-29T10:00:00.000Z"
+        }
+      ],
+      "createdAt": "2025-01-29T10:00:00.000Z"
+    }
+  ]
+}
+```
+
+## Programmatic Usage
+
+You can also use convex-devtools programmatically in your Node.js projects:
+
+```typescript
+import { createServer, SchemaWatcher, ConvexClient } from 'convex-devtools';
+
+// Start a schema watcher
+const schemaWatcher = new SchemaWatcher('/path/to/project');
+await schemaWatcher.start();
+
+// Create and start the server
+const server = await createServer({
+  port: 5173,
+  projectDir: '/path/to/project',
+  convexUrl: 'https://your-deployment.convex.cloud',
+  deployKey: 'prod:your-deploy-key',
+  schemaWatcher,
+});
+
+// Clean up when done
+schemaWatcher.stop();
+server.close();
+```
+
+## Development
+
+### Prerequisites
+
+- Node.js 18+
+- pnpm (recommended) or npm
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/your-username/convex-devtools.git
+cd convex-devtools
+
+# Install dependencies
+pnpm install
+
+# Run in development mode
+pnpm dev
+
+# Build for production
+pnpm build:all
+```
+
+### Project Structure
+
+```
+convex-devtools/
+├── src/
+│   ├── cli/           # CLI entry point
+│   ├── components/    # React components for the UI
+│   ├── server/        # Express server & Convex client
+│   └── stores/        # Zustand state management
+├── public/            # Static assets
+├── dist/              # Built output (generated)
+└── package.json
+```
+
+### Scripts
+
+| Script           | Description                      |
+| ---------------- | -------------------------------- |
+| `pnpm dev`       | Start development server         |
+| `pnpm build`     | Build the frontend               |
+| `pnpm build:cli` | Build the CLI                    |
+| `pnpm build:all` | Build everything for production  |
+| `pnpm typecheck` | Run TypeScript type checking     |
+| `pnpm lint`      | Run ESLint                       |
+| `pnpm preview`   | Preview production build locally |
+
+## Publishing to npm
+
+### First-time Setup
+
+1. Create an npm account at [npmjs.com](https://www.npmjs.com/signup)
+
+2. Login to npm from your terminal:
+
+   ```bash
+   npm login
+   ```
+
+3. Verify your login:
+   ```bash
+   npm whoami
+   ```
+
+### Building and Publishing
+
+```bash
+# 1. Make sure all tests pass and there are no errors
+pnpm typecheck
+pnpm lint
+
+# 2. Build the project
+pnpm build:all
+
+# 3. Update the version (choose one)
+npm version patch  # for bug fixes (0.1.0 -> 0.1.1)
+npm version minor  # for new features (0.1.0 -> 0.2.0)
+npm version major  # for breaking changes (0.1.0 -> 1.0.0)
+
+# 4. Publish to npm
+npm publish
+
+# Or for a scoped package (if using @your-org/convex-devtools)
+npm publish --access public
+```
+
+### Testing Before Publishing
+
+```bash
+# Create a tarball to see what will be published
+npm pack
+
+# This creates convex-devtools-x.x.x.tgz
+# You can inspect it or install it locally:
+npm install ./convex-devtools-0.1.0.tgz -g
+
+# Test the CLI
+convex-devtools --help
+```
+
+### Publishing a Pre-release
+
+```bash
+# For beta versions
+npm version prerelease --preid=beta
+npm publish --tag beta
+
+# Users can install with: npm install convex-devtools@beta
+```
+
+## Security Considerations
+
+- **Never use in production** - This tool has full admin access to your Convex deployment
+- **Keep your deploy key secret** - Don't commit it to version control
+- **Local development only** - The `CONVEX_DEVTOOLS_ENABLED` flag should never be set in production
+- **Use dev deploy keys when possible** - Prefer `dev:xxx` keys over `prod:xxx` keys during development
+
+## Troubleshooting
+
+### "CONVEX_DEVTOOLS_ENABLED is not set to true"
+
+Add `CONVEX_DEVTOOLS_ENABLED=true` to your `.env.local` file. This safety check ensures you don't accidentally run the devtools against production.
+
+### "Convex generated files not found"
+
+Run `npx convex dev` in your project directory first to generate the required files.
+
+### "Identity mocking is disabled"
+
+You need to set `CONVEX_DEPLOY_KEY` in your `.env.local` file. Get your deploy key from the Convex Dashboard under Settings → Deploy Keys.
+
+### Port already in use
+
+Use the `--port` flag to specify a different port:
+
+```bash
+convex-devtools --port 3001
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+MIT © [Šahzudin Mahmić]
+
+## Related Projects
+
+- [Convex](https://convex.dev) - The backend platform this tool is designed for
+- [Convex Dashboard](https://dashboard.convex.dev) - Official Convex admin dashboard

package/dist/cli/chunk-5AG6RQBI.js

@@ -0,0 +1,102 @@
+import {
+  ConvexClient
+} from "./chunk-A7PTPOQI.js";
+
+// src/server/index.ts
+import cors from "cors";
+import express from "express";
+import http from "http";
+import path from "path";
+import { fileURLToPath } from "url";
+import { WebSocket, WebSocketServer } from "ws";
+var __dirname = path.dirname(fileURLToPath(import.meta.url));
+async function createServer(config) {
+  const app = express();
+  app.use(cors());
+  app.use(express.json({ limit: "10mb" }));
+  const uiPath = path.join(__dirname, "..", "ui");
+  app.use(express.static(uiPath));
+  const convexClient = new ConvexClient(config.convexUrl, config.deployKey);
+  app.get("/api/schema", (_req, res) => {
+    const schema = config.schemaWatcher.getSchema();
+    if (!schema) {
+      res.status(503).json({ error: "Schema not yet loaded" });
+      return;
+    }
+    res.json(schema);
+  });
+  app.get("/api/health", (_req, res) => {
+    res.json({
+      status: "ok",
+      convexUrl: config.convexUrl,
+      projectDir: config.projectDir
+    });
+  });
+  app.post("/api/invoke", async (req, res) => {
+    const { functionPath, functionType, args, jwtToken } = req.body;
+    if (!functionPath || !functionType) {
+      res.status(400).json({ error: "Missing functionPath or functionType" });
+      return;
+    }
+    try {
+      const startTime = Date.now();
+      const result = await convexClient.invoke(
+        functionPath,
+        functionType,
+        args || {},
+        { jwtToken }
+      );
+      const duration = Date.now() - startTime;
+      res.json({
+        success: true,
+        result,
+        duration,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    } catch (error) {
+      res.json({
+        success: false,
+        error: {
+          message: error.message,
+          code: error.code,
+          data: error.data
+        },
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    }
+  });
+  const server = http.createServer(app);
+  const wss = new WebSocketServer({ server, path: "/ws" });
+  const clients = /* @__PURE__ */ new Set();
+  wss.on("connection", (ws) => {
+    clients.add(ws);
+    const schema = config.schemaWatcher.getSchema();
+    if (schema) {
+      ws.send(JSON.stringify({ type: "schema", data: schema }));
+    }
+    ws.on("close", () => {
+      clients.delete(ws);
+    });
+  });
+  config.schemaWatcher.on("schema-updated", (schema) => {
+    const message = JSON.stringify({ type: "schema", data: schema });
+    for (const client of clients) {
+      if (client.readyState === WebSocket.OPEN) {
+        client.send(message);
+      }
+    }
+  });
+  app.get("*", (_req, res) => {
+    res.sendFile(path.join(uiPath, "index.html"));
+  });
+  return new Promise((resolve) => {
+    server.listen(config.port, () => {
+      resolve(server);
+    });
+  });
+}
+
+export {
+  createServer
+};
+//# sourceMappingURL=chunk-5AG6RQBI.js.map

package/dist/cli/chunk-5AG6RQBI.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/server/index.ts"],"sourcesContent":["import cors from 'cors';\nimport express from 'express';\nimport http from 'http';\nimport path from 'path';\nimport { fileURLToPath } from 'url';\nimport { WebSocket, WebSocketServer } from 'ws';\nimport { ConvexClient } from './convex-client.js';\nimport { SchemaWatcher } from './schema-watcher.js';\n\nconst __dirname = path.dirname(fileURLToPath(import.meta.url));\n\nexport interface ServerConfig {\n  port: number;\n  projectDir: string;\n  convexUrl: string;\n  deployKey: string;\n  schemaWatcher: SchemaWatcher;\n}\n\nexport async function createServer(config: ServerConfig): Promise<http.Server> {\n  const app = express();\n\n  app.use(cors());\n  app.use(express.json({ limit: '10mb' }));\n\n  // Serve static UI files in production\n  const uiPath = path.join(__dirname, '..', 'ui');\n  app.use(express.static(uiPath));\n\n  // Create Convex client\n  const convexClient = new ConvexClient(config.convexUrl, config.deployKey);\n\n  // API Routes\n  app.get('/api/schema', (_req, res) => {\n    const schema = config.schemaWatcher.getSchema();\n    if (!schema) {\n      res.status(503).json({ error: 'Schema not yet loaded' });\n      return;\n    }\n    res.json(schema);\n  });\n\n  app.get('/api/health', (_req, res) => {\n    res.json({\n      status: 'ok',\n      convexUrl: config.convexUrl,\n      projectDir: config.projectDir,\n    });\n  });\n\n  // Invoke a function\n  app.post('/api/invoke', async (req, res) => {\n    const { functionPath, functionType, args, jwtToken } = req.body;\n\n    if (!functionPath || !functionType) {\n      res.status(400).json({ error: 'Missing functionPath or functionType' });\n      return;\n    }\n\n    try {\n      const startTime = Date.now();\n      const result = await convexClient.invoke(\n        functionPath,\n        functionType,\n        args || {},\n        { jwtToken }\n      );\n      const duration = Date.now() - startTime;\n\n      res.json({\n        success: true,\n        result,\n        duration,\n        timestamp: new Date().toISOString(),\n      });\n    } catch (error: any) {\n      res.json({\n        success: false,\n        error: {\n          message: error.message,\n          code: error.code,\n          data: error.data,\n        },\n        timestamp: new Date().toISOString(),\n      });\n    }\n  });\n\n  // Create HTTP server\n  const server = http.createServer(app);\n\n  // WebSocket for real-time schema updates\n  const wss = new WebSocketServer({ server, path: '/ws' });\n\n  const clients = new Set<WebSocket>();\n\n  wss.on('connection', (ws) => {\n    clients.add(ws);\n\n    // Send initial schema\n    const schema = config.schemaWatcher.getSchema();\n    if (schema) {\n      ws.send(JSON.stringify({ type: 'schema', data: schema }));\n    }\n\n    ws.on('close', () => {\n      clients.delete(ws);\n    });\n  });\n\n  // Broadcast schema updates\n  config.schemaWatcher.on('schema-updated', (schema) => {\n    const message = JSON.stringify({ type: 'schema', data: schema });\n    for (const client of clients) {\n      if (client.readyState === WebSocket.OPEN) {\n        client.send(message);\n      }\n    }\n  });\n\n  // SPA fallback - serve index.html for non-API routes\n  app.get('*', (_req, res) => {\n    res.sendFile(path.join(uiPath, 'index.html'));\n  });\n\n  return new Promise((resolve) => {\n    server.listen(config.port, () => {\n      resolve(server);\n    });\n  });\n}\n"],"mappings":"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","names":[]}

package/dist/cli/chunk-A7PTPOQI.js

@@ -0,0 +1,137 @@
+// src/server/convex-client.ts
+var ConvexClient = class {
+  baseUrl;
+  deployKey;
+  constructor(convexUrl, deployKey) {
+    this.baseUrl = convexUrl;
+    this.deployKey = deployKey;
+  }
+  async invoke(functionPath, functionType, args = {}, options) {
+    const normalizedPath = this.normalizeFunctionPath(functionPath);
+    const endpoint = this.getEndpoint(functionType);
+    const url = `${this.baseUrl}/${endpoint}`;
+    const headers = {
+      "Content-Type": "application/json",
+      "Convex-Client": "convex-devtools-0.1.0"
+    };
+    if (options?.jwtToken) {
+      headers["Authorization"] = `Bearer ${options.jwtToken}`;
+      console.log("[ConvexClient] Using JWT token authentication");
+    } else if (this.deployKey) {
+      headers["Authorization"] = `Convex ${this.deployKey}`;
+      console.log("[ConvexClient] Using deploy key (admin) authentication");
+    }
+    const body = {
+      path: normalizedPath,
+      args: this.encodeArgs(args),
+      format: "json"
+    };
+    const response = await fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body)
+    });
+    if (!response.ok) {
+      const errorText = await response.text();
+      let errorData;
+      try {
+        errorData = JSON.parse(errorText);
+      } catch {
+        errorData = { message: errorText };
+      }
+      const error = new Error(errorData.message || `HTTP ${response.status}`);
+      error.code = errorData.code;
+      error.data = errorData;
+      throw error;
+    }
+    const result = await response.json();
+    return this.decodeResult(result);
+  }
+  normalizeFunctionPath(path) {
+    if (path.includes(":")) {
+      return path;
+    }
+    if (path.includes(".")) {
+      const parts2 = path.split(".");
+      const funcName = parts2.pop();
+      return `${parts2.join("/")}:${funcName}`;
+    }
+    const parts = path.split("/");
+    if (parts.length > 1) {
+      const funcName = parts.pop();
+      return `${parts.join("/")}:${funcName}`;
+    }
+    return path;
+  }
+  getEndpoint(functionType) {
+    switch (functionType) {
+      case "query":
+        return "api/query";
+      case "mutation":
+        return "api/mutation";
+      case "action":
+        return "api/action";
+    }
+  }
+  encodeArgs(args) {
+    return this.convertToConvexJson(args);
+  }
+  convertToConvexJson(value) {
+    if (value === null || value === void 0) {
+      return value;
+    }
+    if (Array.isArray(value)) {
+      return value.map((v) => this.convertToConvexJson(v));
+    }
+    if (typeof value === "object") {
+      const obj = value;
+      if ("$type" in obj) {
+        return obj;
+      }
+      const converted = {};
+      for (const [k, v] of Object.entries(obj)) {
+        converted[k] = this.convertToConvexJson(v);
+      }
+      return converted;
+    }
+    if (typeof value === "bigint") {
+      return { $type: "bigint", value: value.toString() };
+    }
+    return value;
+  }
+  decodeResult(result) {
+    return this.convertFromConvexJson(result);
+  }
+  convertFromConvexJson(value) {
+    if (value === null || value === void 0) {
+      return value;
+    }
+    if (Array.isArray(value)) {
+      return value.map((v) => this.convertFromConvexJson(v));
+    }
+    if (typeof value === "object") {
+      const obj = value;
+      if ("$type" in obj) {
+        switch (obj.$type) {
+          case "bigint":
+            return BigInt(obj.value);
+          case "bytes":
+            return new Uint8Array(obj.value);
+          default:
+            return obj;
+        }
+      }
+      const result = {};
+      for (const [k, v] of Object.entries(obj)) {
+        result[k] = this.convertFromConvexJson(v);
+      }
+      return result;
+    }
+    return value;
+  }
+};
+
+export {
+  ConvexClient
+};
+//# sourceMappingURL=chunk-A7PTPOQI.js.map

package/dist/cli/chunk-A7PTPOQI.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/server/convex-client.ts"],"sourcesContent":["/**\n * Convex HTTP Client wrapper for DevTools\n * Supports two authentication methods:\n * 1. Deploy key - runs as admin (for admin operations)\n * 2. JWT token - runs as the authenticated user (from your auth provider like Clerk)\n */\n\nexport interface UserIdentity {\n  subject: string;\n  issuer?: string;\n  tokenIdentifier?: string;\n  name?: string;\n  email?: string;\n  pictureUrl?: string;\n  // Custom claims\n  [key: string]: unknown;\n}\n\nexport interface InvokeOptions {\n  identity?: UserIdentity;\n  jwtToken?: string; // Real JWT token from auth provider\n}\n\nexport class ConvexClient {\n  private baseUrl: string;\n  private deployKey: string;\n\n  constructor(convexUrl: string, deployKey: string) {\n    // Convert deployment URL to HTTP endpoint\n    // e.g., https://happy-otter-123.convex.cloud -> https://happy-otter-123.convex.cloud\n    this.baseUrl = convexUrl;\n    this.deployKey = deployKey;\n  }\n\n  async invoke(\n    functionPath: string,\n    functionType: 'query' | 'mutation' | 'action',\n    args: Record<string, unknown> = {},\n    options?: InvokeOptions\n  ): Promise<unknown> {\n    // Normalize function path: module/submodule:functionName\n    const normalizedPath = this.normalizeFunctionPath(functionPath);\n\n    // Build the request\n    const endpoint = this.getEndpoint(functionType);\n    const url = `${this.baseUrl}/${endpoint}`;\n\n    // Build headers\n    const headers: Record<string, string> = {\n      'Content-Type': 'application/json',\n      'Convex-Client': 'convex-devtools-0.1.0',\n    };\n\n    // Authentication priority:\n    // 1. JWT token (authenticates as the user who owns the token)\n    // 2. Deploy key (authenticates as admin)\n    // 3. No auth (unauthenticated request)\n    if (options?.jwtToken) {\n      // Use Bearer token auth - this is what the Convex HTTP API expects for user auth\n      headers['Authorization'] = `Bearer ${options.jwtToken}`;\n      console.log('[ConvexClient] Using JWT token authentication');\n    } else if (this.deployKey) {\n      // Deploy key gives admin access but cannot impersonate users\n      headers['Authorization'] = `Convex ${this.deployKey}`;\n      console.log('[ConvexClient] Using deploy key (admin) authentication');\n    }\n    // Without any auth, calls will be unauthenticated\n\n    const body = {\n      path: normalizedPath,\n      args: this.encodeArgs(args),\n      format: 'json',\n    };\n\n    const response = await fetch(url, {\n      method: 'POST',\n      headers,\n      body: JSON.stringify(body),\n    });\n\n    if (!response.ok) {\n      const errorText = await response.text();\n      let errorData;\n      try {\n        errorData = JSON.parse(errorText);\n      } catch {\n        errorData = { message: errorText };\n      }\n\n      const error = new Error(errorData.message || `HTTP ${response.status}`);\n      (error as any).code = errorData.code;\n      (error as any).data = errorData;\n      throw error;\n    }\n\n    const result = await response.json();\n    return this.decodeResult(result);\n  }\n\n  private normalizeFunctionPath(path: string): string {\n    // Convert various formats to Convex function path format\n    // Input: \"products/products:list\" or \"products.products.list\" or \"products/products/list\"\n    // Output: \"products/products:list\"\n\n    // Already in correct format\n    if (path.includes(':')) {\n      return path;\n    }\n\n    // Dot notation: products.products.list -> products/products:list\n    if (path.includes('.')) {\n      const parts = path.split('.');\n      const funcName = parts.pop()!;\n      return `${parts.join('/')}:${funcName}`;\n    }\n\n    // Slash only: products/products/list -> products/products:list\n    const parts = path.split('/');\n    if (parts.length > 1) {\n      const funcName = parts.pop()!;\n      return `${parts.join('/')}:${funcName}`;\n    }\n\n    return path;\n  }\n\n  private getEndpoint(functionType: 'query' | 'mutation' | 'action'): string {\n    switch (functionType) {\n      case 'query':\n        return 'api/query';\n      case 'mutation':\n        return 'api/mutation';\n      case 'action':\n        return 'api/action';\n    }\n  }\n\n  private encodeArgs(args: Record<string, unknown>): Record<string, unknown> {\n    // Convex uses a special encoding format for complex types\n    // For now, we'll pass through JSON-serializable values\n    // Special handling for Convex types like Id, etc.\n    return this.convertToConvexJson(args) as Record<string, unknown>;\n  }\n\n  private convertToConvexJson(value: unknown): unknown {\n    if (value === null || value === undefined) {\n      return value;\n    }\n\n    if (Array.isArray(value)) {\n      return value.map((v) => this.convertToConvexJson(v));\n    }\n\n    if (typeof value === 'object') {\n      const obj = value as Record<string, unknown>;\n\n      // Check for special $type markers (Convex encoded JSON)\n      if ('$type' in obj) {\n        return obj; // Already encoded\n      }\n\n      // Regular object\n      const converted: Record<string, unknown> = {};\n      for (const [k, v] of Object.entries(obj)) {\n        converted[k] = this.convertToConvexJson(v);\n      }\n      return converted;\n    }\n\n    // Handle BigInt\n    if (typeof value === 'bigint') {\n      return { $type: 'bigint', value: value.toString() };\n    }\n\n    return value;\n  }\n\n  private decodeResult(result: unknown): unknown {\n    // Decode Convex-specific types back to JavaScript\n    return this.convertFromConvexJson(result);\n  }\n\n  private convertFromConvexJson(value: unknown): unknown {\n    if (value === null || value === undefined) {\n      return value;\n    }\n\n    if (Array.isArray(value)) {\n      return value.map((v) => this.convertFromConvexJson(v));\n    }\n\n    if (typeof value === 'object') {\n      const obj = value as Record<string, unknown>;\n\n      // Check for special $type markers\n      if ('$type' in obj) {\n        switch (obj.$type) {\n          case 'bigint':\n            return BigInt(obj.value as string);\n          case 'bytes':\n            return new Uint8Array(obj.value as number[]);\n          default:\n            return obj;\n        }\n      }\n\n      // Regular object\n      const result: Record<string, unknown> = {};\n      for (const [k, v] of Object.entries(obj)) {\n        result[k] = this.convertFromConvexJson(v);\n      }\n      return result;\n    }\n\n    return value;\n  }\n}\n"],"mappings":";AAuBO,IAAM,eAAN,MAAmB;AAAA,EAChB;AAAA,EACA;AAAA,EAER,YAAY,WAAmB,WAAmB;AAGhD,SAAK,UAAU;AACf,SAAK,YAAY;AAAA,EACnB;AAAA,EAEA,MAAM,OACJ,cACA,cACA,OAAgC,CAAC,GACjC,SACkB;AAElB,UAAM,iBAAiB,KAAK,sBAAsB,YAAY;AAG9D,UAAM,WAAW,KAAK,YAAY,YAAY;AAC9C,UAAM,MAAM,GAAG,KAAK,OAAO,IAAI,QAAQ;AAGvC,UAAM,UAAkC;AAAA,MACtC,gBAAgB;AAAA,MAChB,iBAAiB;AAAA,IACnB;AAMA,QAAI,SAAS,UAAU;AAErB,cAAQ,eAAe,IAAI,UAAU,QAAQ,QAAQ;AACrD,cAAQ,IAAI,+CAA+C;AAAA,IAC7D,WAAW,KAAK,WAAW;AAEzB,cAAQ,eAAe,IAAI,UAAU,KAAK,SAAS;AACnD,cAAQ,IAAI,wDAAwD;AAAA,IACtE;AAGA,UAAM,OAAO;AAAA,MACX,MAAM;AAAA,MACN,MAAM,KAAK,WAAW,IAAI;AAAA,MAC1B,QAAQ;AAAA,IACV;AAEA,UAAM,WAAW,MAAM,MAAM,KAAK;AAAA,MAChC,QAAQ;AAAA,MACR;AAAA,MACA,MAAM,KAAK,UAAU,IAAI;AAAA,IAC3B,CAAC;AAED,QAAI,CAAC,SAAS,IAAI;AAChB,YAAM,YAAY,MAAM,SAAS,KAAK;AACtC,UAAI;AACJ,UAAI;AACF,oBAAY,KAAK,MAAM,SAAS;AAAA,MAClC,QAAQ;AACN,oBAAY,EAAE,SAAS,UAAU;AAAA,MACnC;AAEA,YAAM,QAAQ,IAAI,MAAM,UAAU,WAAW,QAAQ,SAAS,MAAM,EAAE;AACtE,MAAC,MAAc,OAAO,UAAU;AAChC,MAAC,MAAc,OAAO;AACtB,YAAM;AAAA,IACR;AAEA,UAAM,SAAS,MAAM,SAAS,KAAK;AACnC,WAAO,KAAK,aAAa,MAAM;AAAA,EACjC;AAAA,EAEQ,sBAAsB,MAAsB;AAMlD,QAAI,KAAK,SAAS,GAAG,GAAG;AACtB,aAAO;AAAA,IACT;AAGA,QAAI,KAAK,SAAS,GAAG,GAAG;AACtB,YAAMA,SAAQ,KAAK,MAAM,GAAG;AAC5B,YAAM,WAAWA,OAAM,IAAI;AAC3B,aAAO,GAAGA,OAAM,KAAK,GAAG,CAAC,IAAI,QAAQ;AAAA,IACvC;AAGA,UAAM,QAAQ,KAAK,MAAM,GAAG;AAC5B,QAAI,MAAM,SAAS,GAAG;AACpB,YAAM,WAAW,MAAM,IAAI;AAC3B,aAAO,GAAG,MAAM,KAAK,GAAG,CAAC,IAAI,QAAQ;AAAA,IACvC;AAEA,WAAO;AAAA,EACT;AAAA,EAEQ,YAAY,cAAuD;AACzE,YAAQ,cAAc;AAAA,MACpB,KAAK;AACH,eAAO;AAAA,MACT,KAAK;AACH,eAAO;AAAA,MACT,KAAK;AACH,eAAO;AAAA,IACX;AAAA,EACF;AAAA,EAEQ,WAAW,MAAwD;AAIzE,WAAO,KAAK,oBAAoB,IAAI;AAAA,EACtC;AAAA,EAEQ,oBAAoB,OAAyB;AACnD,QAAI,UAAU,QAAQ,UAAU,QAAW;AACzC,aAAO;AAAA,IACT;AAEA,QAAI,MAAM,QAAQ,KAAK,GAAG;AACxB,aAAO,MAAM,IAAI,CAAC,MAAM,KAAK,oBAAoB,CAAC,CAAC;AAAA,IACrD;AAEA,QAAI,OAAO,UAAU,UAAU;AAC7B,YAAM,MAAM;AAGZ,UAAI,WAAW,KAAK;AAClB,eAAO;AAAA,MACT;AAGA,YAAM,YAAqC,CAAC;AAC5C,iBAAW,CAAC,GAAG,CAAC,KAAK,OAAO,QAAQ,GAAG,GAAG;AACxC,kBAAU,CAAC,IAAI,KAAK,oBAAoB,CAAC;AAAA,MAC3C;AACA,aAAO;AAAA,IACT;AAGA,QAAI,OAAO,UAAU,UAAU;AAC7B,aAAO,EAAE,OAAO,UAAU,OAAO,MAAM,SAAS,EAAE;AAAA,IACpD;AAEA,WAAO;AAAA,EACT;AAAA,EAEQ,aAAa,QAA0B;AAE7C,WAAO,KAAK,sBAAsB,MAAM;AAAA,EAC1C;AAAA,EAEQ,sBAAsB,OAAyB;AACrD,QAAI,UAAU,QAAQ,UAAU,QAAW;AACzC,aAAO;AAAA,IACT;AAEA,QAAI,MAAM,QAAQ,KAAK,GAAG;AACxB,aAAO,MAAM,IAAI,CAAC,MAAM,KAAK,sBAAsB,CAAC,CAAC;AAAA,IACvD;AAEA,QAAI,OAAO,UAAU,UAAU;AAC7B,YAAM,MAAM;AAGZ,UAAI,WAAW,KAAK;AAClB,gBAAQ,IAAI,OAAO;AAAA,UACjB,KAAK;AACH,mBAAO,OAAO,IAAI,KAAe;AAAA,UACnC,KAAK;AACH,mBAAO,IAAI,WAAW,IAAI,KAAiB;AAAA,UAC7C;AACE,mBAAO;AAAA,QACX;AAAA,MACF;AAGA,YAAM,SAAkC,CAAC;AACzC,iBAAW,CAAC,GAAG,CAAC,KAAK,OAAO,QAAQ,GAAG,GAAG;AACxC,eAAO,CAAC,IAAI,KAAK,sBAAsB,CAAC;AAAA,MAC1C;AACA,aAAO;AAAA,IACT;AAEA,WAAO;AAAA,EACT;AACF;","names":["parts"]}