@rnsk/toolkits 0.0.10 → 0.0.12

package/dist/toolkits/convex/manifest.js

@@ -0,0 +1,33 @@
+import { defineToolkit, defineTool } from '../../core/define.js';
+import { inferToolScope } from '../../core/scope.js';
+import { CONVEX_ICON } from './icon.js';
+import { convexTools } from './tools/index.js';
+export default defineToolkit({
+    id: 'convex',
+    displayName: 'Convex',
+    shortDescription: 'Projects, deployments, functions, and logs.',
+    category: 'Developer Tools & DevOps',
+    icon: CONVEX_ICON,
+    auth: {
+        type: 'bearer_token',
+        tokenField: 'convexToken',
+        provider: {
+            connectDescription: 'Connect Convex with a team access token. Create one from the Convex dashboard under Team Settings > Access Tokens. The same token works for management (api.convex.dev) and deployment-scoped calls (*.convex.cloud, sent with the Convex auth prefix).',
+        },
+    },
+    allowedHosts: ['api.convex.dev', 'convex.cloud'],
+    tools: convexTools.map((entry) => defineTool({
+        name: entry.name,
+        description: entry.description,
+        tool: entry.tool,
+        requiredAuth: entry.requiredAuth,
+        scope: entry.scope ?? inferToolScope(entry.name),
+    })),
+    meta: {
+        since: '0.0.10',
+        homepage: 'https://www.convex.dev',
+        docsUrl: 'https://docs.convex.dev/management-api/overview',
+        apiDocsUrl: 'https://api.convex.dev/v1/openapi.json',
+    },
+});
+//# sourceMappingURL=manifest.js.map

package/dist/toolkits/convex/tools/client.d.ts

@@ -0,0 +1,28 @@
+export declare class ConvexApiError extends Error {
+    status: number;
+    details: unknown;
+    constructor(message: string, status: number, details: unknown);
+}
+/** Convex Management API: Bearer team token against api.convex.dev. */
+export declare function convexMgmt(convexToken: string, method: 'GET' | 'POST' | 'PATCH' | 'DELETE', path: string, options?: {
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+}): Promise<any>;
+/**
+ * Deployment-scoped APIs on {deploymentUrl}: queries, timestamps, log streams.
+ * These use the `Convex ` auth prefix; team tokens are accepted as well as deploy keys.
+ */
+export declare function convexDeployment(convexToken: string, deploymentUrl: string, method: 'GET' | 'POST', path: string, body?: unknown): Promise<any>;
+export declare function toConvexError(error: unknown, label: string): {
+    error: string;
+    details: any;
+    message?: undefined;
+} | {
+    error: string;
+    message: string;
+    details?: undefined;
+};
+export declare function requireToken(convexToken: string | undefined): {
+    error: string;
+} | null;
+//# sourceMappingURL=client.d.ts.map

package/dist/toolkits/convex/tools/client.js

@@ -0,0 +1,85 @@
+// @ts-nocheck
+const MGMT_BASE = 'https://api.convex.dev/v1';
+export class ConvexApiError extends Error {
+    status;
+    details;
+    constructor(message, status, details) {
+        super(message);
+        this.status = status;
+        this.details = details;
+    }
+}
+function appendQuery(url, query) {
+    if (!query)
+        return;
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined)
+            continue;
+        url.searchParams.set(key, String(value));
+    }
+}
+async function parseBody(response) {
+    const text = await response.text();
+    if (!text)
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { raw: text };
+    }
+}
+/** Convex Management API: Bearer team token against api.convex.dev. */
+export async function convexMgmt(convexToken, method, path, options) {
+    const url = new URL(`${MGMT_BASE}${path}`);
+    appendQuery(url, options?.query);
+    const response = await fetch(url.toString(), {
+        method,
+        headers: {
+            Authorization: `Bearer ${convexToken}`,
+            'Content-Type': 'application/json',
+        },
+        body: options?.body !== undefined ? JSON.stringify(options.body) : undefined,
+    });
+    const data = await parseBody(response);
+    if (!response.ok) {
+        throw new ConvexApiError(`Convex API request failed${data?.message ? `: ${data.message}` : ''}`, response.status, data);
+    }
+    return data;
+}
+/**
+ * Deployment-scoped APIs on {deploymentUrl}: queries, timestamps, log streams.
+ * These use the `Convex ` auth prefix; team tokens are accepted as well as deploy keys.
+ */
+export async function convexDeployment(convexToken, deploymentUrl, method, path, body) {
+    const base = deploymentUrl.replace(/\/$/, '');
+    const response = await fetch(`${base}${path}`, {
+        method,
+        headers: {
+            Authorization: `Convex ${convexToken}`,
+            'Content-Type': 'application/json',
+        },
+        body: body !== undefined ? JSON.stringify(body) : method === 'POST' ? '{}' : undefined,
+    });
+    const data = await parseBody(response);
+    if (!response.ok) {
+        throw new ConvexApiError(`Convex deployment request failed${data?.message ? `: ${data.message}` : ''}`, response.status, data);
+    }
+    return data;
+}
+export function toConvexError(error, label) {
+    if (error?.details !== undefined) {
+        return { error: label, details: error.details };
+    }
+    return {
+        error: label.replace('Failed', 'Error').replace('failed', 'error'),
+        message: error instanceof Error ? error.message : 'Unknown error',
+    };
+}
+export function requireToken(convexToken) {
+    if (!convexToken) {
+        return { error: 'Convex API token is required. Connect Convex first.' };
+    }
+    return null;
+}
+//# sourceMappingURL=client.js.map

package/dist/toolkits/convex/tools/deploy-keys.d.ts

@@ -0,0 +1,10 @@
+export declare const convexCreateDeployKey: import("ai").Tool<{
+    name: string;
+    deploymentName: string;
+    convexToken?: string | undefined;
+}, any>;
+export declare const convexListDeployKeys: import("ai").Tool<{
+    deploymentName: string;
+    convexToken?: string | undefined;
+}, any>;
+//# sourceMappingURL=deploy-keys.d.ts.map

package/dist/toolkits/convex/tools/deploy-keys.js

@@ -0,0 +1,46 @@
+// @ts-nocheck
+import { tool } from 'ai';
+import { z } from 'zod';
+import { convexMgmt, toConvexError, requireToken } from './client.js';
+const tokenField = z.string().optional().describe('Injected by system; do not provide');
+export const convexCreateDeployKey = tool({
+    description: 'Create a deploy key for CLI development or deployment workflows. The key grants admin access — store it securely and confirm with the user first.',
+    inputSchema: z.object({
+        convexToken: tokenField,
+        deploymentName: z.string().describe('Deployment to create the key for'),
+        name: z.string().describe("Human-readable key name, e.g. 'ci-cd-key'"),
+    }),
+    execute: async ({ convexToken, deploymentName, name }) => {
+        try {
+            const missing = requireToken(convexToken);
+            if (missing)
+                return missing;
+            return await convexMgmt(convexToken, 'POST', `/deployments/${deploymentName}/create_deploy_key`, {
+                body: { name },
+            });
+        }
+        catch (error) {
+            return toConvexError(error, 'Failed to create deploy key');
+        }
+    },
+});
+export const convexListDeployKeys = tool({
+    description: 'List deploy keys for a deployment (names, creators, creation and last-used times). Key values are not returned — create a new key if one is lost.',
+    inputSchema: z.object({
+        convexToken: tokenField,
+        deploymentName: z.string().describe('Deployment to list keys for'),
+    }),
+    execute: async ({ convexToken, deploymentName }) => {
+        try {
+            const missing = requireToken(convexToken);
+            if (missing)
+                return missing;
+            const data = await convexMgmt(convexToken, 'GET', `/deployments/${deploymentName}/list_deploy_keys`);
+            return Array.isArray(data) ? { deploy_keys: data } : data;
+        }
+        catch (error) {
+            return toConvexError(error, 'Failed to list deploy keys');
+        }
+    },
+});
+//# sourceMappingURL=deploy-keys.js.map

package/dist/toolkits/convex/tools/deployments.d.ts

@@ -0,0 +1,35 @@
+export declare const convexCreateDeployment: import("ai").Tool<{
+    type: "custom" | "dev" | "prod";
+    projectId: number;
+    region?: string | undefined;
+    convexToken?: string | undefined;
+    deploymentClass?: string | undefined;
+    reference?: string | undefined;
+}, any>;
+export declare const convexListDeployments: import("ai").Tool<{
+    projectId: number;
+    isDefault?: boolean | undefined;
+    deploymentType?: string | undefined;
+    convexToken?: string | undefined;
+    includeLocal?: boolean | undefined;
+}, any>;
+export declare const convexGetDeployment: import("ai").Tool<{
+    deploymentName: string;
+    convexToken?: string | undefined;
+}, any>;
+export declare const convexUpdateDeployment: import("ai").Tool<{
+    deploymentName: string;
+    convexToken?: string | undefined;
+    reference?: string | undefined;
+    dashboardEditConfirmation?: boolean | undefined;
+}, any>;
+export declare const convexDeleteDeployment: import("ai").Tool<{
+    deploymentName: string;
+    convexToken?: string | undefined;
+}, {
+    error: string;
+} | {
+    success: boolean;
+    deployment_name: string;
+}>;
+//# sourceMappingURL=deployments.d.ts.map

package/dist/toolkits/convex/tools/deployments.js

@@ -0,0 +1,126 @@
+// @ts-nocheck
+import { tool } from 'ai';
+import { z } from 'zod';
+import { convexMgmt, toConvexError, requireToken } from './client.js';
+const tokenField = z.string().optional().describe('Injected by system; do not provide');
+export const convexCreateDeployment = tool({
+    description: 'Create a dev, prod, or custom deployment in a project, with optional class, reference, and region. Returns the deployment name and URL.',
+    inputSchema: z.object({
+        convexToken: tokenField,
+        projectId: z.number().describe('Numeric project ID'),
+        type: z.enum(['dev', 'prod', 'custom']).describe('Deployment type'),
+        deploymentClass: z.string().optional().describe('Deployment class (defaults to the team default)'),
+        reference: z.string().optional().describe('Unique reference within the project (auto-generated when omitted)'),
+        region: z.string().optional().describe('Hosting region (defaults to the team default)'),
+    }),
+    execute: async ({ convexToken, projectId, type, deploymentClass, reference, region }) => {
+        try {
+            const missing = requireToken(convexToken);
+            if (missing)
+                return missing;
+            return await convexMgmt(convexToken, 'POST', `/projects/${projectId}/create_deployment`, {
+                body: {
+                    type,
+                    class: deploymentClass,
+                    reference,
+                    region,
+                },
+            });
+        }
+        catch (error) {
+            return toConvexError(error, 'Failed to create deployment');
+        }
+    },
+});
+export const convexListDeployments = tool({
+    description: 'List deployments for a project (production, preview, and optionally local), with filters for default status, type, and local inclusion.',
+    inputSchema: z.object({
+        convexToken: tokenField,
+        projectId: z.number().describe('Numeric project ID'),
+        isDefault: z.boolean().optional().describe('True for default deployments only, false for non-default only'),
+        includeLocal: z.boolean().optional().describe('Include local deployments (only your own)'),
+        deploymentType: z.string().optional().describe('Filter by deployment type'),
+    }),
+    execute: async ({ convexToken, projectId, isDefault, includeLocal, deploymentType }) => {
+        try {
+            const missing = requireToken(convexToken);
+            if (missing)
+                return missing;
+            const data = await convexMgmt(convexToken, 'GET', `/projects/${projectId}/list_deployments`, {
+                query: {
+                    isDefault,
+                    includeLocal,
+                    deploymentType,
+                },
+            });
+            return Array.isArray(data) ? { items: data } : data;
+        }
+        catch (error) {
+            return toConvexError(error, 'Failed to list deployments');
+        }
+    },
+});
+export const convexGetDeployment = tool({
+    description: 'Get details for a deployment by name: configuration, region, creation time, and status.',
+    inputSchema: z.object({
+        convexToken: tokenField,
+        deploymentName: z.string().describe("Deployment name, e.g. 'quiet-llama-744'"),
+    }),
+    execute: async ({ convexToken, deploymentName }) => {
+        try {
+            const missing = requireToken(convexToken);
+            if (missing)
+                return missing;
+            return await convexMgmt(convexToken, 'GET', `/deployments/${deploymentName}`);
+        }
+        catch (error) {
+            return toConvexError(error, 'Failed to get deployment');
+        }
+    },
+});
+export const convexUpdateDeployment = tool({
+    description: 'Update deployment settings (reference, dashboard edit confirmation). Only provided fields are modified.',
+    inputSchema: z.object({
+        convexToken: tokenField,
+        deploymentName: z.string().describe('Deployment name to update'),
+        reference: z.string().optional().describe('Unique reference (3-100 chars, lowercase, numbers, - and /)'),
+        dashboardEditConfirmation: z.boolean().optional().describe('Require dashboard confirmation before edits'),
+    }),
+    execute: async ({ convexToken, deploymentName, reference, dashboardEditConfirmation }) => {
+        try {
+            const missing = requireToken(convexToken);
+            if (missing)
+                return missing;
+            const data = await convexMgmt(convexToken, 'PATCH', `/deployments/${deploymentName}`, {
+                body: {
+                    reference,
+                    dashboardEditConfirmation,
+                },
+            });
+            return data && Object.keys(data).length ? data : { success: true, deployment_name: deploymentName };
+        }
+        catch (error) {
+            return toConvexError(error, 'Failed to update deployment');
+        }
+    },
+});
+export const convexDeleteDeployment = tool({
+    description: 'Permanently delete a deployment and all its data and files. Irreversible — confirm with the user first.',
+    inputSchema: z.object({
+        convexToken: tokenField,
+        deploymentName: z.string().describe('Deployment name to delete'),
+    }),
+    execute: async ({ convexToken, deploymentName }) => {
+        try {
+            const missing = requireToken(convexToken);
+            if (missing)
+                return missing;
+            await convexMgmt(convexToken, 'POST', `/deployments/${deploymentName}/delete`, { body: {} });
+            return { success: true, deployment_name: deploymentName };
+        }
+        catch (error) {
+            return toConvexError(error, 'Failed to delete deployment');
+        }
+    },
+});
+//# sourceMappingURL=deployments.js.map

package/dist/toolkits/convex/tools/domains.d.ts

@@ -0,0 +1,7 @@
+export declare const convexDeleteCustomDomain: import("ai").Tool<{
+    domain: string;
+    deploymentName: string;
+    requestDestination: "convexCloud" | "convexSite";
+    convexToken?: string | undefined;
+}, any>;
+//# sourceMappingURL=domains.d.ts.map

package/dist/toolkits/convex/tools/domains.js

@@ -0,0 +1,29 @@
+// @ts-nocheck
+import { tool } from 'ai';
+import { z } from 'zod';
+import { convexMgmt, toConvexError, requireToken } from './client.js';
+const tokenField = z.string().optional().describe('Injected by system; do not provide');
+export const convexDeleteCustomDomain = tool({
+    description: 'Remove a custom domain from a deployment. Specify whether it serves the Convex Cloud backend or the Convex Site frontend. Confirm with the user first.',
+    inputSchema: z.object({
+        convexToken: tokenField,
+        deploymentName: z.string().describe('Deployment the domain is configured on'),
+        domain: z.string().describe("Custom domain to delete, e.g. 'app.mydomain.com'"),
+        requestDestination: z.enum(['convexCloud', 'convexSite']).describe('Domain destination to remove'),
+    }),
+    execute: async ({ convexToken, deploymentName, domain, requestDestination }) => {
+        try {
+            const missing = requireToken(convexToken);
+            if (missing)
+                return missing;
+            const data = await convexMgmt(convexToken, 'POST', `/deployments/${deploymentName}/delete_custom_domain`, {
+                body: { requestDestination, domain },
+            });
+            return data && Object.keys(data).length ? data : { success: true, domain };
+        }
+        catch (error) {
+            return toConvexError(error, 'Failed to delete custom domain');
+        }
+    },
+});
+//# sourceMappingURL=domains.js.map

package/dist/toolkits/convex/tools/functions.d.ts

@@ -0,0 +1,14 @@
+export declare const convexExecuteQueryBatch: import("ai").Tool<{
+    deploymentUrl: string;
+    queries: {
+        path: string;
+        args?: Record<string, any> | undefined;
+        format?: string | undefined;
+    }[];
+    convexToken?: string | undefined;
+}, any>;
+export declare const convexGetQueryTimestamp: import("ai").Tool<{
+    deploymentName: string;
+    convexToken?: string | undefined;
+}, any>;
+//# sourceMappingURL=functions.d.ts.map

package/dist/toolkits/convex/tools/functions.js

@@ -0,0 +1,49 @@
+// @ts-nocheck
+import { tool } from 'ai';
+import { z } from 'zod';
+import { convexDeployment, toConvexError, requireToken } from './client.js';
+const tokenField = z.string().optional().describe('Injected by system; do not provide');
+const queryItem = z.object({
+    path: z.string().describe("Query function path, e.g. 'messages:list'"),
+    args: z.record(z.any()).optional().describe('Named arguments (empty object when none)'),
+    format: z.string().optional().describe("Output format (only 'json' is supported)"),
+});
+export const convexExecuteQueryBatch = tool({
+    description: 'Run multiple query functions against a deployment in one batch call. Results come back in request order with per-query status, value, and log lines.',
+    inputSchema: z.object({
+        convexToken: tokenField,
+        deploymentUrl: z.string().describe("Full deployment URL, e.g. 'https://quiet-llama-744.convex.cloud'"),
+        queries: z.array(queryItem).min(1).describe('Queries to execute in order'),
+    }),
+    execute: async ({ convexToken, deploymentUrl, queries }) => {
+        try {
+            const missing = requireToken(convexToken);
+            if (missing)
+                return missing;
+            const data = await convexDeployment(convexToken, deploymentUrl, 'POST', '/api/query_batch', queries);
+            return Array.isArray(data) ? { results: data } : data;
+        }
+        catch (error) {
+            return toConvexError(error, 'Failed to execute query batch');
+        }
+    },
+});
+export const convexGetQueryTimestamp = tool({
+    description: 'Get the latest query timestamp (base64) for a deployment. Use for consistent reads or auditing the deployment state.',
+    inputSchema: z.object({
+        convexToken: tokenField,
+        deploymentName: z.string().describe("Deployment name, e.g. 'quiet-llama-744'"),
+    }),
+    execute: async ({ convexToken, deploymentName }) => {
+        try {
+            const missing = requireToken(convexToken);
+            if (missing)
+                return missing;
+            return await convexDeployment(convexToken, `https://${deploymentName}.convex.cloud`, 'POST', '/api/query_ts');
+        }
+        catch (error) {
+            return toConvexError(error, 'Failed to get query timestamp');
+        }
+    },
+});
+//# sourceMappingURL=functions.js.map

package/dist/toolkits/convex/tools/index.d.ts

@@ -0,0 +1,176 @@
+import { convexCreateProject, convexListProjects, convexGetProjectById, convexGetProjectBySlug, convexDeleteProject } from './projects.js';
+import { convexCreateDeployment, convexListDeployments, convexGetDeployment, convexUpdateDeployment, convexDeleteDeployment } from './deployments.js';
+import { convexCreateDeployKey, convexListDeployKeys } from './deploy-keys.js';
+import { convexDeleteCustomDomain } from './domains.js';
+import { convexGetTokenDetails, convexListDeploymentClasses, convexListDeploymentRegions } from './teams.js';
+import { convexExecuteQueryBatch, convexGetQueryTimestamp } from './functions.js';
+import { convexListLogStreams } from './logging.js';
+export { convexCreateProject, convexListProjects, convexGetProjectById, convexGetProjectBySlug, convexDeleteProject, convexCreateDeployment, convexListDeployments, convexGetDeployment, convexUpdateDeployment, convexDeleteDeployment, convexCreateDeployKey, convexListDeployKeys, convexDeleteCustomDomain, convexGetTokenDetails, convexListDeploymentClasses, convexListDeploymentRegions, convexExecuteQueryBatch, convexGetQueryTimestamp, convexListLogStreams, };
+export declare const convexTools: ({
+    name: string;
+    description: string;
+    tool: import("ai").Tool<{
+        teamId: string | number;
+        projectName: string;
+        deploymentType?: string | undefined;
+        convexToken?: string | undefined;
+        deploymentClass?: string | undefined;
+        deploymentRegion?: string | undefined;
+    }, any>;
+    requiredAuth: "convexToken";
+    scope: "write";
+} | {
+    name: string;
+    description: string;
+    tool: import("ai").Tool<{
+        teamId: string | number;
+        convexToken?: string | undefined;
+    }, any>;
+    requiredAuth: "convexToken";
+    scope: "read";
+} | {
+    name: string;
+    description: string;
+    tool: import("ai").Tool<{
+        projectId: number;
+        convexToken?: string | undefined;
+    }, any>;
+    requiredAuth: "convexToken";
+    scope: "read";
+} | {
+    name: string;
+    description: string;
+    tool: import("ai").Tool<{
+        teamIdOrSlug: string | number;
+        projectSlug: string;
+        convexToken?: string | undefined;
+    }, any>;
+    requiredAuth: "convexToken";
+    scope: "read";
+} | {
+    name: string;
+    description: string;
+    tool: import("ai").Tool<{
+        projectId: number;
+        convexToken?: string | undefined;
+    }, {
+        error: string;
+    } | {
+        success: boolean;
+        project_id: number;
+    }>;
+    requiredAuth: "convexToken";
+    scope: "delete";
+} | {
+    name: string;
+    description: string;
+    tool: import("ai").Tool<{
+        type: "custom" | "dev" | "prod";
+        projectId: number;
+        region?: string | undefined;
+        convexToken?: string | undefined;
+        deploymentClass?: string | undefined;
+        reference?: string | undefined;
+    }, any>;
+    requiredAuth: "convexToken";
+    scope: "write";
+} | {
+    name: string;
+    description: string;
+    tool: import("ai").Tool<{
+        projectId: number;
+        isDefault?: boolean | undefined;
+        deploymentType?: string | undefined;
+        convexToken?: string | undefined;
+        includeLocal?: boolean | undefined;
+    }, any>;
+    requiredAuth: "convexToken";
+    scope: "read";
+} | {
+    name: string;
+    description: string;
+    tool: import("ai").Tool<{
+        deploymentName: string;
+        convexToken?: string | undefined;
+    }, any>;
+    requiredAuth: "convexToken";
+    scope: "read";
+} | {
+    name: string;
+    description: string;
+    tool: import("ai").Tool<{
+        deploymentName: string;
+        convexToken?: string | undefined;
+        reference?: string | undefined;
+        dashboardEditConfirmation?: boolean | undefined;
+    }, any>;
+    requiredAuth: "convexToken";
+    scope: "write";
+} | {
+    name: string;
+    description: string;
+    tool: import("ai").Tool<{
+        deploymentName: string;
+        convexToken?: string | undefined;
+    }, {
+        error: string;
+    } | {
+        success: boolean;
+        deployment_name: string;
+    }>;
+    requiredAuth: "convexToken";
+    scope: "delete";
+} | {
+    name: string;
+    description: string;
+    tool: import("ai").Tool<{
+        name: string;
+        deploymentName: string;
+        convexToken?: string | undefined;
+    }, any>;
+    requiredAuth: "convexToken";
+    scope: "write";
+} | {
+    name: string;
+    description: string;
+    tool: import("ai").Tool<{
+        domain: string;
+        deploymentName: string;
+        requestDestination: "convexCloud" | "convexSite";
+        convexToken?: string | undefined;
+    }, any>;
+    requiredAuth: "convexToken";
+    scope: "delete";
+} | {
+    name: string;
+    description: string;
+    tool: import("ai").Tool<{
+        convexToken?: string | undefined;
+    }, any>;
+    requiredAuth: "convexToken";
+    scope: "read";
+} | {
+    name: string;
+    description: string;
+    tool: import("ai").Tool<{
+        deploymentUrl: string;
+        queries: {
+            path: string;
+            args?: Record<string, any> | undefined;
+            format?: string | undefined;
+        }[];
+        convexToken?: string | undefined;
+    }, any>;
+    requiredAuth: "convexToken";
+    scope: "read";
+} | {
+    name: string;
+    description: string;
+    tool: import("ai").Tool<{
+        deploymentUrl: string;
+        convexToken?: string | undefined;
+    }, any>;
+    requiredAuth: "convexToken";
+    scope: "read";
+})[];
+//# sourceMappingURL=index.d.ts.map