feat: enhance API response handling and add new components for module management

packages/shared/package.json

@@ -16,7 +16,8 @@
     "./registry": "./src/registry/index.ts",
     "./env": "./src/env/index.ts",
     "./dates": "./src/dates/index.ts",
-    "./formatters": "./src/dates/index.ts"
+    "./formatters": "./src/dates/index.ts",
+    "./api-response": "./src/api-response.ts"
   },
   "scripts": {
     "clean": "git clean -xdf .turbo node_modules",

packages/shared/src/api-response.ts

@@ -0,0 +1,46 @@
+/**
+ * Canonical API response types for all server actions and route handlers.
+ * Every action/endpoint should return one of these shapes.
+ */
+
+/** Successful action result */
+export type ActionSuccess<T = void> = T extends void
+  ? { success: true }
+  : { success: true; data: T };
+
+/** Failed action result */
+export interface ActionError {
+  success: false;
+  error: string;
+  validationErrors?: Array<{ field: string; message: string }>;
+}
+
+/** Union of success and error */
+export type ActionResult<T = void> = ActionSuccess<T> | ActionError;
+
+/** Standardized file download payload (used inside ActionSuccess.data) */
+export interface FileDownload {
+  content: string;
+  filename: string;
+  mimeType: string;
+}
+
+/** Helper to create a success response */
+export function actionSuccess(): { success: true };
+export function actionSuccess<T>(data: T): { success: true; data: T };
+export function actionSuccess<T>(data?: T) {
+  if (data === undefined) {
+    return { success: true };
+  }
+  return { success: true, data };
+}
+
+/** Helper to create an error response */
+export function actionError(
+  error: string,
+  validationErrors?: Array<{ field: string; message: string }>,
+): ActionError {
+  return validationErrors
+    ? { success: false, error, validationErrors }
+    : { success: false, error };
+}