create-velox-app 0.4.14 → 0.6.25

package/src/templates/source/api/router.auth.ts

@@ -0,0 +1,31 @@
+/**
+ * Router Definition
+ *
+ * This file exports the router type for frontend type safety.
+ * It MUST NOT have any side effects (like importing dotenv) so that
+ * the frontend can safely import types from here.
+ *
+ * IMPORTANT: Do not add 'import dotenv/config' or any side-effect imports here.
+ * The server entry point (index.ts) handles environment setup.
+ */
+
+import { extractRoutes } from '@veloxts/velox';
+
+import { authProcedures } from './procedures/auth.js';
+import { healthProcedures } from './procedures/health.js';
+import { userProcedures } from './procedures/users.js';
+
+// Procedure collections for routing
+export const collections = [healthProcedures, authProcedures, userProcedures];
+
+// Router definition for frontend type safety
+export const router = {
+  auth: authProcedures,
+  health: healthProcedures,
+  users: userProcedures,
+};
+
+export type AppRouter = typeof router;
+
+// Route mappings for frontend client
+export const routes = extractRoutes(collections);

package/src/templates/source/api/router.default.ts

@@ -0,0 +1,29 @@
+/**
+ * Router Definition
+ *
+ * This file exports the router type for frontend type safety.
+ * It MUST NOT have any side effects (like importing dotenv) so that
+ * the frontend can safely import types from here.
+ *
+ * IMPORTANT: Do not add 'import dotenv/config' or any side-effect imports here.
+ * The server entry point (index.ts) handles environment setup.
+ */
+
+import { extractRoutes } from '@veloxts/velox';
+
+import { healthProcedures } from './procedures/health.js';
+import { userProcedures } from './procedures/users.js';
+
+// Procedure collections for routing
+export const collections = [healthProcedures, userProcedures];
+
+// Router definition for frontend type safety
+export const router = {
+  health: healthProcedures,
+  users: userProcedures,
+};
+
+export type AppRouter = typeof router;
+
+// Route mappings for frontend client
+export const routes = extractRoutes(collections);

package/src/templates/source/api/router.trpc.ts

@@ -0,0 +1,37 @@
+/**
+ * Router Definition - tRPC Hybrid Template
+ *
+ * This file exports the router type for frontend type safety.
+ * It MUST NOT have any side effects (like importing dotenv) so that
+ * the frontend can safely import types from here.
+ *
+ * IMPORTANT: Do not add 'import dotenv/config' or any side-effect imports here.
+ * The server entry point (index.ts) handles environment setup.
+ */
+
+import { healthProcedures } from './procedures/health.js';
+import { userProcedures } from './procedures/users.js';
+
+// Procedure collections for routing
+export const collections = [healthProcedures, userProcedures];
+
+/**
+ * AppRouter type for frontend type safety
+ *
+ * Constructed from procedure collections to preserve full type information.
+ * This enables type-safe API calls with full autocomplete.
+ *
+ * @example
+ * ```typescript
+ * import type { AppRouter } from '../../api/src/router.js';
+ * import { createVeloxHooks } from '@veloxts/client/react';
+ *
+ * export const api = createVeloxHooks<AppRouter>();
+ * ```
+ */
+export const router = {
+  health: healthProcedures,
+  users: userProcedures,
+};
+
+export type AppRouter = typeof router;

package/src/templates/source/api/router.types.auth.ts

@@ -0,0 +1,88 @@
+/**
+ * Router Types - Browser-Safe Type Definitions
+ *
+ * BROWSER-SAFE: This file imports ONLY from schemas/ and zod.
+ * Never import from procedures/ or @veloxts/* packages here.
+ *
+ * Uses inline contract definitions for automatic type inference from Zod schemas.
+ * This provides "Great DX" - one line per procedure instead of verbose type definitions.
+ */
+
+import { z } from 'zod';
+
+import * as AuthSchemas from './schemas/auth.js';
+import * as HealthSchemas from './schemas/health.js';
+import * as UserSchemas from './schemas/user.js';
+
+// ============================================================================
+// Contract Helper (Browser-Safe)
+// ============================================================================
+
+/**
+ * Type-safe contract definition helper.
+ * Provides autocomplete and type inference without importing @veloxts/router.
+ */
+type ContractEntry = {
+  input?: z.ZodType;
+  output?: z.ZodType;
+};
+
+const defineContract = <T extends Record<string, ContractEntry>>(contracts: T): T => contracts;
+
+// ============================================================================
+// Health Contracts
+// ============================================================================
+
+export const healthContracts = defineContract({
+  getHealth: { output: HealthSchemas.HealthResponse },
+});
+
+// ============================================================================
+// User Contracts
+// ============================================================================
+
+export const userContracts = defineContract({
+  getUser: { input: UserSchemas.GetUserInput, output: UserSchemas.UserSchema },
+  listUsers: { input: UserSchemas.ListUsersInput, output: UserSchemas.ListUsersResponse },
+  createUser: { input: UserSchemas.CreateUserInput, output: UserSchemas.UserSchema },
+  updateUser: {
+    input: UserSchemas.UpdateUserInput.extend({ id: z.string().uuid() }),
+    output: UserSchemas.UserSchema,
+  },
+  patchUser: {
+    input: UserSchemas.UpdateUserInput.extend({ id: z.string().uuid() }),
+    output: UserSchemas.UserSchema,
+  },
+  deleteUser: {
+    input: z.object({ id: z.string().uuid() }),
+    output: z.object({ success: z.boolean() }),
+  },
+});
+
+// ============================================================================
+// Auth Contracts
+// ============================================================================
+
+export const authContracts = defineContract({
+  createAccount: { input: AuthSchemas.RegisterInput, output: AuthSchemas.TokenResponse },
+  createSession: { input: AuthSchemas.LoginInput, output: AuthSchemas.TokenResponse },
+  createRefresh: { input: AuthSchemas.RefreshInput, output: AuthSchemas.TokenResponse },
+  deleteSession: { output: AuthSchemas.LogoutResponse },
+  getMe: { output: AuthSchemas.UserResponse },
+});
+
+// ============================================================================
+// AppRouter Type - Automatic Inference
+// ============================================================================
+
+/**
+ * The complete router type, inferred from contracts.
+ *
+ * This replaces 50+ lines of manual type definitions with automatic inference.
+ * Each contract's input/output types are automatically extracted from Zod schemas.
+ */
+export type AppRouter = {
+  health: typeof healthContracts;
+  users: typeof userContracts;
+  auth: typeof authContracts;
+};

package/src/templates/source/api/router.types.default.ts

@@ -0,0 +1,73 @@
+/**
+ * Router Types - Browser-Safe Type Definitions
+ *
+ * BROWSER-SAFE: This file imports ONLY from schemas/ and zod.
+ * Never import from procedures/ or @veloxts/* packages here.
+ *
+ * Uses inline contract definitions for automatic type inference from Zod schemas.
+ * This provides "Great DX" - one line per procedure instead of verbose type definitions.
+ */
+
+import { z } from 'zod';
+
+import * as HealthSchemas from './schemas/health.js';
+import * as UserSchemas from './schemas/user.js';
+
+// ============================================================================
+// Contract Helper (Browser-Safe)
+// ============================================================================
+
+/**
+ * Type-safe contract definition helper.
+ * Provides autocomplete and type inference without importing @veloxts/router.
+ */
+type ContractEntry = {
+  input?: z.ZodType;
+  output?: z.ZodType;
+};
+
+const defineContract = <T extends Record<string, ContractEntry>>(contracts: T): T => contracts;
+
+// ============================================================================
+// Health Contracts
+// ============================================================================
+
+export const healthContracts = defineContract({
+  getHealth: { output: HealthSchemas.HealthResponse },
+});
+
+// ============================================================================
+// User Contracts
+// ============================================================================
+
+export const userContracts = defineContract({
+  getUser: { input: UserSchemas.GetUserInput, output: UserSchemas.UserSchema },
+  listUsers: { input: UserSchemas.ListUsersInput, output: UserSchemas.ListUsersResponse },
+  createUser: { input: UserSchemas.CreateUserInput, output: UserSchemas.UserSchema },
+  updateUser: {
+    input: UserSchemas.UpdateUserInput.extend({ id: z.string().uuid() }),
+    output: UserSchemas.UserSchema,
+  },
+  patchUser: {
+    input: UserSchemas.UpdateUserInput.extend({ id: z.string().uuid() }),
+    output: UserSchemas.UserSchema,
+  },
+  deleteUser: {
+    input: z.object({ id: z.string().uuid() }),
+    output: z.object({ success: z.boolean() }),
+  },
+});
+
+// ============================================================================
+// AppRouter Type - Automatic Inference
+// ============================================================================
+
+/**
+ * The complete router type, inferred from contracts.
+ *
+ * This replaces manual type definitions with automatic inference from Zod schemas.
+ */
+export type AppRouter = {
+  health: typeof healthContracts;
+  users: typeof userContracts;
+};

package/src/templates/source/api/router.types.trpc.ts

@@ -0,0 +1,73 @@
+/**
+ * Router Types - Browser-Safe Type Definitions
+ *
+ * BROWSER-SAFE: This file imports ONLY from schemas/ and zod.
+ * Never import from procedures/ or @veloxts/* packages here.
+ *
+ * Uses inline contract definitions for automatic type inference from Zod schemas.
+ * This provides "Great DX" - one line per procedure instead of verbose type definitions.
+ */
+
+import { z } from 'zod';
+
+import * as HealthSchemas from './schemas/health.js';
+import * as UserSchemas from './schemas/user.js';
+
+// ============================================================================
+// Contract Helper (Browser-Safe)
+// ============================================================================
+
+/**
+ * Type-safe contract definition helper.
+ * Provides autocomplete and type inference without importing @veloxts/router.
+ */
+type ContractEntry = {
+  input?: z.ZodType;
+  output?: z.ZodType;
+};
+
+const defineContract = <T extends Record<string, ContractEntry>>(contracts: T): T => contracts;
+
+// ============================================================================
+// Health Contracts
+// ============================================================================
+
+export const healthContracts = defineContract({
+  getHealth: { output: HealthSchemas.HealthResponse },
+});
+
+// ============================================================================
+// User Contracts
+// ============================================================================
+
+export const userContracts = defineContract({
+  getUser: { input: UserSchemas.GetUserInput, output: UserSchemas.UserSchema },
+  listUsers: { input: UserSchemas.ListUsersInput, output: UserSchemas.ListUsersResponse },
+  createUser: { input: UserSchemas.CreateUserInput, output: UserSchemas.UserSchema },
+  updateUser: {
+    input: UserSchemas.UpdateUserInput.extend({ id: z.string().uuid() }),
+    output: UserSchemas.UserSchema,
+  },
+  patchUser: {
+    input: UserSchemas.UpdateUserInput.extend({ id: z.string().uuid() }),
+    output: UserSchemas.UserSchema,
+  },
+  deleteUser: {
+    input: z.object({ id: z.string().uuid() }),
+    output: z.object({ success: z.boolean() }),
+  },
+});
+
+// ============================================================================
+// AppRouter Type - Automatic Inference
+// ============================================================================
+
+/**
+ * The complete router type, inferred from contracts.
+ *
+ * This replaces manual type definitions with automatic inference from Zod schemas.
+ */
+export type AppRouter = {
+  health: typeof healthContracts;
+  users: typeof userContracts;
+};

package/src/templates/source/api/routes.auth.ts

@@ -0,0 +1,66 @@
+/**
+ * Routes - Browser-Safe Route Definitions
+ *
+ * BROWSER-SAFE: This file contains only static route metadata.
+ * Never import from procedures/ or @veloxts/* packages here.
+ *
+ * These route mappings tell the frontend client how to call each procedure.
+ */
+
+// ============================================================================
+// Route Helper (Browser-Safe)
+// ============================================================================
+
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+type RouteEntry = {
+  method: HttpMethod;
+  path: string;
+};
+
+const defineRoutes = <T extends Record<string, RouteEntry>>(routes: T): T => routes;
+
+// ============================================================================
+// Health Routes
+// ============================================================================
+
+export const healthRoutes = defineRoutes({
+  getHealth: { method: 'GET', path: '/health' },
+});
+
+// ============================================================================
+// Auth Routes
+// ============================================================================
+
+export const authRoutes = defineRoutes({
+  createAccount: { method: 'POST', path: '/auth/register' },
+  createSession: { method: 'POST', path: '/auth/login' },
+  createRefresh: { method: 'POST', path: '/auth/refresh' },
+  deleteSession: { method: 'POST', path: '/auth/logout' },
+  getMe: { method: 'GET', path: '/auth/me' },
+});
+
+// ============================================================================
+// User Routes
+// ============================================================================
+
+export const userRoutes = defineRoutes({
+  getUser: { method: 'GET', path: '/users/:id' },
+  listUsers: { method: 'GET', path: '/users' },
+  createUser: { method: 'POST', path: '/users' },
+  updateUser: { method: 'PUT', path: '/users/:id' },
+  patchUser: { method: 'PATCH', path: '/users/:id' },
+  deleteUser: { method: 'DELETE', path: '/users/:id' },
+});
+
+// ============================================================================
+// Combined Routes Export
+// ============================================================================
+
+export const routes = {
+  health: healthRoutes,
+  auth: authRoutes,
+  users: userRoutes,
+} as const;
+
+export type Routes = typeof routes;

package/src/templates/source/api/routes.default.ts

@@ -0,0 +1,53 @@
+/**
+ * Routes - Browser-Safe Route Definitions
+ *
+ * BROWSER-SAFE: This file contains only static route metadata.
+ * Never import from procedures/ or @veloxts/* packages here.
+ *
+ * These route mappings tell the frontend client how to call each procedure.
+ */
+
+// ============================================================================
+// Route Helper (Browser-Safe)
+// ============================================================================
+
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+type RouteEntry = {
+  method: HttpMethod;
+  path: string;
+};
+
+const defineRoutes = <T extends Record<string, RouteEntry>>(routes: T): T => routes;
+
+// ============================================================================
+// Health Routes
+// ============================================================================
+
+export const healthRoutes = defineRoutes({
+  getHealth: { method: 'GET', path: '/health' },
+});
+
+// ============================================================================
+// User Routes
+// ============================================================================
+
+export const userRoutes = defineRoutes({
+  getUser: { method: 'GET', path: '/users/:id' },
+  listUsers: { method: 'GET', path: '/users' },
+  createUser: { method: 'POST', path: '/users' },
+  updateUser: { method: 'PUT', path: '/users/:id' },
+  patchUser: { method: 'PATCH', path: '/users/:id' },
+  deleteUser: { method: 'DELETE', path: '/users/:id' },
+});
+
+// ============================================================================
+// Combined Routes Export
+// ============================================================================
+
+export const routes = {
+  health: healthRoutes,
+  users: userRoutes,
+} as const;
+
+export type Routes = typeof routes;

package/src/templates/source/api/schemas/auth.ts

@@ -0,0 +1,79 @@
+/**
+ * Auth Schemas
+ *
+ * BROWSER-SAFE: This file imports ONLY from 'zod'.
+ * Never import from @veloxts/* packages here.
+ */
+
+import { z } from 'zod';
+
+// ============================================================================
+// Password Schema (for validation display)
+// ============================================================================
+
+export const PasswordSchema = z
+  .string()
+  .min(12, 'Password must be at least 12 characters')
+  .max(128, 'Password must not exceed 128 characters');
+
+// ============================================================================
+// Email Schema
+// ============================================================================
+
+export const EmailSchema = z
+  .string()
+  .email('Invalid email address')
+  .transform((email) => email.toLowerCase().trim());
+
+// ============================================================================
+// Input Schemas
+// ============================================================================
+
+export const RegisterInput = z.object({
+  name: z.string().min(2).max(100).trim(),
+  email: EmailSchema,
+  password: PasswordSchema,
+});
+
+export const LoginInput = z.object({
+  email: EmailSchema,
+  password: z.string().min(1),
+});
+
+export const RefreshInput = z.object({
+  refreshToken: z.string(),
+});
+
+// ============================================================================
+// Response Schemas
+// ============================================================================
+
+export const TokenResponse = z.object({
+  accessToken: z.string(),
+  refreshToken: z.string(),
+  expiresIn: z.number(),
+  tokenType: z.literal('Bearer'),
+});
+
+export const UserResponse = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string(),
+  roles: z.array(z.string()),
+});
+
+export const LogoutResponse = z.object({
+  success: z.boolean(),
+  message: z.string(),
+});
+
+// ============================================================================
+// Type Exports
+// ============================================================================
+
+export type RegisterData = z.infer<typeof RegisterInput>;
+export type LoginData = z.infer<typeof LoginInput>;
+export type RefreshData = z.infer<typeof RefreshInput>;
+export type TokenResponseData = z.infer<typeof TokenResponse>;
+export type UserResponseData = z.infer<typeof UserResponse>;
+export type LogoutResponseData = z.infer<typeof LogoutResponse>;

package/src/templates/source/api/schemas/health.ts

@@ -0,0 +1,21 @@
+/**
+ * Health Schemas
+ *
+ * BROWSER-SAFE: This file imports ONLY from 'zod'.
+ * Never import from @veloxts/* packages here.
+ */
+
+import { z } from 'zod';
+
+// ============================================================================
+// Health Check Schema
+// ============================================================================
+
+export const HealthResponse = z.object({
+  status: z.literal('ok'),
+  version: z.string(),
+  timestamp: z.string().datetime(),
+  uptime: z.number(),
+});
+
+export type HealthResponseData = z.infer<typeof HealthResponse>;

package/src/templates/source/api/schemas/user.ts

@@ -1,34 +1,84 @@
 /**
  * User Schemas
  *
- * Uses withTimestamps() for automatic Date → string serialization.
- * No manual transformation needed in procedure handlers.
+ * BROWSER-SAFE: This file imports ONLY from 'zod'.
+ * Never import from @veloxts/* packages here.
  */
 
-import { createIdSchema, emailSchema, withTimestamps, z } from '@veloxts/velox';
+import { z } from 'zod';
 
-// Business fields only - timestamps added separately
-const UserFields = z.object({
-  id: createIdSchema('uuid'),
+// ============================================================================
+// Timestamp Helper
+// ============================================================================
+
+/**
+ * Schema that accepts Date or string and outputs ISO string.
+ * Handles Prisma Date objects → JSON-safe strings.
+ */
+const dateToString = z
+  .union([z.date(), z.string()])
+  .transform((val) => (val instanceof Date ? val.toISOString() : val));
+
+// ============================================================================
+// User Schema
+// ============================================================================
+
+export const UserSchema = z.object({
+  id: z.string().uuid(),
   name: z.string().min(1).max(100),
-  email: emailSchema,
+  email: z.string().email(),
+  createdAt: dateToString,
+  updatedAt: dateToString,
 });
 
-// Complete schema with automatic Date → string serialization
-export const UserSchema = withTimestamps(UserFields);
-
 export type User = z.infer<typeof UserSchema>;
 
+// ============================================================================
+// Input Schemas
+// ============================================================================
+
+export const GetUserInput = z.object({
+  id: z.string().uuid(),
+});
+
 export const CreateUserInput = z.object({
   name: z.string().min(1).max(100),
-  email: emailSchema,
+  email: z.string().email(),
 });
 
 export type CreateUserData = z.infer<typeof CreateUserInput>;
 
 export const UpdateUserInput = z.object({
   name: z.string().min(1).max(100).optional(),
-  email: emailSchema.optional(),
+  email: z.string().email().optional(),
 });
 
 export type UpdateUserData = z.infer<typeof UpdateUserInput>;
+
+export const DeleteUserInput = z.object({
+  id: z.string().uuid(),
+});
+
+export const ListUsersInput = z
+  .object({
+    page: z.number().int().positive().optional(),
+    limit: z.number().int().positive().max(100).optional(),
+  })
+  .optional();
+
+export type ListUsersData = z.infer<typeof ListUsersInput>;
+
+// ============================================================================
+// Response Schemas
+// ============================================================================
+
+export const PaginationMeta = z.object({
+  page: z.number(),
+  limit: z.number(),
+  total: z.number(),
+});
+
+export const ListUsersResponse = z.object({
+  data: z.array(UserSchema),
+  meta: PaginationMeta,
+});