feat(common): add validated-function utilities and conventions guide

Implements the function-conventions OpenSpec change and records the project's
coding conventions.

- ValidationError: structured, field-level wrapper over ZodError with toJSON()
- withErrorHandlingAndValidation: validates input via a Zod schema, throws
  ValidationError on failure, passes typed data through on success
- unit tests (node:test) for both, exported from @qcobro/common
- CLAUDE.md: conventions home (validated-function pattern, i18n, commits, layout)
- /create-validated-function command to scaffold the pattern

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: psanders

.claude/commands/create-validated-function.md

@@ -0,0 +1,166 @@
+---
+name: "Create Validated Function"
+description: Scaffold a function using the validated-function pattern (DI + Zod validation + error handling)
+---
+
+# Create Validated Function
+
+Create a new function using the validation and error-handling pattern with Zod schemas.
+
+## Pattern Overview
+
+A builder-style approach:
+
+1. **Outer function** (`createXxx`) accepts dependencies as parameters (dependency injection).
+2. **Inner function** (`fn`) contains the actual business logic with typed parameters.
+3. **Wrapper** (`withErrorHandlingAndValidation`) handles validation and errors.
+
+This enables **dependency injection**, making functions easy to test by swapping real
+dependencies with mocks.
+
+## Instructions
+
+1. **Identify or create the Zod schema** in `@qcobro/common`:
+   - Check if a schema already exists in `mods/common/src/schemas/`.
+   - If not, create a new schema file following the naming convention: `<domain>.ts`.
+   - Export the schema and its inferred type from `mods/common/src/schemas/index.ts`.
+   - Export from `mods/common/src/index.ts`.
+
+2. **Use existing client interfaces** from `@qcobro/common`:
+   - Client interfaces live in `mods/common/src/types/`.
+   - Import them: `import type { CustomerClient } from "@qcobro/common"`.
+   - If a new interface is needed, add it to the types folder.
+
+3. **Create the function file** following the naming pattern `create<FunctionName>.ts`:
+
+   ```typescript
+   import {
+     withErrorHandlingAndValidation,
+     <schemaName>,
+     type <InputType>,
+     type <ClientType>
+   } from "@qcobro/common";
+
+   export function create<FunctionName>(client: <ClientType>) {
+     const fn = async (params: <InputType>) => {
+       // Business logic here using the injected client
+       return client.doSomething(params);
+     };
+
+     return withErrorHandlingAndValidation(fn, <schemaName>);
+   }
+   ```
+
+4. **Export the function** from the appropriate barrel file or index.
+
+## Example: Customer Operations
+
+### Using Shared Types
+
+```typescript
+import {
+  withErrorHandlingAndValidation,
+  createCustomerSchema,
+  type CreateCustomerInput,
+  type CustomerClient
+} from "@qcobro/common";
+
+export function createCreateCustomer(client: CustomerClient) {
+  const fn = async (params: CreateCustomerInput) => {
+    return client.customer.create({ data: params });
+  };
+
+  return withErrorHandlingAndValidation(fn, createCustomerSchema);
+}
+```
+
+### Production Usage
+
+```typescript
+import { prisma } from "./db.js";
+import { createCreateCustomer } from "./customers/createCreateCustomer.js";
+
+// Inject the real database client
+const createCustomer = createCreateCustomer(prisma);
+
+// Validates input and throws ValidationError if invalid
+const customer = await createCustomer({
+  name: "John Doe",
+  phone: "+1234567890"
+});
+```
+
+## Example: Custom Service Function
+
+The pattern works for any function, not just database operations.
+
+### Schema
+
+```typescript
+// mods/common/src/schemas/notification.ts
+import { z } from "zod";
+
+export const sendNotificationSchema = z.object({
+  recipient: z.string().email(),
+  subject: z.string().min(1),
+  body: z.string().min(1),
+  priority: z.enum(["low", "normal", "high"]).optional()
+});
+
+export type SendNotificationInput = z.infer<typeof sendNotificationSchema>;
+```
+
+### Client Interface
+
+```typescript
+// mods/common/src/types/notification.ts
+import type { SendNotificationInput } from "../schemas/notification.js";
+
+export interface NotificationClient {
+  send(params: SendNotificationInput): Promise<{ messageId: string }>;
+}
+```
+
+## Testing
+
+Inject a mock client and assert on validation + delegation:
+
+```typescript
+it("throws ValidationError and never calls the client on invalid input", async () => {
+  const mockClient = { customer: { create: sinon.stub() } };
+  const createCustomer = createCreateCustomer(mockClient);
+
+  try {
+    await createCustomer({ name: "" });
+    expect.fail("Expected ValidationError to be thrown");
+  } catch (error) {
+    expect(error).to.be.instanceOf(ValidationError);
+    expect(mockClient.customer.create.called).to.be.false;
+  }
+});
+```
+
+Benefits: testability (mocks, no live services), isolation, fast tests, predictable behavior,
+and guaranteed validation coverage (invalid input never reaches the client).
+
+## Error Handling
+
+The `withErrorHandlingAndValidation` wrapper:
+
+- Validates input against the Zod schema using `safeParse`.
+- Throws `ValidationError` with field-level errors if validation fails.
+- Passes validated, typed data to the inner function.
+
+`ValidationError` includes:
+
+- `message`: human-readable message.
+- `fieldErrors`: array of `{ field, message, code }`.
+- `zodError`: original Zod error for debugging.
+- `toJSON()`: serializable form for API responses.
+
+## Files Reference
+
+- Utility: `mods/common/src/utils/withErrorHandlingAndValidation.ts`
+- Error: `mods/common/src/errors/ValidationError.ts`
+- Schemas: `mods/common/src/schemas/`
+- Client interfaces: `mods/common/src/types/`

CLAUDE.md

@@ -0,0 +1,68 @@
+# QCobro — Agent Guide
+
+QCobro (by Fonoster) is a **multilingual** AI-voice debt-collections platform. It is being
+rebuilt spec-first with OpenSpec. The previous implementation is archived on the `demo` branch.
+
+## How work is organized
+
+- **Product behavior (the WHAT)** lives in OpenSpec specs under `openspec/specs/`, and is changed
+  through proposals in `openspec/changes/`. Use `/opsx:propose`, `/opsx:apply`, `/opsx:archive`.
+  Specs describe observable, testable behavior — not coding style.
+- **Coding conventions (the HOW)** live in this file. They apply to every change.
+
+## Repository layout
+
+- `mods/common` — shared types and Zod schemas; the single source of truth for contracts.
+  Depends on no other workspace package.
+- `mods/apiserver` — tRPC API over Prisma/PostgreSQL. Procedures reach shared services
+  (DB today; telephony and other integrations later) through the tRPC **context**.
+- `mods/webapp` — React + Vite + Tailwind operator console; i18n-ready.
+- `site` — marketing site (hand-authored; ESLint/Prettier-ignored).
+
+## Coding conventions
+
+### Validated functions (preferred pattern for service/data functions)
+
+When defining a function that takes external input and performs an operation (DB writes,
+service calls, business logic), use the **validated-function** pattern: a builder that injects
+dependencies and wraps the logic with Zod validation.
+
+```typescript
+import {
+  withErrorHandlingAndValidation,
+  createCustomerSchema,
+  type CreateCustomerInput,
+  type CustomerClient
+} from "@qcobro/common";
+
+export function createCreateCustomer(client: CustomerClient) {
+  const fn = async (params: CreateCustomerInput) => {
+    return client.customer.create({ data: params });
+  };
+
+  return withErrorHandlingAndValidation(fn, createCustomerSchema);
+}
+```
+
+- Schemas and client interfaces live in `@qcobro/common` (`src/schemas/`, `src/types/`).
+- Dependencies are injected (the outer `create…` takes the client), so tests swap real clients
+  for mocks — no live services needed.
+- Invalid input throws `ValidationError` (field-level errors, `toJSON()` for API responses)
+  before the inner function runs.
+- Full guide and scaffolding: run `/create-validated-function`.
+
+> Apply this pattern when it fits (input-validating operations). Trivial pure helpers or
+> framework glue don't need it.
+
+### General
+
+- TypeScript strict; no `any` (ESLint enforces `@typescript-eslint/no-explicit-any`).
+- Share contracts via `@qcobro/common`; don't duplicate types between apiserver and webapp.
+- All user-facing console text goes through the i18n layer (`mods/webapp/src/lib/i18n.tsx`),
+  never hardcoded literals. The product is multilingual; assume no single default language.
+- Reach services through the tRPC context, not via ad-hoc imports inside procedures.
+
+## Commits
+
+Use **Conventional Commits** (`type(scope): subject`, e.g. `feat(api): add objectives router`).
+A Husky `commit-msg` hook runs commitlint and rejects non-conforming messages.

mods/common/package.json

@@ -9,12 +9,14 @@
   "scripts": {
     "build": "tsc -b --force",
     "clean": "rm -rf dist *.tsbuildinfo",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test \"src/**/*.test.ts\""
   },
   "dependencies": {
     "zod": "^4.0.0"
   },
   "devDependencies": {
+    "tsx": "^4.0.0",
     "typescript": "^5.9.0"
   }
 }

mods/common/src/errors/ValidationError.test.ts

@@ -0,0 +1,38 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { z } from "zod";
+import { ValidationError } from "./ValidationError.js";
+
+const schema = z.object({ name: z.string().min(1), age: z.number() });
+
+function zodErrorFor(input: unknown): z.ZodError {
+  const result = schema.safeParse(input);
+  assert.equal(result.success, false);
+  return (result as { success: false; error: z.ZodError }).error;
+}
+
+describe("ValidationError", () => {
+  it("exposes a stable code and field-level errors", () => {
+    const error = new ValidationError(zodErrorFor({ name: "", age: "nope" }));
+
+    assert.equal(error.code, "VALIDATION_ERROR");
+    assert.equal(error.name, "ValidationError");
+    assert.ok(error instanceof Error);
+
+    const fields = error.fieldErrors.map((f) => f.field);
+    assert.ok(fields.includes("name"));
+    assert.ok(fields.includes("age"));
+    for (const fieldError of error.fieldErrors) {
+      assert.equal(typeof fieldError.message, "string");
+      assert.equal(typeof fieldError.code, "string");
+    }
+  });
+
+  it("serializes to a JSON shape for API responses", () => {
+    const error = new ValidationError(zodErrorFor({ name: "", age: 1 }));
+    const json = error.toJSON();
+
+    assert.deepEqual(Object.keys(json).sort(), ["code", "fieldErrors", "message"]);
+    assert.equal(json.code, "VALIDATION_ERROR");
+  });
+});

mods/common/src/errors/ValidationError.ts

@@ -0,0 +1,68 @@
+import type { z } from "zod";
+
+export interface FieldError {
+  field: string;
+  message: string;
+  code: string;
+}
+
+/**
+ * Wraps a Zod validation error with structured, field-level details suitable
+ * for API responses.
+ */
+export class ValidationError extends Error {
+  public readonly code = "VALIDATION_ERROR";
+  public readonly fieldErrors: FieldError[];
+  public readonly zodError: z.ZodError;
+
+  constructor(zodError: z.ZodError) {
+    const fieldErrors = ValidationError.extractFieldErrors(zodError);
+    const message = ValidationError.formatMessage(fieldErrors);
+
+    super(message);
+    this.name = "ValidationError";
+    this.zodError = zodError;
+    this.fieldErrors = fieldErrors;
+
+    // Maintains proper stack trace for where the error was thrown (V8 engines).
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, ValidationError);
+    }
+  }
+
+  private static extractFieldErrors(zodError: z.ZodError): FieldError[] {
+    return zodError.issues.map((issue) => ({
+      field: issue.path.join(".") || "root",
+      message: issue.message,
+      code: issue.code
+    }));
+  }
+
+  private static formatMessage(fieldErrors: FieldError[]): string {
+    if (fieldErrors.length === 0) {
+      return "Validation failed";
+    }
+
+    if (fieldErrors.length === 1) {
+      const { field, message } = fieldErrors[0];
+      return field === "root" ? message : `${field}: ${message}`;
+    }
+
+    const details = fieldErrors
+      .map(({ field, message }) => (field === "root" ? message : `${field}: ${message}`))
+      .join("; ");
+
+    return `Validation failed: ${details}`;
+  }
+
+  /**
+   * Returns a JSON-serializable representation for API responses.
+   */
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      fieldErrors: this.fieldErrors
+    };
+  }
+}

mods/common/src/errors/index.ts

@@ -0,0 +1 @@
+export { ValidationError, type FieldError } from "./ValidationError.js";

mods/common/src/index.ts

@@ -1,5 +1,8 @@
 import { z } from "zod";
 
+export * from "./errors/index.js";
+export * from "./utils/index.js";
+
 /**
  * Placeholder contract proving the shared-schema pattern.
  *

mods/common/src/utils/index.ts

@@ -0,0 +1 @@
+export { withErrorHandlingAndValidation } from "./withErrorHandlingAndValidation.js";