@surfjs/zod 0.2.0

package/README.md

@@ -0,0 +1,140 @@
+# @surfjs/zod
+
+Zod schema integration for [Surf.js](https://surf.codes) — define commands with Zod instead of raw `ParamSchema`.
+
+## Why?
+
+Surf commands use a `ParamSchema` format to define parameters. This works, but if you're already using Zod in your project, you'd rather write schemas once and get both validation and TypeScript inference from a single source of truth.
+
+`@surfjs/zod` lets you do exactly that.
+
+## Install
+
+```bash
+npm install @surfjs/zod zod
+```
+
+## Usage
+
+### Before: Raw ParamSchema
+
+```ts
+import { createSurf } from '@surfjs/core';
+
+const surf = createSurf({
+  name: 'my-store',
+  commands: {
+    search: {
+      description: 'Search products',
+      params: {
+        query: { type: 'string', required: true, description: 'Search query' },
+        limit: { type: 'number', required: false, default: 20 },
+        category: {
+          type: 'string',
+          required: false,
+          enum: ['electronics', 'clothing', 'books'],
+        },
+      },
+      // params is Record<string, unknown> — no inference
+      run: async (params) => {
+        const query = params.query as string;
+        const limit = (params.limit as number) ?? 20;
+        return { results: [] };
+      },
+    },
+  },
+});
+```
+
+### After: defineZodCommand
+
+```ts
+import { z } from 'zod';
+import { createSurf } from '@surfjs/core';
+import { defineZodCommand } from '@surfjs/zod';
+
+const surf = createSurf({
+  name: 'my-store',
+  commands: {
+    search: defineZodCommand({
+      description: 'Search products',
+      params: z.object({
+        query: z.string().describe('Search query'),
+        limit: z.number().int().min(1).max(100).optional().default(20),
+        category: z.enum(['electronics', 'clothing', 'books']).optional(),
+      }),
+      // params are fully typed: { query: string; limit: number; category?: 'electronics' | 'clothing' | 'books' }
+      run: async ({ query, limit, category }) => {
+        return { results: [] };
+      },
+    }),
+  },
+});
+```
+
+## API
+
+### `defineZodCommand(config)`
+
+Defines a Surf command using a Zod object schema for parameters. Returns a standard `CommandDefinition` that can be used anywhere Surf expects one.
+
+The Zod schema is converted to Surf's `ParamSchema` format at runtime, so the manifest, DevUI, and agents all see native Surf types.
+
+### `zodToSurfParams(schema)`
+
+Lower-level utility that converts a `z.object({...})` schema to `Record<string, ParamSchema>`. Useful if you want the conversion without the full command definition.
+
+```ts
+import { z } from 'zod';
+import { zodToSurfParams } from '@surfjs/zod';
+
+const params = zodToSurfParams(
+  z.object({
+    name: z.string(),
+    age: z.number().optional(),
+  }),
+);
+// { name: { type: 'string', required: true }, age: { type: 'number', required: false } }
+```
+
+### `zodValidator(schema)`
+
+Middleware that validates incoming params against a Zod schema at runtime. Use this for stricter validation (min/max, regex, custom refinements) beyond what Surf's built-in validation supports.
+
+```ts
+import { z } from 'zod';
+import { zodValidator } from '@surfjs/zod';
+
+const schema = z.object({
+  email: z.string().email(),
+  age: z.number().int().min(0).max(150),
+});
+
+const surf = createSurf({
+  name: 'my-app',
+  middleware: [zodValidator(schema)],
+  commands: { ... },
+});
+```
+
+### `convertZodType(zodType)`
+
+Convert a single Zod type to a Surf `ParamSchema`. Used internally by `zodToSurfParams` but exported for advanced use cases.
+
+## Type Mapping
+
+| Zod Type | Surf ParamSchema |
+|---|---|
+| `z.string()` | `{ type: 'string' }` |
+| `z.number()` | `{ type: 'number' }` |
+| `z.boolean()` | `{ type: 'boolean' }` |
+| `z.enum([...])` | `{ type: 'string', enum: [...] }` |
+| `z.object({})` | `{ type: 'object', properties: {...} }` |
+| `z.array(item)` | `{ type: 'array', items: ... }` |
+| `.optional()` | `required: false` |
+| `.default(val)` | `default: val` |
+| `.describe(text)` | `description: text` |
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,155 @@
+'use strict';
+
+var zod = require('zod');
+
+// src/convert.ts
+function convertZodType(zodType) {
+  const description = zodType.description;
+  const base = convertZodTypeInner(zodType);
+  if (description) {
+    base.description = description;
+  }
+  return base;
+}
+function convertZodTypeInner(zodType) {
+  if (zodType instanceof zod.ZodEffects) {
+    return convertZodTypeInner(zodType._def.schema);
+  }
+  if (zodType instanceof zod.ZodDefault) {
+    const inner = convertZodTypeInner(zodType._def.innerType);
+    inner.default = zodType._def.defaultValue();
+    return inner;
+  }
+  if (zodType instanceof zod.ZodOptional) {
+    const inner = convertZodTypeInner(zodType._def.innerType);
+    inner.required = false;
+    return inner;
+  }
+  if (zodType instanceof zod.ZodNullable) {
+    const inner = convertZodTypeInner(zodType._def.innerType);
+    inner.required = false;
+    return inner;
+  }
+  if (zodType instanceof zod.ZodString) {
+    return { type: "string" };
+  }
+  if (zodType instanceof zod.ZodNumber) {
+    return { type: "number" };
+  }
+  if (zodType instanceof zod.ZodBoolean) {
+    return { type: "boolean" };
+  }
+  if (zodType instanceof zod.ZodLiteral) {
+    const value = zodType._def.value;
+    if (typeof value === "string") {
+      return { type: "string", enum: [value] };
+    }
+    if (typeof value === "number") {
+      return { type: "number" };
+    }
+    if (typeof value === "boolean") {
+      return { type: "boolean" };
+    }
+    return { type: "string" };
+  }
+  if (zodType instanceof zod.ZodEnum) {
+    const values = zodType._def.values;
+    return { type: "string", enum: values };
+  }
+  if (zodType instanceof zod.ZodNativeEnum) {
+    const enumObj = zodType._def.values;
+    const values = Object.values(enumObj).filter(
+      (v) => typeof v === "string"
+    );
+    if (values.length > 0) {
+      return { type: "string", enum: values };
+    }
+    return { type: "string" };
+  }
+  if (zodType instanceof zod.ZodObject) {
+    const shape = zodType._def.shape();
+    const properties = {};
+    for (const [key, value] of Object.entries(shape)) {
+      if (value) {
+        const converted = convertZodType(value);
+        if (converted.required === void 0) {
+          converted.required = true;
+        }
+        properties[key] = converted;
+      }
+    }
+    return { type: "object", properties };
+  }
+  if (zodType instanceof zod.ZodArray) {
+    const itemSchema = convertZodType(zodType._def.type);
+    return { type: "array", items: itemSchema };
+  }
+  if (zodType instanceof zod.ZodUnion) {
+    const options = zodType._def.options;
+    if (options.length > 0 && options[0]) {
+      return convertZodTypeInner(options[0]);
+    }
+    return { type: "string" };
+  }
+  return { type: "string" };
+}
+function zodToSurfParams(schema) {
+  const shape = schema._def.shape();
+  const result = {};
+  for (const [key, value] of Object.entries(shape)) {
+    if (value) {
+      const converted = convertZodType(value);
+      if (converted.required === void 0) {
+        converted.required = true;
+      }
+      result[key] = converted;
+    }
+  }
+  return result;
+}
+
+// src/validate.ts
+function zodValidator(schema) {
+  return async (ctx, next) => {
+    const parseResult = schema.safeParse(ctx.params);
+    if (!parseResult.success) {
+      const issues = parseResult.error.issues;
+      const message = issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ");
+      ctx.error = {
+        ok: false,
+        error: {
+          code: "INVALID_PARAMS",
+          message: `Zod validation failed: ${message}`,
+          details: {
+            issues: issues.map((issue) => ({
+              path: issue.path,
+              message: issue.message,
+              code: issue.code
+            }))
+          }
+        }
+      };
+      return;
+    }
+    ctx.params = parseResult.data;
+    await next();
+  };
+}
+
+// src/index.ts
+function defineZodCommand(config) {
+  const { params: zodSchema, run, ...rest } = config;
+  const surfParams = zodToSurfParams(zodSchema);
+  return {
+    ...rest,
+    params: surfParams,
+    run
+  };
+}
+
+exports.convertZodType = convertZodType;
+exports.defineZodCommand = defineZodCommand;
+exports.zodToSurfParams = zodToSurfParams;
+exports.zodValidator = zodValidator;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/convert.ts","../src/validate.ts","../src/index.ts"],"names":["ZodEffects","ZodDefault","ZodOptional","ZodNullable","ZodString","ZodNumber","ZodBoolean","ZodLiteral","ZodEnum","ZodNativeEnum","ZodObject","ZodArray","ZodUnion"],"mappings":"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","file":"index.cjs","sourcesContent":["import type { ParamSchema } from '@surfjs/core';\nimport {\n  type ZodTypeAny,\n  ZodString,\n  ZodNumber,\n  ZodBoolean,\n  ZodEnum,\n  ZodObject,\n  ZodArray,\n  ZodOptional,\n  ZodDefault,\n  ZodNullable,\n  ZodEffects,\n  ZodLiteral,\n  ZodUnion,\n  ZodNativeEnum,\n} from 'zod';\n\n/**\n * Convert a single Zod type to a Surf ParamSchema.\n * Recursively handles nested objects, arrays, optionals, defaults, etc.\n */\nexport function convertZodType(zodType: ZodTypeAny): ParamSchema {\n  const description = zodType.description;\n  const base = convertZodTypeInner(zodType);\n\n  if (description) {\n    base.description = description;\n  }\n\n  return base;\n}\n\nfunction convertZodTypeInner(zodType: ZodTypeAny): ParamSchema {\n  // Unwrap ZodEffects (refinements, transforms, preprocess)\n  if (zodType instanceof ZodEffects) {\n    return convertZodTypeInner(zodType._def.schema as ZodTypeAny);\n  }\n\n  // ZodDefault — extract default value, recurse into inner type\n  if (zodType instanceof ZodDefault) {\n    const inner = convertZodTypeInner(zodType._def.innerType as ZodTypeAny);\n    inner.default = zodType._def.defaultValue();\n    return inner;\n  }\n\n  // ZodOptional — mark as not required, recurse\n  if (zodType instanceof ZodOptional) {\n    const inner = convertZodTypeInner(zodType._def.innerType as ZodTypeAny);\n    inner.required = false;\n    return inner;\n  }\n\n  // ZodNullable — treat like optional for Surf's purposes\n  if (zodType instanceof ZodNullable) {\n    const inner = convertZodTypeInner(zodType._def.innerType as ZodTypeAny);\n    inner.required = false;\n    return inner;\n  }\n\n  // Primitives\n  if (zodType instanceof ZodString) {\n    return { type: 'string' };\n  }\n\n  if (zodType instanceof ZodNumber) {\n    return { type: 'number' };\n  }\n\n  if (zodType instanceof ZodBoolean) {\n    return { type: 'boolean' };\n  }\n\n  // ZodLiteral — infer type from value\n  if (zodType instanceof ZodLiteral) {\n    const value = zodType._def.value as unknown;\n    if (typeof value === 'string') {\n      return { type: 'string', enum: [value] };\n    }\n    if (typeof value === 'number') {\n      return { type: 'number' };\n    }\n    if (typeof value === 'boolean') {\n      return { type: 'boolean' };\n    }\n    return { type: 'string' };\n  }\n\n  // ZodEnum — string enum\n  if (zodType instanceof ZodEnum) {\n    const values = zodType._def.values as readonly string[];\n    return { type: 'string', enum: values };\n  }\n\n  // ZodNativeEnum — JS enum\n  if (zodType instanceof ZodNativeEnum) {\n    const enumObj = zodType._def.values as Record<string, string | number>;\n    const values = Object.values(enumObj).filter(\n      (v): v is string => typeof v === 'string',\n    );\n    if (values.length > 0) {\n      return { type: 'string', enum: values };\n    }\n    return { type: 'string' };\n  }\n\n  // ZodObject — recursive conversion\n  if (zodType instanceof ZodObject) {\n    const shape = zodType._def.shape() as Record<string, ZodTypeAny>;\n    const properties: Record<string, ParamSchema> = {};\n\n    for (const [key, value] of Object.entries(shape)) {\n      if (value) {\n        const converted = convertZodType(value);\n        // In Zod, fields are required by default unless wrapped in .optional()\n        if (converted.required === undefined) {\n          converted.required = true;\n        }\n        properties[key] = converted;\n      }\n    }\n\n    return { type: 'object', properties };\n  }\n\n  // ZodArray — convert item type\n  if (zodType instanceof ZodArray) {\n    const itemSchema = convertZodType(zodType._def.type as ZodTypeAny);\n    return { type: 'array', items: itemSchema };\n  }\n\n  // ZodUnion — use first variant as a best-effort conversion\n  if (zodType instanceof ZodUnion) {\n    const options = zodType._def.options as ZodTypeAny[];\n    if (options.length > 0 && options[0]) {\n      return convertZodTypeInner(options[0]);\n    }\n    return { type: 'string' };\n  }\n\n  // Fallback for unsupported types\n  return { type: 'string' };\n}\n\n/**\n * Convert a Zod object schema to Surf's `Record<string, ParamSchema>` format.\n * This is the primary conversion function used by `defineZodCommand`.\n *\n * @param schema - A `z.object({...})` schema defining command parameters\n * @returns A record of parameter names to their Surf ParamSchema definitions\n */\nexport function zodToSurfParams(\n  schema: ZodObject<Record<string, ZodTypeAny>>,\n): Record<string, ParamSchema> {\n  const shape = schema._def.shape() as Record<string, ZodTypeAny>;\n  const result: Record<string, ParamSchema> = {};\n\n  for (const [key, value] of Object.entries(shape)) {\n    if (value) {\n      const converted = convertZodType(value);\n      // Top-level params: required by default unless explicitly optional\n      if (converted.required === undefined) {\n        converted.required = true;\n      }\n      result[key] = converted;\n    }\n  }\n\n  return result;\n}\n","import type { ZodObject, ZodTypeAny } from 'zod';\nimport type { MiddlewareContext, SurfMiddleware } from '@surfjs/core';\n\n/**\n * Create a Surf middleware that validates command params against a Zod schema.\n * Use this for runtime validation in addition to (or instead of) Surf's built-in validation.\n *\n * @param schema - A `z.object({...})` schema to validate incoming params against\n * @returns A SurfMiddleware function\n *\n * @example\n * ```ts\n * import { z } from 'zod';\n * import { zodValidator } from '@surfjs/zod';\n *\n * const schema = z.object({\n *   query: z.string().min(1),\n *   limit: z.number().int().min(1).max(100).optional(),\n * });\n *\n * // Use as middleware in a Surf config\n * middleware: [zodValidator(schema)]\n * ```\n */\nexport function zodValidator(\n  schema: ZodObject<Record<string, ZodTypeAny>>,\n): SurfMiddleware {\n  return async (ctx: MiddlewareContext, next: () => Promise<void>) => {\n    const parseResult = schema.safeParse(ctx.params);\n\n    if (!parseResult.success) {\n      const issues = parseResult.error.issues;\n      const message = issues\n        .map((issue) => `${issue.path.join('.')}: ${issue.message}`)\n        .join('; ');\n\n      ctx.error = {\n        ok: false,\n        error: {\n          code: 'INVALID_PARAMS',\n          message: `Zod validation failed: ${message}`,\n          details: {\n            issues: issues.map((issue) => ({\n              path: issue.path,\n              message: issue.message,\n              code: issue.code,\n            })),\n          },\n        },\n      };\n      return;\n    }\n\n    // Replace params with parsed (and potentially transformed/defaulted) values\n    ctx.params = parseResult.data as Record<string, unknown>;\n    await next();\n  };\n}\n","import type { ZodObject, ZodTypeAny, infer as ZodInfer } from 'zod';\nimport type {\n  CommandDefinition,\n  CommandHints,\n  CommandExample,\n  ExecutionContext,\n  PaginationConfig,\n  ParamSchema,\n  RateLimitConfig,\n  TypeRef,\n} from '@surfjs/core';\nimport { zodToSurfParams } from './convert.js';\n\nexport { zodToSurfParams, convertZodType } from './convert.js';\nexport { zodValidator } from './validate.js';\n\n/**\n * Configuration for defining a Surf command using a Zod schema.\n * The `params` field accepts a `z.object({...})` instead of raw `ParamSchema`.\n */\nexport interface ZodCommandConfig<\n  S extends ZodObject<Record<string, ZodTypeAny>>,\n  R = unknown,\n> {\n  /** Human-readable description of what this command does (shown to agents). */\n  description: string;\n  /** Zod object schema defining the command's parameters. */\n  params: S;\n  /** Return type schema for manifest documentation. */\n  returns?: ParamSchema | TypeRef;\n  /** Tags for grouping/filtering commands. */\n  tags?: string[];\n  /** Authentication requirement for this command. */\n  auth?: 'none' | 'required' | 'optional' | 'hidden';\n  /** Behavioral hints for agent optimization. */\n  hints?: CommandHints;\n  /** Enable SSE streaming for this command. */\n  stream?: boolean;\n  /** Per-command rate limiting. */\n  rateLimit?: RateLimitConfig;\n  /** Example request/response pairs shown in manifest. */\n  examples?: CommandExample[];\n  /** Enable pagination for this command. */\n  paginated?: boolean | PaginationConfig;\n  /** The command handler — receives fully-typed params inferred from the Zod schema. */\n  run: (params: ZodInfer<S>, ctx: ExecutionContext) => R | Promise<R>;\n}\n\n/**\n * Define a Surf command using a Zod schema for parameters.\n *\n * Converts the Zod schema to Surf's native `ParamSchema` format at runtime,\n * while providing full TypeScript inference from the Zod schema for the handler.\n *\n * @example\n * ```ts\n * import { z } from 'zod';\n * import { defineZodCommand } from '@surfjs/zod';\n *\n * const search = defineZodCommand({\n *   description: 'Search products',\n *   params: z.object({\n *     query: z.string().describe('Search query'),\n *     limit: z.number().int().min(1).max(100).optional().default(20),\n *     category: z.enum(['electronics', 'clothing', 'books']).optional(),\n *   }),\n *   run: async ({ query, limit, category }) => {\n *     // params are fully typed!\n *     return { results: [] };\n *   },\n * });\n * ```\n */\nexport function defineZodCommand<\n  S extends ZodObject<Record<string, ZodTypeAny>>,\n  R = unknown,\n>(config: ZodCommandConfig<S, R>): CommandDefinition {\n  const { params: zodSchema, run, ...rest } = config;\n  const surfParams = zodToSurfParams(zodSchema);\n\n  return {\n    ...rest,\n    params: surfParams,\n    run: run as CommandDefinition['run'],\n  };\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,96 @@
+import { ZodTypeAny, ZodObject, infer } from 'zod';
+import { ParamSchema, SurfMiddleware, TypeRef, CommandHints, RateLimitConfig, CommandExample, PaginationConfig, ExecutionContext, CommandDefinition } from '@surfjs/core';
+
+/**
+ * Convert a single Zod type to a Surf ParamSchema.
+ * Recursively handles nested objects, arrays, optionals, defaults, etc.
+ */
+declare function convertZodType(zodType: ZodTypeAny): ParamSchema;
+/**
+ * Convert a Zod object schema to Surf's `Record<string, ParamSchema>` format.
+ * This is the primary conversion function used by `defineZodCommand`.
+ *
+ * @param schema - A `z.object({...})` schema defining command parameters
+ * @returns A record of parameter names to their Surf ParamSchema definitions
+ */
+declare function zodToSurfParams(schema: ZodObject<Record<string, ZodTypeAny>>): Record<string, ParamSchema>;
+
+/**
+ * Create a Surf middleware that validates command params against a Zod schema.
+ * Use this for runtime validation in addition to (or instead of) Surf's built-in validation.
+ *
+ * @param schema - A `z.object({...})` schema to validate incoming params against
+ * @returns A SurfMiddleware function
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * import { zodValidator } from '@surfjs/zod';
+ *
+ * const schema = z.object({
+ *   query: z.string().min(1),
+ *   limit: z.number().int().min(1).max(100).optional(),
+ * });
+ *
+ * // Use as middleware in a Surf config
+ * middleware: [zodValidator(schema)]
+ * ```
+ */
+declare function zodValidator(schema: ZodObject<Record<string, ZodTypeAny>>): SurfMiddleware;
+
+/**
+ * Configuration for defining a Surf command using a Zod schema.
+ * The `params` field accepts a `z.object({...})` instead of raw `ParamSchema`.
+ */
+interface ZodCommandConfig<S extends ZodObject<Record<string, ZodTypeAny>>, R = unknown> {
+    /** Human-readable description of what this command does (shown to agents). */
+    description: string;
+    /** Zod object schema defining the command's parameters. */
+    params: S;
+    /** Return type schema for manifest documentation. */
+    returns?: ParamSchema | TypeRef;
+    /** Tags for grouping/filtering commands. */
+    tags?: string[];
+    /** Authentication requirement for this command. */
+    auth?: 'none' | 'required' | 'optional' | 'hidden';
+    /** Behavioral hints for agent optimization. */
+    hints?: CommandHints;
+    /** Enable SSE streaming for this command. */
+    stream?: boolean;
+    /** Per-command rate limiting. */
+    rateLimit?: RateLimitConfig;
+    /** Example request/response pairs shown in manifest. */
+    examples?: CommandExample[];
+    /** Enable pagination for this command. */
+    paginated?: boolean | PaginationConfig;
+    /** The command handler — receives fully-typed params inferred from the Zod schema. */
+    run: (params: infer<S>, ctx: ExecutionContext) => R | Promise<R>;
+}
+/**
+ * Define a Surf command using a Zod schema for parameters.
+ *
+ * Converts the Zod schema to Surf's native `ParamSchema` format at runtime,
+ * while providing full TypeScript inference from the Zod schema for the handler.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * import { defineZodCommand } from '@surfjs/zod';
+ *
+ * const search = defineZodCommand({
+ *   description: 'Search products',
+ *   params: z.object({
+ *     query: z.string().describe('Search query'),
+ *     limit: z.number().int().min(1).max(100).optional().default(20),
+ *     category: z.enum(['electronics', 'clothing', 'books']).optional(),
+ *   }),
+ *   run: async ({ query, limit, category }) => {
+ *     // params are fully typed!
+ *     return { results: [] };
+ *   },
+ * });
+ * ```
+ */
+declare function defineZodCommand<S extends ZodObject<Record<string, ZodTypeAny>>, R = unknown>(config: ZodCommandConfig<S, R>): CommandDefinition;
+
+export { type ZodCommandConfig, convertZodType, defineZodCommand, zodToSurfParams, zodValidator };

package/dist/index.d.ts

@@ -0,0 +1,96 @@
+import { ZodTypeAny, ZodObject, infer } from 'zod';
+import { ParamSchema, SurfMiddleware, TypeRef, CommandHints, RateLimitConfig, CommandExample, PaginationConfig, ExecutionContext, CommandDefinition } from '@surfjs/core';
+
+/**
+ * Convert a single Zod type to a Surf ParamSchema.
+ * Recursively handles nested objects, arrays, optionals, defaults, etc.
+ */
+declare function convertZodType(zodType: ZodTypeAny): ParamSchema;
+/**
+ * Convert a Zod object schema to Surf's `Record<string, ParamSchema>` format.
+ * This is the primary conversion function used by `defineZodCommand`.
+ *
+ * @param schema - A `z.object({...})` schema defining command parameters
+ * @returns A record of parameter names to their Surf ParamSchema definitions
+ */
+declare function zodToSurfParams(schema: ZodObject<Record<string, ZodTypeAny>>): Record<string, ParamSchema>;
+
+/**
+ * Create a Surf middleware that validates command params against a Zod schema.
+ * Use this for runtime validation in addition to (or instead of) Surf's built-in validation.
+ *
+ * @param schema - A `z.object({...})` schema to validate incoming params against
+ * @returns A SurfMiddleware function
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * import { zodValidator } from '@surfjs/zod';
+ *
+ * const schema = z.object({
+ *   query: z.string().min(1),
+ *   limit: z.number().int().min(1).max(100).optional(),
+ * });
+ *
+ * // Use as middleware in a Surf config
+ * middleware: [zodValidator(schema)]
+ * ```
+ */
+declare function zodValidator(schema: ZodObject<Record<string, ZodTypeAny>>): SurfMiddleware;
+
+/**
+ * Configuration for defining a Surf command using a Zod schema.
+ * The `params` field accepts a `z.object({...})` instead of raw `ParamSchema`.
+ */
+interface ZodCommandConfig<S extends ZodObject<Record<string, ZodTypeAny>>, R = unknown> {
+    /** Human-readable description of what this command does (shown to agents). */
+    description: string;
+    /** Zod object schema defining the command's parameters. */
+    params: S;
+    /** Return type schema for manifest documentation. */
+    returns?: ParamSchema | TypeRef;
+    /** Tags for grouping/filtering commands. */
+    tags?: string[];
+    /** Authentication requirement for this command. */
+    auth?: 'none' | 'required' | 'optional' | 'hidden';
+    /** Behavioral hints for agent optimization. */
+    hints?: CommandHints;
+    /** Enable SSE streaming for this command. */
+    stream?: boolean;
+    /** Per-command rate limiting. */
+    rateLimit?: RateLimitConfig;
+    /** Example request/response pairs shown in manifest. */
+    examples?: CommandExample[];
+    /** Enable pagination for this command. */
+    paginated?: boolean | PaginationConfig;
+    /** The command handler — receives fully-typed params inferred from the Zod schema. */
+    run: (params: infer<S>, ctx: ExecutionContext) => R | Promise<R>;
+}
+/**
+ * Define a Surf command using a Zod schema for parameters.
+ *
+ * Converts the Zod schema to Surf's native `ParamSchema` format at runtime,
+ * while providing full TypeScript inference from the Zod schema for the handler.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * import { defineZodCommand } from '@surfjs/zod';
+ *
+ * const search = defineZodCommand({
+ *   description: 'Search products',
+ *   params: z.object({
+ *     query: z.string().describe('Search query'),
+ *     limit: z.number().int().min(1).max(100).optional().default(20),
+ *     category: z.enum(['electronics', 'clothing', 'books']).optional(),
+ *   }),
+ *   run: async ({ query, limit, category }) => {
+ *     // params are fully typed!
+ *     return { results: [] };
+ *   },
+ * });
+ * ```
+ */
+declare function defineZodCommand<S extends ZodObject<Record<string, ZodTypeAny>>, R = unknown>(config: ZodCommandConfig<S, R>): CommandDefinition;
+
+export { type ZodCommandConfig, convertZodType, defineZodCommand, zodToSurfParams, zodValidator };

package/dist/index.js

@@ -0,0 +1,150 @@
+import { ZodEffects, ZodDefault, ZodOptional, ZodNullable, ZodString, ZodNumber, ZodBoolean, ZodLiteral, ZodEnum, ZodNativeEnum, ZodObject, ZodArray, ZodUnion } from 'zod';
+
+// src/convert.ts
+function convertZodType(zodType) {
+  const description = zodType.description;
+  const base = convertZodTypeInner(zodType);
+  if (description) {
+    base.description = description;
+  }
+  return base;
+}
+function convertZodTypeInner(zodType) {
+  if (zodType instanceof ZodEffects) {
+    return convertZodTypeInner(zodType._def.schema);
+  }
+  if (zodType instanceof ZodDefault) {
+    const inner = convertZodTypeInner(zodType._def.innerType);
+    inner.default = zodType._def.defaultValue();
+    return inner;
+  }
+  if (zodType instanceof ZodOptional) {
+    const inner = convertZodTypeInner(zodType._def.innerType);
+    inner.required = false;
+    return inner;
+  }
+  if (zodType instanceof ZodNullable) {
+    const inner = convertZodTypeInner(zodType._def.innerType);
+    inner.required = false;
+    return inner;
+  }
+  if (zodType instanceof ZodString) {
+    return { type: "string" };
+  }
+  if (zodType instanceof ZodNumber) {
+    return { type: "number" };
+  }
+  if (zodType instanceof ZodBoolean) {
+    return { type: "boolean" };
+  }
+  if (zodType instanceof ZodLiteral) {
+    const value = zodType._def.value;
+    if (typeof value === "string") {
+      return { type: "string", enum: [value] };
+    }
+    if (typeof value === "number") {
+      return { type: "number" };
+    }
+    if (typeof value === "boolean") {
+      return { type: "boolean" };
+    }
+    return { type: "string" };
+  }
+  if (zodType instanceof ZodEnum) {
+    const values = zodType._def.values;
+    return { type: "string", enum: values };
+  }
+  if (zodType instanceof ZodNativeEnum) {
+    const enumObj = zodType._def.values;
+    const values = Object.values(enumObj).filter(
+      (v) => typeof v === "string"
+    );
+    if (values.length > 0) {
+      return { type: "string", enum: values };
+    }
+    return { type: "string" };
+  }
+  if (zodType instanceof ZodObject) {
+    const shape = zodType._def.shape();
+    const properties = {};
+    for (const [key, value] of Object.entries(shape)) {
+      if (value) {
+        const converted = convertZodType(value);
+        if (converted.required === void 0) {
+          converted.required = true;
+        }
+        properties[key] = converted;
+      }
+    }
+    return { type: "object", properties };
+  }
+  if (zodType instanceof ZodArray) {
+    const itemSchema = convertZodType(zodType._def.type);
+    return { type: "array", items: itemSchema };
+  }
+  if (zodType instanceof ZodUnion) {
+    const options = zodType._def.options;
+    if (options.length > 0 && options[0]) {
+      return convertZodTypeInner(options[0]);
+    }
+    return { type: "string" };
+  }
+  return { type: "string" };
+}
+function zodToSurfParams(schema) {
+  const shape = schema._def.shape();
+  const result = {};
+  for (const [key, value] of Object.entries(shape)) {
+    if (value) {
+      const converted = convertZodType(value);
+      if (converted.required === void 0) {
+        converted.required = true;
+      }
+      result[key] = converted;
+    }
+  }
+  return result;
+}
+
+// src/validate.ts
+function zodValidator(schema) {
+  return async (ctx, next) => {
+    const parseResult = schema.safeParse(ctx.params);
+    if (!parseResult.success) {
+      const issues = parseResult.error.issues;
+      const message = issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ");
+      ctx.error = {
+        ok: false,
+        error: {
+          code: "INVALID_PARAMS",
+          message: `Zod validation failed: ${message}`,
+          details: {
+            issues: issues.map((issue) => ({
+              path: issue.path,
+              message: issue.message,
+              code: issue.code
+            }))
+          }
+        }
+      };
+      return;
+    }
+    ctx.params = parseResult.data;
+    await next();
+  };
+}
+
+// src/index.ts
+function defineZodCommand(config) {
+  const { params: zodSchema, run, ...rest } = config;
+  const surfParams = zodToSurfParams(zodSchema);
+  return {
+    ...rest,
+    params: surfParams,
+    run
+  };
+}
+
+export { convertZodType, defineZodCommand, zodToSurfParams, zodValidator };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/convert.ts","../src/validate.ts","../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { ParamSchema } from '@surfjs/core';\nimport {\n  type ZodTypeAny,\n  ZodString,\n  ZodNumber,\n  ZodBoolean,\n  ZodEnum,\n  ZodObject,\n  ZodArray,\n  ZodOptional,\n  ZodDefault,\n  ZodNullable,\n  ZodEffects,\n  ZodLiteral,\n  ZodUnion,\n  ZodNativeEnum,\n} from 'zod';\n\n/**\n * Convert a single Zod type to a Surf ParamSchema.\n * Recursively handles nested objects, arrays, optionals, defaults, etc.\n */\nexport function convertZodType(zodType: ZodTypeAny): ParamSchema {\n  const description = zodType.description;\n  const base = convertZodTypeInner(zodType);\n\n  if (description) {\n    base.description = description;\n  }\n\n  return base;\n}\n\nfunction convertZodTypeInner(zodType: ZodTypeAny): ParamSchema {\n  // Unwrap ZodEffects (refinements, transforms, preprocess)\n  if (zodType instanceof ZodEffects) {\n    return convertZodTypeInner(zodType._def.schema as ZodTypeAny);\n  }\n\n  // ZodDefault — extract default value, recurse into inner type\n  if (zodType instanceof ZodDefault) {\n    const inner = convertZodTypeInner(zodType._def.innerType as ZodTypeAny);\n    inner.default = zodType._def.defaultValue();\n    return inner;\n  }\n\n  // ZodOptional — mark as not required, recurse\n  if (zodType instanceof ZodOptional) {\n    const inner = convertZodTypeInner(zodType._def.innerType as ZodTypeAny);\n    inner.required = false;\n    return inner;\n  }\n\n  // ZodNullable — treat like optional for Surf's purposes\n  if (zodType instanceof ZodNullable) {\n    const inner = convertZodTypeInner(zodType._def.innerType as ZodTypeAny);\n    inner.required = false;\n    return inner;\n  }\n\n  // Primitives\n  if (zodType instanceof ZodString) {\n    return { type: 'string' };\n  }\n\n  if (zodType instanceof ZodNumber) {\n    return { type: 'number' };\n  }\n\n  if (zodType instanceof ZodBoolean) {\n    return { type: 'boolean' };\n  }\n\n  // ZodLiteral — infer type from value\n  if (zodType instanceof ZodLiteral) {\n    const value = zodType._def.value as unknown;\n    if (typeof value === 'string') {\n      return { type: 'string', enum: [value] };\n    }\n    if (typeof value === 'number') {\n      return { type: 'number' };\n    }\n    if (typeof value === 'boolean') {\n      return { type: 'boolean' };\n    }\n    return { type: 'string' };\n  }\n\n  // ZodEnum — string enum\n  if (zodType instanceof ZodEnum) {\n    const values = zodType._def.values as readonly string[];\n    return { type: 'string', enum: values };\n  }\n\n  // ZodNativeEnum — JS enum\n  if (zodType instanceof ZodNativeEnum) {\n    const enumObj = zodType._def.values as Record<string, string | number>;\n    const values = Object.values(enumObj).filter(\n      (v): v is string => typeof v === 'string',\n    );\n    if (values.length > 0) {\n      return { type: 'string', enum: values };\n    }\n    return { type: 'string' };\n  }\n\n  // ZodObject — recursive conversion\n  if (zodType instanceof ZodObject) {\n    const shape = zodType._def.shape() as Record<string, ZodTypeAny>;\n    const properties: Record<string, ParamSchema> = {};\n\n    for (const [key, value] of Object.entries(shape)) {\n      if (value) {\n        const converted = convertZodType(value);\n        // In Zod, fields are required by default unless wrapped in .optional()\n        if (converted.required === undefined) {\n          converted.required = true;\n        }\n        properties[key] = converted;\n      }\n    }\n\n    return { type: 'object', properties };\n  }\n\n  // ZodArray — convert item type\n  if (zodType instanceof ZodArray) {\n    const itemSchema = convertZodType(zodType._def.type as ZodTypeAny);\n    return { type: 'array', items: itemSchema };\n  }\n\n  // ZodUnion — use first variant as a best-effort conversion\n  if (zodType instanceof ZodUnion) {\n    const options = zodType._def.options as ZodTypeAny[];\n    if (options.length > 0 && options[0]) {\n      return convertZodTypeInner(options[0]);\n    }\n    return { type: 'string' };\n  }\n\n  // Fallback for unsupported types\n  return { type: 'string' };\n}\n\n/**\n * Convert a Zod object schema to Surf's `Record<string, ParamSchema>` format.\n * This is the primary conversion function used by `defineZodCommand`.\n *\n * @param schema - A `z.object({...})` schema defining command parameters\n * @returns A record of parameter names to their Surf ParamSchema definitions\n */\nexport function zodToSurfParams(\n  schema: ZodObject<Record<string, ZodTypeAny>>,\n): Record<string, ParamSchema> {\n  const shape = schema._def.shape() as Record<string, ZodTypeAny>;\n  const result: Record<string, ParamSchema> = {};\n\n  for (const [key, value] of Object.entries(shape)) {\n    if (value) {\n      const converted = convertZodType(value);\n      // Top-level params: required by default unless explicitly optional\n      if (converted.required === undefined) {\n        converted.required = true;\n      }\n      result[key] = converted;\n    }\n  }\n\n  return result;\n}\n","import type { ZodObject, ZodTypeAny } from 'zod';\nimport type { MiddlewareContext, SurfMiddleware } from '@surfjs/core';\n\n/**\n * Create a Surf middleware that validates command params against a Zod schema.\n * Use this for runtime validation in addition to (or instead of) Surf's built-in validation.\n *\n * @param schema - A `z.object({...})` schema to validate incoming params against\n * @returns A SurfMiddleware function\n *\n * @example\n * ```ts\n * import { z } from 'zod';\n * import { zodValidator } from '@surfjs/zod';\n *\n * const schema = z.object({\n *   query: z.string().min(1),\n *   limit: z.number().int().min(1).max(100).optional(),\n * });\n *\n * // Use as middleware in a Surf config\n * middleware: [zodValidator(schema)]\n * ```\n */\nexport function zodValidator(\n  schema: ZodObject<Record<string, ZodTypeAny>>,\n): SurfMiddleware {\n  return async (ctx: MiddlewareContext, next: () => Promise<void>) => {\n    const parseResult = schema.safeParse(ctx.params);\n\n    if (!parseResult.success) {\n      const issues = parseResult.error.issues;\n      const message = issues\n        .map((issue) => `${issue.path.join('.')}: ${issue.message}`)\n        .join('; ');\n\n      ctx.error = {\n        ok: false,\n        error: {\n          code: 'INVALID_PARAMS',\n          message: `Zod validation failed: ${message}`,\n          details: {\n            issues: issues.map((issue) => ({\n              path: issue.path,\n              message: issue.message,\n              code: issue.code,\n            })),\n          },\n        },\n      };\n      return;\n    }\n\n    // Replace params with parsed (and potentially transformed/defaulted) values\n    ctx.params = parseResult.data as Record<string, unknown>;\n    await next();\n  };\n}\n","import type { ZodObject, ZodTypeAny, infer as ZodInfer } from 'zod';\nimport type {\n  CommandDefinition,\n  CommandHints,\n  CommandExample,\n  ExecutionContext,\n  PaginationConfig,\n  ParamSchema,\n  RateLimitConfig,\n  TypeRef,\n} from '@surfjs/core';\nimport { zodToSurfParams } from './convert.js';\n\nexport { zodToSurfParams, convertZodType } from './convert.js';\nexport { zodValidator } from './validate.js';\n\n/**\n * Configuration for defining a Surf command using a Zod schema.\n * The `params` field accepts a `z.object({...})` instead of raw `ParamSchema`.\n */\nexport interface ZodCommandConfig<\n  S extends ZodObject<Record<string, ZodTypeAny>>,\n  R = unknown,\n> {\n  /** Human-readable description of what this command does (shown to agents). */\n  description: string;\n  /** Zod object schema defining the command's parameters. */\n  params: S;\n  /** Return type schema for manifest documentation. */\n  returns?: ParamSchema | TypeRef;\n  /** Tags for grouping/filtering commands. */\n  tags?: string[];\n  /** Authentication requirement for this command. */\n  auth?: 'none' | 'required' | 'optional' | 'hidden';\n  /** Behavioral hints for agent optimization. */\n  hints?: CommandHints;\n  /** Enable SSE streaming for this command. */\n  stream?: boolean;\n  /** Per-command rate limiting. */\n  rateLimit?: RateLimitConfig;\n  /** Example request/response pairs shown in manifest. */\n  examples?: CommandExample[];\n  /** Enable pagination for this command. */\n  paginated?: boolean | PaginationConfig;\n  /** The command handler — receives fully-typed params inferred from the Zod schema. */\n  run: (params: ZodInfer<S>, ctx: ExecutionContext) => R | Promise<R>;\n}\n\n/**\n * Define a Surf command using a Zod schema for parameters.\n *\n * Converts the Zod schema to Surf's native `ParamSchema` format at runtime,\n * while providing full TypeScript inference from the Zod schema for the handler.\n *\n * @example\n * ```ts\n * import { z } from 'zod';\n * import { defineZodCommand } from '@surfjs/zod';\n *\n * const search = defineZodCommand({\n *   description: 'Search products',\n *   params: z.object({\n *     query: z.string().describe('Search query'),\n *     limit: z.number().int().min(1).max(100).optional().default(20),\n *     category: z.enum(['electronics', 'clothing', 'books']).optional(),\n *   }),\n *   run: async ({ query, limit, category }) => {\n *     // params are fully typed!\n *     return { results: [] };\n *   },\n * });\n * ```\n */\nexport function defineZodCommand<\n  S extends ZodObject<Record<string, ZodTypeAny>>,\n  R = unknown,\n>(config: ZodCommandConfig<S, R>): CommandDefinition {\n  const { params: zodSchema, run, ...rest } = config;\n  const surfParams = zodToSurfParams(zodSchema);\n\n  return {\n    ...rest,\n    params: surfParams,\n    run: run as CommandDefinition['run'],\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@surfjs/zod",
+  "version": "0.2.0",
+  "description": "Zod schema integration for Surf.js — define commands with Zod instead of raw ParamSchema",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@surfjs/core": ">=0.2.0",
+    "zod": ">=3.0.0"
+  },
+  "devDependencies": {
+    "@surfjs/core": "workspace:*",
+    "tsup": "^8.5.1",
+    "typescript": "^5.8.0",
+    "zod": "^3.24.0"
+  },
+  "license": "MIT",
+  "keywords": [
+    "surf",
+    "zod",
+    "schema",
+    "validation",
+    "ai",
+    "agents",
+    "protocol"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hauselabs/surf.git",
+    "directory": "packages/zod"
+  },
+  "homepage": "https://surf.codes",
+  "bugs": {
+    "url": "https://github.com/hauselabs/surf/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}