opentool 0.7.8 → 0.7.10

package/README.md

@@ -5,12 +5,14 @@
 
 Build serverless TypeScript tools that work with AI assistants, handle crypto payments, and deploy to AWS Lambda automatically.
 
-**For LLMs/AI Code Generation:** [`dist/opentool-context.ts`](./scripts/build-context.ts)
+**For LLMs/AI Code Generation:** [`context/opentool-context.ts`](./context/opentool-context.ts)
 
 ## What is it?
 
 OpenTool lets you write simple TypeScript functions that can be called by other agents, monetized with crypto payments, and deployed as serverless functions. It handles the boring stuff like:
 
+Tools are either Public or Private. Public tools are accessible to the public and are monetized with crypto payments using x402. Private tools are accessible only to the app developer and are mainly for trading and onchain interaction use cases.
+
 ## Installation
 
 ```bash
@@ -65,9 +67,62 @@ npx opentool validate
 npx opentool dev
 ```
 
-### 4. Add x402 payments (optional)
+### Private tools: GET-only and POST-only
+
+For private tools, say for internal trading apps:
+
+- GET-only (scheduled default profile)
+- POST-only (one-off, parameterized with Zod)
+
+GET-only (scheduled default)
+
+```typescript
+// tools/aave-stake.ts
+export const profile = {
+  description: "Stake 100 USDC daily at 12:00 UTC",
+  fixedAmount: "100",
+  tokenSymbol: "USDC",
+  schedule: { cron: "0 12 * * *", enabled: false },
+  limits: { concurrency: 1, dailyCap: 1 },
+};
+
+export async function GET(_req: Request) {
+  const amount = profile.fixedAmount;
+  return Response.json({
+    ok: true,
+    action: "stake",
+    amount,
+    token: profile.tokenSymbol,
+  });
+}
+```
+
+POST-only (one-off)
+
+```typescript
+// tools/aave-unstake.ts
+import { z } from "zod";
+
+export const schema = z.object({
+  amount: z.string(),
+  token: z.string().default("USDC"),
+});
+
+export async function POST(req: Request) {
+  const body = await req.json();
+  const { amount, token } = schema.parse(body);
+  return Response.json({ ok: true, action: "unstake", amount, token });
+}
+```
+
+### Cron schedules (`profile.schedule`)
+
+- GET-only tools require `profile.schedule` with a standard 5–6 field cron expression (e.g., `0 12 * * *` or `0 0 ? * MON-FRI *`).
+- Build validates the cron shape and emits `.well-known/opentool/cron.json` capturing each scheduled tool (`toolName`, `toolPath`, `scheduleExpression`). Enabled defaults to `false` even if authors set it to `true` in code. Deployment targets can translate these cron strings to their provider format (e.g., EventBridge) downstream.
+
+### Public tools: Add x402 payments (optional)
 
-Protect your tools with crypto payments using x402:
+Protect your public tools with crypto payments using x402:
 
 ```typescript
 // tools/premium-report.ts

package/dist/cli/index.d.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { h as Metadata, I as InternalToolDefinition } from '../validate-BrOwtVYW.js';
-export { G as GenerateMetadataOptions, j as GenerateMetadataResult, V as ValidateOptions, g as generateMetadata, a as generateMetadataCommand, l as loadAndValidateTools, v as validateCommand, k as validateFullCommand } from '../validate-BrOwtVYW.js';
+import { M as Metadata, I as InternalToolDefinition } from '../validate-uetwG5jo.js';
+export { G as GenerateMetadataOptions, a as GenerateMetadataResult, V as ValidateOptions, b as generateMetadata, g as generateMetadataCommand, l as loadAndValidateTools, v as validateCommand, c as validateFullCommand } from '../validate-uetwG5jo.js';
 import 'zod';
 import '../x402/index.js';
 import 'viem';
@@ -17,6 +17,7 @@ interface BuildArtifacts {
     tools: InternalToolDefinition[];
     compiledTools: CompiledToolArtifact[];
     workflowBundles: WorkflowBundleArtifact | null;
+    cronManifestPath: string | null;
 }
 interface CompiledToolArtifact {
     name: string;

package/dist/cli/index.js

@@ -932,6 +932,40 @@ var HTTP_METHODS = [
   "OPTIONS"
 ];
 
+// src/utils/schedule.ts
+var CRON_WRAPPED_REGEX = /^cron\((.*)\)$/i;
+var CRON_TOKEN_REGEX = /^[A-Za-z0-9*?/,\-#L]+$/;
+function normalizeScheduleExpression(raw, context) {
+  const value = raw?.trim();
+  if (!value) {
+    throw new Error(`${context}: profile.schedule.cron must be a non-empty string`);
+  }
+  const cronBody = extractCronBody(value);
+  const cronFields = cronBody.trim().split(/\s+/).filter(Boolean);
+  if (cronFields.length !== 5 && cronFields.length !== 6) {
+    throw new Error(`${context}: cron expression must have 5 or 6 fields (got ${cronFields.length})`);
+  }
+  validateCronTokens(cronFields, context);
+  return {
+    type: "cron",
+    expression: cronFields.join(" ")
+  };
+}
+function extractCronBody(value) {
+  const cronMatch = CRON_WRAPPED_REGEX.exec(value);
+  if (cronMatch) {
+    return (cronMatch[1] ?? "").trim();
+  }
+  return value;
+}
+function validateCronTokens(fields, context) {
+  fields.forEach((token, idx) => {
+    if (!CRON_TOKEN_REGEX.test(token)) {
+      throw new Error(`${context}: invalid cron token "${token}" at position ${idx + 1}`);
+    }
+  });
+}
+
 // src/cli/validate.ts
 var SUPPORTED_EXTENSIONS = [
   ".ts",
@@ -1008,6 +1042,12 @@ async function loadAndValidateTools(toolsDir, options = {}) {
   if (fs4.existsSync(tempDir)) {
     fs4.rmSync(tempDir, { recursive: true, force: true });
   }
+  const kebabCase = /^[a-z0-9]+(?:-[a-z0-9]+)*\.[a-z]+$/;
+  for (const f of files) {
+    if (!kebabCase.test(f)) {
+      throw new Error(`Tool filename must be kebab-case: ${f}`);
+    }
+  }
   const entryPoints = files.map((file) => path5.join(toolsDir, file));
   const { outDir, cleanup } = await transpileWithEsbuild({
     entryPoints,
@@ -1032,6 +1072,35 @@ async function loadAndValidateTools(toolsDir, options = {}) {
       const inputSchemaRaw = schema ? toJsonSchema(toolName, schema) : void 0;
       const inputSchema = normalizeInputSchema(inputSchemaRaw);
       const httpHandlersRaw = collectHttpHandlers(toolModule, file);
+      const hasGET = typeof toolModule.GET === "function";
+      const hasPOST = typeof toolModule.POST === "function";
+      const otherMethods = HTTP_METHODS.filter((m) => m !== "GET" && m !== "POST").filter(
+        (m) => typeof toolModule[m] === "function"
+      );
+      if (otherMethods.length > 0) {
+        throw new Error(
+          `${file} must not export ${otherMethods.join(", ")}. Only one of GET or POST is allowed.`
+        );
+      }
+      if (hasGET === hasPOST) {
+        throw new Error(`${file}: export exactly one of GET or POST`);
+      }
+      let normalizedSchedule = null;
+      if (hasGET) {
+        const schedule = toolModule?.profile?.schedule;
+        if (!schedule || typeof schedule?.cron !== "string" || schedule.cron.trim().length === 0) {
+          throw new Error(`${file}: GET tools require profile.schedule { cron }`);
+        }
+        normalizedSchedule = normalizeScheduleExpression(schedule.cron, file);
+        if (typeof schedule.enabled === "boolean") {
+          normalizedSchedule.authoredEnabled = schedule.enabled;
+        }
+      }
+      if (hasPOST) {
+        if (!schema) {
+          throw new Error(`${file}: POST tools must export a Zod schema as 'schema'`);
+        }
+      }
       const httpHandlers = [...httpHandlersRaw];
       if (httpHandlers.length === 0) {
         throw new Error(
@@ -1082,7 +1151,9 @@ async function loadAndValidateTools(toolsDir, options = {}) {
         filename: toBaseName(file),
         sourcePath: path5.join(toolsDir, file),
         handler: async (params) => adapter(params),
-        payment: paymentExport ?? null
+        payment: paymentExport ?? null,
+        schedule: normalizedSchedule,
+        profileDescription: typeof toolModule?.profile?.description === "string" ? toolModule.profile?.description ?? null : null
       };
       tools.push(tool);
     }
@@ -1304,6 +1375,11 @@ async function buildProject(options) {
     projectRoot,
     outputDir
   });
+  const cronManifestPath = await writeCronManifest({
+    tools,
+    compiledTools,
+    outputDir
+  });
   const workflowBundles = await buildWorkflowsIfPresent({
     projectRoot,
     outputDir
@@ -1326,7 +1402,8 @@ async function buildProject(options) {
     defaultsApplied,
     tools,
     compiledTools,
-    workflowBundles
+    workflowBundles,
+    cronManifestPath
   };
 }
 async function emitTools(tools, config) {
@@ -1469,6 +1546,55 @@ async function writeMcpServer(options) {
   fs4.writeFileSync(serverPath, serverCode);
   fs4.chmodSync(serverPath, 493);
 }
+function writeCronManifest(options) {
+  const scheduledTools = options.tools.filter((tool) => tool.schedule?.expression);
+  const manifestDir = path5.join(options.outputDir, ".well-known", "opentool");
+  const manifestPath = path5.join(manifestDir, "cron.json");
+  if (scheduledTools.length === 0) {
+    if (fs4.existsSync(manifestPath)) {
+      fs4.rmSync(manifestPath);
+    }
+    return null;
+  }
+  const entries = scheduledTools.map((tool) => {
+    const schedule = tool.schedule;
+    if (!schedule) {
+      throw new Error(`Internal error: missing schedule for tool ${tool.filename}`);
+    }
+    const compiled = options.compiledTools.find(
+      (artifact) => artifact.filename === tool.filename
+    );
+    if (!compiled) {
+      throw new Error(`Internal error: missing compiled artifact for ${tool.filename}`);
+    }
+    const toolName = tool.metadata?.name ?? tool.filename;
+    const description = tool.metadata?.description ?? tool.profileDescription ?? void 0;
+    const payloadPath = compiled.modulePath.replace(/\\/g, "/");
+    const entry = {
+      toolName,
+      scheduleType: schedule.type,
+      scheduleExpression: schedule.expression,
+      enabledDefault: false,
+      ...schedule.authoredEnabled !== void 0 ? { authoredEnabled: schedule.authoredEnabled } : {},
+      payload: {
+        toolPath: payloadPath,
+        httpMethod: "GET"
+      }
+    };
+    if (description !== void 0) {
+      entry.description = description;
+    }
+    return entry;
+  });
+  const manifest = {
+    version: 1,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    entries
+  };
+  fs4.mkdirSync(manifestDir, { recursive: true });
+  fs4.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+  return manifestPath;
+}
 function logBuildSummary(artifacts, options) {
   const end = timestamp();
   console.log(`[${end}] Build completed successfully!`);
@@ -1485,6 +1611,9 @@ function logBuildSummary(artifacts, options) {
     console.log(`     - ${tool.name} [${methods}]${walletBadge}`);
   });
   console.log("  \u2022 metadata.json (registry artifact)");
+  if (artifacts.cronManifestPath) {
+    console.log("  \u2022 .well-known/opentool/cron.json (cron manifest)");
+  }
   if (artifacts.workflowBundles) {
     console.log("  \u2022 .well-known/workflow/v1/ (workflow bundles)");
     console.log("     - flow.js");